# AIEC-RAG 智能检索增强生成系统

## 项目简介

AIEC-RAG 是一个基于 LangChain、LangGraph 和 HippoRAG 架构的企业级智能检索增强生成（RAG）系统。该系统专门针对企业知识库设计，提供高质量的智能问答服务，支持复杂的多跳推理和迭代检索。

### 核心特性

- 🚀 **迭代式检索**：基于 LangGraph 的智能迭代检索，自动判断信息充分性
- 🔍 **多跳推理**：支持复杂的知识图谱推理，处理多步骤问题
- 📊 **向量+图谱融合**：结合向量检索和知识图谱的混合检索架构
- 🎯 **智能查询分解**：自动将复杂查询分解为多个子查询并行处理
- 📈 **可观测性**：集成 LangSmith 提供完整的追踪和监控
- 🔧 **灵活配置**：支持提示词模板和参数的动态配置
- 🌐 **生产就绪**：提供 Docker 部署和负载均衡支持

## 系统架构

```
用户查询
    ↓
查询复杂度判断
    ↓
┌─────────────┬──────────────┐
│  简单查询    │   复杂查询     │
│     ↓       │      ↓        │
│  向量检索    │   查询分解     │
│     ↓       │      ↓        │
│  简单回答    │   并行检索     │
└─────────────┤      ↓        │
              │  充分性检查     │
              │    ↓    ↓      │
              │  充分  不充分   │
              │   ↓     ↓      │
              │         子查询  │
              │          ↓     │
              │      迭代检索   │
              └───────┬────────┘
                      ↓
                   最终答案
```

## 快速开始

### 1. 环境要求

- Python 3.8+
- Elasticsearch 8.x（用于向量存储）
- 至少 8GB RAM
- 推荐 GPU（用于嵌入模型，可选）

### 2. 安装依赖

```bash
# 克隆项目
git clone <repository_url>
cd AIEC-RAG

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

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

### 3. 配置环境

创建 `.env` 文件并配置以下参数：

```env
# API密钥（使用OneAPI或其他兼容接口）
ONEAPI_KEY=your_api_key_here

# 模型配置
ONEAPI_MODEL=qwen2-7b-instruct        # 主模型
ONEAPI_MODEL_EMBED=text-embedding-v3   # 嵌入模型

# Elasticsearch配置
ELASTICSEARCH_HOST=http://localhost:9200
ELASTICSEARCH_USERNAME=elastic
ELASTICSEARCH_PASSWORD=your_password

# LangSmith配置（可选）
LANGCHAIN_TRACING_V2=false
LANGCHAIN_API_KEY=your_langsmith_key
LANGCHAIN_PROJECT=aiec-rag
```

### 4. 配置提示词（可选）

编辑 `rag_config_production.yaml` 自定义提示词模板：

```yaml
prompt_templates:
  query_decomposition:
    enabled: true
    default_sub_queries: 2
    # template: "自定义提示词..."  # 可选
```

### 5. 启动服务

```bash
# 生产环境启动
python rag_api_server_production.py

# 服务将在 http://localhost:8100 启动
```

## API 使用

### 基础检索

```bash
curl -X POST http://localhost:8100/retrieve \
  -H "Content-Type: application/json" \
  -d '{
    "query": "什么是混沌工程？",
    "mode": "0",
    "save_output": true
  }'
```

### 响应格式

```json
{
  "success": true,
  "query": "什么是混沌工程？",
  "answer": "混沌工程是一种...",
  "supporting_facts": [
    ["段落1标题", "段落1内容"],
    ["段落2标题", "段落2内容"]
  ],
  "supporting_events": [
    ["事件1", "event_id_1"],
    ["事件2", "event_id_2"]
  ],
  "metadata": {
    "iterations": 2,
    "total_passages": 15,
    "confidence": 0.85
  }
}
```

## Docker 部署

### 构建镜像

```bash
docker build -t aiec-rag:latest .
```

### 运行容器

```bash
docker run -d \
  --name aiec-rag \
  -p 8100:8100 \
  -v $(pwd)/.env:/app/.env \
  -v $(pwd)/rag_config_production.yaml:/app/rag_config_production.yaml \
  aiec-rag:latest
