commit 6339cdebb97f2f79bed662caa7ab88233ebf34b6 Author: 闫旭隆 <15945644+yan-xulong@user.noreply.gitee.com> Date: Wed Sep 24 09:28:08 2025 +0800 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..675d4fc --- /dev/null +++ b/README.md @@ -0,0 +1,327 @@ +# 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 +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月* \ No newline at end of file