---
id: plan.week06
title: "第 6 周：RAG 知识库问答（下）——评测、混合检索、重排、记忆、缓存、LangChain、部署"
type: week
domain: plan
stack: [postgresql, redis, docker, rag, vector-db, langchain]
week: [6]
est_hours: 12
order: 6
---

# 第 6 周：RAG 知识库问答（下）——评测、混合检索、重排、记忆、缓存、LangChain、部署

> 项目二 `rag-qa` 的第 2 周。上周 `week05-rag-1.md` 完成了手写主流程；下周 `week07-frontend.md` 做前端界面。

**本周目标**：从“能跑”到“能用数字证明好不好”。先建评测集，再逐个加混合检索、重排、多轮改写、缓存，**每加一项都跑一次评测**并记录结果；最后用 LangChain 重写一遍做对照，了解 Milvus / pgvector，用 Docker Compose 部署。

**本周新增文件**

```text
rag-qa/
├── src/rag_qa/
│   ├── config.py               # 覆盖：新增检索模式、Redis 配置
│   ├── container.py            # 覆盖：按配置组装混合检索、缓存、会话
│   ├── eval_metrics.py         # Hit@K、MRR、拒答准确率
│   ├── retrieval/bm25.py       # 关键词检索（jieba 分词）
│   ├── retrieval/hybrid.py     # RRF 融合 + 混合检索问答服务
│   ├── retrieval/rerank.py     # 重排（接口实现 + 假实现）
│   ├── qa/rewrite.py           # 多轮追问改写
│   ├── memory/__init__.py
│   ├── memory/session.py       # 会话短期记忆（内存 / Redis）
│   ├── cache.py                # 向量缓存、答案缓存
│   ├── api/chat.py             # 多轮对话接口
│   └── lc_pipeline.py          # LangChain LCEL 版对照
├── eval/
│   ├── questions.jsonl
│   ├── run_eval.py
│   └── results.md
├── Dockerfile
├── docker-compose.yml
└── tests/
    ├── test_eval.py
    ├── test_hybrid.py
    ├── test_rerank.py
    ├── test_memory.py
    ├── test_cache.py
    └── test_lc_pipeline.py
```

```bash
uv add rank-bm25 jieba "redis>=5" langchain-core
```

---

## 第 1 天：评测集和指标

### 学习内容

- 说明：
  - **没有评测，所有优化都是感觉**。面试官最爱问“你怎么知道改完变好了？”——答案就是评测集 + 指标 + 对比记录。
  - 检索指标（不需要调用大模型，便宜、稳定，先做这个）：
    - **Hit@K**：前 K 个结果里有没有至少一个相关片段。
    - **MRR**（平均倒数排名）：第一个相关片段排第 1 得 1 分，排第 2 得 0.5 分，没找到得 0 分，取平均。看的是“排得够不够靠前”。
    - **拒答准确率**：本来就没有答案的问题，系统是否正确地一个片段都不返回。
  - 怎么判断“相关”：每道题写一个**必须出现在片段里的关键句**（不用片段 ID，因为改切分参数后 ID 会变）。
  - 生成质量（忠实度、是否答对）可以人工抽查，也可以用模型打分（LLM-as-judge），本周人工抽查即可，第 13 周 Agent 评测再系统做。
- 案例：

```python
# 文件：rag-qa/src/rag_qa/eval_metrics.py
import json
from pathlib import Path

from pydantic import BaseModel

from rag_qa.vectorstore.base import ScoredChunk


class EvalItem(BaseModel):
    q: str
    must_contain: str = ""   # 相关片段必须包含的关键句；为空表示这题应该拒答


class EvalReport(BaseModel):
    hit_at_k: float
    mrr: float
    refuse_acc: float
    n_answerable: int
    n_refuse: int
    misses: list[str]


def load_items(path: Path) -> list[EvalItem]:
    return [EvalItem.model_validate_json(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]


def first_relevant_rank(item: EvalItem, hits: list[ScoredChunk]) -> int | None:
    for rank, h in enumerate(hits, start=1):
        if item.must_contain in h.chunk.text:
            return rank
    return None


def evaluate(items: list[EvalItem], results: list[list[ScoredChunk]]) -> EvalReport:
    hit = rr = refuse_ok = 0.0
    answerable = [(i, r) for i, r in zip(items, results) if i.must_contain]
    refuse = [(i, r) for i, r in zip(items, results) if not i.must_contain]
    misses = []
    for item, hits in answerable:
        rank = first_relevant_rank(item, hits)
        if rank is None:
            misses.append(item.q)
        else:
            hit += 1
            rr += 1 / rank
    for item, hits in refuse:
        if hits:
            misses.append(f"（应拒答）{item.q}")
        else:
            refuse_ok += 1
    na, nr = len(answerable), len(refuse)
    return EvalReport(hit_at_k=round(hit / na, 3) if na else 0, mrr=round(rr / na, 3) if na else 0,
                      refuse_acc=round(refuse_ok / nr, 3) if nr else 0, n_answerable=na, n_refuse=nr, misses=misses)


def to_markdown_row(name: str, r: EvalReport) -> str:
    return f"| {name} | {r.hit_at_k:.3f} | {r.mrr:.3f} | {r.refuse_acc:.3f} | {len(r.misses)} |"


if __name__ == "__main__":
    print(json.dumps({"q": "Redis 旁路缓存怎么更新", "must_contain": "先写数据库"}, ensure_ascii=False))
```

```python
# 文件：rag-qa/tests/test_eval.py
from rag_qa.eval_metrics import EvalItem, evaluate
from rag_qa.ingest.chunker import Chunk
from rag_qa.vectorstore.base import ScoredChunk


def hit(text: str) -> ScoredChunk:
    return ScoredChunk(chunk=Chunk(chunk_id=text, doc_id="d", filename="f.md", text=text, index=0), score=0.5)


def test_metrics():
    items = [EvalItem(q="q1", must_contain="甲"), EvalItem(q="q2", must_contain="乙"),
             EvalItem(q="q3", must_contain="丙"), EvalItem(q="q4")]
    results = [[hit("甲是答案")], [hit("无关"), hit("乙在第二")], [hit("无关")], []]
    r = evaluate(items, results)
    assert r.hit_at_k == round(2 / 3, 3)
    assert r.mrr == round((1 + 0.5 + 0) / 3, 3)
    assert r.refuse_acc == 1.0 and r.misses == ["q3"]
```

评测集文件（每行一条 JSON，至少 30 条，其中 5~8 条是文档里没有答案的）：

