LlamaIndex Embeddings 实战指南自定义模型、本地 HuggingFace 模型与 Text-Embedding-Inference 接入全解【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇技术指南以 LlamaIndex 官方 FAQ 中关于 Embeddings 的四个高频问题为骨架系统讲解如何在 LlamaIndex 中使用自定义/本地 embedding 模型、如何接入本地 HuggingFace 模型、如何直接调用 embedding 模型为文本生成向量以及如何对接 HuggingFace Text-Embedding InferenceTEI推理服务。读完本文你将掌握BaseEmbedding的继承与实现要点、HuggingFaceEmbedding的核心参数与指令instruction机制、get_text_embedding/get_query_embedding/ 批量与异步接口的正确用法以及通过 HTTP 服务完成文本向量化的完整链路。1. 如何在 LlamaIndex 中使用自定义/本地 Embedding 模型在 LlamaIndex 中所有 embedding 能力都统一抽象在BaseEmbedding基类之下。无论底层是 OpenAI、HuggingFace、TEI 还是自研模型上层索引、检索器、查询引擎都只与这一抽象打交道因此实现一个自定义 embedding 类本质上就是继承BaseEmbedding并实现几个核心方法。1.1 认识BaseEmbedding抽象基类BaseEmbedding定义于 llama-index-core/llama_index/core/base/embeddings/base.py并从 llama-index-core/llama_index/core/embeddings/init.py 对外导出。它是一个TransformComponent意味着可以直接作为管线中的 Transform 使用内置以下常用字段model_name模型名称标识默认unknownembed_batch_size批处理大小默认取DEFAULT_EMBED_BATCH_SIZE取值范围(0, 2048]callback_manager回调管理器用于产生EMBEDDING类型的事件num_workers异步调用时的并发 worker 数embeddings_cache嵌入缓存须为BaseKVStore类型命中缓存时直接返回结果避免重复调用rate_limiter限流器用于在调用前按需限流。子类必须实现的抽象方法共有四个它们构成嵌入能力的底层原语_get_query_embedding(query)与_aget_query_embedding(query)同步/异步地对查询进行编码_get_text_embedding(text)与可选_aget_text_embedding(text)同步/异步地对文档文本进行编码。其中异步文本方法在基类中提供了默认实现即直接回退到同步版本批量方法_get_text_embeddings的默认实现则是循环调用单条方法。子类可以根据自身能力如 GPU 批量编码重写这些方法以获得更好的吞吐。1.2 自定义 Embedding 类的完整模板原文档指向的 Custom Embeddings 示例 给出了继承BaseEmbedding的最小实现方式核心代码如下from typing import List, Optional from llama_index.core.embeddings import BaseEmbedding class MyEmbedding(BaseEmbedding): def _get_query_embedding(self, query: str) - List[float]: # 在这里实现 query 的向量化逻辑 return self._get_text_embedding(query) async def _aget_query_embedding(self, query: str) - List[float]: # 异步版本可直接返回同步结果或使用真正的异步实现 return self._get_query_embedding(query) def _get_text_embedding(self, text: str) - List[float]: # 在这里实现文本的向量化逻辑 return [1.0, 0.0, 0.0] # 替换为真实模型输出 def _get_text_embeddings(self, texts: List[str]) - List[List[float]]: # 可选的批量优化默认实现是逐条调用 _get_text_embedding return [self._get_text_embedding(text) for text in texts]关键点返回类型必须是List[float]即一个定长的浮点向量基类中定义了Embedding List[float]类型别名查询与文本的编码路径相互独立很多模型如 bge、instructor要求 query 与 document 使用不同的指令instruction前缀因此_get_query_embedding与_get_text_embedding通常需要区分实现实例化后可以通过Settings.embed_model MyEmbedding(...)把它注册为全局默认嵌入模型也可以直接调用其公开方法使用。1.3 通过字符串快速切换模型resolve_embed_model除了手写子类LlamaIndex 还提供resolve_embed_model位于 llama-index-core/llama_index/core/embeddings/utils.py支持用字符串一键解析出可用的BaseEmbedding实例embed_modeldefault默认使用OpenAIEmbedding需要llama-index-embeddings-openai包与OPENAI_API_KEY测试环境设置了IS_TESTING下会退化为MockEmbeddingembed_modellocal或local:模型名解析为本地HuggingFaceEmbedding模型名缺省时使用默认模型并自动把模型缓存在get_cache_dir()/models目录embed_modelclip:模型名解析为多模态ClipEmbedding传入LangChain的Embeddings对象自动包装为LangchainEmbedding传入None显式禁用嵌入使用MockEmbedding。也就是说使用本地 embedding 模型除了直接实例化HuggingFaceEmbedding之外还可以简单地写Settings.embed_model local:BAAI/bge-small-en由框架完成解析与缓存目录的创建。2. 如何在本机使用 HuggingFace Embedding 模型原文档 FAQ 第 2 问给出了使用本地 HuggingFace 模型的入口Local Embeddings with HuggingFace 示例。其底层实现类是HuggingFaceEmbedding源码位于 llama-index-integrations/embeddings/llama-index-embeddings-huggingface/llama_index/embeddings/huggingface/base.py。2.1 安装与最小用法首先安装集成包pip install llama-index-embeddings-huggingface然后在代码中加载模型并注册为全局嵌入模型from llama_index.core import Settings from llama_index.embeddings.huggingface import HuggingFaceEmbedding # 加载本地/远程 SentenceTransformer 模型 embed_model HuggingFaceEmbedding(model_nameBAAI/bge-small-en) Settings.embed_model embed_model # 单独为一段文本生成向量 embeddings embed_model.get_text_embedding(I want to Embed this text!)HuggingFaceEmbedding内部基于sentence-transformers的SentenceTransformer实现model_name既可以是 HuggingFace Hub 上的模型名也可以是本机磁盘上的模型目录路径——传入本地路径即可做到完全离线使用。默认模型名为BAAI/bge-small-en定义于 huggingface/utils.py 中的DEFAULT_HUGGINGFACE_EMBEDDING_MODEL。2.2 核心参数详解构造函数的主要参数及其默认值如下参数默认值说明model_nameBAAI/bge-small-enHub 模型名或本地模型目录路径max_length512输入序列的最大长度会写入模型配置query_instructionNone附加到 query 前的指令文本缺省时按模型名自动推导text_instructionNone附加到文档文本前的指令文本缺省时按模型名自动推导normalizeTrue是否对输出向量做 L2 归一化embed_batch_sizeDEFAULT_EMBED_BATCH_SIZE单次编码的批量大小cache_folderNone模型缓存目录缺省使用get_cache_dir()trust_remote_codeFalse是否信任 Hub 上的自定义建模代码仅对可信仓库开启device自动推断计算设备如cuda、cpu、mps缺省用infer_torch_device()推断parallel_processFalse是否启用多进程编码池适合海量文本target_devicesNoneparallel_processTrue时使用的目标设备列表show_progress_barFalse编码时是否显示进度条从源码看_embed内部调用SentenceTransformer.encode(..., normalize_embeddingsself.normalize, show_progress_bar...)并用tenacity包裹了指数退避重试最多 3 次当parallel_processTrue时会启动start_multi_process_pool多进程池进行encode_multi_process编码。同时该类继承自MultiModalEmbedding还提供了_get_image_embedding等图片编码能力。2.3 指令Instruction机制query 与 document 为什么不同对 bge、instructor 这类指令型模型直接对 query 与文档使用同一编码路径会显著影响检索效果。HuggingFaceEmbedding通过prompts{query: ..., text: ...}把指令传入SentenceTransformer并在编码时分别使用prompt_namequery与prompt_nametext。指令的自动推导逻辑位于 huggingface/utils.py对BAAI/bge-*系列模型query 自动加上英文指令Represent this question for searching relevant passages: 中文模型模型名含zh则使用中文指令为这个句子生成表示以用于检索相关文章对hku-nlp/instructor-*/hkunlp/instructor-*系列query 使用Represent the question for retrieving supporting documents: 文档文本使用Represent the document for retrieval: 其他模型默认不加指令返回空字符串。因此使用 bge 或 instructor 模型时无需手动编写指令框架会自动为 query 和 document 选择正确的提示模板如需自定义直接传入query_instruction/text_instruction覆盖即可。3. 如何用 Embedding 模型为文本生成向量原文档 FAQ 第 3 问给出了最核心的一行 APItext_embedding embed_model.get_text_embedding(YOUR_TEXT)get_text_embedding是BaseEmbedding的公开方法见 base.py它会依次派发EmbeddingStartEvent→ 检查embeddings_cache是否命中 → 经过rate_limiter限流后调用子类的_get_text_embedding→ 产生EmbeddingEndEvent与回调事件 → 返回List[float]向量。也就是说单条调用之外还自动完成了缓存、限流与可观测性事件埋点。3.1 常用 API 全景在索引构建、查询与评测等场景中最常用的方法如下# 单条文档文本向量入库时使用 emb embed_model.get_text_embedding(document text) # 单条查询向量检索时使用可能附加 query 指令 q_emb embed_model.get_query_embedding(your question) # 批量自动按 embed_batch_size 分批可显示进度条 emb_list embed_model.get_text_embedding_batch( [text 1, text 2, text 3], show_progressTrue ) # 异步版本 emb await embed_model.aget_text_embedding(document text) emb_list await embed_model.aget_text_embedding_batch([text 1, text 2]) # 相似度计算支持 cosine默认/ dot_product / euclidean from llama_index.core.base.embeddings.base import SimilarityMode score embed_model.similarity( emb_a, emb_b, modeSimilarityMode.DEFAULT ) # cosine 相似度其中get_query_embedding与get_text_embedding的区别正是上一节提到的指令差异查询走_get_query_embedding文档走_get_text_embedding二者可能产生不同的向量。批量接口按embed_batch_size切分到达批次上限或遍历到最后一个文本时统一 flush异步批量接口在num_workers 1时还会用run_jobs做并发调度。3.2 相似度与聚合辅助函数BaseEmbedding模块还提供了两个可独立使用的工具函数similarity(embedding1, embedding2, mode)计算两个向量的相似度。SimilarityMode支持三种模式——cosine余弦相似度默认、dot_product点积、euclidean以负欧氏距离作为相似度保持排序方向一致mean_agg(embeddings)对多个向量做逐元素平均聚合配合get_agg_embedding_from_queries可以把多个查询的向量聚合成一个代表向量。3.3 Embedding 缓存与限流从源码可以看到BaseEmbedding支持两个生产级能力缓存设置embeddings_cache须为BaseKVStore实例如 llama-index-core/llama_index/core/storage/kvstore 中的实现后文本会被当作 key 存储于embeddingscollection重复文本直接命中缓存而不再调用模型同步与异步路径均支持限流设置rate_limiter实现自llama_index.core.rate_limiter的BaseRateLimiter后每次调用前自动acquire()异步为async_acquire()防止对第三方 API 或自建服务造成过载。4. 如何在 LlamaIndex 中接入 HuggingFace Text-Embedding InferenceTEI原文档 FAQ 第 4 问指向 Text-Embedding-Inference 示例。TEIText Embeddings Inference是 HuggingFace 提供的高性能文本向量推理服务可以把 embedding 模型封装成独立 HTTP 服务由 LlamaIndex 通过 HTTP 请求消费。4.1 部署 TEI 服务TEI 本身以独立容器/服务方式部署典型做法是 Docker 启动镜像并加载指定模型部署完成后服务默认监听8080端口提供POST /embed接口请求体形如{inputs: [文本列表], truncate: true}。这一步不在 LlamaIndex 代码库内但后续客户端类完全围绕该 HTTP 协议设计。4.2 使用TextEmbeddingsInference客户端类LlamaIndex 提供了对应的客户端封装TextEmbeddingsInference源码位于 llama-index-integrations/embeddings/llama-index-embeddings-text-embeddings-inference/llama_index/embeddings/text_embeddings_inference/base.py安装与用法如下pip install llama-index-embeddings-text-embeddings-inferencefrom llama_index.core import Settings from llama_index.embeddings.text_embeddings_inference import TextEmbeddingsInference embed_model TextEmbeddingsInference( model_nameBAAI/bge-large-en-v1.5, # 模型标识服务端已加载该模型 base_urlhttp://127.0.0.1:8080, # TEI 服务地址 timeout60.0, # 请求超时秒 truncate_textTrue, # 是否截断超长文本 embed_batch_size32, # 批量大小 ) Settings.embed_model embed_model4.3 客户端参数与底层协议从源码可以确认该类的关键参数及其默认值参数默认值说明model_name必填模型标识用于标记当前嵌入模型base_urlhttp://127.0.0.1:8080TEI 服务的基础地址endpoint/embed实际请求路径最终 URL 为base_url endpointtimeout60.0单次请求超时秒truncate_textTrue是否截断超长输入query_instructionNonequery 指令前缀text_instructionNone文档指令前缀auth_tokenNone鉴权 token 或返回 token 的可调用对象传入后请求头携带Authorization: Bearer token底层使用httpx发起POST {base_url}{endpoint}请求体为{inputs: texts, truncate: truncate_text}响应直接解析为向量列表。_get_query_embedding与_get_text_embedding分别把输入交给format_query/format_text处理指令前缀逻辑与上一节相同取自llama_index.utils.huggingface再调用 HTTP 接口。仓库内还提供了对应的单元测试 test_embeddings_text_embeddings_inference.py 用于验证该类的基本行为。4.4 适用场景与注意事项TEI 方案适合模型常驻服务、多客户端共享、需要 GPU 推理的生产场景将模型加载与推理从应用进程中剥离base_url必须是 TEI 服务实际可达的地址若服务部署在远端或启用了鉴权需要同步设置auth_token指令型模型如 bge建议保持query_instruction/text_instruction缺省让框架按模型名自动生成指令若 TEI 返回的向量维度与预期不符应检查model_name与服务端实际加载的模型是否一致。5. 小结与延伸阅读围绕原文档的四个 FAQ本文完整覆盖了 LlamaIndex Embeddings 的四条主线以BaseEmbedding为基类实现自定义模型、以HuggingFaceEmbedding在本地运行 HuggingFace 模型含参数与指令机制、以get_text_embedding/get_query_embedding/ 批量与异步接口直接生成向量以及通过TextEmbeddingsInference消费 TEI HTTP 服务。所有能力均建立在统一的抽象之上切换底层模型不会影响上层索引与检索代码。可进一步阅读的仓库资源基类与工具llama-index-core/llama_index/core/base/embeddings/base.py、llama-index-core/llama_index/core/embeddings/utils.py、llama-index-core/llama_index/core/embeddings/init.py官方示例Custom Embeddings、HuggingFace 本地嵌入、Text-Embedding-Inference集成实现HuggingFaceEmbedding 源码、指令工具、TEI 客户端源码【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LlamaIndex Embeddings 实战指南：自定义模型、本地 HuggingFace 模型与 Text-Embedding-Inference 接入全解
LlamaIndex Embeddings 实战指南自定义模型、本地 HuggingFace 模型与 Text-Embedding-Inference 接入全解【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇技术指南以 LlamaIndex 官方 FAQ 中关于 Embeddings 的四个高频问题为骨架系统讲解如何在 LlamaIndex 中使用自定义/本地 embedding 模型、如何接入本地 HuggingFace 模型、如何直接调用 embedding 模型为文本生成向量以及如何对接 HuggingFace Text-Embedding InferenceTEI推理服务。读完本文你将掌握BaseEmbedding的继承与实现要点、HuggingFaceEmbedding的核心参数与指令instruction机制、get_text_embedding/get_query_embedding/ 批量与异步接口的正确用法以及通过 HTTP 服务完成文本向量化的完整链路。1. 如何在 LlamaIndex 中使用自定义/本地 Embedding 模型在 LlamaIndex 中所有 embedding 能力都统一抽象在BaseEmbedding基类之下。无论底层是 OpenAI、HuggingFace、TEI 还是自研模型上层索引、检索器、查询引擎都只与这一抽象打交道因此实现一个自定义 embedding 类本质上就是继承BaseEmbedding并实现几个核心方法。1.1 认识BaseEmbedding抽象基类BaseEmbedding定义于 llama-index-core/llama_index/core/base/embeddings/base.py并从 llama-index-core/llama_index/core/embeddings/init.py 对外导出。它是一个TransformComponent意味着可以直接作为管线中的 Transform 使用内置以下常用字段model_name模型名称标识默认unknownembed_batch_size批处理大小默认取DEFAULT_EMBED_BATCH_SIZE取值范围(0, 2048]callback_manager回调管理器用于产生EMBEDDING类型的事件num_workers异步调用时的并发 worker 数embeddings_cache嵌入缓存须为BaseKVStore类型命中缓存时直接返回结果避免重复调用rate_limiter限流器用于在调用前按需限流。子类必须实现的抽象方法共有四个它们构成嵌入能力的底层原语_get_query_embedding(query)与_aget_query_embedding(query)同步/异步地对查询进行编码_get_text_embedding(text)与可选_aget_text_embedding(text)同步/异步地对文档文本进行编码。其中异步文本方法在基类中提供了默认实现即直接回退到同步版本批量方法_get_text_embeddings的默认实现则是循环调用单条方法。子类可以根据自身能力如 GPU 批量编码重写这些方法以获得更好的吞吐。1.2 自定义 Embedding 类的完整模板原文档指向的 Custom Embeddings 示例 给出了继承BaseEmbedding的最小实现方式核心代码如下from typing import List, Optional from llama_index.core.embeddings import BaseEmbedding class MyEmbedding(BaseEmbedding): def _get_query_embedding(self, query: str) - List[float]: # 在这里实现 query 的向量化逻辑 return self._get_text_embedding(query) async def _aget_query_embedding(self, query: str) - List[float]: # 异步版本可直接返回同步结果或使用真正的异步实现 return self._get_query_embedding(query) def _get_text_embedding(self, text: str) - List[float]: # 在这里实现文本的向量化逻辑 return [1.0, 0.0, 0.0] # 替换为真实模型输出 def _get_text_embeddings(self, texts: List[str]) - List[List[float]]: # 可选的批量优化默认实现是逐条调用 _get_text_embedding return [self._get_text_embedding(text) for text in texts]关键点返回类型必须是List[float]即一个定长的浮点向量基类中定义了Embedding List[float]类型别名查询与文本的编码路径相互独立很多模型如 bge、instructor要求 query 与 document 使用不同的指令instruction前缀因此_get_query_embedding与_get_text_embedding通常需要区分实现实例化后可以通过Settings.embed_model MyEmbedding(...)把它注册为全局默认嵌入模型也可以直接调用其公开方法使用。1.3 通过字符串快速切换模型resolve_embed_model除了手写子类LlamaIndex 还提供resolve_embed_model位于 llama-index-core/llama_index/core/embeddings/utils.py支持用字符串一键解析出可用的BaseEmbedding实例embed_modeldefault默认使用OpenAIEmbedding需要llama-index-embeddings-openai包与OPENAI_API_KEY测试环境设置了IS_TESTING下会退化为MockEmbeddingembed_modellocal或local:模型名解析为本地HuggingFaceEmbedding模型名缺省时使用默认模型并自动把模型缓存在get_cache_dir()/models目录embed_modelclip:模型名解析为多模态ClipEmbedding传入LangChain的Embeddings对象自动包装为LangchainEmbedding传入None显式禁用嵌入使用MockEmbedding。也就是说使用本地 embedding 模型除了直接实例化HuggingFaceEmbedding之外还可以简单地写Settings.embed_model local:BAAI/bge-small-en由框架完成解析与缓存目录的创建。2. 如何在本机使用 HuggingFace Embedding 模型原文档 FAQ 第 2 问给出了使用本地 HuggingFace 模型的入口Local Embeddings with HuggingFace 示例。其底层实现类是HuggingFaceEmbedding源码位于 llama-index-integrations/embeddings/llama-index-embeddings-huggingface/llama_index/embeddings/huggingface/base.py。2.1 安装与最小用法首先安装集成包pip install llama-index-embeddings-huggingface然后在代码中加载模型并注册为全局嵌入模型from llama_index.core import Settings from llama_index.embeddings.huggingface import HuggingFaceEmbedding # 加载本地/远程 SentenceTransformer 模型 embed_model HuggingFaceEmbedding(model_nameBAAI/bge-small-en) Settings.embed_model embed_model # 单独为一段文本生成向量 embeddings embed_model.get_text_embedding(I want to Embed this text!)HuggingFaceEmbedding内部基于sentence-transformers的SentenceTransformer实现model_name既可以是 HuggingFace Hub 上的模型名也可以是本机磁盘上的模型目录路径——传入本地路径即可做到完全离线使用。默认模型名为BAAI/bge-small-en定义于 huggingface/utils.py 中的DEFAULT_HUGGINGFACE_EMBEDDING_MODEL。2.2 核心参数详解构造函数的主要参数及其默认值如下参数默认值说明model_nameBAAI/bge-small-enHub 模型名或本地模型目录路径max_length512输入序列的最大长度会写入模型配置query_instructionNone附加到 query 前的指令文本缺省时按模型名自动推导text_instructionNone附加到文档文本前的指令文本缺省时按模型名自动推导normalizeTrue是否对输出向量做 L2 归一化embed_batch_sizeDEFAULT_EMBED_BATCH_SIZE单次编码的批量大小cache_folderNone模型缓存目录缺省使用get_cache_dir()trust_remote_codeFalse是否信任 Hub 上的自定义建模代码仅对可信仓库开启device自动推断计算设备如cuda、cpu、mps缺省用infer_torch_device()推断parallel_processFalse是否启用多进程编码池适合海量文本target_devicesNoneparallel_processTrue时使用的目标设备列表show_progress_barFalse编码时是否显示进度条从源码看_embed内部调用SentenceTransformer.encode(..., normalize_embeddingsself.normalize, show_progress_bar...)并用tenacity包裹了指数退避重试最多 3 次当parallel_processTrue时会启动start_multi_process_pool多进程池进行encode_multi_process编码。同时该类继承自MultiModalEmbedding还提供了_get_image_embedding等图片编码能力。2.3 指令Instruction机制query 与 document 为什么不同对 bge、instructor 这类指令型模型直接对 query 与文档使用同一编码路径会显著影响检索效果。HuggingFaceEmbedding通过prompts{query: ..., text: ...}把指令传入SentenceTransformer并在编码时分别使用prompt_namequery与prompt_nametext。指令的自动推导逻辑位于 huggingface/utils.py对BAAI/bge-*系列模型query 自动加上英文指令Represent this question for searching relevant passages: 中文模型模型名含zh则使用中文指令为这个句子生成表示以用于检索相关文章对hku-nlp/instructor-*/hkunlp/instructor-*系列query 使用Represent the question for retrieving supporting documents: 文档文本使用Represent the document for retrieval: 其他模型默认不加指令返回空字符串。因此使用 bge 或 instructor 模型时无需手动编写指令框架会自动为 query 和 document 选择正确的提示模板如需自定义直接传入query_instruction/text_instruction覆盖即可。3. 如何用 Embedding 模型为文本生成向量原文档 FAQ 第 3 问给出了最核心的一行 APItext_embedding embed_model.get_text_embedding(YOUR_TEXT)get_text_embedding是BaseEmbedding的公开方法见 base.py它会依次派发EmbeddingStartEvent→ 检查embeddings_cache是否命中 → 经过rate_limiter限流后调用子类的_get_text_embedding→ 产生EmbeddingEndEvent与回调事件 → 返回List[float]向量。也就是说单条调用之外还自动完成了缓存、限流与可观测性事件埋点。3.1 常用 API 全景在索引构建、查询与评测等场景中最常用的方法如下# 单条文档文本向量入库时使用 emb embed_model.get_text_embedding(document text) # 单条查询向量检索时使用可能附加 query 指令 q_emb embed_model.get_query_embedding(your question) # 批量自动按 embed_batch_size 分批可显示进度条 emb_list embed_model.get_text_embedding_batch( [text 1, text 2, text 3], show_progressTrue ) # 异步版本 emb await embed_model.aget_text_embedding(document text) emb_list await embed_model.aget_text_embedding_batch([text 1, text 2]) # 相似度计算支持 cosine默认/ dot_product / euclidean from llama_index.core.base.embeddings.base import SimilarityMode score embed_model.similarity( emb_a, emb_b, modeSimilarityMode.DEFAULT ) # cosine 相似度其中get_query_embedding与get_text_embedding的区别正是上一节提到的指令差异查询走_get_query_embedding文档走_get_text_embedding二者可能产生不同的向量。批量接口按embed_batch_size切分到达批次上限或遍历到最后一个文本时统一 flush异步批量接口在num_workers 1时还会用run_jobs做并发调度。3.2 相似度与聚合辅助函数BaseEmbedding模块还提供了两个可独立使用的工具函数similarity(embedding1, embedding2, mode)计算两个向量的相似度。SimilarityMode支持三种模式——cosine余弦相似度默认、dot_product点积、euclidean以负欧氏距离作为相似度保持排序方向一致mean_agg(embeddings)对多个向量做逐元素平均聚合配合get_agg_embedding_from_queries可以把多个查询的向量聚合成一个代表向量。3.3 Embedding 缓存与限流从源码可以看到BaseEmbedding支持两个生产级能力缓存设置embeddings_cache须为BaseKVStore实例如 llama-index-core/llama_index/core/storage/kvstore 中的实现后文本会被当作 key 存储于embeddingscollection重复文本直接命中缓存而不再调用模型同步与异步路径均支持限流设置rate_limiter实现自llama_index.core.rate_limiter的BaseRateLimiter后每次调用前自动acquire()异步为async_acquire()防止对第三方 API 或自建服务造成过载。4. 如何在 LlamaIndex 中接入 HuggingFace Text-Embedding InferenceTEI原文档 FAQ 第 4 问指向 Text-Embedding-Inference 示例。TEIText Embeddings Inference是 HuggingFace 提供的高性能文本向量推理服务可以把 embedding 模型封装成独立 HTTP 服务由 LlamaIndex 通过 HTTP 请求消费。4.1 部署 TEI 服务TEI 本身以独立容器/服务方式部署典型做法是 Docker 启动镜像并加载指定模型部署完成后服务默认监听8080端口提供POST /embed接口请求体形如{inputs: [文本列表], truncate: true}。这一步不在 LlamaIndex 代码库内但后续客户端类完全围绕该 HTTP 协议设计。4.2 使用TextEmbeddingsInference客户端类LlamaIndex 提供了对应的客户端封装TextEmbeddingsInference源码位于 llama-index-integrations/embeddings/llama-index-embeddings-text-embeddings-inference/llama_index/embeddings/text_embeddings_inference/base.py安装与用法如下pip install llama-index-embeddings-text-embeddings-inferencefrom llama_index.core import Settings from llama_index.embeddings.text_embeddings_inference import TextEmbeddingsInference embed_model TextEmbeddingsInference( model_nameBAAI/bge-large-en-v1.5, # 模型标识服务端已加载该模型 base_urlhttp://127.0.0.1:8080, # TEI 服务地址 timeout60.0, # 请求超时秒 truncate_textTrue, # 是否截断超长文本 embed_batch_size32, # 批量大小 ) Settings.embed_model embed_model4.3 客户端参数与底层协议从源码可以确认该类的关键参数及其默认值参数默认值说明model_name必填模型标识用于标记当前嵌入模型base_urlhttp://127.0.0.1:8080TEI 服务的基础地址endpoint/embed实际请求路径最终 URL 为base_url endpointtimeout60.0单次请求超时秒truncate_textTrue是否截断超长输入query_instructionNonequery 指令前缀text_instructionNone文档指令前缀auth_tokenNone鉴权 token 或返回 token 的可调用对象传入后请求头携带Authorization: Bearer token底层使用httpx发起POST {base_url}{endpoint}请求体为{inputs: texts, truncate: truncate_text}响应直接解析为向量列表。_get_query_embedding与_get_text_embedding分别把输入交给format_query/format_text处理指令前缀逻辑与上一节相同取自llama_index.utils.huggingface再调用 HTTP 接口。仓库内还提供了对应的单元测试 test_embeddings_text_embeddings_inference.py 用于验证该类的基本行为。4.4 适用场景与注意事项TEI 方案适合模型常驻服务、多客户端共享、需要 GPU 推理的生产场景将模型加载与推理从应用进程中剥离base_url必须是 TEI 服务实际可达的地址若服务部署在远端或启用了鉴权需要同步设置auth_token指令型模型如 bge建议保持query_instruction/text_instruction缺省让框架按模型名自动生成指令若 TEI 返回的向量维度与预期不符应检查model_name与服务端实际加载的模型是否一致。5. 小结与延伸阅读围绕原文档的四个 FAQ本文完整覆盖了 LlamaIndex Embeddings 的四条主线以BaseEmbedding为基类实现自定义模型、以HuggingFaceEmbedding在本地运行 HuggingFace 模型含参数与指令机制、以get_text_embedding/get_query_embedding/ 批量与异步接口直接生成向量以及通过TextEmbeddingsInference消费 TEI HTTP 服务。所有能力均建立在统一的抽象之上切换底层模型不会影响上层索引与检索代码。可进一步阅读的仓库资源基类与工具llama-index-core/llama_index/core/base/embeddings/base.py、llama-index-core/llama_index/core/embeddings/utils.py、llama-index-core/llama_index/core/embeddings/init.py官方示例Custom Embeddings、HuggingFace 本地嵌入、Text-Embedding-Inference集成实现HuggingFaceEmbedding 源码、指令工具、TEI 客户端源码【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考