Skip to content

RAG 专题:从一句话到可运维的知识问答 ​

这个专题只回答一个问题:当模型不知道你公司的文档时,怎样让它基于文档回答,并且答得对、说得出出处、答不出时敢说不知道。

它分成三层:

  1. 能用大白话讲清楚:不写代码的人读完 01 白话 RAG,也能说明白 RAG 是什么、解决什么问题、什么时候没用。
  2. 能自己写出来:跟着 03 最小实现 跑通一个三百行左右、零依赖的版本,再逐层替换成生产组件。
  3. 能解释故障并上线:用 08 全链路、09 评估、10 生产化、12 排障手册 把 Demo 变成可运维系统。

1、三条阅读路径 ​

你是谁建议顺序读完能做到
完全不了解 AI01 → 02 → 13用比喻解释 RAG,判断一个产品是不是真 RAG
要动手做01 → 03 → 04 → 05 → 06 → 07 → 09独立搭出带引用、可评估的知识库问答
要负责上线02 → 08 → 09 → 10 → 12 → 11做选型、拆故障、设计权限与回滚

已经熟悉基础的人可以直接跳到 08 文档上传到问答全链路,那里用 WeKnora 的真实源码拆解了上传、异步摄取、混合检索、引用协议和流式收尾。其余章节负责补齐它背后的通用原理。

遇到读不准的缩写,先查 14 术语与读法:每个缩写都给了英文全称、中文含义和读法。

2、一张总图 ​

离线 · 文档进来准备可检索的资料
  1. 上传文档保存原文件
  2. 解析与切块解析 → 清洗 → 切分
  3. 向量化与索引向量 / 关键词 → 写索引
  4. 状态收敛校验处理结果
  5. 可检索文档就绪
持久化索引离线写入 ↓ 在线召回时读取
在线 · 问题进来根据证据组织回答
  1. 提问与理解理解 / 改写问题
  2. 召回从索引取候选片段
  3. 融合与重排合并候选 → 排序
  4. 组装证据证据 → Prompt
  5. 生成与引用流式回答 → 引用 / 拒答
两条独立链路通过索引衔接,不是每次提问都重新处理文档。

两条链路通过一份持久化的索引衔接,而不是通过内存或一次请求衔接。这决定了三件事:

  • 生产环境的大文档处理通常异步执行,并记录状态、重试与幂等(重复执行不重复写入);
  • 索引必须带版本、来源、权限和删除能力;
  • 问答失败时要能判断是“文档没进来”“没检索到”还是“模型没用好证据”。

3、同一段资料,四种角色 ​

数据契约就是各环节约定“交给下一步哪些信息”。 用“午餐补贴是多少?”看一次数据变化:

同一段资料怎样变成回答
同一段资料怎样变成回答文档块 chunk 记录正文和来源;命中 hit 增加本次排名;证据 evidence 增加本轮引用 E1;answer 引用 E1。找到的候选不一定全部交给模型。chunk · 原文块 hr-v2-c003工作日加班,每餐补贴 30 元hit · 本次命中,rank = 1其他候选可被筛掉evidence · 选给模型的资料本轮 E1 → hr-v2-c003 → v2 / 第 3 页answer · 工作日加班,每餐补贴 30 元 [E1]保留条件、金额和引用
命中不等于给模型看了;E1 仅本轮有效。对象是环节约定,不强制对应四张表。
必须保留为了什么
块 ID、版本、位置找回准确原文,而非只剩一句答案
服务端校验的访问权限未授权内容不能进入模型
本次排名、本轮证据编号、run_id分清“没找到”“没选入”“模型没用对”

字段参考见 02 数据契约。分数不是正确概率;出处由系统绑定,不让模型编地址。

4、文章地图 ​

文章核心问题关键产出
01 白话 RAGRAG 到底是什么?一个不用术语的解释
02 原理地图系统由哪些层组成?和微调、长上下文怎么选?链路图与选型表
03 最小实现300 行怎么跑通?可运行的 ingest/ask/test
04 数据摄取文档怎么变成可检索的块?解析、切分、增量、删除方案
05 向量化与索引向量是什么?索引怎么选?模型与向量库选型
06 检索与重排为什么找不到?怎么排得准?混合检索、RRF、重排
07 生成与引用怎么让答案有出处、不瞎编?Prompt、引用、拒答设计
08 上传到问答全链路真实系统怎么串起来?WeKnora 源码级拆解
09 评估怎么证明改好了?指标、数据集、CI 门禁
10 生产化多租户、回滚、成本怎么办?上线检查表
11 高级 RAGGraphRAG、Agentic RAG 何时值得?模式与成本对照
12 排障手册出问题先看哪里?症状 → 证据 → 修复
13 项目与资料该读哪些代码和论文?经核对的项目清单
14 术语与读法这些缩写怎么念?全称、中文与读法速查

5、示例代码 ​

examples/rag_demo.py 是本专题的基线:

  • 只用 Python 标准库,通过 HTTP 调 OpenAI 兼容接口:硅基流动做嵌入、OpenAI GPT 做对话;
  • ingest 把 Markdown 切成片段、算向量、原子写入 JSON 索引;
  • ask 做余弦召回、阈值过滤、编号证据、带引用回答,证据不足时拒答;
  • 自带单元测试,用假客户端隔离网络。

先看代码从哪里开始执行: 两个子命令通过 index.json 衔接,建索引与问答不是同一次运行。

命令入口:从启动到结束沿箭头阅读 · 菱形为判断 · 圆角为开始 / 返回 / 结束
命令入口:从启动到结束开始 → 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。两条正常路径汇合后结束。

这里展示的是 Demo 的真实行为:直接读本地 Markdown,没有上传接口、异步队列、关键词检索或流式回答。不要把上一张通用架构图里的能力都当成这个教学脚本已经实现。

进入 03:执行流程图与全部函数详解,继续看 ingest、ask 的内部步骤、判断分支和函数输入输出。

bash
cd docs/articles/rag/examples
python3 -m unittest discover -s tests -v

export SILICONFLOW_API_KEY=...   # 嵌入:硅基流动
export OPENAI_API_KEY=...        # 对话:OpenAI
python3 rag_demo.py ingest data index.json
python3 rag_demo.py ask index.json "午餐补贴是多少"

03 最小实现 会逐段解释它;04 到 07 则说明每一段在生产环境要换成什么。

6、事实与版本约定 ​

  • 文章日期为 2026-11-14。涉及模型、价格、stars、许可证的信息会标注“快照”,使用前必须重新核对官方页面。
  • 08 全链路 基于 WeKnora 公开源码的静态拆解:文中把“源码已实现”和“文档中的目标设计”分开写,不把规划当现状。
  • 开源项目的许可证以仓库 LICENSE 为准。Dify、FastGPT、WeKnora 在 GitHub API 中显示为 NOASSERTION,属于自定义/修改条款,不能简单写成 MIT 或 Apache-2.0。
  • 论文数字(如 Contextual Retrieval 的失败率下降)只在原实验设置下成立,不能直接当成本项目的预期收益。

7、一句话总结 ​

RAG 不是“把文档塞给模型”,而是建一套可追溯的证据供应链:文档进得来、切得好、找得到、排得准、用得对、说得清、错得了可查。

评论

正在加载评论…