```json
{"q": "Redis 旁路缓存更新数据时的顺序是什么", "must_contain": "先写数据库"}
```

```json
{"q": "goroutine 之间推荐用什么通信", "must_contain": "channel"}
```

```json
{"q": "公司今年的年终奖怎么算"}
```

```python
# 文件：rag-qa/eval/run_eval.py
"""用法：uv run python eval/run_eval.py   （先 rag-qa ingest samples/）"""
import asyncio
from pathlib import Path

from rag_qa.container import build_container
from rag_qa.eval_metrics import evaluate, load_items, to_markdown_row


async def main() -> None:  # 不自动运行
    items = load_items(Path(__file__).with_name("questions.jsonl"))
    print("| 方案 | Hit@K | MRR | 拒答准确率 | 失败数 |\n| --- | --- | --- | --- | --- |")
    for mode in ["vector", "hybrid", "hybrid_rerank"]:
        c = build_container(mode=mode)
        results = [await c.qa.retrieve(i.q) for i in items]
        report = evaluate(items, results)
        print(to_markdown_row(mode, report))
        for m in report.misses:
            print(f"<!-- {mode} 失败：{m} -->")


if __name__ == "__main__":
    asyncio.run(main())
```

**易错点 / 面试常问（补充）**

- 易错点：评测集要包含“本来就没有答案”的问题，否则看不出系统会不会硬答。
- 易错点：评测集写好后不要按评测结果去改题目；改了系统再跑同一套题才有可比性。评测结果要记下当时的参数（Top-K、阈值、检索方式）。
- 面试常问：Hit@K 和 MRR 分别衡量什么（前 K 个里有没有命中 / 命中的排名靠不靠前）；检索指标和回答质量指标的区别（后者可以用人工或模型评分）。

### 要建的文件

- `eval_metrics.py`、`tests/test_eval.py`、`eval/questions.jsonl`（从上周 8 条人工试验扩充到 30 条以上）、`eval/run_eval.py`、`eval/results.md`

### 运行方式

```bash
uv run pytest tests/test_eval.py -v
uv run python eval/run_eval.py      # 第 2、3 天的代码写完后才能跑全部三种方案
```

### 完成标准

- 评测集 ≥ 30 条；`eval/results.md` 记下**基线**（纯向量检索）的三个指标。每次改动后追加一行，写清改了什么、指标变化、原因分析。
- 实验一：把 `chunk_size` 分别设为 300 / 500 / 800，重新入库并评测，记录哪个最好（数值取决于你的文档和模型，以你自己的结果为准）。

---

## 第 2 天：BM25 关键词检索 + RRF 混合检索

### 学习内容

- 说明：
  - 向量检索擅长“意思相近”，但对**专有名词、错误码、函数名、版本号**这类精确匹配不敏感；BM25 是经典关键词检索算法（Elasticsearch 默认算法），正好互补。两者一起用叫**混合检索**。
  - 中文要先分词（jieba），英文按单词。
  - 两路结果的分数尺度不同（余弦 0~1，BM25 可能是 0~20），不能直接相加。**RRF（倒数排名融合）**只看排名：每个片段得分 = Σ 1/(k + 排名)，k 一般取 60。简单、稳定、不用调权重。
  - 坑：rank-bm25 的 `BM25Okapi` 在文档很少时，出现在一半以上文档里的词 IDF 会接近 0 甚至为负，测试时语料要多准备几条。
- 案例：

```python
# 文件：rag-qa/src/rag_qa/retrieval/bm25.py
import logging
import re

import jieba
from rank_bm25 import BM25Okapi

from rag_qa.ingest.chunker import Chunk
from rag_qa.vectorstore.base import ScoredChunk

jieba.setLogLevel(logging.WARNING)
STOP = set("的 了 是 在 和 与 及 或 也 就 都 而 吗 呢 啊 怎么 什么 如何 哪些 为什么 一个".split())


def tokenize(text: str) -> list[str]:
    words = jieba.lcut(text.lower())
    return [w for w in words if w.strip() and w not in STOP and not re.fullmatch(r"\W+", w)]


class BM25Index:
    def __init__(self, chunks: list[Chunk]):
        self.chunks = chunks
        self.bm25 = BM25Okapi([tokenize(c.heading_path + " " + c.text) for c in chunks]) if chunks else None

    def search(self, query: str, top_k: int) -> list[ScoredChunk]:
        if self.bm25 is None:
            return []
        scores = self.bm25.get_scores(tokenize(query))
        ranked = sorted(range(len(scores)), key=lambda i: scores[i], reverse=True)[:top_k]
        return [ScoredChunk(chunk=self.chunks[i], score=float(scores[i])) for i in ranked if scores[i] > 0]
```

```python
# 文件：rag-qa/src/rag_qa/retrieval/hybrid.py
from rag_qa.llm.base import ChatModel, Embedder
from rag_qa.qa.answer import QAService
from rag_qa.retrieval.bm25 import BM25Index
from rag_qa.retrieval.rerank import Reranker
from rag_qa.vectorstore.base import ScoredChunk, VectorStore


def rrf(*ranked_lists: list[ScoredChunk], k: int = 60) -> list[ScoredChunk]:
    scores: dict[str, float] = {}
    by_id: dict[str, ScoredChunk] = {}
    for lst in ranked_lists:
        for rank, h in enumerate(lst, start=1):
            cid = h.chunk.chunk_id
            scores[cid] = scores.get(cid, 0) + 1 / (k + rank)
            by_id.setdefault(cid, h)
    order = sorted(scores, key=scores.get, reverse=True)
    return [ScoredChunk(chunk=by_id[cid].chunk, score=round(scores[cid], 6)) for cid in order]


class HybridQAService(QAService):
    """只覆盖 retrieve()，回答、流式、引用逻辑全部复用父类。"""

    def __init__(self, store: VectorStore, embedder: Embedder, chat: ChatModel, *,
                 top_k: int = 4, min_score: float = 0.2, max_context_chars: int = 6000,
                 candidates: int = 20, reranker: Reranker | None = None, rerank_min_score: float = 0.0):
        super().__init__(store, embedder, chat, top_k, min_score, max_context_chars)
        self.candidates, self.reranker, self.rerank_min_score = candidates, reranker, rerank_min_score
        self._bm25: BM25Index | None = None
        self._version: tuple = ()

    def bm25(self) -> BM25Index:
        version = tuple((d.doc_id, d.content_hash) for d in self.store.list_docs())
        if self._bm25 is None or version != self._version:  # 文档有变化才重建索引
            self._bm25, self._version = BM25Index(self.store.all_chunks()), version
        return self._bm25

    async def retrieve(self, question: str) -> list[ScoredChunk]:
        [qv] = await self.embedder.embed([question])
        vec = [h for h in self.store.query(qv, self.candidates) if h.score >= self.min_score]
        kw = self.bm25().search(question, self.candidates)
        fused = rrf(vec, kw)
        if self.reranker and fused:
            fused = [h for h in await self.reranker.rerank(question, fused) if h.score >= self.rerank_min_score]
        return fused[: self.top_k]
```

