# HydroAgentRag

**Repository Path**: three2one_xu/hydro-agent-rag

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-20
- **Last Updated**: 2025-12-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HydroAgentRag - 水利工程专家智能体

[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)
[![Python](https://img.shields.io/badge/Python-3.10+-green.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

🚀 **HydroAgentRag** 是一个基于水利工程领域知识的专业智能问答系统，采用先进的RAG（检索增强生成）技术和多Agent架构，为水利工程管理、运行和维护提供智能化的知识检索和决策支持。

## ✨ 核心特性

### 🧠 多Agent协作架构
- **Planner（规划器）**: 智能分解用户查询，制定执行计划
- **Executor（执行器）**: 执行搜索任务，获取相关文档和信息
- **Reflector（反思器）**: 评估回答质量，优化搜索策略
- **Synthesizer（合成器）**: 整合信息，生成最终回答

### 📚 全文档处理流程
- 支持PDF、Word、Excel等多种文档格式
- 5阶段数据处理管道：扫描→提取→分块→丰富化→索引
- 智能文档分类和关键词提取
- 结构化数据存储和检索

### 🔍 高级检索能力
- 语义搜索和关键词检索相结合
- 双索引架构（主RAG索引 + 元数据索引）
- 上下文感知的智能查询分解
- 实时流式响应

### 🌐 现代化Web界面
- FastAPI后端 + 前端界面
- Server-Sent Events流式响应
- 实时进度追踪
- RESTful API接口

## 🏗️ 系统架构

```
HydroAgentRag/
├── agentRag/                    # 智能体核心模块
│   ├── src/
│   │   ├── agent_control/       # Agent控制器
│   │   │   ├── planner.py       # 规划器
│   │   │   ├── executor.py      # 执行器
│   │   │   ├── reflector.py     # 反思器
│   │   │   └── synthesizer.py   # 合成器
│   │   ├── orchestration/       # 工作流编排
│   │   ├── data_layer/          # 数据访问层
│   │   ├── tool_layer/          # 工具层
│   │   ├── config/              # 配置管理
│   │   └── utils/               # 工具函数
│   ├── main.py                  # CLI交互入口
│   └── web_api.py               # Web API服务
├── vectorDataset/               # 数据处理模块
│   ├── src/
│   │   ├── stage1_file_scanner.py        # 文件扫描
│   │   ├── stage2_content_extractor.py   # 内容提取
│   │   ├── stage3_chunker.py             # 智能分块
│   │   ├── stage4_metadata_enricher.py   # 元数据丰富化
│   │   ├── stage5_indexer.py             # 索引构建
│   │   └── main_pipeline.py              # 数据处理管道
│   └── documents/              # 文档存储目录
├── docker-compose.yml           # Docker编排配置
└── README.md                   # 项目文档
```

## 🚀 快速开始

### 环境要求

- Docker & Docker Compose
- Python 3.10+ (如果不使用Docker)
- 足够的存储空间用于文档和索引

### 一键部署

```bash
# 克隆项目
git clone <repository-url>
cd HydroAgentRag

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps
```

服务启动后，访问：
- **Web界面**: http://localhost:8005
- **API文档**: http://localhost:8005/docs

### 手动部署

#### 1. 配置环境变量

```bash
# 复制并编辑配置文件
cp .env.example .env

# 编辑配置
vim .env
```

主要配置项：
```env
# LLM配置
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_API_KEY=your_api_key_here

# Ollama配置（本地模型）
OLLAMA_HOST=http://host.docker.internal:11434
OLLAMA_EMBEDDING_MODEL=qwen3-embedding:latest
OLLAMA_LLM_MODEL=gemma3:27b

# Weaviate配置
WEAVIATE_URL=weaviate
WEAVIATE_PORT=8080
```

#### 2. 安装依赖

```bash
# Agent模块
cd agentRag
pip install -r requirements.txt

# 数据处理模块
cd ../vectorDataset
pip install -r requirements.txt
```

#### 3. 启动Weaviate向量数据库

```bash
docker run -d \
  --name weaviate \
  -p 8080:8080 \
  -e QUERY_DEFAULTS_LIMIT=25 \
  -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED='true' \
  -e PERSISTENCE_DATA_PATH='/var/lib/weaviate' \
  -e ENABLE_MODULES='text2vec-ollama,generative-ollama' \
  -v $(pwd)/data:/var/lib/weaviate \
  semitechnologies/weaviate:1.33.0
```

#### 4. 处理文档数据

```bash
cd vectorDataset
python main.py --config configs/data_process.yaml --stage 1  # 文件扫描
python main.py --config configs/data_process.yaml --stage 2  # 内容提取
python main.py --config configs/data_process.yaml --stage 3  # 智能分块
python main.py --config configs/data_process.yaml --stage 4  # 元数据丰富化
python main.py --config configs/data_process.yaml --stage 5  # 索引构建
```

#### 5. 启动智能体服务

```bash
cd ../agentRag
python web_api.py
```

## 📖 使用指南

### Web界面使用

1. 打开浏览器访问 http://localhost:8005
2. 在聊天界面输入您的问题
3. 系统将实时显示处理进度
4. 获得基于水利工程知识库的专业回答

### API接口调用

```python
import requests

# 流式API调用
response = requests.post(
    "http://localhost:8005/api/v1/chat/stream",
    json={"query": "引江济淮工程的船闸运行标准是什么？"},
    stream=True
)

for line in response.iter_lines():
    if line:
        print(line.decode('utf-8'))
```

### CLI交互模式

```bash
cd agentRag
python main.py
```

### 典型查询示例

- 🏗️ **工程技术**: "引江济淮蜀山泵站的技术参数有哪些？"
- 🛠️ **运行维护**: "船闸日常维护需要注意哪些事项？"
- 🚨 **安全管理**: "水利工程的安全巡检标准是什么？"
- 📊 **管理制度**: "汛期调度方案的主要内容有哪些？"
- 🔧 **设备操作**: "柴油发电机组的操作流程是什么？"

## 🔧 配置说明

### 数据处理配置 (vectorDataset/configs/data_process.yaml)

```yaml
# 文档扫描配置
file_scanner:
  root_directory: "documents/引江济淮合肥建管处知识库建设资料-20250711"
  supported_extensions: [".pdf", ".docx", ".xlsx"]

# 分块策略
chunker:
  procedure_strategy:
    chunk_size: 2000
    chunk_overlap: 200
  knowledge_strategy:
    chunk_size: 1000
    chunk_overlap: 150

# 向量数据库配置
weaviate:
  url: "WEAVIATE_URL"
  module: "text2vec-ollama"
  ollama:
    model: "OLLAMA_EMBEDDING_MODEL"
```

### Agent配置 (agentRag/src/config/settings.py)

```python
class Settings:
    # API配置
    api_base_url: str = "https://api.deepseek.com/v1"
    api_key: str = "your_api_key"

    # 向量数据库
    main_index_name: str = "HEA_Main_RAG"
    metadata_index_name: str = "HEA_Metadata"

    # 模型参数
    temperature: float = 0.1
    max_tokens: int = 4000
```

## 🐳 Docker部署详解

### 服务架构

- **agent**: 智能体服务 (端口: 8005)
- **vectordataset**: 数据处理服务 (端口: 8081)
- **weaviate**: 向量数据库 (端口: 8080)

### 数据持久化

```yaml
volumes:
  - ./vectorDataset/data:/var/lib/weaviate  # Weaviate数据
  - ./agentRag:/workspace                  # Agent代码
  - ./vectorDataset:/workspace             # 数据处理代码
```

### 网络配置

```yaml
networks:
  my-app-net:
    driver: bridge
```

## 📊 性能优化

### 硬件建议

- **CPU**: 8核心以上
- **内存**: 16GB以上
- **存储**: SSD，100GB以上可用空间
- **网络**: 稳定的互联网连接（用于API调用）

### 优化策略

1. **文档处理优化**
   - 批量处理文档
   - 合理设置分块大小
   - 并行化处理流程

2. **搜索优化**
   - 智能查询分解
   - 缓存常用查询结果
   - 优化检索策略

3. **模型优化**
   - 选择合适的embedding模型
   - 调整LLM参数
   - 使用流式响应提升用户体验

## 🛠️ 开发指南

### 添加新的Agent

```python
from src.agent_control.base import BaseAgent

class CustomAgent(BaseAgent):
    def __init__(self, llm=None):
        super().__init__(llm, agent_name="CustomAgent")

    async def process(self, input_data, **kwargs):
        # 实现自定义逻辑
        return result
```

### 扩展搜索工具

```python
from src.tool_layer.search_tools import BaseSearchTool

class CustomSearchTool(BaseSearchTool):
    async def search(self, query: str):
        # 实现自定义搜索逻辑
        return results
```

### 添加新的文档类型支持

```python
# 在 stage2_content_extractor.py 中添加
def extract_custom_format(self, file_path: str):
    # 实现自定义格式提取
    return extracted_content
```

## 🐛 故障排除

### 常见问题

1. **服务启动失败**
   ```bash
   # 检查端口占用
   netstat -tulpn | grep :8005

   # 检查Docker服务状态
   docker-compose ps
   docker-compose logs agent
   ```

2. **文档处理失败**
   ```bash
   # 检查文档格式和路径
   ls -la documents/

   # 查看处理日志
   tail -f vectorDataset/output_files/data_processing.log
   ```

3. **搜索无结果**
   ```bash
   # 检查索引状态
   curl http://localhost:8080/v1/objects

   # 重建索引
   python vectorDataset/main.py --stage 5
   ```

4. **API调用失败**
   ```bash
   # 检查API密钥和URL
   curl -H "Authorization: Bearer $API_KEY" \
        https://api.deepseek.com/v1/models
   ```

### 日志查看

```bash
# 实时查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f agent
docker-compose logs -f vectordataset
docker-compose logs -f weaviate
```

## 🤝 贡献指南

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

### 代码规范

- 使用 Python 3.10+ 语法特性
- 遵循 PEP 8 编码规范
- 添加完整的文档字符串
- 编写单元测试
- 使用类型注解

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [LangChain](https://python.langchain.com/) - LLM应用开发框架
- [Weaviate](https://weaviate.io/) - 向量数据库
- [FastAPI](https://fastapi.tiangolo.com/) - 现代Web框架
- [Ollama](https://ollama.ai/) - 本地大语言模型
- [DeepSeek](https://www.deepseek.com/) - 大语言模型API服务

## 📞 联系我们

- 项目主页: [GitHub Repository]
- 问题反馈: [GitHub Issues]
- 邮箱联系: [your-email@example.com]

---

🌟 **如果这个项目对您有帮助，请给我们一个Star！** 🌟