# EduRAg

**Repository Path**: FELearnAI/edu-rag

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-07-30
- **Last Updated**: 2025-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EduRAG - 教育领域检索增强生成系统

EduRAG 是一个专为教育领域设计的检索增强生成（RAG）系统，提供智能的文档检索和问答功能。

## 🌟 项目特色

- **智能查询分类**: 自动识别查询类型（事实性、概念性、操作性、比较性）
- **动态策略选择**: 根据查询特征选择最优检索策略
- **高效向量检索**: 基于 Milvus 的向量相似性检索
- **多轮对话支持**: 支持上下文相关的多轮对话
- **缓存优化**: 使用 Redis 缓存提升检索性能
- **模块化设计**: 松耦合的组件架构，易于扩展

## 📁 项目结构

```
EduRAG/
├── config.ini                 # 配置文件，包含所有模块的配置
├── base/                      # 基础模块
│   ├── __init__.py           # 模块初始化
│   ├── config.py             # 配置管理，加载 config.ini
│   └── logger.py             # 日志设置
├── rag_qa/                   # RAG 问答模块
│   ├── __init__.py           # 模块初始化
│   ├── core/                 # 核心功能
│   │   ├── __init__.py       # 核心模块初始化
│   │   ├── prompts.py        # RAG 提示模板
│   │   ├── query_classifier.py # 查询分类器
│   │   ├── strategy_selector.py # 检索策略选择器
│   │   ├── vector_store.py   # 向量存储与检索
│   │   └── rag_system.py     # RAG 系统核心逻辑
│   └── main.py               # RAG 系统独立入口，支持存储和查询
├── requirements.txt          # 依赖文件
├── docker-compose.yml        # Docker 服务配置
├── milvus_db.py             # Milvus 数据库操作
├── volumes/                  # Docker 数据卷（已在 .gitignore 中排除）
└── logs/                     # 日志目录
    └── app.log               # 应用日志文件
```

## 🚀 快速开始

### 环境要求

- **Python**: 3.8+ (推荐 3.12)
- **Docker**: 20.0+
- **Docker Compose**: 2.0+
- **内存**: 至少 4GB RAM
- **存储**: 至少 2GB 可用空间

### 1. 克隆项目

```bash
git clone <repository-url>
cd EduRAG
```

### 2. 安装依赖

```bash
# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

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

### 3. 启动服务

```bash
# 启动 Milvus、Redis 等服务
docker-compose up -d

# 检查服务状态
docker-compose ps

# 查看服务日志
docker-compose logs -f
```

### 4. 验证安装

```bash
# 检查系统状态
cd rag_qa
python main.py --mode info
```

如果看到类似以下输出，说明安装成功：

```
=== RAG 系统信息 ===

配置信息:
Milvus 主机: localhost
Milvus 端口: 19530
Redis 主机: localhost
Redis 端口: 6379
嵌入维度: 384

系统统计: {
  "vector_store": {
    "name": "edu_rag_collection",
    "num_entities": 0,
    "dimension": 384
  },
  "chat_history_length": 0,
  "max_history_length": 10,
  "system_status": "running"
}
```

## 📖 使用指南

### 基本使用

```bash
cd rag_qa

# 1. 查看系统信息
python main.py --mode info

# 2. 交互式添加文档
python main.py --mode add

# 3. 交互式查询
python main.py --mode query

# 4. 从文件批量添加文档
python main.py --mode add --file documents.json

# 5. 批量查询
python main.py --mode batch --file questions.txt --output results.json
```

### 文档格式示例

创建 `documents.json` 文件：

```json
[
  {
    "doc_id": "ml_001",
    "content": "机器学习是人工智能的一个分支，它使计算机能够在没有明确编程的情况下学习。机器学习算法通过分析数据来识别模式，并使用这些模式来做出预测或决策。",
    "embedding": [0.1, 0.2, 0.3, ...],
    "metadata": {
      "subject": "计算机科学",
      "difficulty": "中级",
      "source": "教材第一章",
      "keywords": ["机器学习", "人工智能", "算法"]
    }
  },
  {
    "doc_id": "dl_001", 
    "content": "深度学习是机器学习的一个子集，它使用多层神经网络来学习数据的复杂模式。深度学习在图像识别、自然语言处理等领域取得了突破性进展。",
    "embedding": [0.4, 0.5, 0.6, ...],
    "metadata": {
      "subject": "计算机科学",
      "difficulty": "高级",
      "source": "教材第五章",
      "keywords": ["深度学习", "神经网络", "图像识别"]
    }
  }
]
```

### 查询示例

```bash
# 启动交互式查询
python main.py --mode query