```python
# 文件：rag-qa/tests/test_hybrid.py
from rag_qa.ingest.chunker import Chunk
from rag_qa.ingest.loaders import load_bytes
from rag_qa.ingest.pipeline import ingest_document
from rag_qa.llm.fake import FakeChat, FakeEmbedder
from rag_qa.retrieval.bm25 import BM25Index
from rag_qa.retrieval.hybrid import HybridQAService, rrf
from rag_qa.vectorstore.base import ScoredChunk
from rag_qa.vectorstore.chroma_store import ChromaStore

DOC = """# 运维手册
## 错误码
错误码 E1024 表示磁盘空间不足，需要清理日志目录。
## 缓存
缓存命中率下降时，先检查过期时间设置。
## 数据库
慢查询要先看执行计划，再考虑加索引。
## 部署
部署前先跑完测试，再构建镜像。
## 监控
监控面板要包含请求量、错误率、延迟。
"""


def sc(cid: str) -> ScoredChunk:
    return ScoredChunk(chunk=Chunk(chunk_id=cid, doc_id="d", filename="f", text=cid, index=0), score=1)


def test_rrf_prefers_items_in_both_lists():
    fused = rrf([sc("a"), sc("b"), sc("c")], [sc("c"), sc("d")])
    assert fused[0].chunk.chunk_id == "c"      # 两路都出现，排第一
    assert {h.chunk.chunk_id for h in fused} == {"a", "b", "c", "d"}


def test_bm25_exact_term():
    chunks = [Chunk(chunk_id=str(i), doc_id="d", filename="f", text=t, index=i)
              for i, t in enumerate(["错误码 E1024 表示磁盘不足", "缓存过期", "执行计划", "镜像构建", "监控面板"])]
    hits = BM25Index(chunks).search("E1024 是什么错误", top_k=3)
    assert hits[0].chunk.text.startswith("错误码 E1024")


async def test_hybrid_service(tmp_path):
    store, emb = ChromaStore(str(tmp_path)), FakeEmbedder()
    await ingest_document(load_bytes("ops.md", DOC.encode()), store, emb)
    svc = HybridQAService(store, emb, FakeChat("见 [1]"), top_k=2)
    hits = await svc.retrieve("E1024")
    assert "磁盘空间不足" in hits[0].chunk.text
    ans = await svc.answer("E1024")
    assert ans.citations[0].cited
```

### 要建的文件

- `retrieval/bm25.py`、`retrieval/hybrid.py`、`tests/test_hybrid.py`（`retrieval/rerank.py` 明天写，今天可以先写一个只有 `Reranker` 协议的版本）

### 运行方式

```bash
uv run pytest tests/test_hybrid.py -v
uv run python eval/run_eval.py
```

### 完成标准

- 测试通过；评测结果追加 `hybrid` 一行。如果评测集里有专有名词、错误码类问题，通常能看到混合检索的提升——**以你自己的数据为准**，没有提升也要记录并分析原因。
- 面试常问：为什么要混合检索？RRF 的公式和优点？

---

## 第 3 天：重排（Rerank）

### 学习内容

- 说明：
  - 向量检索用的是“双塔”模型：问题和片段**分别**变成向量再比较，快但粗。**重排模型（cross-encoder）**把“问题 + 片段”**放在一起**打分，准但慢。所以流程是：先粗召回 20~50 个候选，再用重排模型精排，取前 K 个。
  - 常见重排模型：bge-reranker 系列等；很多模型服务提供 `/rerank` 接口，请求一般是 `{model, query, documents, top_n}`，返回每个文档的 `index` 和 `relevance_score`。**不同服务商的字段可能不同，以服务商文档为准**。
  - 重排分数可以再设一个阈值，进一步减少“不相关片段混进上下文”。
- 案例：

```python
# 文件：rag-qa/src/rag_qa/retrieval/rerank.py
from typing import Protocol

import httpx

from rag_qa.llm.base import LLMError
from rag_qa.llm.fake import tokens
from rag_qa.vectorstore.base import ScoredChunk


class Reranker(Protocol):
    async def rerank(self, query: str, hits: list[ScoredChunk]) -> list[ScoredChunk]: ...


class ApiReranker:
    """调用 /rerank 接口。请求和响应字段以你所用服务商的文档为准。"""

    def __init__(self, client: httpx.AsyncClient, model: str, top_n: int = 8):
        self.client, self.model, self.top_n = client, model, top_n

    async def rerank(self, query: str, hits: list[ScoredChunk]) -> list[ScoredChunk]:
        resp = await self.client.post("/rerank", json={
            "model": self.model, "query": query,
            "documents": [h.chunk.text for h in hits], "top_n": min(self.top_n, len(hits)),
        })
        if resp.status_code >= 400:
            raise LLMError("RERANK", f"重排服务返回 {resp.status_code}")
        results = sorted(resp.json()["results"], key=lambda r: r["relevance_score"], reverse=True)
        return [ScoredChunk(chunk=hits[r["index"]].chunk, score=r["relevance_score"]) for r in results]


class OverlapReranker:
    """假实现：按“问题词在片段里出现的比例”打分。只用于测试和没有重排服务时的演示。"""

    async def rerank(self, query: str, hits: list[ScoredChunk]) -> list[ScoredChunk]:
        q = set(tokens(query))
        scored = [ScoredChunk(chunk=h.chunk, score=len(q & set(tokens(h.chunk.text))) / (len(q) or 1)) for h in hits]
        return sorted(scored, key=lambda h: h.score, reverse=True)
```

