Skip to content

最小实现:300 行跑通 RAG ​

这一篇逐段拆 examples/rag_demo.py。它的目标不是生产可用,而是让你亲眼看到 RAG 的每个关键动作,并且能用测试证明它按预期工作。

1、设计边界 ​

这个 Demo 刻意做了减法:

有没有
Markdown 读取与按行切块PDF/Word/OCR 解析
调用云端 API:硅基流动做嵌入、OpenAI GPT 做对话重试、限流、批量并发、成本控制
余弦相似度全量扫描HNSW/IVF 等 ANN 索引
JSON 文件索引向量数据库、增量更新
阈值过滤、证据编号、拒答重排、混合检索
命令行 ingest / askHTTP 服务、流式输出、多租户
假客户端单元测试端到端模型质量评估

这些“没有”正是后续章节要补的。先把最小闭环跑通,再逐层替换,比一上来堆框架更容易理解。

2、运行方式 ​

准备两个账号的 API Key,通过环境变量传入。Key 只放在终端里,不要写进代码、索引文件或提交记录:

bash
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 覆盖默认地址。

然后:

bash
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 先看入口:程序不是从第一个函数开始执行 ​

函数定义不等于调用。直接运行文件时,末尾触发入口;被测试导入时不会启动命令行:

python
if __name__ == "__main__":
    main()
命令入口:从启动到结束沿箭头阅读 · 菱形为判断 · 圆角为开始 / 返回 / 结束
命令入口:从启动到结束开始 → main() 解析参数 → 创建客户端 → 判断子命令。ingest 分支建索引后打印片段数;ask 分支先加载索引,再调用 ask,最后打印 JSON。两条正常路径汇合后结束。ingestask开始:执行脚本开始:执行脚本main();解析命令行参数main()解析命令行参数创建 OpenAICompatible 客户端;读取两个端点地址与 Key,不发请求创建 OpenAICompatible 客户端读取两个端点地址与 Key,不发请求子命令;是什么?子命令是什么?ingest();读文档 → 切块 → 嵌入 → 写索引ingest()读文档 → 切块 → 嵌入 → 写索引load_index();读取 index.json,检查模型名load_index()读取 index.json,检查模型名打印片段数量;「已写入 N 个片段」打印片段数量「已写入 N 个片段」ask();检索 → 证据 / 拒答 / 回答ask()检索 → 证据 / 拒答 / 回答打印 JSON;answer + evidence打印 JSONanswer + evidence结束结束
两条命令分别运行,通过磁盘上的 index.json 衔接。ask 不会自动重新切块或给文档计算向量。图中是正常路径;异常会中断执行,不会汇合到正常结束。
文字版流程(方便复制与辅助阅读)

开始 → main() 解析参数 → 创建客户端 → 判断子命令。ingest 分支建索引后打印片段数;ask 分支先加载索引,再调用 ask,最后打印 JSON。两条正常路径汇合后结束。

main() 负责解析、分派和打印;客户端构造只存配置,不发网络请求。Demo 没有后台任务,执行完即退出。

一条命令,拆成五块 ​

bash
python3 rag_demo.py --timeout 90 ask index.json "午餐补贴是多少" --top-k 5
--timeout 90全局参数timeout = 90.0
ask子命令command = ask
index.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,不是“证据不足”的拒答。解析器的类型转换也不代替正数、有限分数等业务校验。

所有参数一览 ​

参数默认值 / 作用影响哪个动作
--timeout60 秒单次请求超时;全局参数应放在子命令前
SILICONFLOW_API_KEY、OPENAI_API_KEY环境变量,必填分别用于嵌入与对话;缺失时在发请求前报错
ingest docs index文档目录、索引文件路径,均必填从目录读资料并替换索引
ask index question索引路径、问题,均必填读取已有索引并提问
--embed-modelBAAI/bge-m3两个子命令都支持;文档向量与问题向量应来自同一模型
--chat-modelgpt-6.1-terra仅 ask,决定谁根据证据写答案;可换成账号里可用的其他 GPT
--top-k3先取最相似的几个候选
--min-score0.2再过滤掉分数低的候选
--retrieval-only默认关闭;出现即为真只返回证据,不调用对话接口

例如:python3 rag_demo.py --timeout 60 ask index.json "午餐补贴是多少" --top-k 5。这里 --timeout 放在 ask 前,--top-k 放在后面。

2.2 建索引的真实调用顺序 ​

