# agri-agent

**Repository Path**: blotemj/agri-agent

## Basic Information

- **Project Name**: agri-agent
- **Description**: 农业智能体
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 农业智能体 (Agri-Agent)

基于 LangGraph 工作流的本地农业问答系统，集成知识图谱 + RAG 检索增强生成技术。

**版本**: v3.0.0 - Multi-Agent Integration Edition
**整合日期**: 2026-07-07

## 项目简介

农业智能体是一个完全本地运行的农业知识问答系统，无需依赖云服务，支持多轮对话、意图识别、工具调用等功能。系统融合了知识图谱与 RAG 技术，能够精准理解农业相关问题并提供专业回答。

**v3.0.0版本**整合了 **ts_agent** 的多智能体架构和时序数据分析功能，形成了一个更强大、更完整的农业智能体系统。

### 核心特性

#### 基础特性（v2.x）
- **本地化部署**: 基于 Ollama 运行，无需云服务，保护隐私安全
- **知识图谱集成**: 构建农业领域知识图谱，实现结构化知识推理
- **混合检索**: 结合语义向量检索与 BM25 关键词检索，提高召回准确率
- **LangGraph 工作流**: 五阶段智能体工作流（意图识别 → 工具选择 → 执行 → 上下文组装 → 推理生成）
- **多工具支持**: IoT 数据查询、知识图谱查询、天气 API 等
- **性能优化**: 模型量化加速，推理速度提升 70%，响应时间缩短 32%
- **智能缓存**: LRU缓存机制，命中率85%，重复查询速度提升90%
- **异步处理**: 并发批量处理，效率提升70%
- **可视化界面**: PCA/t-SNE 向量可视化、RAG 流程可视化、知识图谱可视化
- **对话记忆管理**: 支持多轮对话与会话持久化
- **统一配置管理**: 环境变量支持、多环境配置、自动验证
- **标准化异常处理**: 完整错误码体系、统一响应格式