```python
# 文件：rag-qa/tests/test_rerank.py
import json

import httpx

from rag_qa.ingest.chunker import Chunk
from rag_qa.retrieval.rerank import ApiReranker, OverlapReranker
from rag_qa.vectorstore.base import ScoredChunk


def hits(*texts: str) -> list[ScoredChunk]:
    return [ScoredChunk(chunk=Chunk(chunk_id=t, doc_id="d", filename="f", text=t, index=i), score=0.5)
            for i, t in enumerate(texts)]


async def test_api_reranker_reorders():
    def handler(request: httpx.Request) -> httpx.Response:
        body = json.loads(request.content)
        assert body["documents"] == ["甲", "乙"] and body["top_n"] == 2
        return httpx.Response(200, json={"results": [{"index": 0, "relevance_score": 0.1},
                                                     {"index": 1, "relevance_score": 0.9}]})

    async with httpx.AsyncClient(transport=httpx.MockTransport(handler), base_url="https://r.test") as c:
        out = await ApiReranker(c, "reranker").rerank("问题", hits("甲", "乙"))
    assert [h.chunk.text for h in out] == ["乙", "甲"] and out[0].score == 0.9


async def test_overlap_reranker():
    out = await OverlapReranker().rerank("索引 执行计划", hits("部署镜像", "先看执行计划再加索引"))
    assert out[0].chunk.text.startswith("先看执行计划")
```

### 要建的文件

- `retrieval/rerank.py`、`tests/test_rerank.py`

### 运行方式

```bash
uv run pytest tests/test_rerank.py -v
uv run python eval/run_eval.py
```

### 完成标准

- 评测结果追加 `hybrid_rerank` 一行；记下重排带来的**延迟增加**（在 `rag-qa ask` 里看 `latency_ms`），说明“效果和速度的取舍”。
- 面试常问：双塔和交叉编码器的区别？为什么不直接用重排模型检索全部文档？（太慢，每个片段都要和问题一起过一遍模型）

---

## 第 4 天：多轮追问——问题改写 + 会话短期记忆（Redis）

### 学习内容

- 说明：
  - 用户第二轮常问“那它的缺点呢？”——直接拿去检索肯定找不到。做法：**用模型把追问改写成独立问题**（“Redis 旁路缓存的缺点是什么”），再检索。
  - 会话历史存 Redis 列表：`RPUSH` 追加、`LTRIM` 只保留最近 N 轮、`EXPIRE` 设置过期。这是“短期记忆”；跨会话的“长期记忆”放到第 12 周 Agent 项目。
  - 历史只用于改写和展示，回答时仍然**只给模型当前检索到的资料**，避免历史里的错误被反复放大。
- 案例：

```python
# 文件：rag-qa/src/rag_qa/memory/__init__.py
```

```python
# 文件：rag-qa/src/rag_qa/memory/session.py
import json
from typing import Protocol

from rag_qa.llm.base import Message


class SessionStore(Protocol):
    async def history(self, session_id: str) -> list[Message]: ...
    async def append(self, session_id: str, question: str, answer: str) -> None: ...


class MemorySessionStore:
    def __init__(self, max_turns: int = 6):
        self.max_turns = max_turns
        self.data: dict[str, list[Message]] = {}

    async def history(self, session_id: str) -> list[Message]:
        return list(self.data.get(session_id, []))

    async def append(self, session_id: str, question: str, answer: str) -> None:
        items = self.data.setdefault(session_id, [])
        items += [{"role": "user", "content": question}, {"role": "assistant", "content": answer}]
        del items[: -self.max_turns * 2]


class RedisSessionStore:
    def __init__(self, redis, max_turns: int = 6, ttl_s: int = 3600):
        self.r, self.max_turns, self.ttl_s = redis, max_turns, ttl_s

    def _key(self, session_id: str) -> str:
        return f"rag:session:{session_id}"

    async def history(self, session_id: str) -> list[Message]:
        return [json.loads(x) for x in await self.r.lrange(self._key(session_id), 0, -1)]

    async def append(self, session_id: str, question: str, answer: str) -> None:
        key = self._key(session_id)
        async with self.r.pipeline(transaction=True) as p:  # 一次往返完成四个命令
            p.rpush(key, json.dumps({"role": "user", "content": question}, ensure_ascii=False),
                    json.dumps({"role": "assistant", "content": answer}, ensure_ascii=False))
            p.ltrim(key, -self.max_turns * 2, -1)
            p.expire(key, self.ttl_s)
            await p.execute()
```

```python
# 文件：rag-qa/src/rag_qa/qa/rewrite.py
from rag_qa.llm.base import ChatModel, Message
from rag_qa.memory.session import SessionStore
from rag_qa.qa.answer import Answer, QAService

REWRITE = """根据对话历史，把用户最后的追问改写成一个不依赖上下文、可以单独检索的完整问题。
只输出改写后的问题，不要回答，不要解释。"""


async def rewrite_question(chat: ChatModel, history: list[Message], question: str) -> str:
    if not history:
        return question  # 第一轮不需要改写，省一次模型调用
    convo = "\n".join(f"{m['role']}: {m['content'][:300]}" for m in history[-6:])
    out = (await chat.complete([
        {"role": "system", "content": REWRITE},
        {"role": "user", "content": f"对话历史：\n{convo}\n\n追问：{question}"},
    ])).strip()
    return out if 0 < len(out) <= 200 else question  # 改写结果异常就退回原问题


class ConversationalQA:
    def __init__(self, qa: QAService, sessions: SessionStore, rewriter: ChatModel):
        self.qa, self.sessions, self.rewriter = qa, sessions, rewriter

    async def ask(self, session_id: str, question: str) -> tuple[str, Answer]:
        history = await self.sessions.history(session_id)
        standalone = await rewrite_question(self.rewriter, history, question)
        ans = await self.qa.answer(standalone)
        await self.sessions.append(session_id, question, ans.text)
        return standalone, ans
```