ingest:切块、循环嵌入、检查、写入沿箭头阅读 · 菱形为判断 · 圆角为开始 / 返回 / 结束
ingest:切块、循环嵌入、检查、写入进入 ingest,make_chunks 调用 read_markdown 切块。只要还有未嵌入的块,就取下一个块调用 embed,再回到循环判断。全部完成后检查维度;不一致抛异常,一致则原子写入并返回块数。是:继续循环处理下一块否:循环完成否是进入 ingest()进入 ingest()make_chunks() → read_markdown();读 *.md → 按行切块 → 编号 C0001…make_chunks() → read_markdown()读 *.md → 按行切块 → 编号 C0001…还有块;没有嵌入?还有块没有嵌入?取下一个块 → client.embed();_post('/embeddings');把返回向量加入 vectors取下一个块 → client.embed()_post('/embeddings')把返回向量加入 vectorsdimension = 第一条向量长度;没有块时,dimension = 0dimension = 第一条向量长度没有块时,dimension = 0所有向量;维度一致?所有向量维度一致?抛 ValueError → 中断;不写入,不覆盖旧索引抛 ValueError → 中断不写入,不覆盖旧索引atomic_write();写同目录临时 JSON;os.replace() 替换 index.jsonatomic_write()写同目录临时 JSONos.replace() 替换 index.jsonreturn len(chunks);把片段数量交回 main()return len(chunks)把片段数量交回 main()返回调用方返回调用方
串行、全量重建,不是并发嵌入。嵌入请求失败时立即抛异常,不进入后续写入。空目录跳过循环,仍可写入 dimension=0、chunks=[] 的空索引。
文字版流程(方便复制与辅助阅读)

进入 ingest,make_chunks 调用 read_markdown 切块。只要还有未嵌入的块,就取下一个块调用 embed,再回到循环判断。全部完成后检查维度;不一致抛异常,一致则原子写入并返回块数。

一条 ingest 命令只走这条线。假设目录产生了 N 个块,它会串行发出 N 次嵌入请求、0 次对话请求;全部向量准备好且维度一致后才写文件。没有做批量请求、并发或失败重试。

2.3 问答的真实调用顺序与提前返回 ​

ask:先检索,再按条件选择返回路径沿箭头阅读 · 菱形为判断 · 圆角为开始 / 返回 / 结束
ask:先检索,再按条件选择返回路径先 load_index,再进入 ask 并调用 retrieve:问题嵌入、余弦算分、排序取 top_k。过滤并编号后,先判断 retrieval_only,为真直接返回 answer=null;否则判断证据是否为空,空则固定拒答,非空则组装 Prompt 调用 chat。三条正常返回路径汇合到 main 打印结果。是:只检索否:普通问答是否load_index() → 进入 ask();读 JSON、检查 embedding_modelload_index() → 进入 ask()读 JSON、检查 embedding_modelretrieve();embed(问题) → 逐块 cosine();降序排序 → 取前 top_k 条retrieve()embed(问题) → 逐块 cosine()降序排序 → 取前 top_k 条阈值过滤并编号;保留 score ≥ min_score → 副本 id 改为 E1…阈值过滤并编号保留 score ≥ min_score → 副本 id 改为 E1…retrieval_only;为真?retrieval_only为真?返回检索结果;answer=null,evidence 可为空;不调用 chat返回检索结果answer=null,evidence 可为空不调用 chatevidence;为空?evidence为空?返回固定拒答;「没有足够证据回答。」;evidence=[];不调用 chat返回固定拒答「没有足够证据回答。」evidence=[];不调用 chat拼 context + prompt;编号、来源、正文、问题拼 context + prompt编号、来源、正文、问题client.chat();/chat/completions,stream=Falseclient.chat()/chat/completions,stream=False返回结果;answer + evidence返回结果answer + evidence回到 main(),打印 JSON,结束回到 main(),打印 JSON,结束
按箭头顺序,先判断 retrieval_only,再判断空证据。只检索仍会调用 embed,空索引也会先计算问题向量。异常不是拒答:文件、网络、JSON 或维度错误会向外抛出,当前 main() 没有统一捕获。
文字版流程(方便复制与辅助阅读)

先 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__()超时 → 读取两个端点的地址与 Keymain()不发请求
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 序列化数据 → Noneingest()写临时文件、替换索引
ingest()客户端、文档目录、索引路径、嵌入模型 → 块数main()文件 + 嵌入请求
load_index()索引路径、嵌入模型名 → 索引字典main() 的 ask 分支读 JSON
retrieve()客户端、索引、问题、模型、top_k → 命中列表ask()问题嵌入请求
ask()检索参数、阈值、模式、对话模型 → answer/evidence 字典main()检索 + 可选对话请求

接下来逐个解释这些函数,阅读时把“输入是什么、返回什么、有没有副作用”带进去。

3、第一层:把 HTTP 调用关进一个类 ​

python
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