# 示例对话
请输入您的问题: 什么是机器学习？
答案: 根据相关文档，机器学习是人工智能的一个分支...

请输入您的问题: 深度学习和机器学习有什么区别？
答案: 基于对话历史和相关文档，深度学习是机器学习的一个子集...

# 特殊命令
clear  # 清空对话历史
stats  # 查看系统统计
quit   # 退出系统
```

## ⚙️ 配置说明

### 主配置文件 (config.ini)

```ini
[milvus]
host = localhost
port = 19530
collection_name = edu_rag_collection

[redis]
host = localhost
port = 6379
db = 0

[embedding]
model_name = sentence-transformers/all-MiniLM-L6-v2
dimension = 384

[llm]
provider = openai
model = gpt-3.5-turbo
api_key = your_api_key_here
max_tokens = 1000
temperature = 0.7

[rag]
max_history_length = 10
default_top_k = 5
default_similarity_threshold = 0.7

[logging]
level = INFO
format = %%(asctime)s - %%(name)s - %%(levelname)s - %%(message)s
file = logs/app.log
max_bytes = 10485760
backup_count = 5
```

### Docker 服务配置

如果您使用的是 ARM64 设备（如 M1/M2/M3 Mac），`docker-compose.yml` 已经配置了正确的平台设置。

## 🔧 高级功能

### 1. 自定义嵌入模型

在 `rag_qa/core/vector_store.py` 中替换嵌入生成方法：

```python
def _generate_query_embedding(self, query: str) -> List[float]:
    from sentence_transformers import SentenceTransformer
    
    model_name = config.get('embedding', 'model_name', 
                           fallback='sentence-transformers/all-MiniLM-L6-v2')
    model = SentenceTransformer(model_name)
    embedding = model.encode(query).tolist()
    
    return embedding
```

### 2. 集成大语言模型

在 `rag_qa/core/rag_system.py` 中替换答案生成方法：

```python
def _generate_answer(self, question: str, context: str, use_history: bool = True) -> str:
    import openai
    
    # 配置 OpenAI
    openai.api_key = config.get('llm', 'api_key')
    
    # 构建提示
    if use_history and self.chat_history:
        prompt_template = MULTI_TURN_TEMPLATE
        chat_history_str = self._format_chat_history()
        prompt = prompt_template.format(
            chat_history=chat_history_str,
            context=context,
            question=question
        )
    else:
        prompt_template = RAG_PROMPT_TEMPLATE
        prompt = prompt_template.format(context=context, question=question)
    
    # 调用 LLM
    response = openai.ChatCompletion.create(
        model=config.get('llm', 'model', fallback='gpt-3.5-turbo'),
        messages=[{"role": "user", "content": prompt}],
        max_tokens=config.getint('llm', 'max_tokens', fallback=1000),
        temperature=config.getfloat('llm', 'temperature', fallback=0.7)
    )
    
    return response.choices[0].message.content
```

### 3. 自定义查询分类规则

在 `rag_qa/core/query_classifier.py` 中修改分类规则：

```python
self.classification_rules = {
    'factual': [
        r'什么是', r'谁是', r'哪里', r'何时', r'多少',
        r'定义', r'含义', r'概念', r'介绍'
    ],
    'conceptual': [
        r'为什么', r'如何理解', r'原理', r'机制',
        r'解释', r'说明', r'阐述', r'意义'
    ],
    'procedural': [
        r'如何', r'怎么', r'步骤', r'方法',
        r'操作', r'实现', r'执行', r'过程'
    ],
    'comparative': [
        r'比较', r'对比', r'区别', r'差异',
        r'优缺点', r'异同', r'相似', r'不同'
    ]
}
```

## 🐛 故障排除

### 常见问题

#### 1. Milvus 连接失败

**错误**: `ConnectionError: Failed to connect to Milvus`

**解决方案**:
```bash
# 检查 Docker 服务状态
docker-compose ps

