第 12 章:上线,一个能跑住的 RAG 服务
前面十一章都是零件。这一章把它们装起来,做成一个能部署、能监控、能回滚的服务。
学习目标
- 画出 RAG 服务的分层结构与依赖
- 写出四个接口:问答、流式问答、文档入库、健康检查
- 用 compose 起 api + qdrant + redis
- 有一份上线清单,逐条能勾
12.1 分层:别把检索逻辑塞进路由里
分层的唯一标准:换掉任何一层,其他层不用改。想换重排模型?只动检索层。想换向量库?只动检索层。想换 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/stream | SSE 流式 | 先发 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 多租户与权限
三条硬规则:
- 每个请求必须带
tenant,缺失直接 400,不给默认值; - 检索必须先过滤 tenant(第 5 章);
- 缓存 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 |
| 配置 | 集合名与模型名进环境变量 |
| compose | api + qdrant + redis,模型预下载 |
| 日志 | trace_id + 四阶段耗时 |
| 多租户 | 先过滤、缺 tenant 直接 400、缓存带前缀 |
| 备份 | 原文 + 状态 + 向量库,一个都不能少 |