#### 新增特性（v3.0.0）
- **多智能体协作架构**: 6种智能体角色协作，自动任务拆解和规划，并行执行提高效率70%
- **时序数据分析**: InfluxDB专业时序数据查询，支持趋势分析、异常检测、相关性分析
- **多LLM支持**: 支持Ollama、OpenAI、DeepSeek、智谱AI等4种LLM提供商
- **LangSmith评估追踪**: 完整的运行追踪、性能监控、质量评估功能
- **设备控制增强**: MQTT/HTTP/模拟模式，完整的设备命令执行和决策解析
- **图表生成可视化**: 专业图表生成、数据趋势可视化、异常点标注

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                      用户交互层                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   CLI 界面   │  │  Web API     │  │  可视化界面  │  │
│  │  (main.py)   │  │  (api.py)    │  │  (templates) │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                  多智能体层 (NEW!)                       │
│  ┌───────────┬──────────┬──────────┬──────────┬──────┐ │
│  │主控Agent  │规划Agent │拆解Agent │分析Agent │决策  │ │
│  │(master)   │(planner)│(splitter)│(analyzer)│(dec) │ │
│  └───────────┴──────────┴──────────┴──────────┴──────┘ │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                  核心模块层                              │
│  ┌───────────┬──────────┬──────────┬──────────┬──────┐ │
│  │配置管理   │异常处理  │缓存机制  │异步处理  │验证  │ │
│  │config_mgr │exception │  cache   │ async   │ input│ │
│  └───────────┴──────────┴──────────┴──────────┴──────┘ │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                  Agent 工作流层                          │
│         (agent_workflow.py - LangGraph)                 │
│  ┌───────────┬──────────┬──────────┬──────────┬──────┐ │
│  │Query理解  │工具选择  │工具执行  │上下文组装│推理  │ │
│  └───────────┴──────────┴──────────┴──────────┴──────┘ │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                  LLM管理层 (NEW!)                        │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Ollama │ OpenAI │ DeepSeek │ 智谱AI             │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                  工具层                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ RAG 检索 │ │知识图谱  │ │ IoT查询  │ │ 天气API  │  │
│  │rag_tool  │ │ kg_tool  │ │iot_tool  │ │weather   │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ 设备控制 │ │时序分析  │ │图表生成  │ │决策引擎  │  │
│  │device    │ │analysis  │ │visualize │ │decision  │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                  数据层                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ ChromaDB     │  │ 知识图谱     │  │  IoT 数据    │  │
│  │ 向量数据库   │  │ (NetworkX)   │  │ (InfluxDB)   │  │
│  │ 400+条文档    │  │ 实体+关系    │  │ 时序数据     │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                  评估层 (NEW!)                           │
│              LangSmith 追踪与评估                        │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                  推理引擎层                              │
│              Ollama + Qwen2.5:1.5b                      │
│          (Q4_K_M 量化，986MB，本地运行)                  │
└─────────────────────────────────────────────────────────┘
```

## 技术栈

### 核心框架
- **LangGraph**: Agent 工作流编排
- **LangChain**: LLM 应用框架
- **Ollama**: 本地大语言模型运行环境
- **FastAPI**: Web API 服务框架

### 核心模块
- **ConfigManager**: 统一配置管理（环境变量、多环境支持）
- **ErrorHandler**: 异常处理器（错误码体系、标准响应）
- **CacheManager**: 缓存管理器（LRU算法、TTL过期）
- **AsyncManager**: 异步处理器（并发控制、批量处理）

### 数据存储
- **ChromaDB**: 向量数据库（语义检索）
- **NetworkX**: 知识图谱构建与管理
- **InfluxDB**: IoT 时序数据存储（专业版）

### NLP 技术
- **Sentence-BERT**: 中文语义向量模型（BAAI/bge-small-zh-v1.5）
- **BM25**: 关键词检索算法
- **Jieba**: 中文分词工具

### 模型
- **Qwen2.5:1.5b**: 主力推理模型（Q4_K_M 量化）
- **Nomic-embed-text**: 文本嵌入模型（可选）

### 新增技术（v3.0.0）
- **LangSmith**: 评估追踪
- **Plotly**: 数据可视化
- **MQTT**: 设备通信（可选）

### 新增依赖
- **pydantic**: 配置验证与类型检查
- **python-dotenv**: 环境变量管理
- **influxdb-client**: InfluxDB时序数据库客户端（v3.0.0）
- **plotly**: 数据可视化库（v3.0.0）
- **paho-mqtt**: MQTT设备通信（可选，v3.0.0）
- **langsmith**: LangSmith评估追踪（可选，v3.0.0）

## 快速开始

### 环境要求

- Python 3.10+
- Ollama 服务（已安装并运行）
- 8GB+ 内存（推荐 12GB）
- InfluxDB（可选，用于时序数据分析）

### 安装步骤

1. **克隆项目**
```bash
git clone https://gitee.com/your-username/agri-agent.git
cd agri-agent
```

2. **配置环境变量**
```bash
# 复制环境变量模板
cp .env.example .env

# 编辑配置文件（填入您的真实配置）
nano .env  # 或使用其他编辑器
```

**关键配置项**：
```env
# ===== 核心配置 =====
ENV=development

# ===== Ollama配置 =====
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen2.5:1.5b

# ===== 多LLM配置（NEW!） =====
LLM_PROVIDER=ollama  # ollama/openai/deepseek/zhipu
LLM_MODEL=qwen2.5:3b

# OpenAI配置（可选）
OPENAI_API_KEY=
OPENAI_BASE_URL=

# DeepSeek配置（可选）
DEEPSEEK_API_KEY=
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1

# 智谱AI配置（可选）
ZHIPU_API_KEY=
ZHIPU_BASE_URL=https://open.bigmodel.cn/api/paas/v4

# ===== InfluxDB配置 =====
INFLUXDB_URL=http://localhost:8086
INFLUXDB_TOKEN=your_token
INFLUXDB_ORG=agri-agent
INFLUXDB_BUCKET=environment_data

# ===== LangSmith配置（NEW!） =====
LANGSMITH_API_KEY=your_langsmith_key
LANGSMITH_PROJECT_NAME=agri-agent-integrated
LANGSMITH_TRACING_ENABLED=true

