# RAG项目

**Repository Path**: zzt-git/rag-project

## Basic Information

- **Project Name**: RAG项目
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
title: PyDoc-RAG
emoji: 🐍
colorFrom: blue
colorTo: indigo
sdk: streamlit
sdk_version: "1.36.0"
app_file: app.py
pinned: false
---

# PyDoc-RAG：Python 官方文档智能问答助手

基于 RAG（检索增强生成）的本地化文档问答系统。用户用自然语言提问，系统从 Python 3.12 官方文档中检索相关段落，调用本地大语言模型生成**带引用来源**的准确回答。

## 核心特性

- **文档自动入库**：下载 Python 3.12 官方 HTML 文档 → BeautifulSoup 清洗 → 递归语义分块
- **混合检索**：向量检索（bge-small-zh）+ BM25 关键词检索加权融合，召回更稳
- **CrossEncoder 重排序**：bge-reranker-base 二次精排，Top-20 → Top-4，再提 3~5% 召回
- **引用溯源**：每条答案标注来源文档路径，可点击直达官方文档
- **本地推理**：Qwen2-7B 经 Ollama 本地运行，数据不出本机
- **流式 Web 界面**：Streamlit 聊天式交互，多轮会话，实时输出
- **一键部署**：Docker Compose 编排（app + ollama + chroma）

## 技术栈

| 模块 | 选型 | 说明 |
|------|------|------|
| 框架 | 原生实现（参考 LlamaIndex 架构思想） | 透明可控的检索/分块/Prompt 链路 |
| 嵌入模型 | BAAI/bge-small-zh-v1.5 | 中文效果好，512 维，CPU 可跑 |
| 向量数据库 | Chroma（生产 Docker 服务）/ numpy 暴力检索（dev） | 双模式：生产用 Chroma HttpClient，开发用 numpy 零依赖 |
| 重排序 | BAAI/bge-reranker-base (CrossEncoder) | 混合检索后二次精排 |
| 大模型 | Qwen2-7B-Instruct (Ollama) | 中文能力强，4-bit 量化本地推理 |
| 界面 | Streamlit | 快速构建聊天 Demo |
| 部署 | Docker + HF Spaces | 容器化 + 免费公开托管 |

## 目录结构

```
pydoc-rag/
├── app.py                  # Streamlit Web 界面
├── config.py               # 全局配置（从 .env 读取）
├── requirements.txt
├── Dockerfile / docker-compose.yml / docker-entrypoint.sh
├── src/
│   ├── data_ingestion.py   # 下载、HTML 清洗、递归分块
│   ├── embeddings.py       # bge 嵌入封装
│   ├── vector_store.py     # 向量库封装（numpy + chroma HttpClient 双模式）
│   ├── retriever.py        # 向量 + BM25 混合检索 + reranker 精排
│   ├── reranker.py         # CrossEncoder 重排序（bge-reranker-base）
│   ├── llm.py              # Ollama LLM 封装
│   ├── prompt.py           # Prompt 模板（防幻觉 + 引用约束）
│   └── pipeline.py         # 端到端问答流水线 + 引用溯源
├── scripts/
│   ├── download_docs.py    # 下载文档
│   ├── build_index.py      # 构建向量索引
│   └── eval_retrieval.py   # 检索召回率评估
├── tests/                  # 单元测试 + 20 题召回评估
└── docs/                   # 架构/API/部署/人工操作/测试文档
```

## 快速开始（本地）

> 完整的人工操作步骤（含 Ollama 安装、验证命令）见 [docs/MANUAL_SETUP.md](docs/MANUAL_SETUP.md)。

```bash
# 1. 创建虚拟环境
python -m venv .venv && .venv\Scripts\activate    # Windows
# source .venv/bin/activate                        # macOS/Linux

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env

# 4. 启动 Ollama 并拉取模型（另开终端）
ollama serve
ollama pull qwen2:7b

# 5. 构建索引（首次需下载约 50MB 文档 + 嵌入模型）
python scripts/build_index.py

# 6. 启动 Web 界面
streamlit run app.py
# 浏览器打开 http://localhost:8501
```

## 命令行问答（可选）

```python
from src.pipeline import RAGPipeline
pipe = RAGPipeline()
ans = pipe.answer("pathlib 怎么读取文件内容？")
print(ans.answer)
for c in ans.citations:
    print(f"[{c.index}] {c.title} ({c.source})")
```

## 评估检索效果

```bash
# 评估 Top-3 召回率与 MRR
python scripts/eval_retrieval.py --top-k 3

# 对比 纯向量 vs 混合检索
python scripts/eval_retrieval.py --compare
```

## 测试

```bash
pytest -v
```

## 文档

- [架构设计](docs/ARCHITECTURE.md)
- [API 文档](docs/API.md)
- [部署指南](docs/DEPLOYMENT.md)
- [人工操作指南](docs/MANUAL_SETUP.md)
- [测试与优化](docs/TESTING.md)

## 分阶段实施计划（4 周）

| 周次 | 目标 | 交付物 |
|------|------|--------|
| 第 1 周 | 环境与数据准备 | 文档入库、Chroma 索引构建脚本 |
| 第 2 周 | 核心问答链路 | 命令行问答、引用溯源、20 题召回测试 |
| 第 3 周 | Web 界面与优化 | Streamlit 聊天界面、混合检索对比实验 |
| 第 4 周 | 部署与复盘 | Docker 部署、HF Spaces 上线、README + 博客 |

## 简历描述（参考）

> 基于 Chroma + Qwen2 构建 Python 官方文档 RAG 问答系统，实现文档自动入库、混合检索（向量+BM25）、引用溯源等功能。通过优化分块策略与混合检索权重，将 Top-3 召回率提升至 78%，支持 Streamlit 交互界面与 Docker 一键部署。

## License

MIT