这段代码有三个值得学的习惯:

  1. 所有外部调用集中在一个边界。硅基流动和 OpenAI 都提供 OpenAI 兼容协议,所以同一段代码可以服务两个端点。以后换模型、换网关、加重试,只改这里。
  2. 把底层异常翻译成自己的异常。HTTPError 单独处理,能保留 401(Key 无效)、429(限流)等状态码和响应正文;URLError、超时、JSON 解析失败统一视为服务不可用。上层不需要知道 urllib 的细节。
  3. 校验返回结构。不能假设服务一定返回 data[0].embedding 或 choices[0].message.content,否则错误会以 KeyError 的形式散落到业务代码里。

embed 和 chat 都只做“取字段 + 类型检查”:

python
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():把消息列表换成完整回答 ​

python
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、第二层:读取与切块 ​

python
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 是最粗糙的标题上下文,后面会拼进证据,帮助模型理解来源。

逐步看返回值怎么产生:

  1. path.read_text() 读出整个文件;文件不存在、权限不足或不是 UTF-8 时抛出异常。
  2. path.stem 是不带扩展名的文件名,作为没有标题时的默认标题。
  3. splitlines() 按行遍历:行首为 # 就更新当前标题;否则非空行就存入 (heading, line.strip())。
  4. 返回元组列表,标题行本身不会成为一个正文块。

例如输入 # 午餐补贴 和下一行 每餐 30 元。,返回 [("午餐补贴", "每餐 30 元。")]。它不是完整 Markdown 解析器:代码块里行首的 # 也会被误认为标题。

但它也很粗糙:

  • 只按行切,标题和正文分离;
  • 列表项、代码块、表格会被拆散;
  • 没有页码和字符偏移;
  • 标题层级只保留最后一层,没有 ["差旅", "住宿标准"] 这样的路径。

生产环境要用结构化解析和递归/语义切分,见 04 数据摄取。

python
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 result

make_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、第三层:余弦相似度 ​

python
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.0