```python
# 文件：rag-qa/tests/test_memory.py
import os

import pytest

from rag_qa.ingest.loaders import load_bytes
from rag_qa.ingest.pipeline import ingest_document
from rag_qa.llm.fake import FakeChat, FakeEmbedder
from rag_qa.memory.session import MemorySessionStore, RedisSessionStore
from rag_qa.qa.answer import QAService
from rag_qa.qa.rewrite import ConversationalQA
from rag_qa.vectorstore.chroma_store import ChromaStore


class ScriptedChat(FakeChat):
    """改写请求返回固定问题，其余请求返回固定回答。"""

    async def complete(self, messages):
        self.received.append(messages)
        if "改写" in messages[0]["content"]:
            return "旁路缓存的缺点是什么"
        return "可能出现短暂不一致 [1]。"


async def test_follow_up_is_rewritten(tmp_path):
    store, emb, chat = ChromaStore(str(tmp_path)), FakeEmbedder(), ScriptedChat()
    doc = "# 缓存\n## 旁路缓存\n旁路缓存的缺点是可能出现短暂的数据不一致。\n## 其他\n无关内容。"
    await ingest_document(load_bytes("cache.md", doc.encode()), store, emb)
    conv = ConversationalQA(QAService(store, emb, chat), MemorySessionStore(), chat)

    q1, _ = await conv.ask("s1", "什么是旁路缓存")
    q2, ans = await conv.ask("s1", "那它的缺点呢")
    assert q1 == "什么是旁路缓存"            # 第一轮不改写
    assert q2 == "旁路缓存的缺点是什么" and ans.citations


async def test_memory_store_keeps_last_turns():
    s = MemorySessionStore(max_turns=2)
    for i in range(3):
        await s.append("s", f"q{i}", f"a{i}")
    assert [m["content"] for m in await s.history("s")] == ["q1", "a1", "q2", "a2"]


@pytest.mark.skipif(not os.getenv("REDIS_URL"), reason="需要 REDIS_URL，例如 redis://localhost:6379/0")
async def test_redis_session_store():
    import redis.asyncio as redis

    r = redis.from_url(os.environ["REDIS_URL"], decode_responses=True)
    s = RedisSessionStore(r, max_turns=2, ttl_s=60)
    await r.delete("rag:session:test")
    for i in range(3):
        await s.append("test", f"q{i}", f"a{i}")
    assert [m["content"] for m in await s.history("test")] == ["q1", "a1", "q2", "a2"]
    assert 0 < await r.ttl("rag:session:test") <= 60
    await r.aclose()
```

**易错点 / 面试常问（补充）**

- 易错点：多轮追问时直接拿“它呢？”去检索会什么都找不到，要先结合历史把问题改写成完整的问题，再检索。
- 易错点：会话历史要限制条数或长度，并设置过期时间（本项目用 Redis 过期），否则越聊越慢、越贵。
- 面试常问：短期记忆和长期记忆的区别（当前会话上下文 / 跨会话的用户偏好和事实）；问题改写失败会有什么后果，怎么兜底（改写结果为空时用原问题）。

### 要建的文件

- `memory/__init__.py`、`memory/session.py`、`qa/rewrite.py`、`tests/test_memory.py`

### 运行方式

```bash
docker run -d --name rag-redis -p 6379:6379 redis:7     # 第 3 周装过可以复用
REDIS_URL=redis://localhost:6379/0 uv run pytest tests/test_memory.py -v
```

### 完成标准

- 三个测试都通过（Redis 测试没有跳过）；用真实模型连续追问 3 轮，看改写结果是否合理。

---

## 第 5 天：缓存、配置组装、多轮对话接口

### 学习内容

- 说明：
  - **向量缓存**：同一段文字的向量永远一样，按“模型名 + 文字哈希”缓存，重复入库、重复问题都省钱。键里必须带模型名，换模型就自动失效。
  - **答案缓存**：同一问题短时间内重复问，直接返回。难点是**失效**：文档一更新，旧答案可能就错了。做法是把“索引版本”（全部文档内容哈希的摘要）放进缓存键，文档一变键就变，旧缓存自然不再命中，过期后自动清理。
  - 这里用“装饰器模式”：`CachedEmbedder` 实现同样的 `Embedder` 协议，包在真实实现外面，业务代码完全不用改。
  - 第 3 周学过的缓存问题（穿透、击穿、雪崩）在这里同样存在，面试时可以结合讲。
- 案例：

```python
# 文件：rag-qa/src/rag_qa/cache.py
import hashlib
import json
import time
from typing import Protocol

from rag_qa.llm.base import Embedder
from rag_qa.qa.answer import Answer, QAService


class KV(Protocol):
    async def get(self, key: str) -> str | None: ...
    async def set(self, key: str, value: str, ttl_s: int) -> None: ...


class MemoryKV:
    def __init__(self):
        self.data: dict[str, tuple[float, str]] = {}

    async def get(self, key: str) -> str | None:
        item = self.data.get(key)
        if item is None or item[0] < time.time():
            return None
        return item[1]

    async def set(self, key: str, value: str, ttl_s: int) -> None:
        self.data[key] = (time.time() + ttl_s, value)


class RedisKV:
    def __init__(self, redis):
        self.r = redis

    async def get(self, key: str) -> str | None:
        return await self.r.get(key)

    async def set(self, key: str, value: str, ttl_s: int) -> None:
        await self.r.set(key, value, ex=ttl_s)


def sha(text: str) -> str:
    return hashlib.sha1(text.encode()).hexdigest()


class CachedEmbedder:
    def __init__(self, inner: Embedder, kv: KV, model: str, ttl_s: int = 7 * 86400):
        self.inner, self.kv, self.model, self.ttl_s = inner, kv, model, ttl_s

    async def embed(self, texts: list[str]) -> list[list[float]]:
        keys = [f"rag:emb:{self.model}:{sha(t)}" for t in texts]
        cached = [await self.kv.get(k) for k in keys]          # 生产环境用 MGET / pipeline 一次取回
        missing = [i for i, v in enumerate(cached) if v is None]
        fresh = await self.inner.embed([texts[i] for i in missing]) if missing else []
        for i, vec in zip(missing, fresh):
            await self.kv.set(keys[i], json.dumps(vec), self.ttl_s)
            cached[i] = json.dumps(vec)
        return [json.loads(v) for v in cached]


class CachedQA:
    def __init__(self, qa: QAService, kv: KV, ttl_s: int = 600):
        self.qa, self.kv, self.ttl_s = qa, kv, ttl_s

    def _key(self, question: str) -> str:
        version = sha("|".join(f"{d.doc_id}:{d.content_hash}" for d in self.qa.store.list_docs()))
        return f"rag:ans:{version[:12]}:{sha(' '.join(question.lower().split()))}"

    async def answer(self, question: str) -> Answer:
        key = self._key(question)
        if (hit := await self.kv.get(key)) is not None:
            return Answer.model_validate_json(hit)
        ans = await self.qa.answer(question)
        await self.kv.set(key, ans.model_dump_json(), self.ttl_s)
        return ans
```