```

### Docker Compose（推荐）

```yaml
version: '3.8'
services:
  aiec-rag:
    build: .
    ports:
      - "8100:8100"
    env_file:
      - .env
    volumes:
      - ./rag_config_production.yaml:/app/rag_config_production.yaml
      - ./api_outputs:/app/api_outputs
    restart: unless-stopped
```

## 配置说明

### 检索参数

| 参数 | 说明 | 默认值 |
|-----|------|-------|
| `max_iterations` | 最大迭代次数 | 2 |
| `top_k_events` | 返回的事件数量 | 10 |
| `top_k_passages` | 返回的段落数量 | 3 |
| `confidence_threshold` | 充分性判断阈值 | 0.7 |

### 提示词配置

系统支持6种核心提示词的自定义：

1. **query_complexity_check** - 查询复杂度判断
2. **query_decomposition** - 查询分解
3. **sufficiency_check** - 充分性检查
4. **sub_query_generation** - 子查询生成
5. **simple_answer** - 简单答案生成
6. **final_answer** - 最终答案生成

详见 `rag_config_production.yaml` 配置文件。

## 性能优化

### 1. 缓存策略

- 使用 Elasticsearch 的查询缓存
- LangChain 的嵌入缓存
- 提示词模板缓存

### 2. 并发处理

- 支持并行子查询检索
- 异步处理长时间运行的查询
- 连接池管理

### 3. 资源限制

```python
# 在配置中设置资源限制
max_parallel_retrievals: 2  # 最大并行检索数
request_timeout: 120        # 请求超时（秒）
max_retries: 3             # 最大重试次数
```

## 监控和日志

### LangSmith 集成

设置环境变量启用 LangSmith 追踪：

```env
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_key
```

### 日志配置

日志文件位于 `api_outputs/` 目录，包含：
- 查询历史
- 性能指标
- 错误日志

## 故障排除

### 常见问题

1. **Elasticsearch 连接失败**
   - 检查 ES 服务是否运行
   - 验证连接参数和认证信息
   - 确认网络连通性

2. **内存不足**
   - 减少 `top_k` 参数值
   - 使用更小的嵌入模型
   - 增加系统内存

3. **响应超时**
   - 调整 `request_timeout` 参数
   - 检查模型响应速度
   - 考虑使用更快的模型

### 调试模式

启用调试模式获取详细日志：

```python
# 在请求中设置
{
  "query": "...",
  "mode": "1"  # 启用调试模式
}
```

## 项目结构

```
AIEC-RAG/
├── atlas_rag/              # HippoRAG核心实现
├── elasticsearch_vectorization/  # ES向量化模块
├── retriver/               # 检索器实现
│   ├── langgraph/         # LangGraph工作流
│   └── langsmith/         # LangSmith集成
├── rag_api_server_production.py  # 生产服务入口
├── rag_config_production.yaml    # 生产配置
├── prompt_loader.py       # 提示词加载器
├── requirements.txt       # 项目依赖
├── Dockerfile            # Docker配置
├── .env.example         # 环境变量示例
└── README.md           # 本文档
```

## 贡献指南

欢迎贡献代码和提出建议！请遵循以下步骤：

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 许可证

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

## 联系方式

- 项目维护者：[团队名称]
- 邮箱：[contact@example.com]
- 问题反馈：[GitHub Issues](https://github.com/xxx/issues)

## 致谢

- [LangChain](https://github.com/langchain-ai/langchain)
- [LangGraph](https://github.com/langchain-ai/langgraph)
- [HippoRAG](https://github.com/xxx/hipporag)
- [Elasticsearch](https://www.elastic.co/)

---

*最后更新：2024年9月*