# MES系统首页AI后端服务

## 项目简介

这是一个为MES（制造执行系统）开发的首页AI后端服务模块，提供智能对话功能。支持四种核心AI能力：

1. **页面跳转引导** - 用户可以用自然语言描述想要执行的操作，AI直接跳转至相应页面
2. **系统使用引导** - 基于知识库RAG，为用户提供系统使用指导
3. **生产QA** - 通过RAG和数据库查询，回答用户关于生产情况的问题
4. **闲聊** - 处理日常对话，提供友好的用户体验

## 系统架构

### AI处理流程

```
用户输入问题
    ↓
问题编排Agent判断问题类型
    ↓
调用相应专家Agent
    ↓
专家Agent判断是否需要RAG
    ↓ (如需要)
执行RAG查询，获取知识库内容
    ↓
专家Agent判断是否需要Tool Call
    ↓ (如需要)
执行工具调用（页面跳转/数据库查询）
    ↓
专家Agent生成回复
    ↓
总结Agent美化最终答案
    ↓
返回给用户
```

### 技术栈

- **框架**: FastAPI + Uvicorn
- **AI模型**: OpenAI GPT-3.5-turbo
- **向量数据库**: ChromaDB
- **文本处理**: LangChain
- **包管理**: uv
- **配置管理**: Pydantic Settings
- **日志**: Loguru

## 快速开始

### 1. 环境要求

- Python >= 3.11
- OpenAI API密钥

### 2. 安装依赖

```bash
# 安装uv（如果未安装）
pip install uv

# 安装项目依赖
uv sync
```

### 3. 配置环境变量

创建`.env`文件：

```bash
# 复制模板（如果存在）
cp .env.example .env

# 或者手动创建
echo "MES_AI_OPENAI_API_KEY=your_openai_api_key_here" > .env
echo "MES_AI_DEBUG=true" >> .env
```

### 4. 启动服务

```bash
# 方式1: 使用启动脚本（推荐）
python scripts/start.py

# 方式2: 直接启动
python main.py

# 方式3: 使用uv
uv run python main.py
```

### 5. 验证服务

访问以下地址验证服务是否正常：

- **API文档**: http://localhost:8000/docs
- **健康检查**: http://localhost:8000/api/v1/health
- **服务信息**: http://localhost:8000/api/v1/info

## API接口

### 聊天接口

**POST** `/api/v1/chat`

请求体：
```json
{
  "message": "我想进行物料入库",
  "session_id": "optional_session_id",
  "context": {}
}
```

响应：
```json
{
  "message": "AI回复内容",
  "question_type": "page_navigation",
  "session_id": "generated_or_provided_session_id",
  "need_rag": true,
  "need_tool_call": true,
  "metadata": {
    "classification_confidence": 0.95,
    "rag_results_count": 2,
    "tool_calls_count": 1
  }
}
```

### 聊天历史

**GET** `/api/v1/chat/history/{session_id}`

响应：
```json
{
  "session_id": "session_id",
  "history": [
    {
      "role": "user",
      "content": "用户消息",
      "question_type": "page_navigation"
    },
    {
      "role": "assistant", 
      "content": "AI回复",
      "question_type": "page_navigation"
    }
  ],
  "message_count": 2
}
```

## 配置说明

### 主要配置项

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|---------|------|
| OpenAI API密钥 | `MES_AI_OPENAI_API_KEY` | - | **必填**，OpenAI API密钥 |
| 服务端口 | `MES_AI_PORT` | 8000 | 服务监听端口 |
| 调试模式 | `MES_AI_DEBUG` | false | 是否开启调试模式 |
| 日志级别 | `MES_AI_LOG_LEVEL` | INFO | 日志输出级别 |
| 知识库路径 | `MES_AI_KNOWLEDGE_BASE_PATH` | knowledge_base | 向量数据库存储路径 |

完整配置项请参考 `src/utils/config.py`

## 开发指南

### 项目结构

```
imes/
├── src/                    # 源代码目录
│   ├── agents/            # AI Agent模块
│   │   ├── orchestrator.py    # 问题编排Agent
│   │   ├── expert_agents.py   # 专家Agent
│   │   └── summary_agent.py   # 总结Agent
│   ├── services/          # 服务模块
│   │   ├── ai_service.py      # AI服务主类
│   │   ├── rag_service.py     # RAG服务
│   │   └── tool_service.py    # 工具调用服务
│   ├── models/           # 数据模型
│   │   └── schemas.py        # Pydantic模型
│   ├── api/              # API接口
│   │   └── routes.py         # 路由定义
│   ├── utils/            # 工具模块
│   │   └── config.py         # 配置管理
│   └── app.py            # FastAPI应用
├── scripts/              # 脚本目录
│   └── start.py          # 启动脚本
├── main.py              # 服务入口
├── pyproject.toml       # 项目配置
└── README.md           # 项目文档
```

### 添加新的Agent

1. 在 `src/agents/expert_agents.py` 中继承 `BaseExpertAgent`
2. 实现必要的方法：`need_rag()`, `need_tool_call()`, `generate_response()`
3. 在 `ExpertAgentFactory` 中注册新的Agent

### 添加新的工具

1. 在 `src/services/tool_service.py` 中继承 `BaseTool`
2. 实现 `execute()` 方法和 `name` 属性
3. 在 `ToolService` 中注册新工具

### 扩展知识库

使用 `RAGService.add_documents()` 方法添加新的文档：

```python
documents = [
    {
        "content": "文档内容",
        "metadata": {"source": "来源", "type": "类型"}
    }
]
await rag_service.add_documents(documents, "collection_name")
```

## 部署指南

### Docker部署（推荐）

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install uv
RUN uv sync

EXPOSE 8000
CMD ["python", "main.py"]
```

### 生产环境配置

1. 设置 `MES_AI_DEBUG=false`
2. 配置适当的 `MES_AI_WORKERS` 数量
3. 设置日志文件路径 `MES_AI_LOG_FILE`
4. 配置数据库和Redis连接
5. 设置安全的 `MES_AI_SECRET_KEY`

## 故障排除

### 常见问题

1. **OpenAI API调用失败**
   - 检查API密钥是否正确
   - 确认网络连接正常
   - 检查API配额是否用完

2. **向量数据库初始化失败**
   - 确保知识库目录有写权限
   - 检查磁盘空间是否充足

3. **服务启动失败**
   - 检查端口是否被占用
   - 验证Python版本 >= 3.11
   - 确认所有依赖已安装

## 贡献指南

1. Fork项目
2. 创建功能分支
3. 提交更改
4. 创建Pull Request

## 许可证

本项目采用MIT许可证。详见LICENSE文件。

## 联系方式

如有问题或建议，请提交Issue或联系项目维护者。