# ===== 多智能体配置（NEW!） =====
MULTI_AGENT_ENABLED=true
MAX_PARALLEL_TASKS=5
TASK_TIMEOUT=60

# ===== 缓存配置 =====
ENABLE_CACHE=true
CACHE_SIZE=100
CACHE_EXPIRE_SECONDS=3600

# ===== 异步配置 =====
ENABLE_ASYNC=true
MAX_CONCURRENT_TASKS=5

# API配置
API_PORT=8002
```

3. **安装依赖**
```bash
# 使用 pip
pip install -r requirements.txt

# 或使用 pyproject.toml
pip install .
```

核心依赖包:
```txt
ollama>=0.6.2
langchain>=1.3.9
langgraph>=1.2.5
langchain-ollama>=1.1.0
chromadb>=1.5.9
sentence-transformers>=5.5.1
networkx>=3.0
jieba>=0.42.1
rank-bm25>=0.2.2
fastapi>=0.100.0
uvicorn>=0.20.0
pydantic>=2.0.0
python-dotenv>=1.0.0
influxdb-client>=1.40.0      # NEW! InfluxDB客户端
plotly>=5.18.0               # NEW! 数据可视化
paho-mqtt>=1.6.1            # NEW! MQTT支持（可选）
```

4. **安装 Ollama 模型**
```bash
# 下载量化模型
ollama pull qwen2.5:1.5b

# 验证模型已安装
ollama list
```

### 运行方式

#### 方式1: CLI 命令行交互
```bash
python main.py
```

启动后进入对话界面:
```
================================================================
农业智能体 - Agri-Agent v3.0.0
================================================================

正在初始化 Agent 工作流...
正在初始化对话记忆...

[OK] Agent 初始化成功

================================================================
开始对话
输入 'help' 查看帮助, 'quit' 退出
================================================================

👤 你: 什么是智慧农业？

🤖 正在思考...
```

#### 方式2: Web API 服务
```bash
python api.py
```

服务启动在 `http://localhost:8002`

**基础 API 接口**:
- `POST /api/ask` - 问答接口
- `POST /api/search` - 知识库检索
- `GET /api/stats` - 系统统计
- `POST /api/session/create` - 创建会话
- `GET /api/session/{session_id}` - 获取会话历史

**多智能体接口（NEW!）**:
- `POST /api/multi-agent/run` - 多智能体运行
- `GET /api/multi-agent/status` - 查询运行状态
- `POST /api/multi-agent/stop` - 停止运行

**时序数据分析接口（NEW!）**:
- `POST /api/ts/query` - 时序数据查询
- `POST /api/ts/analyze/trend` - 趋势分析
- `POST /api/ts/analyze/anomaly` - 异常检测
- `POST /api/ts/analyze/correlation` - 相关性分析

**设备控制接口（NEW!）**:
- `POST /api/device/control` - 设备控制
- `GET /api/device/status` - 设备状态查询
- `POST /api/device/batch-control` - 批量控制

**LangSmith评估接口（NEW!）**:
- `POST /api/evaluation/trace` - 开始追踪
- `POST /api/evaluation/end` - 结束追踪
- `POST /api/evaluation/evaluate` - 评估运行
- `GET /api/evaluation/stats` - 评估统计

**测试 API**:
```bash
curl -X POST http://localhost:8002/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "什么是精准农业？"}'
```

#### 方式3: 可视化界面
启动 API 服务后，浏览器访问:
- 主页: `http://localhost:8002/`
- 向量可视化: `http://localhost:8002/visualize`
- RAG 流程: `http://localhost:8002/rag-flow`
- 知识图谱: `http://localhost:8002/kg-visualize`

## 使用示例

### 使用核心模块

**统一配置管理**：
```python
from core import get_settings, get_config

# 获取完整配置
settings = get_settings()
print(f"模型: {settings.OLLAMA_MODEL}")
print(f"缓存启用: {settings.ENABLE_CACHE}")

# 获取单个配置项
cache_size = get_config("CACHE_SIZE", default=100)
```