# 重启服务
docker-compose restart

# 检查端口是否被占用
lsof -i :19530
```

#### 2. Redis 连接失败

**错误**: `ConnectionError: Error connecting to Redis`

**解决方案**:
```bash
# 检查 Redis 服务
docker-compose logs redis

# 重启 Redis
docker-compose restart redis

# 测试连接
redis-cli ping
```

#### 3. 内存不足

**错误**: `MemoryError` 或容器频繁重启

**解决方案**:
```bash
# 增加 Docker 内存限制
# 在 docker-compose.yml 中添加:
services:
  standalone:
    mem_limit: 2g
    
# 或减少向量维度和 top_k 参数
```

#### 4. 平台兼容性问题 (ARM64)

**错误**: `platform mismatch` 或镜像拉取失败

**解决方案**:
```bash
# 确保 docker-compose.yml 中设置了正确的平台
platform: linux/arm64

# 或使用 Rosetta 2 模拟
docker run --platform linux/amd64 <image>
```

#### 5. Python 导入错误

**错误**: `ModuleNotFoundError` 或 `ImportError`

**解决方案**:
```bash
# 确保在项目根目录运行
cd /path/to/EduRAG

# 检查 Python 路径
python -c "import sys; print(sys.path)"

# 重新安装依赖
pip install -r requirements.txt --force-reinstall
```

### 日志查看

```bash
# 应用日志
tail -f logs/app.log

# Docker 服务日志
docker-compose logs -f

# 特定服务日志
docker-compose logs -f milvus-standalone
docker-compose logs -f redis
```

### 性能优化

1. **向量检索优化**:
   ```python
   # 调整索引参数
   index_params = {
       "metric_type": "COSINE",
       "index_type": "IVF_FLAT",
       "params": {"nlist": 256}  # 增加 nlist
   }
   ```

2. **缓存优化**:
   ```python
   # 增加 Redis 缓存时间
   self.redis_client.setex(cache_key, 7200, json.dumps(cache_data))  # 2小时
   ```

3. **批量处理**:
   ```python
   # 批量插入文档
   batch_size = 100
   for i in range(0, len(documents), batch_size):
       batch = documents[i:i+batch_size]
       self.vector_store.insert_documents(batch)
   ```

## 🧪 测试

```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_query_classifier.py

# 生成覆盖率报告
pytest --cov=rag_qa --cov-report=html
```

## 📈 监控和维护

### 系统监控

```bash
# 查看系统状态
python rag_qa/main.py --mode info

# 监控 Docker 资源使用
docker stats

# 查看 Milvus 集合信息
python -c "
from rag_qa.core.vector_store import VectorStore
vs = VectorStore()
print(vs.get_collection_stats())
"
```

### 数据备份

```bash
# 备份 Milvus 数据
docker-compose exec milvus-standalone milvus-backup create --collection-name edu_rag_collection

# 备份配置文件
cp config.ini config.ini.backup
```

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支: `git checkout -b feature/new-feature`
3. 提交更改: `git commit -am 'Add new feature'`
4. 推送到分支: `git push origin feature/new-feature`
5. 创建 Pull Request

### 代码规范

- 使用 Python 3.8+ 语法
- 遵循 PEP 8 代码风格
- 添加适当的类型注解
- 编写单元测试
- 更新文档

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 📞 支持与联系

- **Issues**: [GitHub Issues](https://github.com/your-repo/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-repo/discussions)
- **Email**: your-email@example.com

## 🙏 致谢

感谢以下开源项目：

- [Milvus](https://milvus.io/) - 向量数据库
- [Redis](https://redis.io/) - 内存数据库
- [Sentence Transformers](https://www.sbert.net/) - 文本嵌入
- [LangChain](https://langchain.com/) - LLM 应用框架
- [FastAPI](https://fastapi.tiangolo.com/) - Web 框架

---

**注意**: 当前版本在某些功能中使用了模拟实现（如嵌入向量生成和答案生成）。在生产环境中，请按照上述指南集成实际的嵌入模型和大语言模型。