最小实现:300 行跑通 RAG
这一篇逐段拆 examples/rag_demo.py。它的目标不是生产可用,而是让你亲眼看到 RAG 的每个关键动作,并且能用测试证明它按预期工作。
1、设计边界
这个 Demo 刻意做了减法:
| 有 | 没有 |
|---|---|
Markdown 读取与按行切块 | PDF/Word/OCR 解析 |
调用云端 API:硅基流动做嵌入、OpenAI GPT 做对话 | 重试、限流、批量并发、成本控制 |
| 余弦相似度全量扫描 | HNSW/IVF 等 ANN 索引 |
JSON 文件索引 | 向量数据库、增量更新 |
| 阈值过滤、证据编号、拒答 | 重排、混合检索 |
命令行 ingest / ask | HTTP 服务、流式输出、多租户 |
| 假客户端单元测试 | 端到端模型质量评估 |
这些“没有”正是后续章节要补的。先把最小闭环跑通,再逐层替换,比一上来堆框架更容易理解。
2、运行方式
准备两个账号的 API Key,通过环境变量传入。Key 只放在终端里,不要写进代码、索引文件或提交记录:
export SILICONFLOW_API_KEY=... # 嵌入:硅基流动
export OPENAI_API_KEY=... # 对话:OpenAI默认嵌入模型是
BAAI/bge-m3(硅基流动),默认对话模型是gpt-6.1-terra(OpenAI)。账号里没有或想换模型时,用--embed-model、--chat-model指定。自建网关或代理可用SILICONFLOW_BASE_URL、OPENAI_BASE_URL覆盖默认地址。
然后:
cd docs/articles/rag/examples
# 建索引(只用到 SILICONFLOW_API_KEY)
python3 rag_demo.py ingest data index.json
# 只检索,不调用对话模型
python3 rag_demo.py ask index.json "午餐补贴是多少" --retrieval-only
# 完整问答(两个 Key 都会用到)
python3 rag_demo.py ask index.json "午餐补贴是多少"
# 跑测试(不需要 API Key)
python3 -m unittest discover -s tests -v示例语料是两份虚构制度:data/hr-policy.md 和 data/security-policy.md。
2.1 先看入口:程序不是从第一个函数开始执行
函数定义不等于调用。直接运行文件时,末尾触发入口;被测试导入时不会启动命令行:
if __name__ == "__main__":
main()文字版流程(方便复制与辅助阅读)
开始 → main() 解析参数 → 创建客户端 → 判断子命令。ingest 分支建索引后打印片段数;ask 分支先加载索引,再调用 ask,最后打印 JSON。两条正常路径汇合后结束。
main() 负责解析、分派和打印;客户端构造只存配置,不发网络请求。Demo 没有后台任务,执行完即退出。
一条命令,拆成五块
python3 rag_demo.py --timeout 90 ask index.json "午餐补贴是多少" --top-k 5--timeout 90全局参数timeout = 90.0ask子命令command = askindex.json第 1 个位置参数index = index.json"午餐补贴是多少"第 2 个位置参数question = 午餐补贴是多少--top-k 5ask 的选项top_k = 5记住三条解析规则:
- 位置按顺序:先索引、后问题;交换后仍可能解析成功,却在打开索引文件时报错。
add_argument("index")的名字是结果字段,不是需要输入的关键字。 - 选项按名字:
--top-k对应args.top_k;--retrieval-only出现就为真,不带true。子命令各有参数表,ingest不认识--top-k。 - 当前解析器要求全局参数在子命令前:
--timeout放到ask后会被拒绝;这是本脚本的定义,不是所有 CLI 的规则。
分派之后发生什么
| 子命令 | 做什么 | 终端输出 |
|---|---|---|
ingest data index.json | 切块 → 嵌入 → 校验维度 → 原子写入 | 已写入 N 个片段 |
ask index.json "问题" | 先 load_index(),再 ask() | 格式化的回答 / 证据 JSON,不写文件 |
--retrieval-only 仍调用嵌入服务,只跳过对话服务;不是离线模式。缺 Key 在实际请求前检查。异常、文件错误会中断并显示 traceback,不是“证据不足”的拒答。解析器的类型转换也不代替正数、有限分数等业务校验。
所有参数一览
| 参数 | 默认值 / 作用 | 影响哪个动作 |
|---|---|---|
--timeout | 60 秒 | 单次请求超时;全局参数应放在子命令前 |
SILICONFLOW_API_KEY、OPENAI_API_KEY | 环境变量,必填 | 分别用于嵌入与对话;缺失时在发请求前报错 |
ingest docs index | 文档目录、索引文件路径,均必填 | 从目录读资料并替换索引 |
ask index question | 索引路径、问题,均必填 | 读取已有索引并提问 |
--embed-model | BAAI/bge-m3 | 两个子命令都支持;文档向量与问题向量应来自同一模型 |
--chat-model | gpt-6.1-terra | 仅 ask,决定谁根据证据写答案;可换成账号里可用的其他 GPT |
--top-k | 3 | 先取最相似的几个候选 |
--min-score | 0.2 | 再过滤掉分数低的候选 |
--retrieval-only | 默认关闭;出现即为真 | 只返回证据,不调用对话接口 |
例如:python3 rag_demo.py --timeout 60 ask index.json "午餐补贴是多少" --top-k 5。这里 --timeout 放在 ask 前,--top-k 放在后面。
2.2 建索引的真实调用顺序
文字版流程(方便复制与辅助阅读)
进入 ingest,make_chunks 调用 read_markdown 切块。只要还有未嵌入的块,就取下一个块调用 embed,再回到循环判断。全部完成后检查维度;不一致抛异常,一致则原子写入并返回块数。
一条 ingest 命令只走这条线。假设目录产生了 N 个块,它会串行发出 N 次嵌入请求、0 次对话请求;全部向量准备好且维度一致后才写文件。没有做批量请求、并发或失败重试。
2.3 问答的真实调用顺序与提前返回
文字版流程(方便复制与辅助阅读)
先 load_index,再进入 ask 并调用 retrieve:问题嵌入、余弦算分、排序取 top_k。过滤并编号后,先判断 retrieval_only,为真直接返回 answer=null;否则判断证据是否为空,空则固定拒答,非空则组装 Prompt 调用 chat。三条正常返回路径汇合到 main 打印结果。
这里尤其要注意判断顺序:
--retrieval-only仍需要嵌入模型服务,只是跳过对话模型。即使索引为空,retrieve()也会先把问题转成向量。- 先判断
retrieval_only,再判断证据是否为空。因此“只检索 + 无证据”返回answer: null;普通问答无证据才返回固定拒答文字。 - 有证据时只发出一次
/chat/completions请求,stream=False,等待完整回答后再打印;没有流式输出。 - 调用报错不等于“没有证据”。报错会中断程序,而不是进入固定拒答分支。
2.4 函数索引:每个函数负责什么
| 函数 / 类型 | 输入 → 输出 | 谁调用它 | 是否访问外部资源 |
|---|---|---|---|
main() | 命令行参数 → 打印结果 | 文件入口 | 编排文件与网络操作 |
ApiError | 自定义异常类型,无普通返回值 | HTTP 适配层抛出 | 不访问 |
OpenAICompatible.__init__() | 超时 → 读取两个端点的地址与 Key | main() | 不发请求 |
OpenAICompatible._post() | 端点地址、Key、接口路径、请求字典 → 响应字典 | embed()、chat() | HTTP |
OpenAICompatible.embed() | 模型名、文本 → 浮点向量列表 | ingest()、retrieve() | /embeddings |
OpenAICompatible.chat() | 模型名、消息列表 → 回答字符串 | ask() 的有证据分支 | /chat/completions |
read_markdown() | 文件路径 → (标题, 正文行) 列表 | make_chunks() | 读 Markdown |
make_chunks() | 目录、字符上限 → 块字典列表 | ingest() | 遍历与读取文件 |
cosine() | 两个等长向量 → 相似度 | retrieve() | 纯计算 |
atomic_write() | 目标路径、可 JSON 序列化数据 → None | ingest() | 写临时文件、替换索引 |
ingest() | 客户端、文档目录、索引路径、嵌入模型 → 块数 | main() | 文件 + 嵌入请求 |
load_index() | 索引路径、嵌入模型名 → 索引字典 | main() 的 ask 分支 | 读 JSON |
retrieve() | 客户端、索引、问题、模型、top_k → 命中列表 | ask() | 问题嵌入请求 |
ask() | 检索参数、阈值、模式、对话模型 → answer/evidence 字典 | main() | 检索 + 可选对话请求 |
接下来逐个解释这些函数,阅读时把“输入是什么、返回什么、有没有副作用”带进去。
3、第一层:把 HTTP 调用关进一个类
class OpenAICompatible:
def _post(self, base_url, api_key, key_name, path, payload):
if not api_key:
raise ApiError(f"缺少环境变量 {key_name}:请先 export {key_name}=...")
request = urllib.request.Request(
base_url + path,
data=json.dumps(payload).encode(),
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {api_key}",
},
)
try:
with urllib.request.urlopen(request, timeout=self.timeout) as response:
data = json.loads(response.read())
except urllib.error.HTTPError as exc:
detail = exc.read().decode("utf-8", "replace")[:200]
raise ApiError(f"{base_url}{path} 返回 HTTP {exc.code}:{detail}") from exc
except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
raise ApiError(f"{base_url}{path} 请求失败:{exc}") from exc
if not isinstance(data, dict):
raise ApiError(f"{base_url}{path} 返回格式错误:预期 JSON 对象")
return data这段代码有三个值得学的习惯:
- 所有外部调用集中在一个边界。硅基流动和
OpenAI都提供 OpenAI 兼容协议,所以同一段代码可以服务两个端点。以后换模型、换网关、加重试,只改这里。 - 把底层异常翻译成自己的异常。
HTTPError单独处理,能保留401(Key 无效)、429(限流)等状态码和响应正文;URLError、超时、JSON解析失败统一视为服务不可用。上层不需要知道urllib的细节。 - 校验返回结构。不能假设服务一定返回
data[0].embedding或choices[0].message.content,否则错误会以KeyError的形式散落到业务代码里。
embed 和 chat 都只做“取字段 + 类型检查”:
def embed(self, model, text):
result = self._post(self.embed_url, self.embed_key, "SILICONFLOW_API_KEY",
"/embeddings", {"model": model, "input": text})
data = result.get("data")
if not isinstance(data, list) or not data or not isinstance(data[0], dict):
raise ApiError("/embeddings 缺少 data[0].embedding")
vector = data[0].get("embedding")
if not isinstance(vector, list) or not vector:
raise ApiError("/embeddings 缺少 data[0].embedding")
return [float(x) for x in vector]注意 /embeddings 返回的是“批量输入的向量列表”,即使只传一个字符串,也要从 data[0].embedding 取第一条。
3.1 __init__():只记配置,不做网络连接
__init__() 从环境变量读取两套配置:SILICONFLOW_BASE_URL、SILICONFLOW_API_KEY 用于嵌入,OPENAI_BASE_URL、OPENAI_API_KEY 用于对话;没有设置地址时使用代码里的默认值。rstrip("/") 去掉地址尾部的 /,避免后续拼出双斜线;self.timeout 保存每次请求的超时秒数。self 指当前客户端实例,之后 embed() 和 chat() 共用这些属性。
Key 只保存在进程内存里,不要打印、写进索引或提交到仓库。构造实例不会发请求;缺 Key 也不会立刻报错,直到 _post() 真正要发请求时才检查。
3.2 _post():统一发送 JSON 并处理响应
payload 字典经过 json.dumps(...).encode() 变为请求字节;Request 在带有 data 时默认使用 POST,Content-Type 声明发送的是 JSON,Authorization: Bearer <key> 用于鉴权。urlopen(..., timeout=...) 执行请求,with 负责关闭响应,json.loads(response.read()) 将响应解析为 Python 对象。
代码把网络错误、超时、JSON 解析失败翻译成 ApiError,并检查最外层是否为字典。它没有重试,也没有捕获所有可能的异常。ApiError(RuntimeError) 本身没有额外逻辑,只是给调用方一个可识别的异常类型;401、429 等状态码会作为错误信息的一部分保留下来。
3.3 embed():把一段文本换成一组数字
比如硅基流动返回 {"data": [{"embedding": [1, 2]}]},函数取 data[0].embedding 后返回 [1.0, 2.0]。float(x) 做数值转换;无法转换会抛出异常。这里已拒绝空向量,但未完整校验非有限值或返回向量是否来自正确模型,因此仍是教学边界,不是完备的响应校验器。
3.4 chat():把消息列表换成完整回答
def chat(self, model, messages):
result = self._post(self.chat_url, self.chat_key, "OPENAI_API_KEY",
"/chat/completions", {
"model": model, "messages": messages, "stream": False
})
try:
return str(result["choices"][0]["message"]["content"])
except (KeyError, IndexError, TypeError) as exc:
raise ApiError("/chat/completions 缺少 choices[0].message.content") from exc输入 messages 是形如 [{"role": "user", "content": "提示词与问题"}] 的列表;stream=False 要求服务一次返回结果。函数取 choices[0].message.content 并用 str() 转为字符串,缺字段或结构错误时抛 ApiError。这里并没有严格验证 content 原本就是字符串,也不验证回答的引用或事实是否正确。
4、第二层:读取与切块
def read_markdown(path: Path):
text = path.read_text(encoding="utf-8")
heading = path.stem
chunks = []
for line in text.splitlines():
if line.startswith("#"):
heading = line.lstrip("#").strip() or heading
elif line.strip():
chunks.append((heading, line.strip()))
return chunks它做了一件很重要的事:给每行文字记住它属于哪个标题。这个 heading 是最粗糙的标题上下文,后面会拼进证据,帮助模型理解来源。
逐步看返回值怎么产生:
path.read_text()读出整个文件;文件不存在、权限不足或不是 UTF-8 时抛出异常。path.stem是不带扩展名的文件名,作为没有标题时的默认标题。splitlines()按行遍历:行首为#就更新当前标题;否则非空行就存入(heading, line.strip())。- 返回元组列表,标题行本身不会成为一个正文块。
例如输入 # 午餐补贴 和下一行 每餐 30 元。,返回 [("午餐补贴", "每餐 30 元。")]。它不是完整 Markdown 解析器:代码块里行首的 # 也会被误认为标题。
但它也很粗糙:
- 只按行切,标题和正文分离;
- 列表项、代码块、表格会被拆散;
- 没有页码和字符偏移;
- 标题层级只保留最后一层,没有
["差旅", "住宿标准"]这样的路径。
生产环境要用结构化解析和递归/语义切分,见 04 数据摄取。
def make_chunks(root: Path, max_chars=500):
result = []
for path in sorted(root.rglob("*.md")):
for heading, line in read_markdown(path):
if len(line) <= max_chars:
pieces = [line]
else:
pieces = [line[i : i + max_chars] for i in range(0, len(line), max_chars)]
for piece in pieces:
result.append({"source": str(path.relative_to(root)), "heading": heading, "text": piece})
for i, item in enumerate(result, 1):
item["id"] = f"C{i:04d}"
return resultmake_chunks() 在 read_markdown() 的结果上继续加工:
root.rglob("*.md")递归找 Markdown,sorted()固定文件顺序,避免同一目录每次读取顺序不一致。- 每条正文不超过 500 字符就直接保留;超过则按
[0:500]、[500:1000]等区间硬切,没有重叠窗口,也不会跨行合并短句。 path.relative_to(root)保存相对来源,而不是本机绝对路径。enumerate(result, 1)从 1 开始统一编号,f"C{i:04d}"中04d表示整数至少四位,不足补零。
输出中的一个块形如:{"source": "hr-policy.md", "heading": "午餐补贴", "text": "每餐 30 元。", "id": "C0003"}。
max_chars=500 是字符数,不是 token 数,二者没有固定换算比例,生产环境要按模型 tokenizer 计算。目录不存在或没有匹配文件时可能直接得到空列表,代码没有额外的“目录必须存在且非空”检查。
id 用 C0001 这种顺序号,重建索引后会变化。生产环境应该用“文档 ID + 版本 + 块序号”或内容哈希,保证稳定可追踪。
5、第三层:余弦相似度
def cosine(a, b):
if len(a) != len(b):
raise ValueError("向量维度不一致,请用同一 embedding 模型重建索引")
denom = math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(x * x for x in b))
return sum(x * y for x, y in zip(a, b)) / denom if denom else 0.0cosine(a, b) 输入两个向量列表,输出一个相似度数值。代码先检查维度,再计算:对应坐标乘积之和 ÷ 两个向量长度的乘积。
sum(x * y for x, y in zip(a, b))是点积。sqrt(sum(x * x ...))是向量长度。- 任一向量为零向量时,
denom为 0,函数约定返回0.0,避免除零。
余弦相似度衡量两个向量的方向接近程度,非零有限向量的理论值在 [-1, 1]。嵌入向量的坐标可以为负,相似度也不是概率。 例如 cosine([1, 0], [2, 0])=1,cosine([1, 0], [0, 1])=0;“分数 0.8”不表示“有 80% 概率能回答”。
维度检查不是可有可无的:不同嵌入模型的维度通常不同(例如 384、768、1024、1536、2560、4096),混用会直接报错或得到无意义结果。生产索引必须记录模型名和维度。
检索会对所有 n 个块各调用一次 cosine(),单次计算遍历 d 个坐标,算分约为 O(n × d),后面还需要排序。数据量较小时适合教学,规模扩大后要考虑 ANN 索引,见 05 向量化与索引。
6、第四层:建索引与原子写入
def ingest(client, docs_dir, index_path, embed_model):
chunks = make_chunks(Path(docs_dir))
vectors = [client.embed(embed_model, item["text"]) for item in chunks]
dimension = len(vectors[0]) if vectors else 0
if any(len(vector) != dimension for vector in vectors):
raise ValueError("embedding 返回了不同维度")
atomic_write(Path(index_path), {
"version": 1,
"embedding_model": embed_model,
"dimension": dimension,
"chunks": [{**item, "vector": vector} for item, vector in zip(chunks, vectors)],
})
return len(chunks)ingest() 是建索引的编排函数,它自己不解析 Markdown,也不实现嵌入模型,而是调用前面的工具函数:
make_chunks()返回块列表。- 列表推导式按块依次调用
client.embed(),返回与块列表位置一一对应的向量列表。 - 取第一条向量长度作为
dimension;空列表则记为 0。任何向量长度不同都先报错,不写索引。 zip(chunks, vectors)将每块与对应向量配对;{**item, "vector": vector}是复制块字典,再增加vector字段,不会原地修改原块。atomic_write()写入完整索引;成功后返回块数,交给main()打印。
它只嵌入 item["text"],没有把标题一起嵌入。标题会保存在索引里,稍后作为提示词中的来源上下文。
索引是一个自描述的 JSON(下面用 3 维假向量展示结构,并非真实模型输出):
{
"version": 1,
"embedding_model": "BAAI/bge-m3",
"dimension": 3,
"chunks": [
{
"source": "hr-policy.md",
"heading": "午餐补贴",
"text": "公司为工作日加班的员工提供每餐 30 元午餐补贴。",
"id": "C0003",
"vector": [0.013, -0.027, 0.041]
}
]
}embedding_model 和 dimension 是索引的一部分,不是元数据装饰。没有它们,就无法判断索引能不能被当前查询使用。
atomic_write 解决的是“写到一半进程挂了”的问题:
def atomic_write(path: Path, value):
path.parent.mkdir(parents=True, exist_ok=True)
fd, temp = tempfile.mkstemp(prefix=path.name + ".", dir=path.parent)
try:
with os.fdopen(fd, "w", encoding="utf-8") as handle:
json.dump(value, handle, ensure_ascii=False, indent=2)
handle.write("\n")
os.replace(temp, path)
finally:
if os.path.exists(temp):
os.unlink(temp)atomic_write() 没有业务返回值,成功时返回 None;它的结果是磁盘上的索引发生变化:
mkdir(..., exist_ok=True)确保目标父目录存在。mkstemp(..., dir=path.parent)在同一目录创建临时文件,返回文件描述符和临时路径,避免跨文件系统替换。os.fdopen()把文件描述符包装成文本句柄;json.dump()写入数据,退出with时关闭文件。- 只有完整写入并关闭后,才用
os.replace(temp, path)原子替换目标。若目标已存在,它会被覆盖,这是全量重建,不是向旧索引追加。 finally在正常退出或异常时检查临时文件是否仍存在,存在就清理。进程被强制终止时不保证执行清理。
在正常的本地文件系统原子替换语义下,读取者看到的是旧文件或新文件,不是写到一半的 JSON。代码没有调用 fsync(),所以“替换原子”不等于“断电后一定持久化成功”;也没有并发写锁,多个建索引进程可能最后写入者覆盖前者。
生产环境同理:新索引写到新版本,校验通过后原子切换别名;失败则保留旧版本。这就是“索引版本切换”的雏形。
7、第五层:加载时拒绝模型不匹配
def load_index(path, embed_model):
data = json.loads(Path(path).read_text(encoding="utf-8"))
if data.get("embedding_model") != embed_model:
raise ValueError(f"索引模型是 {data.get('embedding_model')},当前是 {embed_model};请重新 ingest")
return dataload_index() 在 ask() 外面执行:先读文件、解析 JSON,再比较保存的模型名与本次指定的模型名;匹配才返回整个索引字典。文件不存在、JSON 损坏或模型名不符都会向外抛异常,当前 main() 没有捕获并转换成友好 JSON 错误。
这是一个经常被省略、但线上非常关键的检查。用模型 A 建的索引,拿模型 B 的查询向量检索,即使维度相同也可能静默得到无意义的分数;维度不同则会在 cosine() 中报错。
当前函数只比较模型名字,不会完整验证 JSON 字段结构、version、声明的 dimension 或模型权重是否已更新。同名模型重新拉取后也可能变化,生产环境还需要更严格的版本与结构校验。
进一步可以检查 dimension、模型版本、归一化方式、查询指令前缀。只要影响向量空间的配置变了,就应该视为索引不兼容。
8、第六层:召回
def retrieve(client, index, question, embed_model, top_k=3):
query = client.embed(embed_model, question)
ranked = sorted(
((cosine(query, item["vector"]), item) for item in index["chunks"]),
reverse=True,
key=lambda x: x[0],
)
return [{**item, "score": score} for score, item in ranked[:top_k]]retrieve() 的输入是已经加载的索引字典,不是文件路径;输出是带 score 的候选块列表。
client.embed(embed_model, question)只给问题计算一次向量,文档向量直接从索引读取。- 生成器遍历
index["chunks"],构造(相似度, 原块)二元组。 key=lambda x: x[0]表示按二元组第一项即分数排序;reverse=True表示高分在前。ranked[:top_k]截取前k条,再复制原块字典并加上score。
例如假设有 3 个块得分 0.9、0.5、0.1,top_k=2 只返回前两个;此时尚未考虑 min_score。全量算分约为 O(n × d)(d 是维度),再完整排序约为 O(n log n),并不是高效的近似最近邻检索。
top_k=3 很小,适合演示。生产中常见的是先召回 30–100 条,再重排到 5–10 条。直接取 top-3 的问题是:只要前三条里没有正确证据,后面再准也没用。
返回时把 score 合并进块,方便后续过滤和展示。注意这里没有做阈值,阈值在 ask 里。
9、第七层:证据、拒答与引用
def ask(client, index, question, embed_model, top_k=3,
retrieval_only=False, min_score=0.2, chat_model="gpt-6.1-terra"):
hits = retrieve(client, index, question, embed_model, top_k)
hits = [hit for hit in hits if hit["score"] >= min_score]
evidence = [{**hit, "id": f"E{i}"} for i, hit in enumerate(hits, 1)]
if retrieval_only:
return {"answer": None, "evidence": evidence}
if not evidence:
return {"answer": "没有足够证据回答。", "evidence": []}
context = "\n".join(
f"[{item['id']}] {item['source']} / {item['heading']}: {item['text']}"
for item in evidence
)
prompt = (
"只依据下列证据回答;若证据不足请明确说不知道,并在结论中引用证据编号。\n"
+ context
+ "\n问题:"
+ question
)
answer = client.chat(chat_model, [{"role": "user", "content": prompt}])
return {"answer": answer, "evidence": evidence}ask() 是问答编排器:先调用 retrieve(),再把候选变成本轮证据,最后决定是否需要对话模型。返回值始终包含 answer 和 evidence,但三条返回路径不同:
| 条件(按代码先后顺序) | answer | evidence | 本次调用对话模型? |
|---|---|---|---|
retrieval_only=True | None,打印 JSON 时为 null | 过滤后的列表,允许为空 | 否 |
| 普通问答且没有证据 | 固定文字“没有足够证据回答。” | [] | 否 |
| 普通问答且有证据 | client.chat() 返回的字符串 | 实际放入 Prompt 的证据 | 是 |
注意 return 会立刻结束当前函数,所以只检索模式不会继续走到拒答或生成逻辑。context 是多行证据字符串,prompt 是“规则 + context + 问题”,messages 则是包含这段 Prompt 的消息列表;三者不是同一层对象。
这里有四个关键设计:
9.1 阈值过滤
min_score=0.2 是一道粗筛。低于阈值的块不进入证据,避免“明明不相关却硬塞给模型”。
但阈值不是万能的:不同模型、不同语料的分数分布不同,0.2 对某些模型可能太低,对另一些可能太高。生产环境应该在评估集上校准,而不是拍脑袋。
9.2 证据编号
{**hit, "id": f"E{i}"} 先复制命中字典,再用 E1、E2 覆盖副本里的 id。这样本轮引用更短,且不会原地修改索引中的 C0003;但返回证据里也就不再有独立的原始块 ID 字段。来源文件、标题、正文、向量、分数等仍保留在副本里。
因此,这个 Demo 只是演示“编号证据并让模型引用”,不是完整的引用追溯实现。生产环境应同时保留 evidence_id 和 chunk_id,并验证回答中的编号确实属于本轮证据。
生产环境还要把 E1 映射回 chunk_id 和可点击的来源地址。模型只应看到本轮注册过的证据句柄,不能随便编造数据库 ID。
9.3 无证据拒答
if not evidence:
return {"answer": "没有足够证据回答。", "evidence": []}这一行比很多复杂的提示词都重要。它保证“检索不到”时不会退化成“让模型自由发挥”。
注意:这只是“检索层拒答”。还有一种情况是检索到了相关块,但块里没有答案,模型仍可能编。这需要生成层的提示词和后校验,见 07 生成与引用。
9.4 提示词边界
只依据下列证据回答;若证据不足请明确说不知道,并在结论中引用证据编号。
[E1] hr-policy.md / 午餐补贴: 公司为工作日加班的员工提供每餐 30 元午餐补贴。
问题:午餐补贴是多少?它同时约束了三件事:依据范围(只看证据)、不确定行为(说不知道)、可追溯性(引用编号)。
但它不是安全边界。如果证据里藏着“忽略上述指令”,模型仍可能被诱导。文档必须被视为不可信数据,系统提示要明确这一点,输出侧还要做引用校验。
9.5 用两维假向量手算一遍
为了先弄懂程序而不是猜模型行为,可以暂时假设只有两个块:
| 块 | 正文 | 已存的假向量 |
|---|---|---|
C0001 | 工作日加班午餐补贴每餐 30 元。 | [1, 0] |
C0002 | 访客需要登记。 | [0, 1] |
假设问题“午餐补贴是多少”的向量是 [1, 0],使用默认 top_k=3、min_score=0.2:
cosine([1,0], [1,0])=1,另一个是0;retrieve()排序后返回两个块,因为库里不足 3 个。ask()做阈值过滤,只剩分数为 1 的午餐补贴块。- 复制该块并将副本的
id改成E1,生成evidence。 - 如果加了
--retrieval-only,此时直接返回,answer=null。 - 否则把
[E1] 来源 / 标题: 正文拼进 Prompt,交给chat(),返回模型写出的文字和同一份证据。
这些向量只是计算示意,不是 BAAI/bge-m3 的实际输出。换一个问题后,真实模型的向量和排序都可能改变,不能把上述分数当成运行承诺。
9.6 出错时到底停在哪里
| 问题 | 发生位置 | 当前行为 |
|---|---|---|
| 文档目录为空或没有匹配文件 | make_chunks() / ingest() | 写空索引,打印 0;不主动报错 |
没有导出对应的 API Key | _post() | 抛 ApiError,不发请求 |
| Key 无效、余额不足或被限流 | _post() 收到 HTTPError | 抛 ApiError,带状态码与响应正文片段 |
| 嵌入服务不可用 | embed() → _post() | 抛异常;建索引时不执行后面的文件替换 |
| 索引文件不存在或不是合法 JSON | load_index() | 抛文件 / JSON 异常,不进入 ask() |
| 嵌入模型名与索引不符 | load_index() | 抛 ValueError,提示重新 ingest |
| 问题向量与文档向量维度不同 | cosine() | 抛 ValueError,停止检索 |
| 全部候选低于阈值 | ask() | 只检索返回空证据;普通模式固定拒答 |
| 有证据但对话服务失败 | chat() → _post() | 抛异常,不会伪装成无证据拒答 |
| 回答编造金额或不存在的引用 | chat() 返回之后 | 当前没有后校验,需要另行实现 |
10、测试:证明它真的这样工作
测试文件是 examples/tests/test_rag_demo.py,用 FakeClient 替代真实网络。核心思路是:把不确定性关在边界外,让其余逻辑可确定地验证。
10.1 HTTP 边界
FakeClient 记录调用并返回预设向量或文字,用于隔离真实模型。HTTP 边界测试则通过 patch() 替换 urlopen() 和两个 Key 环境变量:确认嵌入请求发往 /embeddings、对话请求发往 /chat/completions,Authorization 头分别带上两个 Key,{"data": [{"embedding": [1, 2]}]} 被转换成 [1.0, 2.0];另两条分别模拟超时和缺少 Key,确认都抛出 ApiError,后者甚至不会发出请求。测试全程不需要真实 API Key。
这些测试并不等于已覆盖所有错误响应、真实请求参数或模型服务行为;缺字段、非法数值、401/429 等 HTTP 状态仍可继续补测。
10.2 余弦排序
构造几个已知向量,验证最相似的块排第一。这能抓住“排序方向写反”“维度处理错误”这类低级但致命的 bug。
10.3 空索引与模型不匹配
- 空索引应返回空结果,而不是崩溃;
- 模型不匹配应明确报错,而不是静默算出无意义分数。
10.4 重建不残留
对同一目录重新 ingest,索引里不应出现上一次的旧块。这验证的是“全量重建”的语义。生产环境做增量更新时,还要额外测试“删除文档后旧块不可检索”。
10.5 原子写入
写入后文件应是合法 JSON,且临时文件不残留。更严格的测试可以模拟写入中途异常,确认旧文件未被破坏。
10.6 引用与拒答
- 有证据时,返回的
evidence编号从E1开始且连续; - 分数低于阈值时,回答固定为“没有足够证据回答。”,且
evidence为空; retrieval_only时不调用对话模型。
这些测试不评价模型答得好不好,只验证系统契约。模型质量要用 09 评估 的方法单独测。
11、这个 Demo 故意没做的事
| 缺失 | 后果 | 去哪里补 |
|---|---|---|
| 结构化解析 | PDF、表格、扫描件效果差 | 04 |
| 重试、限流、并发 | 网络抖动或触发限流时直接失败;建索引串行,块多时很慢 | 10 |
| 增量与删除 | 改文档要全量重建,旧块可能残留 | 04、10 |
ANN 索引 | 数据量大时检索慢 | 05 |
| 混合检索 | 专有名词、编号召回差 | 06 |
| 重排 | 候选多时排序不准 | 06 |
| 权限过滤 | 多租户会越权 | 10 |
| 流式与停止 | 长答案等待久,无法中断 | 08 |
| 评估集 | 无法判断改动好坏 | 09 |
| 可观测性 | 出错无法定位 | 10、12 |
12、十个升级练习
按难度排序,每个都能独立验证:
- 给
chunk加page和字符偏移,让引用能定位到原文。 - 把按行切块改成按标题 + 段落切块,保留标题路径。
- 加
--top-k之外的--candidate-k,先召回 20 条再截断 3 条。 - 实现
BM25或简单关键词匹配,与向量结果做RRF融合。 - 给索引加
doc_id和version,实现“删除某文档后不可检索”。 - 用内容哈希做幂等:同一文件重复上传不重复建索引。
- 把
JSON索引换成SQLite+ 向量列,练习事务与迁移。 - 加一个
rerank接口(可以是另一个模型),比较重排前后的Recall@3。 - 把
ask包成HTTP服务,支持SSE流式输出和取消。 - 建 30 条评估集,计算
Recall@3、引用覆盖率和拒答准确率。
做完这十个,你已经覆盖了 RAG 的主要工程面;剩下的深度在 08 全链路 和 10 生产化。
13、一句话总结
这个 Demo 的价值不在“能用”,而在每个环节都看得见、每个契约都能测。生产化不是把它推翻,而是把每一层替换成更可靠的实现,同时保留同样的可观测边界。
评论
正在加载评论…