imes

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. 安装依赖

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

# 安装项目依赖
uv sync

3. 配置环境变量

创建.env文件：

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

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

4. 启动服务

# 方式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

请求体：

{
  "message": "我想进行物料入库",
  "session_id": "optional_session_id",
  "context": {}
}

响应：

{
  "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}

响应：

{
  "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() 方法添加新的文档：

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

部署指南

Docker部署（推荐）

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或联系项目维护者。