在Llama Index的向量检索体系中，自定义嵌入是适配不同业务场景、提升检索效果的重要手段。查询嵌入和文本嵌入作为嵌入体系的两大核心组成部分，虽然都基于相同的嵌入模型生成，但在生成逻辑、应用场景和参数配置上存在明显差异。理解这些差异，能帮助开发者更精准地优化检索流程，避免检索结果偏差的问题。
什么是Llama Index自定义嵌入
自定义嵌入指的是开发者不使用Llama Index默认的嵌入模型，而是根据业务需求指定自己训练的嵌入模型、第三方开源嵌入模型，或者调整嵌入模型的参数、添加预处理逻辑的过程。Llama Index提供了灵活的嵌入接口，允许开发者对接各类兼容的嵌入服务，只需要实现对应的嵌入生成方法即可。
自定义嵌入的核心作用是让嵌入向量更贴合业务领域的文本特征，比如针对医疗、法律等垂直领域，使用领域微调后的嵌入模型可以生成更精准的向量表示，提升后续检索的匹配度。
文本嵌入的核心特性
文本嵌入是针对知识库中的原始文档、切片文本生成的向量表示，主要作用是把非结构化的文本转换为计算机可计算的向量形式，存储到向量数据库中，作为检索的候选集合。
文本嵌入的生成逻辑
文本嵌入在生成时，通常会对原始文本做预处理，比如去除无关符号、截断过长文本、添加领域特定的前缀等，保证生成的向量能准确反映文本的核心语义。在Llama Index中，文本嵌入的生成一般发生在文档索引构建阶段，所有入库的文档切片都会先调用嵌入模型生成对应的向量。
文本嵌入的代码示例
以下是自定义文本嵌入的基础配置示例，使用的是HuggingFace的嵌入模型：
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings
# 初始化自定义文本嵌入模型
text_embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-small-zh-v1.5",
max_length=512, # 文本嵌入的最大处理长度
embed_batch_size=32 # 批量处理文本的数量
)
# 将文本嵌入模型设置为全局默认嵌入模型，用于生成文档的向量
Settings.embed_model = text_embed_model
查询嵌入的核心特性
查询嵌入是针对用户输入的检索问题生成的向量表示，主要作用是将用户的查询需求转换为和文本嵌入同维度的向量，方便在向量数据库中做相似度匹配，找到最相关的文档切片。
查询嵌入的生成逻辑
查询嵌入的生成逻辑和文本嵌入有本质区别，因为用户的查询通常是短文本、口语化表达，和知识库中的正式文档文本分布不同。因此查询嵌入通常会添加特定的查询前缀，或者对查询文本做特殊的预处理，比如保留疑问词、调整语句结构，让生成的向量更贴合检索场景的需求。
查询嵌入的代码示例
以下是自定义查询嵌入的配置示例，和文本嵌入使用同一个基础模型，但调整了生成逻辑：
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings
class CustomQueryEmbedding(HuggingFaceEmbedding):
def get_query_embedding(self, query: str) -> list:
# 给查询文本添加前缀，适配模型的查询嵌入要求
processed_query = f"为这个句子生成表示以用于检索相关文章：{query}"
return super().get_query_embedding(processed_query)
# 初始化自定义查询嵌入模型
query_embed_model = CustomQueryEmbedding(
model_name="BAAI/bge-small-zh-v1.5",
max_length=512
)
# 设置查询嵌入模型，用于生成用户查询的向量
Settings.embed_model = query_embed_model
查询嵌入与文本嵌入的核心差异对比
二者虽然基于同一个嵌入模型生成，但在多个维度存在明显不同，具体差异如下表所示：
| 对比维度 | 文本嵌入 | 查询嵌入 |
|---|---|---|
| 作用对象 | 知识库中的文档切片文本 | 用户输入的检索查询文本 |
| 生成阶段 | 索引构建阶段，一次性生成后存储 | 查询检索阶段，每次用户发起查询时实时生成 |
| 预处理逻辑 | 侧重保留文本核心语义，去除无关内容 | 侧重适配检索场景，通常会添加查询前缀 |
| 更新频率 | 文档更新或新增时才重新生成 | 每次查询都会重新生成 |
| 核心目标 | 准确表示文档的语义内容 | 准确匹配用户查询的检索意图 |
自定义嵌入时的注意事项
- 文本嵌入和查询嵌入必须使用同一个嵌入模型或者同系列的兼容模型，否则生成的向量维度不同，无法做相似度匹配。
- 如果使用的嵌入模型有官方的查询前缀要求，一定要在查询嵌入生成时添加对应的前缀，否则会导致检索效果大幅下降。
- 文本嵌入的批量处理参数需要根据硬件资源调整，避免内存溢出；查询嵌入因为是实时生成，要控制单次查询的处理耗时，避免影响用户体验。
- 可以通过
Settings.embed_model同时设置文本和查询嵌入，也可以通过自定义类分别重写get_text_embedding和get_query_embedding方法，实现更灵活的逻辑。
实际场景中的配置示例
以下是一个完整的自定义嵌入配置示例，同时适配文本嵌入和查询嵌入的不同需求：
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings, VectorStoreIndex, SimpleDirectoryReader
class DomainEmbedding(HuggingFaceEmbedding):
def get_text_embedding(self, text: str) -> list:
# 文本嵌入预处理：去除多余换行，截断过长内容
processed_text = text.replace("n", " ").strip()[:1024]
return super().get_text_embedding(processed_text)
def get_query_embedding(self, query: str) -> list:
# 查询嵌入预处理：添加模型要求的查询前缀
processed_query = f"为这个句子生成表示以用于检索相关文章：{query}"
return super().get_query_embedding(processed_query)
# 初始化领域自定义嵌入模型
domain_embed_model = DomainEmbedding(
model_name="BAAI/bge-small-zh-v1.5",
max_length=512,
embed_batch_size=16
)
# 设置全局嵌入模型
Settings.embed_model = domain_embed_model
# 加载文档并构建索引，此时会自动用文本嵌入生成文档向量
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
# 发起查询，此时会自动用查询嵌入生成查询向量
query_engine = index.as_query_engine()
response = query_engine.query("Llama Index自定义嵌入怎么配置")
print(response)
通过上述配置，文本嵌入和查询嵌入会分别按照对应的逻辑生成向量，既保证了文档向量的语义准确性，也保证了查询向量能精准匹配用户的检索意图，最终提升整个检索系统的效果。
Llama_Index自定义嵌入查询嵌入文本嵌入向量检索修改时间：2026-06-25 12:45:37