projects/repobot/v2/README.md

# RepoBot v2

httpx 答疑助手的第二版，对应课程 [04 模块第 7 课](../../../04-rag/07-project-repobot-v2.md)。

## 和 v1 相比

v1 只凭模型自己的记忆回答，在"httpx 默认会不会跟随重定向"这类问题上会答错。v2 在回答之前，先去 httpx 的官方文档里检索相关的段落，照着文档回答，并注明出处。

每一轮的流程：

1. 结合最近几轮对话，把问题改写成英文检索词（httpx 的文档是英文的）。
2. 用关键词检索（BM25）和向量检索各取 20 块，用 RRF 融合；加 `--rerank` 时再用重排模型精排。
3. 把最相关的 5 块编号放进提示词，要求模型每句话都注明依据。
4. 流式输出回答，最后列出实际引用到的文档。

## 文件

- `repobot.py`：对话程序
- `retrieval.py`：切分、BM25、向量检索、融合、重排、查询改写
- `llm.py`：模型客户端、计费、重试
- `eval_retrieval.py`：用 `eval_qa.jsonl` 的 20 道题评估检索效果

## 运行

需要 Python 3.10 以上，并按[第 00 模块第 2 课](../../../00-start/02-setup.md)设置好 `LLM_API_KEY`、`LLM_BASE_URL`、`LLM_MODEL` 三个环境变量。

```bash
pip install -r requirements.txt
export HF_ENDPOINT=https://hf-mirror.com   # 国内下载模型慢时使用镜像
python repobot.py
```

第一次运行会下载嵌入模型 multilingual-e5-small（约 470MB），并计算所有文档块的向量，存到 `.cache/` 目录里。之后启动会直接读取缓存。

加上重排（第一次运行会再下载约 1.1GB 的 bge-reranker-base）：

```bash
python repobot.py --rerank
```

显示每一轮的检索词和检索到的文档：

```bash
python repobot.py --show-query
```

默认读取课程仓库里的 `data/httpx-docs/`。要换成别的文档目录，设置环境变量 `REPOBOT_DOCS`。