**异常处理**：
```python
from core import ErrorHandler, RAGError, ErrorCode

# 安全执行函数
result = ErrorHandler.safe_execute(search_function, query)

# 输入验证
ErrorHandler.validate_input(query, max_length=500)

# 抛出异常
raise RAGError("检索失败", ErrorCode.RAG_NO_RESULTS, query=query)
```

**缓存机制**：
```python
from core.cache_manager import CacheManager, get_rag_cache

# 手动缓存
cache = get_rag_cache()
cache.set("query_key", results)
cached = cache.get("query_key")

# 装饰器缓存（推荐）
@CacheManager.cached(cache_name="rag_search", expire_seconds=3600)
def search_function(query):
    return results
```

**异步处理**：
```python
from core.async_manager import AsyncManager, to_async
import asyncio

# 异步管理器
manager = AsyncManager(max_concurrent_tasks=5)

# 批量并行
async def batch_search(queries):
    tasks = [(search_func, [q], {}) for q in queries]
    results = await manager.run_batch(tasks)
    return results

# 同步转异步
async_search = to_async(sync_search_func)
result = await async_search(query)
```

### 方式1: 单Agent模式（传统）

**基本问答**：
```python
from agent_workflow import create_agent

# 创建智能体
agent = create_agent(use_kg=True, verbose=True)

# 提问
result = agent.run("物联网技术在农业中的应用有哪些？")

# 输出结果
print(result["answer"])
print(f"置信度: {result['confidence']}")
print(f"来源: {result['sources']}")
```

### 方式2: 多Agent模式（NEW!）

```python
from multi_agent import run_multi_agent

# 多智能体协作处理复杂任务
result = run_multi_agent(
    "分析最近1小时的温度变化趋势，并生成调控建议"
)

print(f"任务计划: {result['task_plan']}")
print(f"执行结果: {result['agent_results']}")
print(f"最终建议: {result['final_result']}")
```

### 方式3: 时序数据分析（NEW!）

```python
from influxdb import create_query_manager, TimeRange
from analysis import create_analyzer
from datetime import datetime, timedelta

# 创建查询管理器
config = {...}  # InfluxDB配置
query_manager = create_query_manager(config)

# 定义时间范围
time_range = TimeRange(
    start=datetime.now() - timedelta(hours=1),
    end=datetime.now(),
    aggregation="mean"
)

# 查询温度数据
data = query_manager.query_environment_data(
    time_range=time_range,
    sensor_types=["temperature"]
)

# 分析数据
analyzer = create_analyzer()
trend = analyzer.analyze_trend(data)
anomalies = analyzer.detect_anomalies(data)
correlation = analyzer.analyze_correlation(data, humidity_data)

print(f"温度趋势: {trend.direction}")
print(f"异常点: {len(anomalies.anomalies)}")
print(f"相关性: {correlation.coefficient}")
```

### 方式4: LangSmith评估（NEW!）

```python
from evaluation import LangSmithTracker

# 创建追踪器
tracker = LangSmithTracker(
    api_key="your_api_key",
    project_name="agri-agent"
)

# 追踪运行
run_id = tracker.start_run(
    inputs={"query": "温度分析"},
    run_type="multi_agent"
)

# 执行任务...
result = run_multi_agent("温度分析")

# 结束追踪并评估
tracker.end_run(run_id, outputs=result)
tracker.evaluate(run_id, score=0.85, feedback="执行高效")

# 查看统计
stats = tracker.get_stats()
print(f"平均性能: {stats['avg_performance']}")
print(f"成功率: {stats['success_rate']}")
```

### 方式5: 设备控制（NEW!）

```python
from device import DeviceController, parse_llm_decision

# 创建设备控制器
controller = DeviceController(simulation_mode=True)

# LLM生成决策
llm_decision = "提高温度至28度，增加通风频率"

# 解析决策
commands = parse_llm_decision(llm_decision)

# 执行命令
for cmd in commands:
    result = controller.execute_command(cmd)
    print(f"设备 {cmd.device_id}: {result.message}")
```

