用户问“退款什么时候到账?”,检索程序已经能找出相关规则。接下来,把这些规则交给模型组织回答,再让客户端通过 HTTP 调用,就得到一个文档问答 API。
本文沿用前两篇的虚构退款资料,完成 POST /ask:输入一个问题,返回回答、原文预览与来源。重点看清“检索 → 生成 → 接口”如何连接,完整代码随示例包提供。
1. 先看懂一次请求的数据流
资料里有这样一条规则:“仓库检查通过后,平台会发起退款,通常需要三个工作日,节假日可能顺延。”用户问到账时间时,程序先找到它,再让生成模型根据原文回答。
这种“先取资料,再带着资料回答”的方法叫 RAG(Retrieval-Augmented Generation,检索增强生成)。
本篇使用 Naive RAG,Naive 意为“朴素的、基础的”。它通常先将文档切分、向量化并建立索引;收到问题后,用用户的原始问题直接检索相关文本块,把这些原文和问题一起放进提示词,再让模型生成回答。Naive RAG 流程说明
从执行顺序看,本例也属于 LangChain 所说的 2-Step RAG:检索阶段在前,生成阶段在后。这个名称强调两阶段的固定顺序。RAG 架构说明
1 | 准备资料,资料变化时执行: |
Embedding 模型把文字转换成向量,供 Chroma 比较并检索;生成模型读问题和原文,写出回答。资料在回答时进入生成模型的输入,不会因此写入它的参数。
这一篇要接起来的是下面几个对象:
| 对象 | 接收什么 | 返回什么 |
|---|---|---|
| Retriever,检索入口 | 问题字符串 | 相关 Document 列表 |
| 提示词模板 | 问题、参考资料 | 填好内容的消息 |
| 生成模型与输出解析器 | 消息 | 回答字符串 |
| FastAPI 路由 | JSON 请求 | 回答与来源组成的 JSON |
Document 是 LangChain 用来保存文本与来源的对象:page_content 是原文,metadata 保存文件名、章节或页码。下面用同一个退款问题,逐步观察这些数据怎样传递。
2. 准备示例,先建好知识库
下载完整示例包,解压并进入 naive-rag-api-example 目录。包内的 chunks.jsonl 已有 9 个文本块,每行保存一条原文与来源,可以直接建库。
1 | chunks.jsonl 已加载、切分好的退款资料 |
用 Python 3.12 创建环境,再运行建库脚本:
1 | python3.12 -m venv .venv |
Windows PowerShell 使用 py -3.12 -m venv .venv 创建环境,执行 .venv\Scripts\Activate.ps1 激活,然后运行同样的安装与建库命令。首次加载本地 Embedding 模型需要联网,但建库不需要生成模型 API Key。
完成后应显示 已写入 9 个片段,数据保存在示例目录的 .rag_db/。之后启动问答服务直接读它,不再重复建库。脚本会拒绝写入已经存在的目录;更换资料或编码设置时,先停止服务,将 .rag_db 改名备份,再重新建库。
这部分沿用文档加载与分块和向量化与存储的结果。本例仍使用中文模型 BAAI/bge-small-zh-v1.5,文档与问题都做归一化,查询时添加该模型规定的中文指令,Chroma 使用余弦距离。具体实现与固定版本保留在包内。
后文直接调用 common.py 中两个已经提供的对象:BgeEmbeddings() 加载这套编码设置,open_store(embeddings) 打开已有知识库并返回 LangChain 的 Chroma 对象。它们是示例自己的代码。
3. 从检索结果到一段回答
先看找到的原文
在示例目录运行 python,进入交互环境后执行下面的代码。此时只检索,不调用生成模型:
1 | from common import BgeEmbeddings, open_store |
as_retriever() 创建检索入口,invoke() 接收问题,内部编码问题、查询 Chroma,再返回 list[Document]。k=3 表示最多取 3 个文本块。
本次真实检索依次得到 refund.md 的“退款到账”、policy.pdf 第 2 页,以及 refund.md 的“退款说明”。前两块包含到账规则,第三块只是资料介绍。取回 3 个块,不代表每块都能回答问题。 如果这里没有正确资料,先检查资料与检索,后面的模型也无法凭空补齐依据。
将原文拼成参考资料
模型要读文字,因此需要把 Document 列表转成字符串。在 rag.py 中,format_context() 为每块添加来源与临时标签,再用空行连接:
1 | from langchain_core.documents import Document |
返回的字符串大致如下,只展示格式并缩短原文:
1 | [S1] refund.md,退款到账 |
S1 表示“这次检索得到的第 1 个文本块”,S2 表示第 2 个。上面的 enumerate(..., start=1) 按结果顺序生成编号,每次请求都会从 1 开始。
例如,知识库里有“退款到账”和“退货运费”两块资料,它们的 chunk_id 分别为 chunk-a、chunk-b。换一个问题,检索顺序可能改变,标签也会跟着改变。下面的 ID 与排序是简化示意:
| 用户问题 | 本次 S1 | 本次 S2 |
|---|---|---|
| 退款多久能到账? | 退款到账(chunk-a) |
退货运费(chunk-b) |
| 退货运费谁承担? | 退货运费(chunk-b) |
退款到账(chunk-a) |
因此,**S1 标记本次结果的位置,chunk_id 标识知识库中的具体记录**。同一记录被多次检索出来时,其 chunk_id 不变。回答里的 [S1] 用来指向这一次响应中 label="S1" 的来源,方便核对原文;跨请求追踪同一个块则使用 chunk_id。
让提示词、模型、解析器依次执行
提示词模板保存回答要求,调用时填入 context 和 question。模型返回消息对象,StrOutputParser 从中取出文字。继续看 rag.py 的问答类:
1 | from langchain_chroma import Chroma |
RagService 是本例定义的类,创建时接收知识库和聊天模型对象;BaseChatModel 是聊天模型的公共基类。system 消息规定回答规则,human 消息放资料和问题,模板字段与 invoke() 的字典键对应。
prompt | model | StrOutputParser() 是 LangChain 的 LCEL 组合方式,三个组件依次处理输入:
1 | {"context": "原文与来源", "question": "退款什么时候到账?"} |
重点看 ask():先检索,后拼资料,再生成。它同时返回回答和这一次检索得到的 documents,后面构造来源列表时直接复用,不再查一次。解析器只取文字,不检查回答是否符合原文。
4. 用 FastAPI 接收问题、返回结果
启动时创建问答对象
现在把 Python 问答接到 HTTP。main.py 用 Pydantic 定义请求和响应:AskRequest 接收 question,先去首尾空白,再要求长度为 1~500 字符;AskResponse 返回 answer 和 sources。每条 Source 保存标签、块 ID、文件名、可空的页码与章节,以及原文预览。
这些类型的完整定义在包内。下面只展示 main.py 的启动函数与路由节选,理解连接关系时重点看 app.state.rag 和 rag.ask()。
Embedding 模型与知识库在启动时加载,通过 FastAPI 的 lifespan 保存到应用状态,供请求复用:Lifespan 说明
1 | # main.py 节选:相关导入与请求、响应类型已在包内定义 |
@asynccontextmanager 来自 Python 的 contextlib,让 FastAPI 能按生命周期调用此函数;yield 前的代码在服务接收请求前执行。app.state.rag 是本例保存问答对象的位置,每个服务进程初始化一次。
ChatOpenAI 来自 langchain-openai,将生成模型接入 LangChain。本例明确使用 Chat Completions 接口;timeout=30 是模型 HTTP 调用的超时参数,max_retries=0 表示失败后不自动重试。ChatOpenAI 说明
路由只调用问答,再整理来源
下面是同一文件的完整路由函数节选。Request、HTTPException 来自 FastAPI;EmbeddingInputTooLong 是 common.py 的编码长度错误,APIError 是模型 SDK 的调用错误。
1 |
|
FastAPI 把 JSON 解析成 payload,将校验后的问题交给 rag.ask()。循环按同样的顺序生成来源标签;模型读完整块,客户端的 excerpt 只预览前 160 个字符,没有页码或章节时返回 null。
本例路由使用普通 def,因为编码、检索和 invoke() 都是同步调用。FastAPI 会在线程池中执行它;仅改成 async def 不会让这些调用自动异步化。同步与异步路由说明
5. 跑起来,再用原文检查答案
在完成建库的同一终端配置模型并启动服务。需要填写自己能调用、支持 Chat Completions 文本消息的模型与密钥:
1 | export OPENAI_API_KEY='替换为自己的密钥' |
Windows PowerShell 使用 $env:OPENAI_API_KEY='...' 与 $env:OPENAI_MODEL='...' 设置环境变量。默认使用官方服务,无需设置 OPENAI_BASE_URL;访问符合该 API 规范的自有服务时,可设置此变量,但仍需确认接口兼容性。
浏览器打开 http://127.0.0.1:8000/docs,展开 POST /ask,点击 Try it out 后提交问题;或者在另一个终端调用:
1 | curl -X POST 'http://127.0.0.1:8000/ask' \ |
成功返回 200,JSON 包含 answer 和 sources。回答可能是“仓库检查通过后,平台发起退款,通常需要三个工作日,节假日可能顺延。[S1]”。这是预期语义示例,实际措辞由模型决定。对照来源检查它是否保留了“检查通过后”这个前提,也不能将“平台已发起退款”理解为“银行账户已到账”。
再用下面几种输入检查行为:
| 问题或现象 | 观察什么 |
|---|---|
| “客服周日几点下班?” | 资料没有营业时间,模型应说明资料不足;即使检索返回 3 块,也不能据此编答案 |
| 空白问题、缺少字段或超过长度限制 | 返回 422;还会检查模型的 token 上限,token 是分词后使用的单位,与字符数不同 |
| 模型服务调用失败 | 返回 502,不要将错误信息当作成功回答 |
| “那运费呢?” | 本例没有聊天记忆,应写成“个人原因退货,运费由谁承担?”这样的独立问题 |
来源列表表示检索并交给模型的资料,不是已认证的答案证据。 模型可能只用部分资料,引用标签也可能写错,仍需核对原文。HTTP 成功与回答正确是两项检查。
读懂后可以将 k=3 改成 k=1,用同样的问题比较原文与回答:少取一块漏掉了什么,多取一块是否补充了依据?这比只看回答长短,更容易判断检索有没有帮助。
参考资料
- RAG from Scratch:第 1—4 部分:索引、检索与生成的分步实践。
- LLM Powered Autonomous Agents:Memory:外部存储与检索的背景;本例执行固定流程,不展开自主 Agent。
- 动手学大模型应用开发:知识库、RAG 应用:从文档到问答的组织方式。
- 面向开发者的 LLM 入门教程:基于文档的问答:文档片段与来源的使用。