```python
# 文件：rag-qa/tests/test_cache.py
from rag_qa.cache import CachedEmbedder, CachedQA, MemoryKV
from rag_qa.ingest.loaders import load_bytes
from rag_qa.ingest.pipeline import ingest_document
from rag_qa.llm.fake import FakeChat, FakeEmbedder
from rag_qa.qa.answer import QAService
from rag_qa.vectorstore.chroma_store import ChromaStore


async def test_cached_embedder_only_embeds_missing():
    inner = FakeEmbedder()
    emb = CachedEmbedder(inner, MemoryKV(), model="fake")
    a = await emb.embed(["甲", "乙"])
    b = await emb.embed(["乙", "丙"])
    assert inner.calls == 2 and a[1] == b[0]


async def test_answer_cache_invalidated_by_doc_change(tmp_path):
    store, emb, chat = ChromaStore(str(tmp_path)), FakeEmbedder(), FakeChat("答 [1]")
    await ingest_document(load_bytes("a.md", "# 甲\n甲的内容是一".encode()), store, emb)
    qa = CachedQA(QAService(store, emb, chat), MemoryKV())
    await qa.answer("甲的内容")
    await qa.answer("  甲的内容 ")          # 空白不同也命中缓存
    assert len(chat.received) == 1
    await ingest_document(load_bytes("a.md", "# 甲\n甲的内容是二".encode()), store, emb)
    await qa.answer("甲的内容")
    assert len(chat.received) == 2           # 文档更新后不再使用旧答案
```

把各部分按配置组装起来（覆盖第 5 周的 `config.py` 和 `container.py`）：

```python
# 文件：rag-qa/src/rag_qa/config.py
from typing import Literal

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

    llm_base_url: str = ""
    llm_api_key: str = ""
    chat_model: str = ""
    embed_model: str = ""
    rerank_model: str = ""          # 为空时用假重排
    embed_batch: int = 32
    chroma_path: str = "data/chroma"
    collection: str = "rag_chunks"
    chunk_size: int = 500
    chunk_overlap: int = 80
    top_k: int = 4
    min_score: float = 0.2
    max_context_chars: int = 6000
    max_upload_mb: int = 10
    retrieval_mode: Literal["vector", "hybrid", "hybrid_rerank"] = "hybrid"
    redis_url: str = ""             # 为空时缓存和会话放内存（只适合单进程开发）

    @property
    def use_fake(self) -> bool:
        return not self.llm_api_key
```

```python
# 文件：rag-qa/src/rag_qa/container.py
from dataclasses import dataclass

import httpx

from rag_qa.cache import KV, CachedEmbedder, CachedQA, MemoryKV, RedisKV
from rag_qa.config import Settings
from rag_qa.llm.base import ChatModel, Embedder
from rag_qa.llm.fake import FakeChat, FakeEmbedder
from rag_qa.llm.openai_compat import OpenAICompatChat, OpenAICompatEmbedder
from rag_qa.memory.session import MemorySessionStore, RedisSessionStore, SessionStore
from rag_qa.qa.answer import QAService
from rag_qa.qa.rewrite import ConversationalQA
from rag_qa.retrieval.hybrid import HybridQAService
from rag_qa.retrieval.rerank import ApiReranker, OverlapReranker, Reranker
from rag_qa.vectorstore.base import VectorStore
from rag_qa.vectorstore.chroma_store import ChromaStore


@dataclass
class Container:
    settings: Settings
    store: VectorStore
    embedder: Embedder
    chat: ChatModel
    qa: QAService
    kv: KV
    sessions: SessionStore
    conv: ConversationalQA
    cached_qa: CachedQA


def build_container(settings: Settings | None = None, store: VectorStore | None = None,
                    embedder: Embedder | None = None, chat: ChatModel | None = None,
                    mode: str | None = None) -> Container:
    s = settings or Settings()
    mode = mode or s.retrieval_mode
    client = None
    if not s.use_fake:
        client = httpx.AsyncClient(base_url=s.llm_base_url, timeout=60,
                                   headers={"Authorization": f"Bearer {s.llm_api_key}"})
    embedder = embedder or (OpenAICompatEmbedder(client, s.embed_model, s.embed_batch) if client else FakeEmbedder())
    chat = chat or (OpenAICompatChat(client, s.chat_model) if client else FakeChat())

    if s.redis_url:
        import redis.asyncio as redis

        r = redis.from_url(s.redis_url, decode_responses=True)
        kv: KV = RedisKV(r)
        sessions: SessionStore = RedisSessionStore(r)
    else:
        kv, sessions = MemoryKV(), MemorySessionStore()

    embedder = CachedEmbedder(embedder, kv, s.embed_model or "fake")
    store = store or ChromaStore(s.chroma_path, s.collection)

    if mode == "vector":
        qa = QAService(store, embedder, chat, s.top_k, s.min_score, s.max_context_chars)
    else:
        reranker: Reranker | None = None
        if mode == "hybrid_rerank":
            reranker = ApiReranker(client, s.rerank_model) if client and s.rerank_model else OverlapReranker()
        qa = HybridQAService(store, embedder, chat, top_k=s.top_k, min_score=s.min_score,
                             max_context_chars=s.max_context_chars, reranker=reranker)
    return Container(s, store, embedder, chat, qa, kv, sessions,
                     ConversationalQA(qa, sessions, chat), CachedQA(qa, kv))
```

多轮对话接口单独放一个模块，在 `create_app` 的 `return app` 之前加一行注册：

```python
# 片段：rag-qa/src/rag_qa/api/app.py 的 create_app() 里
    from rag_qa.api.chat import register_chat_routes

    register_chat_routes(app, c)
    return app
```

```python
# 文件：rag-qa/src/rag_qa/api/chat.py
from fastapi import FastAPI
from pydantic import BaseModel, Field

from rag_qa.container import Container
from rag_qa.qa.answer import Answer


class ChatIn(BaseModel):
    session_id: str = Field(min_length=1, max_length=64)
    question: str = Field(min_length=1, max_length=500)


class ChatOut(BaseModel):
    standalone_question: str
    answer: Answer


def register_chat_routes(app: FastAPI, c: Container) -> None:
    @app.post("/chat", response_model=ChatOut)
    async def chat(body: ChatIn):
        q, ans = await c.conv.ask(body.session_id, body.question)
        return ChatOut(standalone_question=q, answer=ans)

    @app.get("/chat/{session_id}/history")
    async def history(session_id: str):
        return await c.sessions.history(session_id)
```