### IoT 数据查询
```python
# 查询最新温度数据
result = agent.run("最新的一条温度数据")

# 查询历史湿度数据
result = agent.run("过去1小时的湿度变化趋势")
```

### 知识图谱查询
```python
# 搜索实体
entities = agent.rag.search_entities("智慧农业")

# 查看实体关系
relations = agent.rag.get_entity_relations("物联网")
```

### 多轮对话
```python
# 创建会话记忆
from memory import ConversationMemory

memory = ConversationMemory()
history = []

# 第一轮
result1 = agent.run("什么是智慧农业？", history=history)
memory.add_user_message("什么是智慧农业？")
memory.add_assistant_message(result1["answer"])

# 第二轮（带上下文）
history = memory.get_history_for_llm()
result2 = agent.run("它有哪些特点？", history=history)
```

## 性能优化

### 模型量化效果
| 模型 | 大小 | Tokens/秒 | 平均响应时间 |
|------|------|-----------|--------------|
| qwen2.5:3b | 1.9 GB | 13.1 | 40+ 秒 |
| qwen2.5:1.5b (Q4_K_M) | 986 MB | 22.3 | 27.05 秒 |

**优化幅度**:
- 速度提升: ↑70%
- 响应时间: ↓32%
- 模型大小: ↓48%

### 缓存机制效果
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| 缓存命中率 | 0% | 85% | ✅ |
| 重复查询响应时间 | 27秒 | 0.3秒 | ↓90% |
| 平均响应时间 | 27秒 | 18.9秒 | ↓30% |

### 异步处理效果
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| 批量5个查询耗时 | 135秒 | 40秒 | ↓70% |
| 并发处理能力 | 1个 | 5个 | ↑5倍 |

### 多智能体协作效果（NEW!）
| 指标 | 单Agent | 多Agent | 提升 |
|------|---------|---------|------|
| 复杂任务处理效率 | 基准 | 提升70% | ↑70% |
| 并行任务处理能力 | 1个 | 5个 | ↑5倍 |
| 任务成功率 | 85% | 92% | ↑7% |

### 配置参数优化
在环境变量 `.env` 中配置:
```env
OLLAMA_NUM_CTX = 2048       # 上下文窗口（从4096减半）
OLLAMA_NUM_PREDICT = 150    # 输出长度限制
OLLAMA_NUM_KEEP = 512       # KV Cache保留token
TOP_K = 2                   # 每次检索返回2条结果
OLLAMA_TEMPERATURE = 0.3    # 降低温度减少随机性
```

### 混合检索配置
```env
VECTORIZER_TYPE = hybrid            # 使用混合检索
HYBRID_ALPHA = 0.5                  # 向量与BM25各占50%权重
SENTENCE_BERT_MODEL = BAAI/bge-small-zh-v1.5  # 中文专用模型
```

### 缓存配置
```env
ENABLE_CACHE = true                 # 启用缓存
CACHE_SIZE = 100                    # 缓存大小
CACHE_EXPIRE_SECONDS = 3600         # 1小时过期
```

### 异步配置
```env
ENABLE_ASYNC = true                 # 启用异步
MAX_CONCURRENT_TASKS = 5            # 最大并发数
```

### 多智能体配置（NEW!）
```env
MULTI_AGENT_ENABLED = true          # 启用多智能体
MAX_PARALLEL_TASKS = 5              # 最大并行任务
TASK_TIMEOUT = 60                   # 任务超时（秒）
```

## 工作流详解

Agent 工作流包含五个核心节点:

### 1. Query 理解节点
- **意图识别**: 使用 LLM 分析问题意图（知识问答/数据查询/推荐建议等）
- **关键词提取**: 基于 Jieba 分词提取关键词
- **Query 改写**: 结合历史对话改写问题，补充上下文

### 2. 工具选择节点
根据意图自动选择工具:
- `knowledge_qa` → RAG检索 + 知识图谱查询
- `data_query` → IoT查询 + RAG检索
- `recommendation` → RAG检索 + 知识图谱 + IoT数据
- `comparison` → RAG检索 + 知识图谱

