# RAG_1

**Repository Path**: IceCream1012/rag_1

## Basic Information

- **Project Name**: RAG_1
- **Description**: 大模型rag知识学习
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-03
- **Last Updated**: 2025-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG-1：从 0 到实战的最小可行项目 (MVP)

> 一个在 Windows 本地即可运行的 RAG 最小项目：文档切分 → 向量化 → FAISS 检索 → LLM 生成（可选）。

## 目录结构

```
RAG-1/
  data/                # 放你的 PDF/Markdown/TXT 文档
  indexes/             # 向量索引与元数据
  build_index.py       # 构建索引脚本
  server.py            # FastAPI 服务
  requirements.txt     # 依赖
  README.md            # 本文档
```

## 一、学习路线（1-2 周）
- 基础概念
  - RAG = 检索（Retrieve）+ 生成（Generate）。
  - 关键环节：文档切分、向量化、索引检索、重排序（可选）、提示词拼装、回答生成与评估。
- 必会工具
  - 嵌入模型：`BAAI/bge-small-zh-v1.5`（中文表现好）。
  - 向量库：FAISS（本地轻量）、Chroma、Qdrant（服务化）。
  - LLM：OpenAI、Moonshot，或本地 `Ollama` + `qwen2.5`。
  - 框架（可选）：LangChain、LlamaIndex（先理解原理再用）。

## 二、最小架构（数据流）
- 文档 → 切分 → 向量化 → FAISS 索引（磁盘持久化）
- 查询 → 向量化 → 相似搜索 topK →（可选 rerank）→ 构造上下文 → 调用 LLM → 返回答案

## 三、技术选型（MVP）
- 语言/框架：Python + FastAPI
- 嵌入模型：`BAAI/bge-small-zh-v1.5`
- 向量库：FAISS（内积 + 向量归一化 ≈ 余弦相似）
- LLM：OpenAI（如无 Key，则先返回基于上下文的演示回答）

## 四、快速开始（Windows PowerShell）
1) 准备环境
```powershell
python -m venv .venv
. .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

2) 准备数据
- 将 PDF/MD/TXT 文件放到 `data/` 目录（已创建）。

3) 构建索引
```powershell
python .\build_index.py
```

4) 可选：配置 OpenAI Key
```powershell
$env:OPENAI_API_KEY="sk-你的key"
```

5) 启动服务
```powershell
uvicorn server:app --reload --host 0.0.0.0 --port 8000
```

6) 测试接口
```powershell
curl -X POST http://localhost:8000/ask -H "Content-Type: application/json" -d "{\"query\":\"给我总结xxx文件的核心要点\"}"
```

## 五、API 说明
- `POST /ask`
  - 请求体
    ```json
    {
      "query": "你的问题",
      "top_k": 5
    }
    ```
  - 响应体
    ```json
    {
      "answer": "模型/演示模式的答案",
      "contexts": [
        {"text": "片段内容", "source": "文件路径", "chunk_id": "xxx", "score": 0.83}
      ]
    }
    ```

## 六、进阶优化清单
- 检索效果
  - 重排序：`BAAI/bge-reranker-base`/`-large` 作为 cross-encoder rerank。
  - 混合检索：BM25（如 Elasticsearch）+ 向量检索加权融合。
  - 更优切分：按标题/语义切分；表格、代码、图片用专用解析。
- 生成质量
  - 提示模板：结构化输出、引用来源标注。
  - 自洽检查：先列依据再输出最终答案。
- 工程化
  - 缓存（查询向量、检索结果、LLM 响应）。
  - 监控与日志（命中率、延迟）。
  - 权限与多租户（数据隔离）。
- 评估
  - RAGAS、ARES 评估 Faithfulness 与 Context Precision/Recall。
  - 构造 Golden Set 做回归测试。
- 部署
  - 向量库服务化（Qdrant/Weaviate）。
  - 网页前端（Next.js/Vue）。

## 七、常见问题（FAQ）
- 切分多大合适？
  - 建议 400-800 字 + 15%-25% overlap 起步。
- 相似度该用什么？
  - 若向量已归一化、索引用内积（IP），等价于余弦相似。
- PDF 解析失败/乱码？
  - 扫描版需 OCR；可用 `paddleocr`、`tesseract` 等。
- 上下文过长导致 LLM 超长？
  - 截断、摘要、或使用长上下文模型。
- 评估怎么做？
  - 先做小规模黄金集，配合 RAGAS 迭代。

## 八、许可
- 仅供学习与内部验证使用，请自行确保数据与模型许可合规。