RAG 专题:从一句话到可运维的知识问答
这个专题只回答一个问题:当模型不知道你公司的文档时,怎样让它基于文档回答,并且答得对、说得出出处、答不出时敢说不知道。
它分成三层:
- 能用大白话讲清楚:不写代码的人读完 01 白话
RAG,也能说明白RAG是什么、解决什么问题、什么时候没用。 - 能自己写出来:跟着 03 最小实现 跑通一个三百行左右、零依赖的版本,再逐层替换成生产组件。
- 能解释故障并上线:用 08 全链路、09 评估、10 生产化、12 排障手册 把 Demo 变成可运维系统。
1、三条阅读路径
| 你是谁 | 建议顺序 | 读完能做到 |
|---|---|---|
完全不了解 AI | 01 → 02 → 13 | 用比喻解释 RAG,判断一个产品是不是真 RAG |
| 要动手做 | 01 → 03 → 04 → 05 → 06 → 07 → 09 | 独立搭出带引用、可评估的知识库问答 |
| 要负责上线 | 02 → 08 → 09 → 10 → 12 → 11 | 做选型、拆故障、设计权限与回滚 |
已经熟悉基础的人可以直接跳到 08 文档上传到问答全链路,那里用 WeKnora 的真实源码拆解了上传、异步摄取、混合检索、引用协议和流式收尾。其余章节负责补齐它背后的通用原理。
遇到读不准的缩写,先查 14 术语与读法:每个缩写都给了英文全称、中文含义和读法。
2、一张总图
- 上传文档保存原文件
- 解析与切块解析 → 清洗 → 切分
- 向量化与索引向量 / 关键词 → 写索引
- 状态收敛校验处理结果
- 可检索文档就绪
持久化索引离线写入 ↓ 在线召回时读取
- 提问与理解理解 / 改写问题
- 召回从索引取候选片段
- 融合与重排合并候选 → 排序
- 组装证据证据 → Prompt
- 生成与引用流式回答 → 引用 / 拒答
两条链路通过一份持久化的索引衔接,而不是通过内存或一次请求衔接。这决定了三件事:
- 生产环境的大文档处理通常异步执行,并记录状态、重试与幂等(重复执行不重复写入);
- 索引必须带版本、来源、权限和删除能力;
- 问答失败时要能判断是“文档没进来”“没检索到”还是“模型没用好证据”。
3、同一段资料,四种角色
数据契约就是各环节约定“交给下一步哪些信息”。 用“午餐补贴是多少?”看一次数据变化:
| 必须保留 | 为了什么 |
|---|---|
| 块 ID、版本、位置 | 找回准确原文,而非只剩一句答案 |
| 服务端校验的访问权限 | 未授权内容不能进入模型 |
| 本次排名、本轮证据编号、run_id | 分清“没找到”“没选入”“模型没用对” |
字段参考见 02 数据契约。分数不是正确概率;出处由系统绑定,不让模型编地址。
4、文章地图
| 文章 | 核心问题 | 关键产出 |
|---|---|---|
01 白话 RAG | RAG 到底是什么? | 一个不用术语的解释 |
| 02 原理地图 | 系统由哪些层组成?和微调、长上下文怎么选? | 链路图与选型表 |
| 03 最小实现 | 300 行怎么跑通? | 可运行的 ingest/ask/test |
| 04 数据摄取 | 文档怎么变成可检索的块? | 解析、切分、增量、删除方案 |
| 05 向量化与索引 | 向量是什么?索引怎么选? | 模型与向量库选型 |
| 06 检索与重排 | 为什么找不到?怎么排得准? | 混合检索、RRF、重排 |
| 07 生成与引用 | 怎么让答案有出处、不瞎编? | Prompt、引用、拒答设计 |
| 08 上传到问答全链路 | 真实系统怎么串起来? | WeKnora 源码级拆解 |
| 09 评估 | 怎么证明改好了? | 指标、数据集、CI 门禁 |
| 10 生产化 | 多租户、回滚、成本怎么办? | 上线检查表 |
11 高级 RAG | GraphRAG、Agentic RAG 何时值得? | 模式与成本对照 |
| 12 排障手册 | 出问题先看哪里? | 症状 → 证据 → 修复 |
| 13 项目与资料 | 该读哪些代码和论文? | 经核对的项目清单 |
| 14 术语与读法 | 这些缩写怎么念? | 全称、中文与读法速查 |
5、示例代码
examples/rag_demo.py 是本专题的基线:
- 只用
Python标准库,通过HTTP调 OpenAI 兼容接口:硅基流动做嵌入、OpenAIGPT 做对话; ingest把Markdown切成片段、算向量、原子写入JSON索引;ask做余弦召回、阈值过滤、编号证据、带引用回答,证据不足时拒答;- 自带单元测试,用假客户端隔离网络。
先看代码从哪里开始执行: 两个子命令通过 index.json 衔接,建索引与问答不是同一次运行。
文字版流程(方便复制与辅助阅读)
开始 → 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 不是“把文档塞给模型”,而是建一套可追溯的证据供应链:文档进得来、切得好、找得到、排得准、用得对、说得清、错得了可查。
评论
正在加载评论…