cosine(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、第四层:建索引与原子写入 ​

python
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,也不实现嵌入模型,而是调用前面的工具函数:

  1. make_chunks() 返回块列表。
  2. 列表推导式按块依次调用 client.embed(),返回与块列表位置一一对应的向量列表。
  3. 取第一条向量长度作为 dimension;空列表则记为 0。任何向量长度不同都先报错,不写索引。
  4. zip(chunks, vectors) 将每块与对应向量配对;{**item, "vector": vector} 是复制块字典,再增加 vector 字段,不会原地修改原块。
  5. atomic_write() 写入完整索引;成功后返回块数,交给 main() 打印。

它只嵌入 item["text"],没有把标题一起嵌入。标题会保存在索引里,稍后作为提示词中的来源上下文。

索引是一个自描述的 JSON(下面用 3 维假向量展示结构,并非真实模型输出):

json
{
  "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 解决的是“写到一半进程挂了”的问题:

python
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;它的结果是磁盘上的索引发生变化:

  1. mkdir(..., exist_ok=True) 确保目标父目录存在。
  2. mkstemp(..., dir=path.parent) 在同一目录创建临时文件,返回文件描述符和临时路径,避免跨文件系统替换。
  3. os.fdopen() 把文件描述符包装成文本句柄;json.dump() 写入数据,退出 with 时关闭文件。
  4. 只有完整写入并关闭后,才用 os.replace(temp, path) 原子替换目标。若目标已存在,它会被覆盖,这是全量重建,不是向旧索引追加。
  5. finally 在正常退出或异常时检查临时文件是否仍存在,存在就清理。进程被强制终止时不保证执行清理。

在正常的本地文件系统原子替换语义下,读取者看到的是旧文件或新文件,不是写到一半的 JSON。代码没有调用 fsync(),所以“替换原子”不等于“断电后一定持久化成功”;也没有并发写锁,多个建索引进程可能最后写入者覆盖前者。

生产环境同理:新索引写到新版本,校验通过后原子切换别名;失败则保留旧版本。这就是“索引版本切换”的雏形。

7、第五层:加载时拒绝模型不匹配 ​

python
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 data

load_index() 在 ask() 外面执行:先读文件、解析 JSON,再比较保存的模型名与本次指定的模型名;匹配才返回整个索引字典。文件不存在、JSON 损坏或模型名不符都会向外抛异常,当前 main() 没有捕获并转换成友好 JSON 错误。

这是一个经常被省略、但线上非常关键的检查。用模型 A 建的索引,拿模型 B 的查询向量检索,即使维度相同也可能静默得到无意义的分数;维度不同则会在 cosine() 中报错。

当前函数只比较模型名字,不会完整验证 JSON 字段结构、version、声明的 dimension 或模型权重是否已更新。同名模型重新拉取后也可能变化,生产环境还需要更严格的版本与结构校验。

进一步可以检查 dimension、模型版本、归一化方式、查询指令前缀。只要影响向量空间的配置变了,就应该视为索引不兼容。

8、第六层:召回 ​

python
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 的候选块列表。

  1. client.embed(embed_model, question) 只给问题计算一次向量,文档向量直接从索引读取。
  2. 生成器遍历 index["chunks"],构造 (相似度, 原块) 二元组。
  3. key=lambda x: x[0] 表示按二元组第一项即分数排序;reverse=True 表示高分在前。
  4. 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、第七层:证据、拒答与引用 ​

python
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,但三条返回路径不同:

条件(按代码先后顺序)answerevidence本次调用对话模型?
retrieval_only=TrueNone,打印 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 无证据拒答 ​

python
if not evidence:
    return {"answer": "没有足够证据回答。", "evidence": []}

这一行比很多复杂的提示词都重要。它保证“检索不到”时不会退化成“让模型自由发挥”。

注意:这只是“检索层拒答”。还有一种情况是检索到了相关块,但块里没有答案,模型仍可能编。这需要生成层的提示词和后校验,见 07 生成与引用。

9.4 提示词边界 ​

text
只依据下列证据回答;若证据不足请明确说不知道,并在结论中引用证据编号。
[E1] hr-policy.md / 午餐补贴: 公司为工作日加班的员工提供每餐 30 元午餐补贴。
问题:午餐补贴是多少?

它同时约束了三件事:依据范围(只看证据)、不确定行为(说不知道)、可追溯性(引用编号)。

但它不是安全边界。如果证据里藏着“忽略上述指令”,模型仍可能被诱导。文档必须被视为不可信数据,系统提示要明确这一点,输出侧还要做引用校验。

9.5 用两维假向量手算一遍 ​

为了先弄懂程序而不是猜模型行为,可以暂时假设只有两个块:

块正文已存的假向量
C0001工作日加班午餐补贴每餐 30 元。[1, 0]
C0002访客需要登记。[0, 1]

假设问题“午餐补贴是多少”的向量是 [1, 0],使用默认 top_k=3、min_score=0.2:

  1. cosine([1,0], [1,0])=1,另一个是 0;retrieve() 排序后返回两个块,因为库里不足 3 个。
  2. ask() 做阈值过滤,只剩分数为 1 的午餐补贴块。
  3. 复制该块并将副本的 id 改成 E1,生成 evidence。
  4. 如果加了 --retrieval-only,此时直接返回,answer=null。
  5. 否则把 [E1] 来源 / 标题: 正文 拼进 Prompt,交给 chat(),返回模型写出的文字和同一份证据。

这些向量只是计算示意,不是 BAAI/bge-m3 的实际输出。换一个问题后,真实模型的向量和排序都可能改变,不能把上述分数当成运行承诺。

9.6 出错时到底停在哪里 ​

问题发生位置当前行为
文档目录为空或没有匹配文件make_chunks() / ingest()写空索引,打印 0;不主动报错
没有导出对应的 API Key_post()抛 ApiError,不发请求
Key 无效、余额不足或被限流_post() 收到 HTTPError抛 ApiError,带状态码与响应正文片段
嵌入服务不可用embed() → _post()抛异常;建索引时不执行后面的文件替换
索引文件不存在或不是合法 JSONload_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、十个升级练习 ​

按难度排序,每个都能独立验证:

  1. 给 chunk 加 page 和字符偏移,让引用能定位到原文。
  2. 把按行切块改成按标题 + 段落切块,保留标题路径。
  3. 加 --top-k 之外的 --candidate-k,先召回 20 条再截断 3 条。
  4. 实现 BM25 或简单关键词匹配,与向量结果做 RRF 融合。
  5. 给索引加 doc_id 和 version,实现“删除某文档后不可检索”。
  6. 用内容哈希做幂等:同一文件重复上传不重复建索引。
  7. 把 JSON 索引换成 SQLite + 向量列,练习事务与迁移。
  8. 加一个 rerank 接口(可以是另一个模型),比较重排前后的 Recall@3。
  9. 把 ask 包成 HTTP 服务,支持 SSE 流式输出和取消。
  10. 建 30 条评估集,计算 Recall@3、引用覆盖率和拒答准确率。

做完这十个,你已经覆盖了 RAG 的主要工程面;剩下的深度在 08 全链路 和 10 生产化。

13、一句话总结 ​

这个 Demo 的价值不在“能用”,而在每个环节都看得见、每个契约都能测。生产化不是把它推翻,而是把每一层替换成更可靠的实现,同时保留同样的可观测边界。

评论

正在加载评论…