LangChain
19 · 综合项目:完整 RAG 系统
把 09~18 章的组件焊成一个真能跑的系统:建库与问答分离、向量+阈值检索、溯源角标、库外拒答、多轮记忆、FastAPI 三端点,附三路检索质量实测与 19 个 pytest 用例
- LangChain
- Python
- RAG
本章在干什么
一句话:从零搭出 python-rag 项目,把 09~18 章的零件焊成一台能交付的整机。
为什么需要它——09~18 章每章都给了可运行的片段,但它们从没被组装起来:13 章的完整链用 InMemoryVectorStore,每次启动都把全量文档重新 embedding 一遍,文档一多冷启动几分钟、费用重复花;18 章的 server.py里检索工具是 return "……检索到的原文……" 占位符,流式与记忆是真的,唯独检索本身是假的。零件全有了,手里却没有一台整机。本章就是总装车间:加载器、切分器、向量库、检索策略、agent、FastAPI,装进一个 12 个文件的项目。
跟着做完,你会得到:建库一次、问答复用(离线 ingest.py 跑一次,在线只查不建,不再重复花 embedding 的钱);阈值拒答(命中 0 条不调 LLM——物理上不可能幻觉);溯源角标(回答带 [1][2],sources 定位到文件 + 页 + 字符偏移);多轮记忆(checkpointer 按 session 隔离,指代能解析,换 session 立刻失忆);FastAPI 三端点流式;19 个 pytest 用例按「是否花钱调 API」分三档,守住以上全部行为。
关于代码来源,先说清楚:本章引用的 python-rag/ 项目不随仓库附带——它是你跟着下面的步骤逐步敲出来的最终产物。每个步骤给出该文件的全量代码,标 📄 的代码块就是要新建的文件,照抄即可;每步末尾有 ✅ 阶段验证,命令加预期输出,跑通再进下一步。
本章所有代码在 macOS arm64 + Python 3.14.4 上实测跑通,每个数字都是真实输出,不是示意。
项目全景
先看整体:一条离线建库流水线,一条在线问答链路,中间用 Qdrant 里的向量索引衔接。
为什么必须分离:建库要跑 OCR、调 embedding API,是花钱又花时间的一次性动作;问答每请求都要走一遍检索,必须快。混在一起的话每次启动都重新 embedding 全量文档——文档一多,冷启动几分钟,费用重复花(11 章向量库一节的动机,在这里落地成代码结构)。
代码侧共 12 个文件(下面每步都会建出来),依赖方向单向:config ← models ← loaders/retrieval ← rag ← server,没有循环导入——python-base 17 章讲的工程化原则,在这里是真实约束而不是练习。
从零一步步搭建
共 11 步(第 0~10 步):先地基(config / models),再数据侧(loaders / ingest),再检索侧(retrieval / calibrate),最后应用侧(prompts / rag / server / evaluate)。每步结构:📄 全量代码 → 本步引入的 API → ✅ 阶段验证。
第 0 步:准备——目录、依赖、Qdrant、语料
mkdir python-rag && cd python-rag
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
mkdir data db
📄 文件:requirements.txt(新建)
langchain # create_agent 等主 API(17 章)
langchain-community # TextLoader / PyPDFLoader / BM25Retriever(09/12 章)
langchain-classic # EnsembleRetriever 只在这个包里有(12 章)
langchain-openai # ChatOpenAI / OpenAIEmbeddings(03/11 章)
langchain-qdrant # QdrantVectorStore(11 章)
langchain-text-splitters # RecursiveCharacterTextSplitter(10 章)
qdrant-client # Qdrant 官方客户端;来源过滤用它的 models 子模块
rank_bm25 # 进程内 BM25(12 章)
jieba # 中文分词:BM25 必须自己切词(12 章)
pypdf # PyPDFLoader 的 PDF 解析后端(09 章)
pypdfium2 # PDF 渲染成图片,OCR 前置;to_pil() 另需 pillow(09 章)
rapidocr # OCR 引擎;Python ≥3.13 用统一包,喂图需 numpy(09 章)
python-dotenv # 读 .env
fastapi uvicorn # Web 框架与 ASGI 服务器(18 章)
requests # 冒烟客户端读流
pytest # 测试
pip install -r requirements.txt # 实测项目的 venv 由 uv 管理,uv pip install 等价
📄 文件:.env.example(新建)
GLM_BASE_URL=https://你的中转端点/v3
GLM_API_KEY=你的key
GLM_MODEL_ID=glm-5.3
EMBEDDING_ID=embedding-3
QDRANT_URL=http://localhost:6333
cp .env.example .env # 填入真实值;.env 含密钥,不能提交
printf '.env\ndb/\nqdrant_storage/\n.venv/\n__pycache__/\n' > .gitignore
起 Qdrant(11 章同款命令,数据挂 volume,容器删了数据还在):
docker run -d --name qdrant-rag \
-p 6333:6333 -p 6334:6334 \
-v $(pwd)/qdrant_storage:/qdrant/storage \
qdrant/qdrant
最后,把 09 章「配套数据下载」的 5 个语料(qiu.txt、gbk文件.txt、report.pdf、novel.pdf、scan.pdf)放进 data/——后面所有实测数字都基于这 5 个文件。
本步引入的库:见 requirements.txt 内联注释,逐行标了对应章节。
✅ 阶段验证(依赖、Qdrant、语料三样就绪):
python -c "import langchain, qdrant_client, jieba, fastapi, rapidocr; print('deps ok')"
# 预期:deps ok
curl http://localhost:6333/collections
# 预期:{"result":{"collections":[]},"status":"ok",...}
# collections 是空数组——对的,库还没建,第 4 步才会有;ls data/ 应见 5 个语料文件
第 1 步:config.py——所有可调项集中一处
📄 文件:config.py(新建)
"""所有可调项集中一处:路径、模型名、分块参数、检索参数。"""
import os
from pathlib import Path
from dotenv import load_dotenv
# 路径以 __file__ 为基准,不依赖「从哪个目录启动」(否则 ingest 与 pytest 的相对路径会打架)
BASE_DIR = Path(__file__).resolve().parent
load_dotenv(BASE_DIR / ".env")
DATA_DIR = BASE_DIR / "data"
DB_DIR = BASE_DIR / "db"
BM25_CACHE = DB_DIR / "bm25_corpus.json" # BM25 语料缓存
# 模型:名字从 .env 读,换模型不改代码(03 章的约定)
GLM_BASE_URL = os.environ["GLM_BASE_URL"]
GLM_API_KEY = os.environ["GLM_API_KEY"]
GLM_MODEL_ID = os.environ["GLM_MODEL_ID"]
EMBEDDING_ID = os.environ["EMBEDDING_ID"]
# 向量库:Qdrant 是独立服务,数据落在 docker volume 里(11 章)
QDRANT_URL = os.getenv("QDRANT_URL", "http://localhost:6333")
QDRANT_COLLECTION = os.getenv("QDRANT_COLLECTION", "rag")
CHUNK_SIZE = 400
CHUNK_OVERLAP = 80
TOP_K = 4
ENSEMBLE_WEIGHTS = [0.4, 0.6] # 混合检索两路权重,BM25 在前、向量在后
SCORE_THRESHOLD = 0.3770 # 由 calibrate.py 实测标定,见第 6 步
三个设计细节:
CHUNK_SIZE用 400 而不是 1.x 默认的 4000:本语料总共才 4248 字,4000/200 会导致「整篇一块」,检索粒度等于全文检索(10 章调参建议的实际应用)。QDRANT_URL从环境变量读,默认本机——11 章说独立向量库的好处之一就是「多个脚本、多个应用共享同一个库」,换部署地址只改.env。SCORE_THRESHOLD的 0.3770 不是拍脑袋:第 6 步会把它标定出来,首次搭建先照抄,跑完标定你会得到同一个数。
本步引入的 API:pathlib.Path(__file__ 基准路径)、load_dotenv、os.getenv(带默认值,与 os.environ[...] 的「必须有」形成两档)。
✅ 阶段验证:
python -c "import config; print(config.CHUNK_SIZE, config.SCORE_THRESHOLD, config.QDRANT_COLLECTION)"
# 预期:400 0.3770 rag
第 2 步:models.py——模型工厂与 429 重试
embedding 与 chat 各只有一处定义,全项目从这取;模块级缓存让服务启动后只初始化一次。
📄 文件:models.py(新建)
"""模型工厂:embedding 与 chat 各一处定义,进程内单例。"""
import functools
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
import config
@functools.lru_cache(maxsize=1)
def get_llm() -> ChatOpenAI:
return ChatOpenAI(
base_url=config.GLM_BASE_URL,
api_key=config.GLM_API_KEY,
model=config.GLM_MODEL_ID,
)
@functools.lru_cache(maxsize=1)
def get_embeddings() -> OpenAIEmbeddings:
return OpenAIEmbeddings(
base_url=config.GLM_BASE_URL,
api_key=config.GLM_API_KEY,
model=config.EMBEDDING_ID,
check_embedding_ctx_length=False, # 非 OpenAI 端点必须,原因见 11 章
max_retries=6, # embedding 端点有间歇性 429,默认 2 次不够,见下文
request_timeout=60,
)
max_retries=6 不是防御性编程,是被真实故障教育出来的。跑测试时撞到:
openai.RateLimitError: Error code: 429 - {'error': {'message': '余额不足或无可用资源包,请充值。'}}
逐端点探测后发现是限流抖动,不是真没额度:
=== /embeddings 连测 3 次 ===
第1次 -> HTTP 429 余额不足或无可用资源包,请充值。
第2次 -> HTTP 429 余额不足或无可用资源包,请充值。
第3次 -> HTTP 200 OK
=== /chat/completions 连测 3 次 ===
第1次 -> HTTP 200 OK
第2次 -> HTTP 200 OK
第3次 -> HTTP 200 OK
chat 端点从不 429,说明账号有钱;是中转端点对 embedding 模型的限流。错误信息写「余额不足」有误导性——看到 429 先分辨是限流还是真欠费,方法是隔几秒重试并对照其他端点。OpenAIEmbeddings 默认 max_retries=2,对这个抖动不够;调到 6 让 SDK 指数退避。实测 8 连击(默认 2 次时 3 连击就撞 429):
第1次: OK 维度=2048 耗时=0.45s
第2次: OK 维度=2048 耗时=0.82s
第3次: OK 维度=2048 耗时=0.64s
第4次: OK 维度=2048 耗时=0.30s
...
成功 8/8
8 次全过,其中几次耗时明显变长(0.82s、1.00s)——那正是退避重试在工作。
本步引入的 API:ChatOpenAI / OpenAIEmbeddings 换 base_url 接 GLM(03/11 章)、check_embedding_ctx_length=False、max_retries + request_timeout(SDK 指数退避)、functools.lru_cache(函数级单例)。
✅ 阶段验证(调一次 embedding,顺带验证 .env 四个变量都能读到):
python -c "import models; e = models.get_embeddings(); print(len(e.embed_query('维度探测')))"
# 预期:2048(11 章实测 embedding-3 输出 2048 维;这一步就是那个「跑一次拿到真实值」的确认)
第 3 步:loaders.py——多源加载与编码坑
loaders.py 把三种来源统一成同构的 Document,下游切分入库就不必为来源写分支。其中 txt 的编码处理有一个文档没说过的坑——先用 TextLoader 的官方开关试试 GBK 文件:
docs = TextLoader("data/gbk文件.txt", autodetect_encoding=True).load()
# ModuleNotFoundError: No module named 'chardet'
autodetect_encoding=True 依赖 chardet 包,没装就直接崩。09 章教的 AutoEncodingTextLoader(自己降级 utf-8→gbk)反而更稳,零额外依赖——本项目用的就是它。扫描件走 OCR(09 章的 load_scanned_pdf,pypdfium2 渲染 + RapidOCR 认字),OCR 引擎做成懒加载:不碰扫描件的调用方(如纯文本测试)完全跳过这笔启动开销。PDF 路线自动选择:先按文字型抽,所有页都是空字符串就判定为扫描件改走 OCR——否则空 Document 入库,就是 09 章说的「明明入库了却永远搜不到」的隐形事故。
📄 文件:loaders.py(新建)
"""多源加载:编码自适应 txt / 文字型 PDF / 扫描件 OCR,统一成 Document。"""
from pathlib import Path
from langchain_community.document_loaders import PyPDFLoader, TextLoader
from langchain_core.documents import Document
import config
_ocr = None
def get_ocr():
"""首次调用载入模型(约 2 秒),之后全进程复用。"""
global _ocr
if _ocr is None:
from rapidocr import RapidOCR # 延迟导入:不碰扫描件就不付这笔开销
_ocr = RapidOCR()
return _ocr
def load_scanned_pdf(path: str, scale: float = 2.0) -> list[Document]:
"""OCR 整本扫描 PDF,返回与 PyPDFLoader 同结构的 Document(每页一个)。"""
import numpy as np # 图像转数组喂给 OCR
import pypdfium2 as pdfium # PDF 渲染成图片
pdf = pdfium.PdfDocument(path)
docs = []
for i, page in enumerate(pdf):
img = page.render(scale=scale).to_pil()
result, _ = get_ocr()(np.array(img)) # 每项 [坐标, 文本, 置信度],取第 2 项
text = "\n".join(item[1] for item in result) if result else ""
docs.append(Document(page_content=text, metadata={"source": path, "page": i}))
return docs
class AutoEncodingTextLoader(TextLoader):
"""先按 UTF-8 读,失败自动降级 GBK。metadata 里记下实际用的编码。"""
def lazy_load(self):
for enc in ("utf-8", "gbk"):
try:
with open(self.file_path, encoding=enc) as f:
text = f.read()
yield Document(
page_content=text,
metadata={"source": self.file_path, "encoding": enc},
)
return
except UnicodeDecodeError:
continue
raise RuntimeError(f"utf-8/gbk 都读不了: {self.file_path}")
def load_file(path: Path) -> tuple[list[Document], str]:
"""加载单个文件,返回 (docs, 路线标签 text / pdf / ocr)。source 归一化见下文。"""
if path.suffix.lower() == ".txt":
docs, kind = AutoEncodingTextLoader(str(path)).load(), "text"
else:
docs = PyPDFLoader(str(path)).load()
if any(d.page_content.strip() for d in docs):
kind = "pdf" # 文字型:至少有一页抽得出字
else:
docs, kind = load_scanned_pdf(str(path)), "ocr" # 全空 = 扫描件
for d in docs:
d.metadata["source"] = path.name # qiu.txt / report.pdf,见下文
return docs, kind
def load_corpus(data_dir: Path | None = None) -> list[Document]:
"""加载整个 data 目录拍平返回(ingest 要逐文件统计,用 load_file 自己循环)。"""
docs: list[Document] = []
for path in sorted((data_dir or config.DATA_DIR).iterdir()):
if path.suffix.lower() in (".txt", ".pdf"):
docs.extend(load_file(path)[0])
return docs
metadata 里 source 存文件名,不要存绝对路径
TextLoader / PyPDFLoader 默认把传入的路径原样写进 metadata["source"],本项目加载时传的是绝对路径,于是存进去的是:
/Users/ruidong/Desktop/python/python-rag/data/report.pdf
两个问题:库随目录移动或换机器后 metadata 就失效;更直接的是 Qdrant 原生 filter 用 MatchValue 精确匹配,存绝对路径就没法用 "report.pdf" 命中(第 5 步的来源过滤全靠它)。所以在加载出口统一归一化(三个 loader 都不用改)——就是 load_file 末尾那两行。
本步引入的 API:TextLoader.lazy_load 重写(继承做编码降级)、PyPDFLoader、pypdfium2 render().to_pil() + RapidOCR(09 章 load_scanned_pdf 同款)、metadata["source"] 归一化。
✅ 阶段验证(加载 5 个文件,含 GBK 与扫描件):
python -c "
import loaders
docs = loaders.load_corpus()
print(len(docs), sorted({d.metadata['source'] for d in docs}))
"
# 预期(可推导,与第 4 步建库实测一致):
# 28 ['gbk文件.txt', 'novel.pdf', 'qiu.txt', 'report.pdf', 'scan.pdf']
# 28 = 1(qiu) + 1(gbk) + 12(novel) + 12(report) + 2(scan·OCR)
第 4 步:ingest.py——建库(离线一次)
建库主流程五步:加载 → 切分 → 清旧库 → embedding 写入 → 缓存 BM25 语料。只有第 4 步花钱。
📄 文件:ingest.py(新建)
"""建库(离线跑一次):加载 → 切分 → embedding → 写入 Qdrant → 缓存 BM25 语料。
本文件只建库不问答;之后所有查询走 retrieval.py(建库/问答分离)。
"""
import json
import time
from langchain_qdrant import QdrantVectorStore
from langchain_text_splitters import RecursiveCharacterTextSplitter
from qdrant_client import QdrantClient
import config
from loaders import load_file
from models import get_embeddings
def main() -> None:
print(f"[1/5] 加载语料 {config.DATA_DIR}")
docs = []
for path in sorted(config.DATA_DIR.iterdir()):
if path.suffix.lower() not in (".txt", ".pdf"):
continue
t0 = time.perf_counter()
loaded, kind = load_file(path)
chars = sum(len(d.page_content) for d in loaded)
print(f" {path.name:<12} {kind:<5} {len(loaded):>3} 块 {chars:>5} 字 "
f"{time.perf_counter() - t0:.2f}s")
docs.extend(loaded)
print(f" 合计 {len(docs)} 个原始 Document,"
f"{sum(len(d.page_content) for d in docs)} 字")
docs = [d for d in docs if d.page_content.strip()] # 空内容兜底,见下文
print(f"[2/5] 切分 chunk_size={config.CHUNK_SIZE} overlap={config.CHUNK_OVERLAP}")
splitter = RecursiveCharacterTextSplitter( # add_start_index:记录块起始位置(10 章)
chunk_size=config.CHUNK_SIZE,
chunk_overlap=config.CHUNK_OVERLAP,
add_start_index=True,
)
chunks = splitter.split_documents(docs)
print(f" 切出 {len(chunks)} 块")
print(f"[3/5] 清理旧 collection {config.QDRANT_COLLECTION}")
client = QdrantClient(url=config.QDRANT_URL)
if client.collection_exists(config.QDRANT_COLLECTION): # 幂等,见下文
client.delete_collection(config.QDRANT_COLLECTION)
print(" 已删除(重建)")
else:
print(" 不存在,直接创建")
print(f"[4/5] embedding({config.EMBEDDING_ID})并写入 Qdrant")
t0 = time.perf_counter()
QdrantVectorStore.from_documents(
chunks, embedding=get_embeddings(),
url=config.QDRANT_URL, collection_name=config.QDRANT_COLLECTION,
)
embed_seconds = time.perf_counter() - t0
print("[5/5] 缓存 BM25 语料")
config.DB_DIR.mkdir(exist_ok=True)
config.BM25_CACHE.write_text(
json.dumps(
[{"page_content": c.page_content, "metadata": c.metadata} for c in chunks],
ensure_ascii=False,
),
encoding="utf-8",
)
info = client.get_collection(config.QDRANT_COLLECTION)
vectors = info.config.params.vectors
params = vectors[""] if isinstance(vectors, dict) else vectors # 兼容未命名向量
by_source: dict[str, int] = {}
for c in chunks:
by_source[c.metadata["source"]] = by_source.get(c.metadata["source"], 0) + 1
dim, distance = params.size, str(params.distance).split(".")[-1]
print(f" Qdrant → {config.QDRANT_URL} / {config.QDRANT_COLLECTION}"
f"({info.points_count} 点,{dim} 维,{distance})")
print(f" BM25 语料 → {config.BM25_CACHE}")
print(f" 各源块数: {by_source}")
print(f"\n建库完成:{len(chunks)} 块,Qdrant {info.points_count} 点"
f"({dim} 维 {distance}),embedding 耗时 {embed_seconds:.2f}s")
if __name__ == "__main__":
main()
✅ 阶段验证(建库,全程约 6 秒,实测输出)——跑 python ingest.py:
[1/5] 加载语料 /Users/ruidong/Desktop/python/python-rag/data
qiu.txt text 1 块 425 字 0.00s
gbk文件.txt text 1 块 226 字 0.00s
novel.pdf pdf 12 块 2307 字 0.07s
report.pdf pdf 12 块 1132 字 0.02s
scan.pdf ocr 2 块 158 字 1.00s
合计 28 个原始 Document,4248 字
[2/5] 切分 chunk_size=400 overlap=80
切出 29 块
[3/5] 清理旧 collection rag
已删除(重建)
[4/5] embedding(embedding-3)并写入 Qdrant
[5/5] 缓存 BM25 语料
Qdrant → http://localhost:6333 / rag(29 点,2048 维,Cosine)
BM25 语料 → db/bm25_corpus.json
各源块数: {'qiu.txt': 2, 'gbk文件.txt': 1, 'novel.pdf': 12, 'report.pdf': 12, 'scan.pdf': 2}
建库完成:29 块,Qdrant 29 点(2048 维 Cosine),embedding 耗时 2.66s
curl http://localhost:6333/collections/rag
# 预期(可推导):result 里 "points_count":29——从数据库侧再确认一次
四个值得注意的点:
- 第 3 步的「清理旧 collection」是必须的:Qdrant 是持久化服务,重跑建库不会覆盖而是追加,点数会翻倍、同一块被检索到两次。FAISS 的
save_local是直接覆盖目录,没这个问题——换到服务型向量库后必须自己保证幂等。 - 28 个原始 Document 切出 29 块:只有
qiu.txt(425 字)被切成 2 块,其余每个源 Document 本身就不超过 400 字,切不动。块数不等于「文件数 × 页数」,取决于原文长度与chunk_size的关系。 - OCR 1.00 秒(模型已加载过;首次约 10 秒)。
scan.pdf若被PyPDFLoader读会得到 2 个空字符串 Document——不报错、不警告,入库了也永远搜不到(09 章的「隐形事故」),所以建库末尾有一道过滤:docs = [d for d in docs if d.page_content.strip()]。 - 为什么要缓存
bm25_corpus.json:rank_bm25是进程内的,没有持久化能力,每次启动都要拿原文重建索引。缓存一份切分结果,服务启动直接重建 BM25,不必重新加载语料、更不必重新 embedding(那要花钱)。向量那半边由 Qdrant 自己持久化,不需要这份缓存。
另一个溯源细节:add_start_index=True 让每块记下在源 Document 里的起始位置,但注意它相对源 Document 而不是整个文件——novel.pdf 每页是独立 Document,每页第一块的 start_index 都是 0,要靠 source + page + start_index 三者合起来才唯一定位。
本步引入的 API:RecursiveCharacterTextSplitter(add_start_index=True)(10 章)、QdrantClient.collection_exists / delete_collection(幂等)、QdrantVectorStore.from_documents(11 章,全项目唯一发生 embedding 的地方)。
第 5 步:retrieval.py——向量 / BM25 / RRF 与来源过滤
retrieval.py 提供三条路,对应 11、12 章:
| 路 | 实现 | 带分数 | 能阈值化 |
|---|---|---|---|
| 向量 | Qdrant similarity_search_with_score(Cosine) | 是(相似度,越大越近) | 能 |
| 关键词 | BM25Retriever + jieba.lcut | 否(封装层未暴露) | 不能 |
| 混合 | EnsembleRetriever RRF 融合 | 否 | 不能 |
📄 文件:retrieval.py(新建)
"""检索:向量(阈值/来源过滤)、BM25、RRF 混合,对应 11、12 章。
注意:本文件同时用到项目 models.py 与 qdrant_client 的 models 子模块,后者取别名 qdrant_models。"""
import functools
import json
import jieba # 中文分词:BM25 必须自己切词(12 章)
from langchain_classic.retrievers import EnsembleRetriever # 混合检索只在这有
from langchain_community.retrievers import BM25Retriever # 从 community 导才无警告
from langchain_core.documents import Document
from langchain_qdrant import QdrantVectorStore
from qdrant_client import QdrantClient
from qdrant_client import models as qdrant_models
import config, models
@functools.lru_cache(maxsize=1)
def get_client() -> QdrantClient:
return QdrantClient(url=config.QDRANT_URL)
@functools.lru_cache(maxsize=1)
def get_vectorstore() -> QdrantVectorStore:
return QdrantVectorStore(
client=get_client(),
collection_name=config.QDRANT_COLLECTION,
embedding=models.get_embeddings(),
)
def source_filter(source: str) -> qdrant_models.Filter:
"""只在指定来源里搜——过滤下沉到数据库侧,不是取回再筛。"""
return qdrant_models.Filter(
must=[qdrant_models.FieldCondition(
key="metadata.source", match=qdrant_models.MatchValue(value=source)
)]
)
def vector_search(query, k=None, source=None):
return get_vectorstore().similarity_search_with_score(
query,
k=k or config.TOP_K,
filter=source_filter(source) if source else None,
)
@functools.lru_cache(maxsize=1)
def get_bm25() -> BM25Retriever:
"""从缓存重建 BM25:不重新加载语料,更不重新 embedding。"""
corpus = json.loads(config.BM25_CACHE.read_text(encoding="utf-8"))
docs = [Document(page_content=e["page_content"], metadata=e["metadata"])
for e in corpus]
retriever = BM25Retriever.from_documents(
docs, preprocess_func=lambda x: jieba.lcut(x)
)
retriever.k = config.TOP_K
return retriever
@functools.lru_cache(maxsize=1)
def get_hybrid() -> EnsembleRetriever:
"""RRF 混合:注意它不带分数,没法阈值化(见下文实测)。"""
return EnsembleRetriever(
retrievers=[
get_bm25(),
get_vectorstore().as_retriever(search_kwargs={"k": config.TOP_K}),
],
weights=config.ENSEMBLE_WEIGHTS,
)
def search_with_threshold(query, k=None, threshold=None, source=None):
"""主检索:向量 + 相似度阈值。Qdrant(Cosine)返回相似度,越大越近,用 >=。"""
limit = threshold if threshold is not None else config.SCORE_THRESHOLD
results = vector_search(query, k, source=source)
if limit is None:
return results
return [(doc, score) for doc, score in results if score >= limit]
def retrieve_hits(query, k=None, source=None):
"""rag.py 的入口:阈值过滤后的命中列表 [(doc, score), ...]。"""
return search_with_threshold(query, k=k, source=source)
def collection_stats() -> dict:
"""/health 的规模信息。这是 Qdrant 的 API——FAISS 的 index.ntotal /
index.reconstruct 在这不存在,换库不改这里会 AttributeError 起不来服务。"""
info = get_client().get_collection(config.QDRANT_COLLECTION)
vectors = info.config.params.vectors
params = vectors[""] if isinstance(vectors, dict) else vectors # 兼容未命名向量
return {"points": info.points_count, "dim": params.size,
"distance": str(params.distance).split(".")[-1]}
两个版本坑,12 章提过、在这里真的会踩:一是 BM25 必须自己分词——不传 preprocess_func 的话 rank_bm25 按空格切词,中文整句会变成一个「词」,检索直接失效(上面 jieba.lcut 那行);二是导入路径——BM25Retriever 要从 langchain_community.retrievers 导,从 langchain_classic 导会打弃用警告,而 EnsembleRetriever 只在 langchain_classic 里有,所以两个包都得装。
✅ 阶段验证(来源过滤,下沉数据库侧):
python -c "
import retrieval
hits = retrieval.vector_search('解析层选用了什么库', k=2, source='report.pdf')
print('=== Qdrant 原生 filter(只在 report.pdf 里搜,k=2)===')
print('返回条数:', len(hits))
for doc, score in hits:
print(' %.4f %s page=%s' % (score, doc.metadata['source'], doc.metadata.get('page')))
print('全部来自 report.pdf:', all(d.metadata['source'] == 'report.pdf' for d, _ in hits))
"
=== Qdrant 原生 filter(只在 report.pdf 里搜,k=2)===
返回条数: 2
0.5286 report.pdf page=2
0.4523 report.pdf page=4
全部来自 report.pdf: True
「过滤交给 Qdrant,不是先取 top-k 再在 Python 里筛」——区别在召回:先取 k 条再筛,会出现「取了 4 条、过滤后只剩 1 条」甚至 0 条;交给数据库筛则是「在目标来源里取最相似的 k 条」,所以 k=2 能返回满 2 条。这就是 11 章说 Qdrant「原生支持 metadata 过滤」的实际含义,也是选独立向量库而非 FAISS 的主要收益之一。前提是 metadata["source"] 存文件名而非绝对路径(MatchValue 精确匹配),归一化见第 3 步。
三路检索质量对比
evaluate.py(第 10 步)用 9 个库内问题 + 3 个库外问题跑三路(k=4),结果提前贴在这里——它决定主检索选哪条路:
=== 检索质量评估(k=4,语料 29 块)===
检索路线 top1 命中 top-k 召回
----------------------------------------------------
向量(GLM embedding-3) 9/9 9/9
BM25(rank_bm25 + jieba) 9/9 9/9
混合(RRF 融合) 9/9 9/9
三路全是 9/9,分不出优劣。 这是个诚实的结果,原因有二:语料只有 29 块(小),且五个文件主题高度同源(都围绕「城南旧货市场 / 老周 / 收音机」),两路检索都能轻松命中。想看出差异需要更大、更杂的语料。
但混合检索有一个致命代价
库外问题的表现完全不同:
=== 库外问题:阈值拒答能力 ===
量子纠缠的数学证明是什么
向量最近相似度 0.3020(阈值 0.377) → 阈值过滤后剩 0 条 | 混合路仍返回 8 条
如何做红烧肉
向量最近相似度 0.2227(阈值 0.377) → 阈值过滤后剩 0 条 | 混合路仍返回 8 条
Python 的 GIL 是什么时候移除的
向量最近相似度 0.3106(阈值 0.377) → 阈值过滤后剩 0 条 | 混合路仍返回 7 条
混合检索拿不到分数,就没法阈值化——RRF 融合比较的是排名,库里再没有相关内容,它也照样返回「排名最靠前」的 7~8 条垃圾。模型拿着这些无关资料,很容易被带着编答案。所以主检索走向量 + 阈值(search_with_threshold),BM25 与混合保留按需切换。对 RAG 来说,「库里没有就如实说没有」比多召回几条更重要。
精确词场景:与 12 章结论不一致
12 章说「报错码、型号这类精确词对 embedding 是无语义的乱码,要靠 BM25 兜底」。本语料上实测未复现:
| 查询 | 向量 top1 | BM25 top1 |
|---|---|---|
SC-2026-1013(检测编号) | scan.pdf p1(相似度 0.5034)✓ | scan.pdf p1 ✓ |
PyPDFLoader(类名) | report.pdf p4(相似度 0.6255)✓ | report.pdf p2(相关但非最佳) |
pypdfium2(语料中不存在) | report.pdf p2(语义相近的 pypdf,0.5717) | scan.pdf / novel.pdf / qiu.txt(全无关) |
2048 维的 embedding-3 对符号串的表征能力比 12 章描述的场景强得多,精确词自己就命中了。反过来,词表外的查询 BM25 会诚实地返回垃圾(它只做字面匹配,匹配不上就按 IDF 乱排),而向量至少会给出语义相近的结果。结论:BM25 的价值要看语料和 embedding 模型,不是无条件成立——这也是 evaluate.py 存在的意义:别信任何通用结论,用自己的语料测。
本步引入的 API:similarity_search_with_score(带分数检索)、qdrant_client.models 的 Filter / FieldCondition / MatchValue、BM25Retriever.from_documents(preprocess_func=...)、EnsembleRetriever(RRF,权重顺序对应 retriever 顺序)。
第 6 步:calibrate.py——阈值标定,让系统能拒答
12 章说「阈值按自己的语料实测」,但没给方法。calibrate.py 就是那个方法:把「库里有答案」和「库里没答案」的问题各跑一遍,看两组分数分布的分界。
📄 文件:calibrate.py(新建)
"""阈值标定:实测「有答案 / 没答案」两组问题的分数分布,取分界中点当阈值。
换语料、换向量库后必须重跑,并把结果回填 config.SCORE_THRESHOLD。
"""
import config
import retrieval
ANSWERABLE = ["秋天的后园里长着什么树", "母亲腌咸菜的缸沿压着什么", # 有答案的 5 问
"收音机送修的申请单位是哪个", "技术科检测回执的编号是多少",
"老周在旧货市场捡到了什么"]
UNANSWERABLE = ["量子纠缠的数学证明是什么", "如何做红烧肉", # 没答案的 3 问
"Python 的 GIL 是什么时候移除的"]
def top1_score(query: str) -> tuple[float, str]:
doc, score = retrieval.vector_search(query, k=1)[0]
meta = doc.metadata
loc = str(meta.get("source", "?"))
if meta.get("page") is not None:
loc += f":p{meta['page']}"
return score, loc + f"@{meta.get('start_index', 0)}"
def main() -> None:
stats = retrieval.collection_stats()
print(f"=== 向量检索分数实测({stats['distance']},{stats['points']} 点 / "
f"{stats['dim']} 维)===")
with_hits = [(*top1_score(q), q) for q in ANSWERABLE]
without_hits = [(*top1_score(q), q) for q in UNANSWERABLE]
for tag, group in (("有答案", with_hits), ("无答案", without_hits)):
print()
for score, loc, q in group:
print(f"[{tag}] {score:.4f} {loc:<16} ← {q}")
with_scores = [s for s, _, _ in with_hits]
without_scores = [s for s, _, _ in without_hits]
print(f"\n有答案分数区间: {min(with_scores):.4f} ~ {max(with_scores):.4f}")
print(f"无答案分数区间: {min(without_scores):.4f} ~ {max(without_scores):.4f}")
# 自动判断方向:两组总和一比,就知道当前库返回的是相似度还是距离——
# 换向量库不用改这个脚本,重跑一次拿新阈值
threshold = (min(with_scores) + max(without_scores)) / 2
if sum(with_scores) > sum(without_scores):
print("\n结论:分数是【相似度】,越大越近;两组完全分开。")
print(f"过滤条件 score >= 阈值,建议 SCORE_THRESHOLD = {threshold:.4f}")
else:
print("\n结论:分数是【距离】,越小越近;两组完全分开。")
print(f"过滤条件 score <= 阈值,建议 SCORE_THRESHOLD = {threshold:.4f}")
print(f"(无答案最高 {max(without_scores):.4f} < 阈值 < "
f"有答案最低 {min(with_scores):.4f})")
if __name__ == "__main__":
main()
✅ 阶段验证(标定,实测输出)——跑 python calibrate.py,标定出的 0.3770 回填 config.py:
=== 向量检索分数实测(Cosine,29 点 / 2048 维)===
[有答案] 0.4805 qiu.txt@0 ← 秋天的后园里长着什么树
[有答案] 0.4435 novel.pdf:p5@0 ← 母亲腌咸菜的缸沿压着什么
[有答案] 0.6226 scan.pdf:p0@0 ← 收音机送修的申请单位是哪个
[有答案] 0.5906 scan.pdf:p1@0 ← 技术科检测回执的编号是多少
[有答案] 0.4794 gbk文件.txt@0 ← 老周在旧货市场捡到了什么
[无答案] 0.3020 gbk文件.txt@0 ← 量子纠缠的数学证明是什么
[无答案] 0.2227 novel.pdf:p7@0 ← 如何做红烧肉
[无答案] 0.3106 report.pdf:p9@0 ← Python 的 GIL 是什么时候移除的
有答案分数区间: 0.4435 ~ 0.6226
无答案分数区间: 0.2227 ~ 0.3106
结论:分数是【相似度】,越大越近;两组完全分开。
过滤条件 score >= 阈值,建议 SCORE_THRESHOLD = 0.3770
(无答案最高 0.3106 < 阈值 < 有答案最低 0.4435)
三个必须记住的事实:
- Qdrant(Cosine)返回的是相似度,越大越近——过滤条件是
score >= 阈值。这与 FAISS 正好相反(FAISS 返回距离、越小越近、过滤是score <= 阈值)。换向量库时这条最容易翻错:方向反了不会报错,只会静默地把好结果全过滤掉、或把垃圾全放进来。 - 阈值数值不能照抄别家的库:用 FAISS(L2 距离)跑同一份语料标定出来是
1.2460(越小越近),Qdrant(Cosine 相似度)是0.3770(越大越近),量纲完全不同。把 1.2460 当相似度阈值用,score >= 1.2460会把所有结果都挡掉(Cosine 相似度上限才 1.0),系统变成永远拒答——而且不报任何错,只表现为「什么都答不上来」。 - 两组分数完全不重叠(0.3106 < 0.4435),所以 0.3770 在本语料上是干净的。换语料必须重新标定。
本步引入的 API:vector_search(k=1) 取 top1 分数(标定的最小样本)、总和比较判分数方向、过滤逻辑在 retrieval.search_with_threshold(注意是 >=)。
第 7 步:prompts.py——防幻觉 prompt 与角标拼装
09 章说过 metadata 能支撑「引用角标 [1]、按来源过滤」,但全书没有任何一章实现过角标。prompts.py 补上:系统提示规定「只依据资料、无答案就明说、结论带角标、冲突分别标注」,build_context 把检索结果拼成带编号的资料块——角标才有依据。
📄 文件:prompts.py(新建)
"""防幻觉 prompt + 带编号的资料块拼装。"""
SYSTEM_PROMPT = """你是一个严谨的知识库问答助手。只依据「资料」回答,不得使用资料之外的知识。
规则:
1. 资料中没有答案时,直接回答「资料中没有相关内容」,不要猜测、不要编造。
2. 每个结论后面标注来源编号,如 [1]、[2][3],编号对应资料列表的序号。
3. 资料之间冲突时,说明冲突并分别标注来源。
4. 回答简洁,先给结论,再给必要细节。不要复述资料全文。
资料:
{context}"""
NO_CONTEXT_ANSWER = "资料中没有相关内容。"
def build_context(hits: list) -> str:
"""把检索结果拼成带编号的资料块,附来源与页码——角标才有依据。"""
parts = []
for i, (doc, score) in enumerate(hits, start=1):
meta = doc.metadata
src = str(meta.get("source", "?")).split("/")[-1]
loc = src
if meta.get("page") is not None:
loc += f" 第{meta['page'] + 1}页" # page 存储从 0 起,展示 +1
parts.append(f"[{i}](来源:{loc})\n{doc.page_content.strip()}")
return "\n\n".join(parts)
两个设计点:资料走 system 而不是 human——资料与提问分开(第 8 步组装成 system + human 两条消息),模型更不容易把资料当成用户的话来回应;build_context 的编号 i 与第 8 步 sources 列表的 index 一一对应,前端可把角标渲染成可点击的出处链接。
本步引入的 API:无新第三方 API——{context} 占位符由第 8 步的 ChatPromptTemplate 填充;page「0 起存储、展示 +1」的换算在这做。
✅ 阶段验证(角标拼接,用假 Document 不花钱):
python -c "
import prompts
from langchain_core.documents import Document
print(prompts.build_context(
[(Document(page_content='测试块正文', metadata={'source': 'a.pdf', 'page': 2}), 0.9)]))
"
# 预期(可推导:格式完全由本函数决定):
# [1](来源:a.pdf 第3页)
# 测试块正文
第 8 步:rag.py——chain 与 agent 双模式
rag.py 提供两种模式,对应 13 章与 18 章:
| 模式 | 结构 | 能力 |
|---|---|---|
ask() | LCEL chain(13 章) | 单轮、可控、能按阈值拒答、带溯源 |
chat() | agent + checkpointer(18 章) | 多轮记忆,模型自己决定何时检索 |
📄 文件:rag.py(新建)
"""编排:ask() 是 13 章的 LCEL chain(单轮溯源),chat() 是 18 章的 agent(多轮记忆)。"""
from pydantic import BaseModel, Field
from langchain.agents import create_agent
from langchain.tools import tool
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langgraph.checkpoint.memory import InMemorySaver
import prompts, retrieval
from models import get_llm
class SourceRef(BaseModel):
"""一条来源引用:index 对应资料块编号,前端可渲染成可点击出处。"""
index: int
source: str
page: int | None = None
start_index: int | None = None
excerpt: str = Field(description="原文摘录(前 100 字)")
def _to_refs(hits: list) -> list[SourceRef]:
return [
SourceRef(index=i, source=str(d.metadata.get("source", "?")),
page=d.metadata.get("page"), start_index=d.metadata.get("start_index"),
excerpt=d.page_content.strip()[:100])
for i, (d, _score) in enumerate(hits, start=1)
]
_ask_chain = None
def get_ask_chain():
"""chain 模式:资料进 system(第 7 步的 SYSTEM_PROMPT),问题进 human。"""
global _ask_chain
if _ask_chain is None:
messages = [("system", prompts.SYSTEM_PROMPT), ("human", "{question}")]
_ask_chain = ChatPromptTemplate.from_messages(messages) | get_llm() | StrOutputParser()
return _ask_chain
def ask(question: str, k: int | None = None, source: str | None = None) -> dict:
"""单轮问答。拒答是短路的:命中 0 条不调 LLM——物理上不可能幻觉。"""
hits = retrieval.retrieve_hits(question, k=k, source=source)
if not hits:
return {"answer": prompts.NO_CONTEXT_ANSWER, "sources": [], "hits_count": 0}
answer = get_ask_chain().invoke({
"context": prompts.build_context(hits),
"question": question,
})
return {"answer": answer, "sources": _to_refs(hits), "hits_count": len(hits)}
class RetrieveInput(BaseModel):
"""检索工具的入参 schema:让模型知道 query 该怎么填。"""
query: str = Field(description="要检索的独立问题。多轮对话里先把指代补全再传")
@tool("retrieve_knowledge", args_schema=RetrieveInput)
def retrieve_tool(query: str) -> str:
"""从知识库检索与问题相关的资料。需要事实性信息时调用。"""
hits = retrieval.retrieve_hits(query)
if not hits:
return "(知识库中没有相关资料)"
return prompts.build_context(hits)
_agent = None
def get_agent():
"""模块级缓存,服务启动时构建一次:embedding 客户端与 agent 都有初始化开销。"""
global _agent
if _agent is None:
_agent = create_agent(
get_llm(),
system_prompt=(
"你是知识库问答助手。用 retrieve_knowledge 工具查资料后再回答,"
"只依据检索到的资料作答并在结论后标注 [1][2] 来源角标;资料里没有就"
"回答「资料中没有相关内容」;用户用指代(它/那个)时,先结合历史补全再检索。"
),
tools=[retrieve_tool],
checkpointer=InMemorySaver(),
)
return _agent
def chat(question: str, session_id: str) -> str:
"""多轮问答:checkpointer 按 thread_id 隔离记忆,换 session 立刻失忆。"""
result = get_agent().invoke(
{"messages": [{"role": "user", "content": question}]},
{"configurable": {"thread_id": session_id}},
)
return result["messages"][-1].content
agent 模式把检索封装成工具——这才是 18 章那个占位符的真实实现:模型看到完整线程历史,构造 query 时自动把「它」补全为「后园」,18 章的改写链被工具调用内化。
✅ 阶段验证(拒答、角标溯源、来源过滤、多轮记忆,均为实测输出):
# 1) 库外问题:短路拒答,不调 LLM
result = rag.ask("如何做红烧肉")
print(result)
# {'answer': '资料中没有相关内容。', 'sources': [], 'hits_count': 0}
# 2) 库内问题:角标 + 完整溯源(注意前两条来自 OCR 出来的 scan.pdf)
result = rag.ask("收音机送修的申请单位是哪个,检测编号是多少")
print(result["answer"])
# 申请单位是**城南旧货市场管理处** [1],检测编号为 **SC-2026-1013** [2]。
print(result["hits_count"])
# 3
for s in result["sources"]:
print(s.model_dump())
# {'index': 1, 'source': 'scan.pdf', 'page': 1, 'start_index': 0, 'excerpt': '售后维修申请单\n申请单位:城南旧货市场管理处\n设备名称:收音机(无商标)\n送修日期:2026年10月13日\n故障描述:夜间出现异常频率\n处理意见:建议移交技术科'}
# {'index': 2, 'source': 'scan.pdf', 'page': 2, 'start_index': 0, 'excerpt': '技术科检测回执\n检测编号:SC-2026-1013\n检测结论:频率来源不明\n备注:该设备出厂信息无法查证\n复核人:(签名)\n日期:2026年10月14日'}
# {'index': 3, 'source': 'novel.pdf', 'page': 5, 'start_index': 0, 'excerpt': '第5章 旧频率\n陈师傅修表的时候不说话,镊子起落之间,齿轮的咬合声细得像雨。'}
角标 [1]``[2] 与 sources 列表的 index 一一对应,前端可以直接把角标渲染成可点击的出处链接。前两条都来自 scan.pdf,也就是 OCR 出来的内容——扫描件先被认成文字、再被检索到、最后被引用,整条链路走通了。
# 3) 来源过滤:只在 report.pdf 里问
result = rag.ask("解析层选用了什么库", source="report.pdf")
print(result["answer"])
# 解析层选用 **pypdf** [1]。
# 补充:加载层使用 LangChain 的 PyPDFLoader,验证方式为逐页文本抽取与元数据核对 [1]。
print(sorted({s["source"] for s in [x.model_dump() for x in result["sources"]]}))
# ['report.pdf']
# 4) 多轮记忆:第二轮用指代「它」;换 session 再问同样的指代(反向验证)
rag.chat("秋天的后园里长着什么树?", session_id="demo1")
# 秋天的后园里,墙角长着一棵**老槐树**。风一起,叶子就簌簌地落,铺了满地碎金。[1]
rag.chat("它的西边种了什么?", session_id="demo1")
# 根据上文,这里的“它”指**后园**。后园的西边种着**几畦青菜**,霜打过后反而更甜。
# 母亲总在这个时节腌一缸咸菜,留到冬天配粥吃。[1]
rag.chat("它的西边种了什么?", session_id="demo2")
# 请问您说的「它」指的是什么呢?目前对话中没有提到任何对象,我无法确定您想问的是
# 哪个事物的西边。请告诉我具体是指什么(比如某个地点、建筑、区域等),我再帮您查询。
demo2 里模型明确反问而不是瞎猜,证明记忆确实按 thread_id 隔离。这正是 13 章那条链做不到的事(它的「坑与下一步」里自己承认了)。
本步引入的 API:ChatPromptTemplate.from_messages 元组列表(system + human)、| 管道组装 LCEL 链(13 章)、@tool(args_schema=...)(17 章,字段描述引导模型补全指代)、create_agent + checkpointer + thread_id(16~18 章)、InMemorySaver(进程内记忆,生产换 PostgresSaver,见 14 章)。
第 9 步:server.py + client.py——服务化与流式
server.py 用 lifespan 在启动时预热——连 Qdrant(顺带校验 collection 已建)、BM25 重建(jieba 首次分词要建前缀词典)、embedding 客户端建立都有初始化开销,别让用户第一个请求承担全部冷启动。/health 的规模信息用 retrieval.collection_stats() 取(第 5 步已实现)——而不是 FAISS 那套 index.ntotal / index.reconstruct(0),后者是 FAISS 特有 API,Qdrant 没有,换库时不改这里会直接 AttributeError 起不来服务。
📄 文件:server.py(新建)
"""FastAPI 三端点:/health 探活、/ask 同步带溯源、/chat 流式(18 章的落地版)。"""
from contextlib import asynccontextmanager
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
import config, rag, retrieval
@asynccontextmanager
async def lifespan(app: FastAPI):
retrieval.get_vectorstore() # 连上 Qdrant,顺带校验 collection 已建(没建就早失败)
retrieval.get_bm25() # 重建 BM25
rag.get_agent() # 构建 agent(含 checkpointer)
yield
app = FastAPI(title="RAG 知识库问答", version="1.0", lifespan=lifespan)
class AskRequest(BaseModel):
question: str
k: int | None = None
source: str | None = None
class ChatRequest(BaseModel):
question: str
session_id: str
@app.get("/health")
def health():
"""不碰 LLM,可以高频探活。"""
stats = retrieval.collection_stats()
return {"status": "ok", "chunks": stats["points"], "dim": stats["dim"],
"distance": stats["distance"], "embedding": config.EMBEDDING_ID,
"chat_model": config.GLM_MODEL_ID, "score_threshold": config.SCORE_THRESHOLD,
"vectorstore": f"qdrant:{config.QDRANT_COLLECTION}", "qdrant_url": config.QDRANT_URL}
@app.post("/ask")
def ask(req: AskRequest):
"""同步返回 JSON:答案 + 溯源列表。"""
result = rag.ask(req.question, k=req.k, source=req.source)
return {
"answer": result["answer"],
"sources": [s.model_dump() for s in result["sources"]],
"hits_count": result["hits_count"],
}
@app.post("/chat")
async def chat(req: ChatRequest):
"""流式吐 token:只放行 model 节点,过滤 tools 节点泄漏的资料原文。"""
async def token_stream():
try:
async for message, meta in rag.get_agent().astream(
{"messages": [{"role": "user", "content": req.question}]},
{"configurable": {"thread_id": req.session_id}},
stream_mode="messages",
):
if meta.get("langgraph_node") != "model":
continue # 跳过 tools 节点的资料原文
if message.content:
yield message.content
except Exception as e:
yield f"Error: {e}" # 响应头已发出就改不了状态码,只能当正文吐出
return StreamingResponse(token_stream(), media_type="text/plain; charset=utf-8")
📄 文件:client.py(新建)
"""流式冒烟客户端:health 检查 + 两轮记忆 + 一轮反向验证。"""
import requests
BASE = "http://127.0.0.1:8080"
def ask_stream(question: str, session_id: str) -> None:
print(f"\n>>> {question}")
with requests.post(f"{BASE}/chat", json={"question": question,
"session_id": session_id}, stream=True) as response:
response.encoding = "utf-8"
for chunk in response.iter_content(chunk_size=None, decode_unicode=True):
print(chunk, end="", flush=True)
print()
if __name__ == "__main__":
health = requests.get(f"{BASE}/health").json()
print(f"health: {health['status']}({health['chunks']} 块)")
ask_stream("秋天的后园里长着什么树", session_id="smoke1")
ask_stream("它的西边种了什么", session_id="smoke1") # 同 session:应解析指代
ask_stream("它的西边种了什么", session_id="smoke2") # 新 session:应反问
✅ 阶段验证(起服务、探活、同步问答):
python -m uvicorn server:app --port 8080
# 预期(可推导):几行 INFO,最后 Application startup complete——
# lifespan 预热在它之前跑完;没建库会在这里早失败
另开一个终端,curl http://127.0.0.1:8080/health:
{
"status": "ok",
"chunks": 29,
"dim": 2048,
"distance": "Cosine",
"embedding": "embedding-3",
"chat_model": "glm-5.3",
"score_threshold": 0.377,
"vectorstore": "qdrant:rag",
"qdrant_url": "http://localhost:6333"
}
/ask 不单独贴 curl:它就是第 8 步的 rag.ask 套了层 HTTP,对 http://127.0.0.1:8080/ask POST {"question":"如何做红烧肉"},预期(可推导)返回 {"answer":"资料中没有相关内容。","sources":[],"hits_count":0}。
流式的一个真坑:ToolMessage 会泄漏
stream_mode="messages" 会把所有节点的消息都吐出来。第一次实测 /chat 时,响应长这样:
[1](来源:qiu.txt)
《秋园小记》
秋天的后园里,墙角有一棵老槐树。风一起,叶子就簌簌地落……(整段资料原文)
[2](来源:qiu.txt)
秋天是收获的季节……(又一段资料原文)
秋天的后园里,墙角长着一棵**老槐树**。风一起,叶子就簌簌地落 [1]。
前面那两大段是 retrieve_knowledge 工具的返回值,不是给用户的回答。18 章的 server.py 也有这个问题,只是它的检索工具是占位符所以从未暴露。先探明消息流构成——临时起个 python 会话,对 agent 逐条打印 type(msg).__name__、meta.get("langgraph_node")、len(msg.content) > 0 三个字段,统计结果是:
AIMessageChunk node=model 有内容=False 次数=288
AIMessageChunk node=model 有内容=True 次数=66
ToolMessage node=tools 有内容=True 次数=1
一次问答:66 个有内容的 model 增量(该流给用户)+ 1 个 tools 消息(不该流)。按 langgraph_node 过滤即可——就是 server.py 里 /chat 的那三行(continue 跳过 tools 节点、if message.content 过滤空增量)。修好后同一次请求的输出:
秋天的后园里,墙角长着一棵老槐树。风一起,槐树叶子就簌簌地落,铺了满地碎金 [1]。
作者后来离开村子,每年到这个时节还会想起那棵老槐树和满地碎金一样的叶子 [2]。
只剩回答本身。curl 实测流式(第一轮 + 第二轮指代,同 session):
curl -N -X POST http://127.0.0.1:8080/chat \
-H 'Content-Type: application/json' \
-d '{"question":"秋天的后园里长着什么树","session_id":"s1"}'
# 秋天的后园里,墙角长着一棵**老槐树**。……[1]
curl -N -X POST http://127.0.0.1:8080/chat \
-H 'Content-Type: application/json' \
-d '{"question":"它的西边种了什么","session_id":"s1"}'
# 后园的西边种着**几畦青菜**,霜打过后反而更甜。……[1]
最后跑 python client.py:预期(可推导,与 curl -N 同一端点)health ok、前两轮输出同上,第三轮(smoke2 新 session)模型反问「它」指什么——即第 8 步 demo2 的行为。异常处理沿用 18 章的结论:响应头已发出就改不了状态码,只能在生成器内把错误当正文 yield 出去(token_stream 的 except 分支);交互式 API 文档在 http://127.0.0.1:8080/docs。
本步引入的 API:FastAPI(lifespan=...)(启动预热)、StreamingResponse、astream(stream_mode="messages") + langgraph_node 过滤(18 章)、iter_content(decode_unicode=True)(客户端逐块读流)。
第 10 步:evaluate.py + tests/——评估与回归
evaluate.py 是检索质量的回归工具(第 5 步那两张实测表就是它跑的):不调 LLM,便宜且可重复——检索质量决定回答上限,改切分参数或换 embedding 模型后先跑它,比端到端试问答更能定位问题。tests/ 按「是否要花钱调 API」分三档,分档动机就是第 2 步那个 429:把要调 API 的用例和纯本地用例混在一起,跑测试会变得又慢又不稳定。
📄 文件:evaluate.py(新建)
"""检索质量评估(不调 LLM,免费可重复):三路对照 + 库外拒答量化。"""
import config, retrieval
CASES = [ # 9 个库内问题与期望命中源
("秋天的后园里长着什么树", "qiu.txt"), ("老周在旧货市场捡到了什么", "gbk文件.txt"),
("收音机送修的申请单位是哪个", "scan.pdf"), ("技术科检测回执的编号是多少", "scan.pdf"),
("母亲腌咸菜的缸沿压着什么", "novel.pdf"), ("解析层选用了什么库", "report.pdf"),
("申请单上的故障描述是什么", "scan.pdf"), ("小说里陈师傅做什么营生", "novel.pdf"),
("年度报告的验证方式是什么", "report.pdf"),
]
OUT_OF_LIBRARY = ["量子纠缠的数学证明是什么", "如何做红烧肉",
"Python 的 GIL 是什么时候移除的"]
def main() -> None:
k = config.TOP_K
points = retrieval.collection_stats()["points"]
src = lambda d: str(d.metadata.get("source", "?"))
print(f"=== 检索质量评估(k={k},语料 {points} 块)===\n")
print(f"{'检索路线':<20} {'top1 命中':<10} {'top-k 召回'}")
print("-" * 52)
routes = [
("向量(GLM embedding-3)", lambda q: [d for d, _ in retrieval.vector_search(q, k)]),
("BM25(rank_bm25 + jieba)", lambda q: retrieval.get_bm25().invoke(q)),
("混合(RRF 融合)", lambda q: retrieval.get_hybrid().invoke(q)),
]
for name, route in routes:
top1 = sum(src(route(q)[0]) == want for q, want in CASES)
topk = sum(any(src(d) == want for d in route(q)) for q, want in CASES)
print(f"{name:<20} {top1}/{len(CASES):<8} {topk}/{len(CASES)}")
print("\n=== 库外问题:阈值拒答能力 ===\n")
for q in OUT_OF_LIBRARY:
results = retrieval.vector_search(q, k)
best = results[0][1] if results else 0.0
kept = retrieval.search_with_threshold(q, k)
hybrid_n = len(retrieval.get_hybrid().invoke(q))
print(f" {q}")
print(f" 向量最近相似度 {best:.4f}(阈值 {config.SCORE_THRESHOLD:.3f}) → "
f"阈值过滤后剩 {len(kept)} 条 | 混合路仍返回 {hybrid_n} 条")
if __name__ == "__main__":
main()
📄 文件:tests/conftest.py(新建)
"""按「是否要花钱调 API」分三档:默认只跑纯本地,network/online 用 -m 显式选择。"""
import pytest
def pytest_collection_modifyitems(config, items):
"""没显式用 -m 选择时,默认跳过所有要调 API 的用例,只留纯本地的。"""
if config.getoption("-m"):
return
skip_paid = pytest.mark.skip(reason="默认跳过要调 API 的用例;用 -m network / online 运行")
for item in items:
if any(m in item.keywords for m in ("network", "online")):
item.add_marker(skip_paid)
📄 文件:tests/test_local.py(新建)
"""纯本地用例:查 Qdrant、读缓存、验拼接逻辑,不调付费 API。"""
import json
import config, prompts, retrieval
from langchain_core.documents import Document
def test_collection_scale():
stats = retrieval.collection_stats()
assert stats == {"points": 29, "dim": 2048, "distance": "Cosine"} # 第 4 步建库输出
def test_bm25_cache_consistency():
corpus = json.loads(config.BM25_CACHE.read_text(encoding="utf-8"))
assert len(corpus) == 29 # 缓存块数 == Qdrant 点数
assert len(retrieval.get_bm25().docs) == 29 # 重建后没有丢块
def test_metadata_traceable():
corpus = json.loads(config.BM25_CACHE.read_text(encoding="utf-8"))
for entry in corpus:
assert entry["metadata"]["source"] in {"qiu.txt", "gbk文件.txt", "novel.pdf",
"report.pdf", "scan.pdf"}
assert "start_index" in entry["metadata"] # 溯源三件套:source+page+start_index
def test_refusal_copy():
assert "资料中没有相关内容" in prompts.NO_CONTEXT_ANSWER
def test_context_numbering():
fake = [
(Document(page_content="第一段", metadata={"source": "a.txt"}), 0.9),
(Document(page_content="第二段", metadata={"source": "b.pdf", "page": 3}), 0.8),
]
context = prompts.build_context(fake)
assert context.startswith("[1](来源:a.txt)")
assert "[2](来源:b.pdf 第4页)" in context # page 从 0 存,展示 +1
📄 文件:tests/test_network.py(新建)
"""要调 embedding API 的用例:pytest tests/ -m network"""
import pytest
import config, retrieval
pytestmark = pytest.mark.network
def test_vector_results_sorted_desc():
scores = [s for _, s in retrieval.vector_search("老周捡到了什么", k=4)]
assert scores == sorted(scores, reverse=True) # 相似度降序
def test_exact_code_hit():
doc, score = retrieval.vector_search("SC-2026-1013", k=1)[0]
assert doc.metadata["source"] == "scan.pdf" and score >= 0.5 # 实测 0.5034
def test_ocr_content_searchable():
doc, _ = retrieval.vector_search("申请单位是哪个", k=1)[0]
assert doc.metadata["source"] == "scan.pdf" # OCR 出来的字照样被检索到
def test_threshold_rejects_out_of_library():
assert retrieval.search_with_threshold("如何做红烧肉") == []
def test_threshold_keeps_in_library():
assert len(retrieval.search_with_threshold("秋天的后园里长着什么树")) >= 1
def test_source_filter_full_k():
hits = retrieval.vector_search("解析层选用了什么库", k=2, source="report.pdf")
assert len(hits) == 2 # 数据库侧过滤:满 k,不是取 4 筛剩 1
assert all(d.metadata["source"] == "report.pdf" for d, _ in hits)
def test_bm25_exact_term():
assert retrieval.get_bm25().invoke("SC-2026-1013")[0].metadata["source"] == "scan.pdf"
def test_hybrid_returns_k():
assert len(retrieval.get_hybrid().invoke("收音机检测编号")) == 4
def test_in_library_score_above_threshold():
_, score = retrieval.vector_search("技术科检测回执的编号是多少", k=1)[0]
assert score >= config.SCORE_THRESHOLD
def test_hit_sources_structure():
for doc, score in retrieval.retrieve_hits("解析层选用了什么库"):
assert score >= config.SCORE_THRESHOLD and doc.metadata["source"]
def test_report_question_hits_report():
doc, _ = retrieval.vector_search("验证方式是什么", k=1)[0]
assert doc.metadata["source"] == "report.pdf"
📄 文件:tests/test_online.py(新建)
"""要调 chat API 的用例:pytest tests/ -m online"""
import pytest
import rag
pytestmark = pytest.mark.online
def test_answer_has_citation():
result = rag.ask("收音机送修的申请单位是哪个")
assert "[1]" in result["answer"] and result["hits_count"] >= 1
def test_same_session_resolves_pronoun():
rag.chat("秋天的后园里长着什么树?", session_id="t-online")
assert "青菜" in rag.chat("它的西边种了什么?", session_id="t-online") # 它 → 后园
def test_new_session_cannot_resolve_pronoun(): # 反向:新会话应答不出「青菜」
answer = rag.chat("它的西边种了什么?", session_id="t-online-fresh")
assert "青菜" not in answer # 失忆才是正确行为
✅ 阶段验证(三档测试与评估,均为实测结果):
pytest tests/ # 纯本地:不调付费 API
# 5 passed, 14 skipped in 1.41s
pytest tests/ -m "network or online" # 调 embedding 与 chat
# 14 passed, 5 deselected in 58.82s
| 档 | 用例数 | 覆盖 | 耗时 |
|---|---|---|---|
| 默认(纯本地) | 5 | 索引规模(查 Qdrant collection,不调付费 API)、BM25 缓存一致性、metadata 可溯源、拒答话术、角标拼接(用假 Document) | 1.41s |
network | 11 | 向量检索排序(相似度降序)、精确词命中、阈值拒答/不误杀、来源过滤、OCR 内容可检索、溯源结构 | ~45s |
online | 3 | 真实回答带角标、多轮指代解析、换 session 失忆 | ~14s |
合计 19 个用例全过。其中 test_new_session_cannot_resolve_pronoun 是个反向测试:断言新会话里模型答不出「青菜」——它验证的是记忆的隔离性,而不是能力。
python evaluate.py # 预期:第 5 步贴过的两张实测表(三路 9/9 + 库外拒答量化)原样复现
本步引入的 API:pytest_collection_modifyitems(收集期改写用例标记)、自定义标记 pytest.mark.network / online 与 -m 选择器、BM25Retriever.docs(重建后核对块数)。
与前文的对应关系
12 个文件分别用到哪几章的知识,搭建时可回查:
| 文件 | 用到的章节 |
|---|---|
requirements.txt / .env / .env.example | 02 环境、03 配置(.env 四变量约定) |
config.py | 03(env 读取)、10 切分(chunk 参数)、11 向量库(QDRANT_URL) |
models.py | 03、11(OpenAIEmbeddings 接 GLM、check_embedding_ctx_length=False、维度 2048) |
loaders.py | 09 加载器(编码降级、PyPDFLoader、OCR、空文档事故) |
ingest.py | 09 → 10 → 11 的流水线;建库幂等 |
retrieval.py / calibrate.py | 11(Qdrant 原生 filter)、12 检索优化(BM25、jieba、RRF、阈值与标定) |
prompts.py | 06 prompt 模板、09(metadata 溯源承诺的兑现) |
rag.py | 13 完整链(LCEL)、16 LangGraph、17 Agent、18 部署(agent 模式 RAG) |
server.py / client.py | 18(FastAPI、流式过滤、异常处理、客户端读流) |
evaluate.py / tests/ | 12(检索评估)、python-base 18 章(pytest) |
14 记忆系统散在两处:rag.py 的 InMemorySaver 是它的开发档,下表生产差距里的 PostgresSaver / SummarizationMiddleware 是它的生产档。
生产差距:这套系统还缺什么
如实列出。每一项都指向对应章节,不是「以后再说」:
| 缺口 | 现状 | 影响 | 参考 |
|---|---|---|---|
| 记忆持久化 | InMemorySaver | 重启丢历史;uvicorn 多 worker 时各存各的,同一 session 会串不上 | 14 章 PostgresSaver |
| 鉴权 | 无 | 任何人都能调,token 费用被刷 | — |
| 长会话成本 | 全量 history 每轮都进 prompt | token 与延迟随轮次线性涨 | 14 章 SummarizationMiddleware |
| 增量入库 | 加文档要删 collection 全量重建 | 语料一大就不可接受 | 12 章 ES 增量写入 |
| Qdrant 裸奔 | 单节点、无认证(xpack 类机制未配)、无副本 | 生产环境任何人都能读写你的向量库 | 11 章 Qdrant 选型 / 12 章 ES 安全配置思路 |
| 生产级 BM25 | rank_bm25 进程内 | 无持久化、多进程不共享;向量那半边已在 Qdrant,关键词这半边还是单机内存 | 12 章 Elasticsearch + IK(向量与 BM25 同库,混合检索一次查完) |
| 容器化 | 只有 Qdrant 跑在容器里,应用本身无 Dockerfile | 部署靠手工 | 12 章 Docker 镜像源配置 |
| 检索评估规模 | 12 个问题、29 块语料 | 三路全 9/9,分不出优劣 | 需更大更杂的语料 |
其中多 worker 记忆串台最容易在生产上出事:InMemorySaver 存在进程内存里,uvicorn 起 4 个 worker 就有 4 份互不相通的记忆,同一个 session_id 的请求落到不同 worker 就会「失忆」。这个坑在单机开发时完全看不出来。
上一节:流式 API 与部署 · 返回目录