llamaindex rag

你已经有一堆 PDF、Markdown 或者 Confluence 导出的文档，想让模型基于这些内容回答问题，但自己写切分、向量化、召回、拼提示词太琐碎。LlamaIndex 正好是干这件事的框架。这篇不讲概念史，只给一条从装包到跑通问答的最小路径，顺带说清哪一步最容易卡住、卡住时先看哪里。

你手上有一堆 PDF、Markdown 或者从 Confluence 导出的文档，想让模型基于这些内容回答问题。自己写切分、向量化、召回、拼提示词，光把链路串起来就够琐碎。LlamaIndex 就是干这件事的框架，它把加载、切分、索引、检索、拼答这几步都做成可替换的积木。

这篇不聊概念史，只给一条从装包到跑通问答的最小路径。每一步都说清做什么、怎么验证，以及卡住时先看哪里。你不需要一次把它用好，先跑通一条能回答的链路，再回头调效果。

先把环境和模型接上

装主包只是第一步。LlamaIndex 很多模型集成拆成独立子包，主包装完并不等于能调你想用的那个厂商。先想清楚嵌入和生成分别用谁，再对应装集成包。装完别急着写业务，先各跑一次最小请求。

• 嵌入模型和大模型是两条独立通道，可以来自不同厂商，接口地址和 Key 分别配
• 先单独发一次嵌入请求，确认向量能返回，再单独发一次生成请求，确认文本能返回
• 两条都通了再往下走，否则后面报错时你分不清断在哪条链路
• 走中转网关而不是官方地址时，先确认 Base URL 和协议兼容，不要在框架层反复改代码

灌数据：加载与切分

各类格式都有对应的读取器，但扫描件和纯图片 PDF 大概率读不出内容，得先做 OCR 清洗再进流程。切分参数直接决定召回质量：块太小会把一句话截断，块太大则一次召回塞进太多无关内容。建议先按文档结构切，再考虑固定长度。

元数据一开始就要存，来源文件、章节、页码都留着，后面引用出处、做过滤全靠它。后补元数据比一开始存下来痛苦得多，因为索引已经建好了。切完先人工抽几条看看块边界，花十分钟，能省掉后面几小时的调参。

建索引与检索

最简做法是把切好的块交给向量索引，框架替你调嵌入并落库。数据量小可以先存本地，量大了再换独立向量库。检索数量这个参数值得手动调：召回条数太多会把上下文撑满、成本上去，太少又容易漏掉关键段落。想更准可以加一层重排，把初筛结果重新排序再交给模型，代价是多一次调用和一点延迟。

• 纯语义检索对专有名词和编号类查询不敏感，命中率差时可以叠加关键词检索做混合
• 重排能提升准确率，但要接受额外调用和延迟，先确认业务能忍
• 每次改检索参数都记一笔，不然回溯效果时很难复现
• 数据量到几十万块再考虑独立向量库，小规模本地存储够用

拼回答与跑通第一条查询

默认问答引擎会把召回到的片段拼进提示词。你要做的是明确告诉模型：只能依据给定资料回答，没有就说没有。把来源一起返回，方便自己核对答案，这也是判断「检索坏了」还是「生成坏了」的关键线索。

1. 准备测试问题挑三到五个你已知答案的问题，范围覆盖简单事实、跨段落归纳、资料里没有的问题三类。
2. 跑第一条查询观察返回的答案和来源片段，来源里有没有正确内容，决定下一步排查方向。
3. 判定故障层来源里有正确内容但答案错，是生成问题；来源里根本没有，是检索问题。
4. 确认没资料时的表现故意问一个资料外的问题，看它是否会老实说不知道，而不是编答案。

先跑通一条能回答的链路，再谈换模型、加缓存、做多轮对话。

报错与效果差的排查顺序

报错别乱试，按固定顺序走最省时间：先查连通与鉴权，再查文档有没有真的被读进来（块数量是不是零），然后查召回内容是否相关，最后才怀疑模型能力。效果差先调切分和召回数量，这两项改动成本最低、收益最明显，换模型通常是最后手段。

成本或延迟异常，多半是召回条数设太大或重复建索引。上线前把并发、超时和重试策略过一遍，本地跑得通不代表压量之后还稳。想知道当前主流模型和中转站的实际报价与可用性，到站内页面核对当时的数字，别凭记忆拍板。