LlamaIndex 检索配置怎么让向量索引真正返回相关文档
LlamaIndex 检索配置的核心是让索引构建和查询参数匹配你的文档和问题类型。
如果检索结果不相关，最常见的原因不是大模型不行，而是嵌入模型没设置对、切分粒度太粗，或者查询时 top_k 太小。
下面按实际配置顺序说明怎么排查和调整。
先确认嵌入模型和文档切分是否匹配
LlamaIndex 默认使用 OpenAI 的嵌入模型，如果你没有配置 API Key 或者想用本地模型，需要显式设置。
嵌入模型决定文档和问题被转成向量的方式，同一个模型必须同时用于建索引和查询，否则向量空间不一致，检索基本失效。
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings
Settings.embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-small-zh-v1.5"
)文档切分方面，默认 SentenceSplitter 的 chunk_size 是 1024，对中文技术文档可能偏大。
切分过大时一个节点里混入多个主题，相似度计算会被稀释；
切分过小又容易丢上下文。
建议先按 256 到 512 调整，观察召回内容是否完整。
from llama_index.core.node_parser import SentenceSplitter
Settings.node_parser = SentenceSplitter(
chunk_size=512,
chunk_overlap=50
)注意：修改切分参数后必须重建索引，旧索引不会自动按新参数重新切分。
建索引和查询时的检索参数
建索引时确认文档已经正确加载。
用 SimpleDirectoryReader 读取本地文件后，调用 VectorStoreIndex.from_documents 会自动完成切分和嵌入。
如果文档量大，建议先小批量测试，确认召回正常再全量构建。
查询阶段最常调的是 similarity_top_k，它控制返回多少个候选节点。
默认值通常偏小，对内容分散的文档集可以适当提高到 5 到 10。
但不要盲目调大，候选过多会引入噪声，也会增加后续大模型的处理成本。
query_engine = index.as_query_engine(
similarity_top_k=5
)
response = query_engine.query("如何配置检索参数")
print(response)如果需要查看具体召回了哪些节点，用检索器单独查询，而不是直接看最终回答。
最终回答经过大模型改写，无法判断是检索错了还是生成错了。
retriever = index.as_retriever(similarity_top_k=5)
nodes = retriever.retrieve("如何配置检索参数")
for node in nodes:
print(node.score, node.text[:200])node.score 是相似度分数，分数普遍很低说明嵌入模型或切分可能有问题；
分数高但内容不相关，则要检查文档本身是否包含答案。
容易踩的三个配置坑
第一，建索引和查询用了不同嵌入模型。 比如建索引时用了默认 OpenAI 模型，查询时切换成本地模型，向量维度或语义空间不一致，检索结果会完全随机。
统一在 Settings 里设置一次，避免多处覆盖。
第二，中文文档用了英文嵌入模型。 英文模型对中文语义区分能力弱，表现为召回内容沾边但不精准。
中文场景优先选支持中文的嵌入模型，并在小样本上对比召回效果。
第三，忽略元数据过滤。 如果文档来自多个来源，可以在建索引时写入 metadata，查询时用 MetadataFilters 限定范围，减少无关文档干扰。
from llama_index.core.vector_stores import MetadataFilters, MetadataFilter
filters = MetadataFilters(
filters=[MetadataFilter(key="source", value="manual")]
)
retriever = index.as_retriever(
similarity_top_k=5,
filters=filters
)怎么验证检索配置是否生效
验证分两步。
先看检索器返回的节点文本是否包含问题答案，再看最终回答是否引用了这些节点。
如果节点文本正确但回答不对，问题在生成阶段；
如果节点文本就不对，继续调整嵌入模型、切分大小或 similarity_top_k。
建议准备 5 到 10 个有明确答案的问题做小批量测试，记录每个问题的召回文本和分数。
调整参数后重新跑同一组问题，对比召回是否改善。
不要只看一个问题的结果就下结论，单个问题的偶然性很大。
另外，修改 chunk_size 后重建索引需要时间，测试阶段可以用少量文档先建临时索引，确认参数后再处理全量数据。
常见疑问
检索分数多少算正常？ 没有统一阈值，不同嵌入模型的分数分布不同。
重点看同一模型下相关文档和不相关文档的分数差距，差距明显比绝对数值更有参考意义。
必须用向量检索吗？ 如果问题包含明确关键词或编号，可以配合关键词检索做混合检索，LlamaIndex 支持组合多个检索器。
纯向量检索对精确匹配类问题不一定最优。
改了参数要不要重建索引？ 嵌入模型和切分参数变了必须重建；
只改 similarity_top_k 不需要重建，它只在查询时生效。
LlamaIndex 检索配置没有一组通用最优参数，关键是让嵌入模型、切分粒度和召回数量与你的文档特点匹配，并用检索器返回的实际节点做验证，而不是只看最终回答。