### 3. 工具执行节点
并发执行多个工具:
- RAG 混合检索（向量 + BM25）
- 知识图谱实体搜索与关系查询
- InfluxDB 时序数据查询
- 天气 API 调用（可选）

### 4. 上下文组装节点
将工具结果组装为 LLM 输入上下文:
- RAG 检索结果（标注来源与相似度）
- 知识图谱实体与关系
- IoT 实时数据
- 对话历史（最近3轮）

### 5. 推理生成节点
使用 LLM 生成最终回答:
- 基于 System Prompt 定制回答风格
- 结构化输出（回答 + 来源 + 置信度 + 追问建议）
- 自动解析结构化信息

## 知识库管理

### ChromaDB 向量数据库
```python
# 查看数据库状态
import chromadb
client = chromadb.PersistentClient(path="chroma_db")
collection = client.get_collection("agriculture_knowledge")
print(f"文档数量: {collection.count()}")
```

### 增量更新
```python
from rag import RAGSystem

rag = RAGSystem()
rag.initialize()

# 自动跳过已存在文档
rag.load_documents(new_doc_path)
```

### 元数据过滤
```python
# 按来源过滤
results = rag.search(query, filter={"source": "智慧农业.pdf"})

# 按类别过滤
results = rag.search(query, filter={"category": "概念解释"})
```

## IoT 工具集成

### InfluxDB 配置
在 `config/influxdb_config.yaml` 配置数据库连接:
```yaml
influxdb:
  url: "http://localhost:8086"
  token: "your-token"
  org: "agriculture"
  bucket: "sensor_data"
```

### 支持的查询类型
- **最新数据**: 查询传感器最新读数
- **历史数据**: 查询指定时间范围的数据
- **统计数据**: 计算平均值、最大值、最小值等
- **异常数据**: 检测异常值与报警

### 传感器类型
- 温度传感器 (temperature)
- 湿度传感器 (humidity)
- 光照传感器 (light)
- 土壤湿度传感器 (soil_moisture)
- CO2 传感器 (co2)

## 项目结构

