Project1: RAG + Reranker + SFT

本项目是一个中文汽车手册问答系统，包含完整链路：

• 文档解析与清洗（PDF -> chunk）
• 双路召回（BM25 + Milvus Hybrid）
• 重排（BGE-M3 Reranker，支持微调）
• 回答生成（Qwen3-8B，支持 LoRA 微调）
• 离线评估（nDCG@k + RAGAS）

1. 项目结构

.
├── src/
│   ├── parser/                 # PDF 解析、切分、入 Mongo
│   ├── retriever/              # BM25 / Milvus 检索
│   ├── reranker/               # BGE-M3 重排
│   ├── client/                 # Mongo/Milvus/LLM 客户端
│   ├── gen_qa/                 # QA 对生成与扩写
│   └── config/settings.py      # 全局配置（pydantic-settings）
├── data/
│   ├── processed_docs/          # raw/clean/split 文档缓存
│   ├── saved_index/             # bm25 与 milvus_lite 本地索引
│   ├── qa_pairs/                # QA、检索上下文、response 数据
│   ├── rerank_data/             # reranker 训练数据
│   ├── summary_data/            # SFT 训练/测试数据
│   └── rerank_eval/             # reranker 对比评测数据
├── RAG-Retrieval/               # reranker 训练框架
├── LlamaFactory/                # chat model 微调与推理
├── build_index.py               # 建库建索引入口
├── generate_sft_data.py         # 训练数据转换
├── eval_reranker_ndcg.py        # reranker nDCG 评估
├── final_score_runner.py        # RAGAS 评估执行
└── run_ragas_split.sh           # RAGAS 批量运行脚本

2. 环境准备

2.1 Python 依赖

推荐 Python 3.10 ~ 3.12。

uv sync

2.2 外部服务

1. MongoDB（用于存储原始/父子文档映射）
2. Semantic Chunk 服务（FastAPI，本项目内置）

启动语义切分服务：

python src/server/semantic_chunk.py

2.3 .env 配置

项目已统一通过 src/config/settings.py 读取 .env，不需要各处手工 load_dotenv()。

最小示例（按需填写）：

GEMINI_API_KEY=
GEMINI_API_KEY2=
GEMINI_API_KEY3=
GEMINI_BASE_URL=
GEMINI_MODEL_NAME=gemini-3-flash-preview

MONGO_HOST=localhost
MONGO_PORT=27017
MONGO_DB_NAME=mydatabase
MONGO_COLLECTION_NAME=manual_text
MONGO_USERNAME=
MONGO_PASSWORD=
MONGO_AUTH_SOURCE=admin

SEMANTIC_CHUNK_URL=http://127.0.0.1:6000/v1/semantic_chunks
LOCAL_QWEN_BASE_URL=http://localhost:8000/v1

3. 快速运行（已有数据）

如果仓库中的 data/ 已有构建结果，可直接做推理/评估。

3.1 构建索引与入库（首次）

python build_index.py

3.2 交互式问答（检索 + 重排 + 生成）

python infer.py

4. 数据构建流程（全量重跑）

说明：本项目部分脚本是“分阶段一次性脚本”，有注释块，需要按阶段启用。推荐顺序：

1. 生成 QA 与问题扩写

python src/gen_qa/run.py

2. （可选）数据筛选与提纯

python scripts/filter.py

3. 生成/补齐 response

cd scripts
python add_response.py
cd ..

4. 转换训练数据（SFT + reranker）

python generate_sft_data.py

主要产物：

• data/rerank_data/train.json
• data/rerank_data/dev.json
• data/rerank_data/test.json
• data/summary_data/train.json
• data/summary_data/test.json

5. Reranker 微调（RAG-Retrieval）

5.1 配置文件

• RAG-Retrieval/rag_retrieval/train/reranker/config/training_bert.yaml

请先确认以下路径与机器一致：

• model_name_or_path
• train_dataset
• val_dataset
• output_dir

5.2 训练命令

cd RAG-Retrieval/rag_retrieval/train/reranker
accelerate launch --config_file ../../../config/xlmroberta_default_config.yaml train_reranker.py --config config/training_bert.yaml

5.3 日志可视化

tensorboard --logdir RAG-Retrieval/rag_retrieval/train/reranker/output

6. Chat 模型微调（LlamaFactory）

6.1 准备数据

• 训练数据文件：LlamaFactory/data/summary_train.json
• 数据注册：LlamaFactory/data/dataset_info.json 中 faq_summary

6.2 训练命令

cd LlamaFactory
llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml

7. 推理与评估

7.1 启动 vLLM（建议在 tmux 中）

cd LlamaFactory
bash vllm_serve.sh

7.2 预测生成

predict.py 依赖根目录 src 包，建议：

cd LlamaFactory
PYTHONPATH=.. python predict.py

7.3 Reranker nDCG 评估

python scripts/generate_reranked_docs.py
python eval_reranker_ndcg.py

7.4 RAGAS 评估

bash run_ragas_split.sh serial all 1

或单项运行：

python final_score_runner.py --dataset before --metric precision --api-key-index 1
python final_score_runner.py --dataset before --metric recall --api-key-index 1
python final_score_runner.py --dataset after --metric precision --api-key-index 1
python final_score_runner.py --dataset after --metric recall --api-key-index 1

8. 常见问题

1. MilvusException: unsupported rank type

• 常见于 milvus-lite 与某些 ranker 参数组合不兼容。优先使用 RRFRanker 并确认 pymilvus 与 milvus-lite 版本匹配。

2. too_many_pings / GOAWAY（grpc）

• 避免频繁创建/关闭 client。
• 复用单例 client，并调大 keepalive 间隔（当前 MilvusConfig 已配置）。

3. milvus_lite 文件锁冲突

• data/saved_index/milvus.db 在多进程并发写时会锁冲突。
• 同一时刻只保留一个写入进程。

4. 训练覆盖旧 checkpoint

• 新实验请改 output_dir，避免覆盖历史结果。

9. 复盘文档

• 项目流程思维导图：PROJECT_REVIEW_MINDMAP.md
• 阶段复盘：项目总结.md