```python
# 文件：rag-qa/tests/test_chat_api.py
from fastapi.testclient import TestClient

from rag_qa.api.app import create_app
from rag_qa.api.chat import register_chat_routes
from rag_qa.config import Settings
from rag_qa.container import build_container
from rag_qa.vectorstore.chroma_store import ChromaStore


def test_chat_routes(tmp_path):
    c = build_container(Settings(llm_api_key="", redis_url=""), store=ChromaStore(str(tmp_path)))
    app = create_app(c)
    register_chat_routes(app, c)
    with TestClient(app) as client:
        flow(client)


def flow(client: TestClient):
    client.post("/documents", files={"file": ("go.md", "# Go\ngoroutine 用 channel 通信".encode(), "text/markdown")})
    r = client.post("/chat", json={"session_id": "s1", "question": "goroutine 怎么通信"})
    assert r.status_code == 200 and r.json()["answer"]["citations"]
    assert len(client.get("/chat/s1/history").json()) == 2
```

**易错点 / 面试常问（补充）**

- 易错点：答案缓存的键要包含“知识库版本”，否则文档更新后还会返回旧答案（本项目用文档哈希算版本）。
- 易错点：流式接口和多轮对话的回答一般不缓存，或者只缓存嵌入向量（同一段文字的向量是固定的）。
- 面试常问：缓存什么最划算（嵌入向量、高频问题的答案）；缓存穿透、击穿、雪崩分别是什么（第 14 周有专题）。

### 要建的文件

- `cache.py`、`config.py`（覆盖）、`container.py`（覆盖）、`api/chat.py`、在 `api/app.py` 里注册路由、`tests/test_cache.py`、`tests/test_chat_api.py`

### 运行方式

```bash
uv run pytest -v
REDIS_URL=redis://localhost:6379/0 uv run rag-qa ask "……"    # 问两次，第二次看 latency_ms
redis-cli --scan --pattern 'rag:*' | head
```

### 完成标准

- 全部测试通过；能讲清“答案缓存怎么失效”和“为什么向量缓存键要带模型名”。

---

## 第 6 天：LangChain 对照实现 + Milvus / pgvector

### 学习内容

**1. LangChain LCEL**

- 说明：LangChain 的 LCEL 用 `|` 把“检索 → 提示词 → 模型 → 解析”串成一条链，每个环节都是 `Runnable`，自带 `invoke` / `ainvoke` / `stream` / `batch`。它帮你省掉的是**胶水代码**；检索策略、阈值、拒答、引用这些**核心逻辑仍然要你自己设计**——这就是先手写的意义，面试时这样讲很加分。
- 接入真实模型可以用 `init_chat_model` 或 `langchain-openai` 的 `ChatOpenAI(base_url=...)`；向量库有 `langchain-chroma`、`langchain-milvus` 等集成包。LangChain 版本更新快，**接口以官方文档为准**：https://python.langchain.com/ （LCEL 概念：https://python.langchain.com/docs/concepts/lcel/ ）
- 案例：复用我们自己的检索和提示词，只把编排换成 LCEL。

```python
# 文件：rag-qa/src/rag_qa/lc_pipeline.py
from langchain_core.language_models import BaseChatModel
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import Runnable, RunnableLambda, RunnablePassthrough

from rag_qa.qa.answer import QAService
from rag_qa.qa.prompts import NOT_FOUND, SYSTEM, build_context


def build_chain(qa: QAService, llm: BaseChatModel) -> Runnable:
    async def retrieve(question: str) -> str:
        hits = await qa.retrieve(question)
        context, _ = build_context(hits, qa.max_context_chars)
        return context

    prompt = ChatPromptTemplate.from_messages([
        ("system", SYSTEM),
        ("human", "<资料>\n{context}\n</资料>\n\n问题：{question}"),  # {} 是模板变量
    ])
    answer_chain = prompt | llm | StrOutputParser()

    async def route(inputs: dict) -> str:  # 没检索到资料就不调模型
        if not inputs["context"]:
            return NOT_FOUND
        return await answer_chain.ainvoke(inputs)

    return {"context": RunnableLambda(retrieve), "question": RunnablePassthrough()} | RunnableLambda(route)
```

```python
# 文件：rag-qa/tests/test_lc_pipeline.py
from langchain_core.language_models.fake_chat_models import FakeListChatModel

from rag_qa.ingest.loaders import load_bytes
from rag_qa.ingest.pipeline import ingest_document
from rag_qa.lc_pipeline import build_chain
from rag_qa.llm.fake import FakeChat, FakeEmbedder
from rag_qa.qa.answer import QAService
from rag_qa.qa.prompts import NOT_FOUND
from rag_qa.vectorstore.chroma_store import ChromaStore


async def test_lcel_chain(tmp_path):
    store, emb = ChromaStore(str(tmp_path)), FakeEmbedder()
    await ingest_document(load_bytes("k8s.md", "# K8s\nPod 是最小调度单位。".encode()), store, emb)
    chain = build_chain(QAService(store, emb, FakeChat()), FakeListChatModel(responses=["Pod 是最小调度单位 [1]"]))
    assert await chain.ainvoke("Pod 是什么") == "Pod 是最小调度单位 [1]"
    assert await chain.ainvoke("今天天气") == NOT_FOUND
```

**对照表（写进 README）**

| 环节 | 手写版 | LangChain 版 |
| --- | --- | --- |
| 模型调用 | `OpenAICompatChat`（httpx） | `ChatOpenAI` / `init_chat_model` |
| 编排 | 普通 async 函数 | LCEL `\|` 组合 Runnable |
| 流式 | 自己解析 `data:` 行 | `astream()` |
| 检索、阈值、拒答、引用 | 自己写 | **仍然自己写**（或用现成 Retriever 再定制） |
| 优点 | 每一步可控、好调试 | 生态集成多、换组件快 |
| 缺点 | 胶水代码多 | 抽象层多，出问题要读源码；版本变化快 |

**2. Milvus 和 pgvector**

- 说明：
  - **Milvus**：专门的分布式向量数据库，适合千万级以上向量、需要水平扩展的场景，部署比 Chroma 重（单机版也要 etcd、MinIO 等组件）；有 Milvus Lite 可以本地体验。
  - **pgvector**：PostgreSQL 的向量扩展。好处是向量和业务数据在同一个库里，可以一条 SQL 同时做向量检索和权限过滤、事务一致；规模中等时很实用。
  - **Chroma**：上手最快，适合原型和中小规模。
  - 换库只需要再写一个实现 `VectorStore` 协议的类，其他代码不动——面试时讲“我是怎么为替换做准备的”。
- 案例：pgvector 版的核心 SQL（需要装好 pgvector 扩展，例如用 `pgvector/pgvector:pg17` 镜像）：