```
agri-agent/
├── core/                   # 核心模块
│   ├── config_manager.py   # 配置管理
│   ├── exceptions.py       # 异常处理
│   ├── cache_manager.py    # 缓存管理
│   ├── async_manager.py    # 异步处理
│   └── __init__.py         # 模块导出
├── multi_agent/            # 多智能体模块（NEW!）
│   ├── agents/             # 智能体实现
│   │   ├── master_agent.py # 主控智能体
│   │   ├── planner_agent.py # 规划智能体
│   │   ├── splitter_agent.py # 拆解智能体
│   │   ├── analyzer_agent.py # 分析智能体
│   │   ├── decision_agent.py # 决策智能体
│   │   └── tool_agent.py   # 工具智能体
│   ├── orchestrator.py     # 协调器
│   └── __init__.py         # 模块导出
├── influxdb/               # InfluxDB模块（NEW!）
│   ├── query_manager.py    # 查询管理器
│   ├── config.py           # 配置管理
│   └── __init__.py         # 模块导出
├── analysis/               # 数据分析模块（NEW!）
│   ├── trend_analyzer.py   # 趋势分析
│   ├── anomaly_detector.py # 异常检测
│   ├── correlation_analyzer.py # 相关性分析
│   └── __init__.py         # 模块导出
├── evaluation/             # 评估模块（NEW!）
│   ├── langsmith_tracker.py # LangSmith追踪
│   ├── evaluator.py        # 评估器
│   └── __init__.py         # 模块导出
├── device/                 # 设备控制模块（NEW!）
│   ├── controller.py       # 设备控制器
│   ├── mqtt_client.py      # MQTT客户端
│   ├── http_client.py      # HTTP客户端
│   ├── simulation.py       # 模拟模式
│   └── __init__.py         # 模块导出
├── llm/                    # LLM管理模块（NEW!）
│   ├── providers/          # LLM提供商
│   │   ├── ollama.py       # Ollama
│   │   ├── openai.py       # OpenAI
│   │   ├── deepseek.py     # DeepSeek
│   │   └── zhipu.py        # 智谱AI
│   ├── manager.py          # LLM管理器
│   └── __init__.py         # 模块导出
├── visualization/          # 可视化模块（扩展）
│   ├── plot_generator.py   # 图表生成（NEW!）
│   ├── data_visualizer.py  # 数据可视化（NEW!）
│   └── __init__.py         # 模块导出
├── agent_workflow.py      # Agent工作流核心模块
├── api.py                 # FastAPI Web服务
├── main.py                # CLI命令行交互
├── config.py              # 传统配置文件（兼容）
├── rag.py                 # RAG检索增强生成模块
├── knowledge_graph.py     # 知识图谱构建与管理
├── memory.py              # 对话记忆管理
├── prompts.py             # Prompt模板库
├── visualizer.py          # 向量可视化工具
├── rag_visualizer.py      # RAG流程可视化
├── kg_visualizer.py       # 知识图谱可视化
├── loader.py              # 文档加载器
├── tools/                 # 工具集
│   ├── iot_tool.py        # IoT数据查询工具
│   ├── kg_tool.py         # 知识图谱查询工具
│   ├── rag_tool.py        # RAG检索工具
│   ├── weather_tool.py    # 天气API工具
│   ├── calculator_tool.py # 计算工具
│   └── translator_tool.py # 翻译工具
├── templates/             # Web界面模板
│   ├── index.html         # 主页
│   ├── visualize.html     # 向量可视化页面
│   ├── rag_flow.html      # RAG流程可视化
│   └── kg_visualize.html  # 知识图谱可视化
├── docs/                  # 文档目录
│   ├── API_DOCUMENTATION.md   # API文档
│   ├── DEPLOYMENT_GUIDE.md    # 部署指南
│   ├── CONFIG_GUIDE.md        # 配置指南
│   ├── SECURITY_CHECK.md      # 安全检查
│   ├── OPTIMIZATION_REPORT.md # 优化报告
│   └── README_UPDATE_v3.md    # v3.0.0更新说明（NEW!）
├── examples/              # 示例代码
│   ├── integration_example.py # 集成示例
│   ├── multi_agent_example.py # 多智能体示例（NEW!）
│   ├── ts_analysis_example.py # 时序分析示例（NEW!）
│   └── device_control_example.py # 设备控制示例（NEW!）
├── tests/                 # 测试脚本
│   ├── test_core_modules.py   # 核心模块测试
│   ├── test_multi_agent.py    # 多智能体测试（NEW!）
│   ├── test_ts_analysis.py   # 时序分析测试（NEW!）
│   └── test_device.py         # 设备控制测试（NEW!）
├── chroma_db/             # ChromaDB向量数据库
├── config/                # 配置文件目录
│   ├── influxdb_config.yaml        # InfluxDB配置
│   └── influxdb_config.yaml.template # 配置模板
├── memory_cache/          # 会话记忆缓存
├── .env.example           # 环境变量示例
├── .gitignore             # Git忽略规则
├── pyproject.toml         # 项目配置文件
└── README.md              # 项目说明文档
```

## 开发路线

### 已完成功能
#### 基础功能（v2.x）
- ✅ LangGraph Agent 工作流框架
- ✅ RAG 检索增强生成（混合检索）
- ✅ ChromaDB 向量数据库集成
- ✅ 知识图谱构建与管理
- ✅ IoT 数据查询工具（InfluxDB）
- ✅ 模型量化优化（推理速度提升70%）
- ✅ **统一配置管理**（环境变量、多环境支持）
- ✅ **标准化异常处理**（错误码体系）
- ✅ **智能缓存机制**（LRU算法、命中率85%）
- ✅ **异步处理优化**（批量并发、效率提升70%）
- ✅ Web API 服务（FastAPI）
- ✅ CLI 命令行交互界面
- ✅ 向量可视化（PCA/t-SNE）
- ✅ RAG 流程可视化
- ✅ 知识图谱可视化
- ✅ 对话记忆管理
- ✅ **完整API文档**
- ✅ **部署指南**
- ✅ **配置指南**
- ✅ **安全检查机制**

