Skip to content

第 12 章:上线,一个能跑住的 RAG 服务 ​

前面十一章都是零件。这一章把它们装起来,做成一个能部署、能监控、能回滚的服务。


学习目标 ​

  • 画出 RAG 服务的分层结构与依赖
  • 写出四个接口:问答、流式问答、文档入库、健康检查
  • 用 compose 起 api + qdrant + redis
  • 有一份上线清单,逐条能勾

12.1 分层:别把检索逻辑塞进路由里 ​

四层,职责不重叠API 层(FastAPI)路由、鉴权、参数校验、SSE、错误包装 —— 不写业务逻辑RAG 编排层改写 → 检索 → 重排 → 组装 → 生成 → 引用校验每一步可单独关闭(降级用)检索层Qdrant 客户端 / BM25 / reranker模型层chat / embedding / 重排封装Qdrant向量与 payloadRedis缓存 / 限流 / 会话对象存储 / 本地盘原始文件↑ 请求

分层的唯一标准:换掉任何一层,其他层不用改。想换重排模型?只动检索层。想换向量库?只动检索层。想换 LLM?只动模型层。


12.2 四个接口 ​

python
from fastapi import FastAPI, HTTPException, Header
from pydantic import BaseModel

app = FastAPI()

class AskIn(BaseModel):
    question: str
    session_id: str | None = None
    top_k: int = 4

@app.post("/ask")
async def ask(body: AskIn, x_tenant: str = Header(...)):
    try:
        return await rag.answer(body.question, tenant=x_tenant, session_id=body.session_id, top_k=body.top_k)
    except RetrievalError as e:
        raise HTTPException(503, detail="检索服务不可用")   # 降级由上层决定
接口作用注意
POST /ask一次性问答返回 answer + claims + sources
POST /ask/streamSSE 流式先发 status,再发 delta,最后发 citation
POST /documents上传入库走第 4 章的增量逻辑,返回 doc_id 与片段数
GET /health健康检查检查 qdrant / redis / 模型连通性,别只返回 ok

/health 要真检查依赖。只返回 {"status":"ok"} 的健康检查,会在下游挂了时继续骗负载均衡器。


12.3 配置走环境变量 ​

python
# config.py
import os

QDRANT_URL = os.getenv("QDRANT_URL", "http://qdrant:6333")
QDRANT_COLLECTION = os.getenv("QDRANT_COLLECTION", "docs__bge_small_zh_v15")
EMBED_MODEL = os.getenv("EMBED_MODEL", "BAAI/bge-small-zh-v1.5")
RERANK_MODEL = os.getenv("RERANK_MODEL", "BAAI/bge-reranker-base")
TOP_K = int(os.getenv("TOP_K", "4"))
CANDIDATES = int(os.getenv("CANDIDATES", "30"))

第 4 章说过:集合名进配置,换模型时改两行就切换。


12.4 compose:三个容器 ​

yaml
services:
  api:
    build: .
    ports: ["8000:8000"]
    environment:
      QDRANT_URL: http://qdrant:6333
      REDIS_URL: redis://redis:6379/0
    depends_on: [qdrant, redis]

  qdrant:
    image: qdrant/qdrant:v1.12.4
    volumes: ["./qdrant_storage:/qdrant/storage"]

  redis:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes: ["./redis_data:/data"]

Dockerfile 两件事:装依赖、预下载模型(否则首次请求要等模型加载)。

dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
RUN python -c "from sentence_transformers import SentenceTransformer as S; S('BAAI/bge-small-zh-v1.5')"
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

12.5 一次请求的完整生命周期 ​

日志一定要带 trace_id 和每阶段耗时,否则线上变慢时你只能猜:

python
import time, uuid
trace_id = uuid.uuid4().hex[:12]
t0 = time.perf_counter()
# ... 各阶段
log.info("rag", extra={"trace": trace_id, "rewrite_ms": 40, "retrieve_ms": 18, "rerank_ms": 410, "gen_ms": 1600})

12.6 多租户与权限 ​

三条硬规则:

  1. 每个请求必须带 tenant,缺失直接 400,不给默认值;
  2. 检索必须先过滤 tenant(第 5 章);
  3. 缓存 key 必须带 tenant,否则串答案。
python
flt = Filter(must=[FieldCondition(key="tenant_id", match=MatchValue(value=tenant))])

这是安全边界,不是性能优化。上线前单独测一遍:"用 A 的 token 问 B 的文档,能不能拿到"。


12.7 上线清单 ​

  • [ ] 集合名、模型名都在配置里,不写死
  • [ ] doc_id / tenant_id 建了 payload 索引
  • [ ] 检索先过滤 tenant,且有跨租户测试
  • [ ] 缓存 key 带 tenant 与文档版本
  • [ ] 引用校验开着,无依据的结论会被标记
  • [ ] /health 真检查 qdrant / redis / 模型
  • [ ] 日志带 trace_id 与四阶段耗时
  • [ ] 超时与降级:检索 800ms、重排 600ms、生成 20s
  • [ ] 评估脚本可跑(golden.jsonl 在仓库里)
  • [ ] 备份:Qdrant 卷 + 原始文件 + 入库状态文件

最后一条常被忽略:原始文件和入库状态也要备份。只备份向量库,出问题时无法重建——没有原文和指纹,你连"哪些文档进过库"都不知道。


12.8 你已经做出了 Boss ​

Lv4 的 Boss 项目是 moqian-rag-assistant。学完这 12 章,它需要的东西都齐了:

Boss 要求对应章节
上传自己的文档2、3、4
问出自己的答案5、6、7
每个答案有出处8
能追问9
效果可衡量10
成本可控11
能部署给人用12

剩下的差别只是产品细节:界面、账号、文档管理。技术骨架已经完整。


全课收尾 ​

十二走走完,回头看第 1 章那张五环节图:

解析(2)→ 切分(3)→ 入库(4)→ 召回(5)→ 重排(6)→ 组装(7)→ 引用(8)→ 多轮(9)→ 评估(10)→ 成本(11)→ 上线(12)

一句话记住这门课:RAG 不是"把文档塞给模型",而是"在正确的时刻,把正确的一小段,放在正确的位置"。 三件事里任何一件没做好,用户看到的就是"AI 胡说八道"。


本章小结 ​

要点说明
分层API / 编排 / 检索 / 模型,换一层不动其他层
四接口ask、stream、documents、health
health真检查依赖,别只返回 ok
配置集合名与模型名进环境变量
composeapi + qdrant + redis,模型预下载
日志trace_id + 四阶段耗时
多租户先过滤、缺 tenant 直接 400、缓存带前缀
备份原文 + 状态 + 向量库,一个都不能少
本文阅读--次|全站访问--次|访客--人