LlamaIndex Embeddings API 详解BaseEmbedding 抽象契约与 resolve_embed_model 模型解析【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文围绕 LlamaIndex 官方 API 文档中的 embeddings 模块llama_index.core.embeddings展开完整讲解该模块对外暴露的两个核心成员BaseEmbedding与resolve_embed_model。读完本文你将理解 LlamaIndex 如何以统一的抽象契约管理数百种嵌入模型实现字段语义、必须实现的抽象方法、同步/异步调用流程、缓存与限流机制、批量处理逻辑以及resolve_embed_model如何根据字符串、实例或空值自动解析出正确的嵌入模型。对应源文档为 docs/api_reference/api_reference/embeddings/index.md它使用 mkdocstrings 自动渲染以下两个成员::: llama_index.core.embeddings options: members: - BaseEmbedding - resolve_embed_model这两个符号的导出入口在 llama-index-core/llama_index/core/embeddings/init.py该模块共导出BaseEmbedding、MockEmbedding、MultiModalEmbedding、MockMultiModalEmbedding、Pooling、resolve_embed_model六个对象即整个 embeddings API 层的公开表面。BaseEmbedding嵌入模型的统一抽象契约BaseEmbedding定义于 llama-index-core/llama_index/core/base/embeddings/base.py类签名如下base.py#L72-L77class BaseEmbedding(TransformComponent, DispatcherSpanMixin): Base class for embeddings.两个父类各有一层含义TransformComponent使它可以直接作为 Ingestion Pipeline 中的转换组件被调用后文__call__协议DispatcherSpanMixin使其所有公开方法都带有 instrumentation 事件上报能力dispatcher.span装饰器。所有第三方集成包如 llama-index-integrations/embeddings/llama-index-embeddings-openai 下的 OpenAI 实现都继承自它。核心字段及其取值约束字段定义见 base.py#L78-L104字段类型 / 默认值说明model_namestr默认unknown嵌入模型名称会随观测事件一起上报embed_batch_sizeint默认DEFAULT_EMBED_BATCH_SIZE值为10定义于 llama-index-core/llama_index/core/constants.py#L8批量嵌入调用的批大小约束为gt0, le2048callback_managerCallbackManager默认空管理器excludeTrue兼容旧版回调体系发出CBEventType.EMBEDDING事件num_workersOptional[int]默认None异步批量嵌入的并发工作数embeddings_cacheOptional[BaseKVStore]默认None嵌入结果缓存必须为 KV Store 实现否则校验器抛出TypeErrorbase.py#L120-L130rate_limiterOptional[BaseRateLimiter]默认NoneexcludeTrue对 API 调用做限流来源注释指向llama_index.core.rate_limiter注意一个设计细节embeddings_cache和rate_limiter都用Any类型声明字段、在校验器中再做运行时类型检查——源码注释说明这是为了避免 import 循环。此外to_payload()方法base.py#L106-L118返回一个不含凭证api_key、auth header 等敏感信息的可观测性表示随 instrumentation 事件和回调 payload 一起发出子类可以覆写以补充安全细节。子类必须实现与可选覆写的方法从源码结构看BaseEmbedding的方法分为三档必须实现的抽象方法abstractmethod_get_query_embedding(query: str) - Embedding同步嵌入一条查询_aget_query_embedding(query: str)异步版本同样是抽象的_get_text_embedding(text: str) - Embedding同步嵌入一段文本。有默认实现、可覆写_aget_text_embedding默认直接回退调用_get_text_embedding_get_text_embeddings(texts)单数 s 结尾的批量方法默认循环调用单条方法如果底层 API 原生支持批量如 OpenAI 的/v1/embeddings子类覆写它可以显著降低请求次数。公开方法由基类完整实现子类不应覆写。它们负责在“裸模型调用”之上叠加缓存、限流、回调与 instrumentation。get_query_embedding的文档字符串中还提到一个实践要点嵌入查询时不同模型可以在原始查询前拼接特殊指令instruction例如Represent the question for retrieving supporting documents: 文档同时指出更多预定义指令示例可以在embeddings/huggingface_utils.py中查找——这是 HuggingFace 集成包里的工具函数用于处理那些要求查询前缀与文档前缀不同指令的模型。公开方法的执行流程缓存、限流与观测以get_query_embeddingbase.py#L150-L202为例其内部流程是固定的五步通过to_payload()生成模型描述经 dispatcher 发出EmbeddingStartEvent进入callback_manager.event(CBEventType.EMBEDDING, ...)上下文若配置了embeddings_cache先以keyquery, collectionembeddings查缓存命中直接返回未命中则调用_get_query_embedding并把结果以{str(uuid.uuid4()): embedding}的字典结构写回缓存若配置了rate_limiter在真正发起模型调用前执行acquire()异步路径为await async_acquire()回调事件on_end携带EventPayload.CHUNKS与EventPayload.EMBEDDINGSdispatcher 发出EmbeddingEndEvent。get_text_embedding/aget_text_embedding的结构与之完全同构。aget_query_embeddingbase.py#L204-L249是查询嵌入唯一的异步原生路径。此外还有面向多查询聚合的get_agg_embedding_from_queries(queries, agg_fnNone)base.py#L251-L259逐条嵌入后调用聚合函数默认使用模块级函数mean_aggbase.py#L47-L52即对多个向量取均值该场景典型用于多路改写查询query rewriting后的结果融合。批量嵌入get_text_embedding_batch 与 aget_text_embedding_batch批量方法是大规模文档索引时的性能关键。同步版get_text_embedding_batchbase.py#L485-L535的机制是顺序遍历texts按embed_batch_size累积cur_batch当到达最后一条或当前批满时flush每批触发一对EmbeddingStartEvent/EmbeddingEndEvent与一个CBEventType.EMBEDDING回调事件若配置了缓存走_get_text_embeddings_cachedbase.py#L318-L348它逐条查缓存只对未命中的文本发起模型调用并用(index, text)元组记录原始下标保证最终返回的向量列表与输入顺序严格一致然后把新生成的向量写回缓存show_progressTrue时通过 tqdm 显示 Generating embeddings 进度条。异步版aget_text_embedding_batchbase.py#L537-L627在此基础上增加了并发控制从源码结构看有三条执行路径num_workers 1通过run_jobs来自llama_index.core.async_utils限制并发工作数执行各批次协程show_progressTrue且无 workers 限制优先使用tqdm_asyncio.gather未安装 tqdm 时回退asyncio.gather其他情况直接asyncio.gather。注意缓存路径的限流差异异步批量中无缓存分支走_aget_text_embeddings_rate_limitedbase.py#L310-L316内部先async_acquire再委托_aget_text_embeddings而缓存分支的限流则发生在_aget_text_embeddings_cached内部的实际调用处。最后所有批次的结果被展平flatten为单个List[Embedding]返回并逐批补发EmbeddingEndEvent与on_event_end回调。相似度计算与 Ingestion Pipeline 集成模块还导出了两种工具base.py#L39-L69SimilarityMode枚举DEFAULT cosine、DOT_PRODUCT、EUCLIDEAN函数式similarity(embedding1, embedding2, mode)欧氏距离模式返回负的欧氏距离作为相似度以与余弦/点积保持相同的排序方向BaseEmbedding.similarity实例方法base.py#L629-L636只是它的转发。最后__call__/acallbase.py#L638-L659实现了TransformComponent协议接收Sequence[BaseNode]对每个节点取node.get_content(metadata_modeMetadataMode.EMBED)得到待嵌入文本批量计算后把向量写回node.embedding并返回节点。这正是 Ingestion Pipeline 中给节点打向量这一步的直接实现。resolve_embed_model嵌入模型的统一解析入口第二个核心成员resolve_embed_model定义于 llama-index-core/llama_index/core/embeddings/utils.py#L30-L139其签名与输入类型如下EmbedType Union[BaseEmbedding, LCEmbeddings, str] def resolve_embed_model( embed_model: Optional[EmbedType] None, callback_manager: Optional[CallbackManager] None, ) - BaseEmbedding: Resolve embed model.它的作用是把用户传入的三种形态——嵌入模型实例、字符串、None——统一解析为一个BaseEmbedding对象。解析逻辑按以下顺序分支1. 传入 None显式禁用嵌入if embed_model is None: print(Embeddings have been explicitly disabled. Using MockEmbedding.) embed_model MockEmbedding(embed_dim1)None被约定为显式关闭嵌入的信号例如纯关键字检索场景此时回退到 1 维的MockEmbedding实现见 llama-index-core/llama_index/core/embeddings/mock_embed_model.py。2. 传入 defaultOpenAI 嵌入default分支utils.py#L42-L76若环境变量IS_TESTING已设置则返回MockEmbedding(embed_dim8)并返回——这是仓库内测试环境避免真实调用的短路逻辑否则尝试导入llama_index.embeddings.openai.OpenAIEmbedding并构造实例随后调用validate_openai_api_key(embed_model.api_key)校验密钥。该集成包位于 llama-index-integrations/embeddings/llama-index-embeddings-openai/llama_index/embeddings/openai包未安装时抛出ImportError提示pip install llama-index-embeddings-openai密钥校验失败时抛出ValueError错误信息明确建议考虑使用embed_modellocal并指出应检查OPENAI_API_KEY。3. 传入 clip... 字符串多模态 CLIP 嵌入以clip开头的字符串utils.py#L78-L90走 CLIP 分支以冒号分割解析模型名clip:ViT-B/32缺省为ViT-B/32构造ClipEmbedding。缺包时提示需要同时安装llama-index-embeddings-clip和 OpenAI 的 CLIP 包。多模态嵌入的基类MultiModalEmbedding定义于 llama-index-core/llama_index/core/embeddings/multi_modal_base.py。4. 传入 local 或 local:model_nameHuggingFace 本地模型其他字符串utils.py#L92-L116统一走 HuggingFace 分支且必须以local开头否则抛出ValueError: embed_model must start with str local or of type BaseEmbedding。冒号后的部分作为model_name传给HuggingFaceEmbedding模型缓存目录为get_cache_dir()/models自动创建。例如resolve_embed_model(local:sentence-transformers/all-MiniLM-L6-v2)会以本地 HuggingFace 模型作为嵌入模型。5. 传入 LangChain Embeddings 实例若环境中安装了 langchain-bridge 且传入对象是 LangChain 的Embeddings实例则包装为LangchainEmbedding需要llama-index-embeddings-langchain包包未安装时抛ImportError。统一的收尾处理无论走哪个分支函数在返回前做两件事utils.py#L135-L139assert isinstance(embed_model, BaseEmbedding) embed_model.callback_manager callback_manager or Settings.callback_manager return embed_model即断言结果必然是BaseEmbedding实例并把回调管理器设置为调用方显式传入的实例或回退到全局Settings.callback_manager——这保证了无论用户如何构造模型事件/回调体系都能统一生效。典型用法与生态延伸结合以上两个成员一个最小的可复制用法是from llama_index.core.embeddings import resolve_embed_model, BaseEmbedding from llama_index.core.schema import TextNode # 1) 解析模型default 需 OPENAI_API_KEYlocal:xxx 需 llama-index-embeddings-huggingface embed_model resolve_embed_model(local:sentence-transformers/all-MiniLM-L6-v2) # 2) 单条查询 / 文本嵌入带缓存、限流与观测事件 q_emb embed_model.get_query_embedding(what is LlamaIndex?) t_emb embed_model.get_text_embedding(LlamaIndex is a data framework for LLMs.) # 3) 批量嵌入按 embed_batch_size10 分批支持进度条 batch embed_model.get_text_embedding_batch([doc one, doc two], show_progressTrue) # 4) 相似度默认余弦 score embed_model.similarity(q_emb, t_emb) # 5) TransformComponent 协议直接给节点写向量 nodes [TextNode(textLlamaIndex is a data framework.)] embed_model(nodes) # 之后 nodes[0].embedding 已填充生态上还有几点值得留意集成包目录每个具体模型实现都是独立 PyPI 包集中在 llama-index-integrations/embeddings 下OpenAI、HuggingFace、Ollama、Cohere、Mistral 等上百个resolve_embed_model中各分支抛出的ImportError提示语就是这些包的安装说明示例 Notebookdocs/examples/embeddings 目录下有按模型组织的实操示例如OpenAI.ipynb、Langchain.ipynb、custom_embeddings.ipynb其中custom_embeddings.ipynb展示如何继承BaseEmbedding实现自定义模型多模态与池化同模块导出的MultiModalEmbedding图像多模态基类与Pooling池化策略分别服务于图文嵌入场景与词向量池化策略选择可观测性如前所述所有公开嵌入方法都通过dispatcher.span与EmbeddingStartEvent/EmbeddingEndEvent上报to_payload()保证上报内容不含凭证——接入 Langfuse、OpenInference 等回调/观测集成时见 llama-index-integrations/callbacks嵌入调用会自动出现在 trace 中。参考文件内容路径本文对应的 API 参考文档docs/api_reference/api_reference/embeddings/index.md模块导出llama-index-core/llama_index/core/embeddings/init.pyBaseEmbedding实现llama-index-core/llama_index/core/base/embeddings/base.pyresolve_embed_model实现llama-index-core/llama_index/core/embeddings/utils.py批大小常量DEFAULT_EMBED_BATCH_SIZE 10llama-index-core/llama_index/core/constants.pyMockEmbeddingllama-index-core/llama_index/core/embeddings/mock_embed_model.py多模态基类llama-index-core/llama_index/core/embeddings/multi_modal_base.py嵌入模型集成包目录llama-index-integrations/embeddings嵌入模型示例 Notebookdocs/examples/embeddings【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考