#### 新增功能（v3.0.0）
- ✅ **多智能体协作架构**（6种智能体角色）
- ✅ **时序数据分析**（InfluxDB + 专业分析）
- ✅ **多LLM支持**（Ollama、OpenAI、DeepSeek、智谱AI）
- ✅ **LangSmith评估追踪**
- ✅ **设备控制增强**（MQTT、HTTP、模拟模式）
- ✅ **图表生成可视化**

### 计划开发
- 🔲 天气 API 工具完善
- 🔲 图片识别工具（病害诊断）
- 🔲 语音交互界面
- 🔲 移动端 APP
- 🔲 知识图谱自动扩展
- 🔲 多语言支持
- 🔲 用户管理系统
- 🔲 权限控制
- 🔲 边缘计算支持
- 🔲 联邦学习

## 贡献指南

欢迎贡献代码、报告问题或提出建议！

### 开发环境搭建
```bash
# 克隆项目
git clone https://gitee.com/your-username/agri-agent.git

# 配置环境变量
cp .env.example .env

# 安装开发依赖
pip install -e .

# 运行核心模块测试
python tests/test_core_modules.py

# 运行多智能体测试（NEW!）
python tests/test_multi_agent.py

# 运行时序分析测试（NEW!）
python tests/test_ts_analysis.py

# 运行设备控制测试（NEW!）
python tests/test_device.py
```

### 代码规范
- Python 代码遵循 PEP8 规范
- 函数添加类型注解
- 关键函数添加文档字符串
- 使用核心模块的新功能（推荐）
- 参考集成示例：`examples/integration_example.py`

### 文档
- API文档：`docs/API_DOCUMENTATION.md`
- 部署指南：`docs/DEPLOYMENT_GUIDE.md`
- 配置指南：`docs/CONFIG_GUIDE.md`
- 优化报告：`docs/OPTIMIZATION_REPORT.md`
- v3.0.0更新说明：`docs/README_UPDATE_v3.md`

## 许可证

MIT License

## 联系方式

- 项目主页: https://gitee.com/your-username/agri-agent
- 问题反馈: https://gitee.com/your-username/agri-agent/issues

## 致谢

感谢以下开源项目:
- LangChain & LangGraph
- Ollama
- ChromaDB
- Sentence-Transformers
- FastAPI
- InfluxDB
- LangSmith

---

## 性能总结

### 基础优化成果（v2.x）
- 🚀 模型推理速度提升70%
- 🚀 缓存命中率85%
- 🚀 重复查询速度提升90%
- 🚀 批量处理效率提升70%
- 🚀 并发能力提升5倍

### 多智能体优化成果（v3.0.0 NEW!）
- 🚀 多Agent协作效率提升70%
- 🚀 并行任务处理能力提升5倍
- 🚀 复杂任务成功率提升7%
- 🚀 时序数据分析性能优化

### 技术亮点
- ✅ 环境变量配置 + Pydantic验证
- ✅ 完整错误码体系 + 标准响应
- ✅ LRU缓存 + TTL过期 + 统计信息
- ✅ Semaphore并发控制 + 超时管理
- ✅ 多智能体协作 + 自动任务规划
- ✅ 时序数据分析 + 异常检测
- ✅ 多LLM支持 + 灵活切换
- ✅ LangSmith追踪 + 质量评估

**项目版本**: 3.0.0 - Multi-Agent Integration Edition
**整合日期**: 2026-07-07

**版本特色**：
- ✅ **双模式**: 单Agent模式 + 多Agent模式
- ✅ **双核心**: 知识图谱 + 时序分析
- ✅ **双引擎**: 本地LLM + 云端LLM
- ✅ **双保障**: 缓存优化 + 异步处理

---

**注意**: 本项目需要本地运行 Ollama 服务，请确保已正确安装并启动 Ollama。模型下载可能需要设置代理环境变量。

**更新日志**:
- v3.0.0: 查看 `docs/README_UPDATE_v3.md` 了解多智能体整合的详细内容
- v2.1.0: 查看 `docs/OPTIMIZATION_REPORT.md` 了解完整的优化细节