跳转到主要内容

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 里的向量索引衔接。

flowchart TB subgraph OFF["离线建库(跑一次)"] S["5 个语料文件<br/>txt / GBK / 文字型PDF / 扫描件"] L["loaders.py<br/>编码自适应 + PyPDFLoader + OCR"] C["切分<br/>chunk_size=400 overlap=80"] E["embedding<br/>GLM embedding-3"] F[("Qdrant collection<br/>rag · Cosine · 2048 维")] J[("BM25 语料缓存<br/>db/bm25_corpus.json")] S --> L --> C --> E --> F C --> J end subgraph ON["在线问答(每请求)"] Q["用户问题"] T["向量检索 + 相似度阈值<br/>(可带来源 filter)"] D{"命中 0 条?"} R["返回固定拒答话术<br/>不调 LLM"] P["拼带角标的资料块<br/>[1] [2] [3]"] M["LLM 生成<br/>带 [n] 溯源"] Q --> T --> D D -->|"是"| R D -->|"否"| P --> M end F -->|"查询"| T J -.->|"BM25 备用路"| T

为什么必须分离:建库要跑 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 兜底」。本语料上实测未复现:

查询向量 top1BM25 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
network11向量检索排序(相似度降序)、精确词命中、阈值拒答/不误杀、来源过滤、OCR 内容可检索、溯源结构~45s
online3真实回答带角标、多轮指代解析、换 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.example02 环境、03 配置(.env 四变量约定)
config.py03(env 读取)、10 切分(chunk 参数)、11 向量库(QDRANT_URL)
models.py03、11(OpenAIEmbeddings 接 GLM、check_embedding_ctx_length=False、维度 2048)
loaders.py09 加载器(编码降级、PyPDFLoader、OCR、空文档事故)
ingest.py09 → 10 → 11 的流水线;建库幂等
retrieval.py / calibrate.py11(Qdrant 原生 filter)、12 检索优化(BM25、jieba、RRF、阈值与标定)
prompts.py06 prompt 模板、09(metadata 溯源承诺的兑现)
rag.py13 完整链(LCEL)、16 LangGraph、17 Agent、18 部署(agent 模式 RAG)
server.py / client.py18(FastAPI、流式过滤、异常处理、客户端读流)
evaluate.py / tests/12(检索评估)、python-base 18 章(pytest)

14 记忆系统散在两处:rag.py 的 InMemorySaver 是它的开发档,下表生产差距里的 PostgresSaver / SummarizationMiddleware 是它的生产档。

生产差距:这套系统还缺什么

如实列出。每一项都指向对应章节,不是「以后再说」:

缺口现状影响参考
记忆持久化InMemorySaver重启丢历史;uvicorn 多 worker 时各存各的,同一 session 会串不上14 章 PostgresSaver
鉴权无任何人都能调,token 费用被刷—
长会话成本全量 history 每轮都进 prompttoken 与延迟随轮次线性涨14 章 SummarizationMiddleware
增量入库加文档要删 collection 全量重建语料一大就不可接受12 章 ES 增量写入
Qdrant 裸奔单节点、无认证(xpack 类机制未配)、无副本生产环境任何人都能读写你的向量库11 章 Qdrant 选型 / 12 章 ES 安全配置思路
生产级 BM25rank_bm25 进程内无持久化、多进程不共享;向量那半边已在 Qdrant,关键词这半边还是单机内存12 章 Elasticsearch + IK(向量与 BM25 同库,混合检索一次查完)
容器化只有 Qdrant 跑在容器里,应用本身无 Dockerfile部署靠手工12 章 Docker 镜像源配置
检索评估规模12 个问题、29 块语料三路全 9/9,分不出优劣需更大更杂的语料

其中多 worker 记忆串台最容易在生产上出事:InMemorySaver 存在进程内存里,uvicorn 起 4 个 worker 就有 4 份互不相通的记忆,同一个 session_id 的请求落到不同 worker 就会「失忆」。这个坑在单机开发时完全看不出来。


上一节:流式 API 与部署 · 返回目录