```sql
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE rag_chunks (
  chunk_id     text PRIMARY KEY,
  doc_id       text NOT NULL,
  filename     text NOT NULL,
  heading_path text NOT NULL DEFAULT '',
  text         text NOT NULL,
  embedding    vector(1024) NOT NULL          -- 维度必须和向量模型一致
);
CREATE INDEX ON rag_chunks USING hnsw (embedding vector_cosine_ops);
CREATE INDEX ON rag_chunks (doc_id);

-- <=> 是余弦距离，相似度 = 1 - 距离；$1 是问题向量
SELECT chunk_id, text, 1 - (embedding <=> $1) AS score
FROM rag_chunks
ORDER BY embedding <=> $1
LIMIT 4;
```

Milvus 的 Python 用法示意（`pymilvus` 的 `MilvusClient`，接口以官方文档为准：https://milvus.io/docs ）：

```python
# 不自动运行：需要 uv add pymilvus 和一个 Milvus 服务（或 Milvus Lite 本地文件）
from pymilvus import MilvusClient

client = MilvusClient("milvus_demo.db")  # 本地 Milvus Lite；连服务器时传 uri="http://host:19530"
client.create_collection(collection_name="rag_chunks", dimension=4, metric_type="COSINE")
client.insert("rag_chunks", [{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4], "text": "示例", "doc_id": "d1"}])
res = client.search("rag_chunks", data=[[0.1, 0.2, 0.3, 0.4]], limit=3, output_fields=["text", "doc_id"])
print(res)
```

| | Chroma | Milvus | pgvector |
| --- | --- | --- | --- |
| 定位 | 轻量、嵌入式或单服务 | 专业分布式向量库 | PostgreSQL 扩展 |
| 规模 | 中小 | 大 | 中 |
| 运维 | 最简单 | 最重 | 复用已有 PostgreSQL |
| 和业务数据联查 | 弱 | 弱 | 强（同一条 SQL、同一个事务） |
| 本项目 | 默认 | 了解 + 选做 | 选做 |

**易错点 / 面试常问（补充）**

- 易错点：LangChain 的包拆得很细（`langchain-core`、`langchain-openai`、各种集成包），网上旧教程的导入路径经常已经失效，以官方文档为准：https://docs.langchain.com/oss/python/langchain/overview 。
- 易错点：换向量库（Milvus、pgvector）时，距离类型（余弦 / 内积 / 欧氏）要和嵌入模型的要求一致，否则分数没有意义。
- 面试常问：Chroma、Milvus、pgvector 怎么选（原型和小规模用 Chroma；数据量大、要分布式用 Milvus；已经有 PostgreSQL 且规模不大用 pgvector，事务和过滤方便）；什么是 HNSW 索引（近似最近邻，用一点精度换速度）。

### 要建的文件

- `lc_pipeline.py`、`tests/test_lc_pipeline.py`；README 加对照表和向量库对比
- 选做：`vectorstore/pgvector_store.py`（复用第 2 周的 PostgreSQL 知识，`uv add "psycopg[binary]" pgvector`）

### 运行方式

```bash
uv run pytest tests/test_lc_pipeline.py -v
```

### 完成标准

- 能回答：“LangChain 帮你做了什么，没做什么？”“Chroma、Milvus、pgvector 怎么选？”

---

## 第 7 天：Docker Compose 部署 + 复盘

### 学习内容

- 说明：
  - Python 镜像用 `python:3.12-slim` + uv：先只复制依赖文件安装依赖（利用缓存层），再复制代码。
  - 数据卷：Chroma 数据（`/app/data`）必须挂卷，否则容器重建数据全丢。
  - Chroma 也可以作为独立服务运行（官方镜像 `chromadb/chroma`），这时代码改用 `chromadb.HttpClient(host=..., port=...)`；本项目单实例先用嵌入式。
  - 多个 API 实例时：会话和缓存必须放 Redis（内存版各实例互相看不到），嵌入式 Chroma 不能被多个进程同时写——要么单实例，要么换成独立的向量库服务。
- 案例：

```dockerfile
FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
COPY pyproject.toml uv.lock README.md ./
RUN uv sync --frozen --no-dev --no-install-project
COPY src ./src
RUN uv sync --frozen --no-dev
ENV PATH="/app/.venv/bin:$PATH"
EXPOSE 8000
CMD ["uvicorn", "rag_qa.api.app:create_app", "--factory", "--host", "0.0.0.0", "--port", "8000"]
```

```yaml
services:
  api:
    build: .
    env_file: .env
    environment:
      REDIS_URL: redis://redis:6379/0
      CHROMA_PATH: /app/data/chroma
    volumes:
      - rag-data:/app/data
    ports:
      - "8000:8000"
    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped
  redis:
    image: redis:7
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 10
volumes:
  rag-data:
```

**易错点 / 面试常问（补充）**

- 易错点：Chroma 的数据目录要挂到数据卷上，否则重建容器后索引就没了。
- 面试常问：RAG 上线后怎么持续优化（收集答不好的问题 → 加进评测集 → 调切分 / 检索 / 提示词 → 对比指标）。

### 要建的文件

- `Dockerfile`、`docker-compose.yml`、`.dockerignore`（`.venv`、`data`、`.env`、`__pycache__`）
- `eval/results.md` 整理成表格；README 补“评测结果”“设计取舍”“对照表”

### 运行方式

```bash
docker compose up -d --build
curl localhost:8000/health
curl -F "file=@samples/你的文件.md" localhost:8000/documents
docker compose restart api && curl localhost:8000/documents    # 重启后数据还在
```

### 完成标准

- Compose 一键启动，重启后数据不丢；部署到服务器的事放到第 14 周统一做。
- 能脱稿回答：
  1. 你的评测集怎么建的？指标是什么？各项优化分别带来了什么变化？
  2. 混合检索和重排分别解决什么问题？代价是什么？
  3. 多轮追问怎么处理？会话存哪里？
  4. 缓存怎么失效？
  5. LangChain 帮你做了什么？
  6. 向量库怎么选？

---

## 本周自查清单

- [ ] 评测集 ≥ 30 条（含拒答题），会算 Hit@K、MRR、拒答准确率
- [ ] `eval/results.md` 有基线、切分实验、混合检索、重排的对比记录
- [ ] 混合检索（BM25 + 向量 + RRF）和重排都有测试
- [ ] 多轮追问改写 + Redis 会话记忆（真实 Redis 测试通过）
- [ ] 向量缓存、答案缓存（带失效策略）
- [ ] LangChain LCEL 对照实现，能讲清手写和框架的取舍
- [ ] 了解 Milvus、pgvector，能说出选型理由
- [ ] Docker Compose 部署，数据持久化