# Auto_Tune_RAG

**Repository Path**: lkq55421/auto_tune_rag

## Basic Information

- **Project Name**: Auto_Tune_RAG
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Auto-Tune RAG

基于 LangChain + Chroma 的零基础智能问答 RAG 系统，面向 RAG 小白开发者。

## 项目简介

Auto-Tune RAG 是一个完整的检索增强生成（Retrieval-Augmented Generation）系统，帮助你：

- **加载文档** - 支持 PDF、Word、TXT、Markdown 等格式
- **智能分块** - 自动将长文档切分成适合检索的文本块
- **向量存储** - 使用 Chroma 向量数据库存储文档向量
- **语义检索** - 基于向量相似度找到相关文档
- **生成回答** - 调用 LLM 基于检索结果生成答案

## 系统架构

```
用户问题
    │
    ▼
┌─────────────────────────────────────┐
│      document_loader.py             │  ← 加载文档
│      PDF / Word / TXT / Markdown     │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│      chunk_optimizer.py              │  ← 智能分块
│      RecursiveCharacterTextSplitter │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│      vector_handler.py              │  ← 向量存储
│      Chroma + HuggingFace          │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│      retriever.py                   │  ← 语义检索
│      similarity / MMR               │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│      generator.py                   │  ← LLM 生成
│      DeepSeek / GPT / Ollama       │
└─────────────────────────────────────┘
    │
    ▼
回答
```

## 快速开始

### 1. 安装依赖

```bash
cd Auto_Tune_RAG
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

pip install -r requirements.txt
```

### 2. 配置 API Key

```bash
# DeepSeek (默认)
export DEEPSEEK_API_KEY="sk-your-key"

# 或创建 .env 文件
cp .env.example .env
# 编辑 .env 填入你的 API Key
```

### 3. 构建索引

```bash
python -m src.main --build
```

### 4. 开始问答

```bash
# 单次问答
python -m src.main --query "什么是 RAG？"

# 交互模式
python -m src.main --interactive
```

## 使用指南

### CLI 命令

```bash
# 构建索引
python -m src.main --build

# 问答
python -m src.main --query "你的问题"

# 交互模式
python -m src.main --interactive

# 自定义参数
python -m src.main --build --chunk-size 300 --chunk-overlap 50

# 显示检索上下文
python -m src.main --query "问题" --show-context
```

### 放置文档

将你的文档放入 `src/data/raw_docs/` 目录，系统会自动加载：

```
src/data/raw_docs/
├── document1.pdf
├── report.docx
├── notes.txt
└── readme.md
```

### 切换 LLM 提供商

```bash
# DeepSeek (默认，国产模型效果好)
export LLM_PROVIDER=deepseek

# OpenAI GPT
export LLM_PROVIDER=openai
export OPENAI_API_KEY="sk-your-key"

# 本地 Ollama (无需 API Key)
export LLM_PROVIDER=ollama
# 需要先运行: ollama serve
```

### 切换 Embedding 模式

```bash
# Chroma 模式 (默认，使用 HuggingFace 模型)
export EMBEDDING_MODE=chroma

# Ollama 模式 (本地运行)
export EMBEDDING_MODE=ollama
```

## 项目结构

```
Auto_Tune_RAG/
├── src/
│   ├── config/
│   │   └── config.py          # 全局配置
│   ├── core/                   # 核心模块
│   │   ├── document_loader.py  # 文档加载
│   │   ├── chunk_optimizer.py  # 智能分块
│   │   ├── vector_handler.py  # 向量存储
│   │   ├── retriever.py        # 语义检索
│   │   └── generator.py        # LLM 生成
│   ├── utils/
│   │   ├── logger.py          # 日志
│   │   └── score_calculator.py # 分块评分
│   └── main.py               # CLI 入口
├── test/                       # 测试
├── doc/                        # 文档
│   └── difficult_code_analysis/ # 核心模块深度分析
└── requirements.txt
```

## 运行测试

```bash
# 运行所有测试
pytest test/ -v

# 运行单个测试文件
pytest test/test_document_loader.py -v

# 运行单个测试函数
pytest test/test_document_loader.py::test_load_pdf -v

# 带覆盖率
pytest test/ -v --cov=src --cov-report=term-missing
```

## 学习资源

### 文档目录

| 文档 | 说明 |
|------|------|
| `doc/01-quick-start.md` | 快速入门 |
| `doc/02-cli-commands.md` | CLI 命令参考 |
| `doc/03-configuration.md` | 配置指南 |
| `doc/04-rag-workflow.md` | RAG 工作流程 |
| `doc/difficult_code_analysis/` | 核心模块深度分析 |

### 核心模块分析

| 模块 | 文件 | 功能 |
|------|------|------|
| 文档加载 | `document_loader.py` | PDF/Word/TXT/Markdown |
| 智能分块 | `chunk_optimizer.py` | RecursiveCharacterTextSplitter |
| 向量处理 | `vector_handler.py` | Chroma + Embedding |
| 语义检索 | `retriever.py` | similarity / MMR |
| LLM 生成 | `generator.py` | DeepSeek / GPT / Ollama |

## 关键配置

| 配置 | 默认值 | 说明 |
|------|--------|------|
| `CHUNK_SIZE` | 256 | 分块字符数 |
| `CHUNK_OVERLAP` | 50 | 分块重叠 |
| `EMBEDDING_MODE` | chroma | chroma 或 ollama |
| `LLM_PROVIDER` | deepseek | ollama/openai/deepseek/anthropic/qwen |
| `RETRIEVAL_CONFIG` | top_k=3 | 检索结果数 |

## 支持的 LLM

| 提供商 | 模型 | 说明 |
|--------|------|------|
| DeepSeek | deepseek-chat | 国产模型，效果好 |
| OpenAI | GPT-4o / GPT-4o-mini | 效果最好 |
| Ollama | llama3 / qwen / deepseek-coder | 本地运行 |
| Anthropic | Claude 3 | 效果好 |
| Qwen | qwen-turbo / qwen-plus | 阿里云 |

## 开发指南

本项目面向 AI 编程助手和人类开发者提供了 `AGENTS.md` 开发指南，包含：

- 构建与测试命令
- 代码风格规范
- 命名约定
- 错误处理模式
- 日志使用规范

## 许可证

MIT License

## 致谢

基于 LangChain、Chroma、SentenceTransformer 等优秀开源项目。