# ai-openubmc

**Repository Path**: yufengmuling/ai-openubmc

## Basic Information

- **Project Name**: ai-openubmc
- **Description**: 基于openubmc开发的运维智能体
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI-Lang-OpenBMC

> 基于大语言模型的智能BMC服务器运维助手

一个现代化的工业级智能运维系统，融合大语言模型能力与BMC（Baseboard Management Controller）管理功能，提供智能化的服务器运维体验。

---

## ✨ 功能特性

### 🤖 智能对话
- **自然语言交互**：支持中文自然语言指令，无需学习复杂命令
- **LangGraph多智能体架构**：基于LangGraph重构的现代化多智能体系统
- **渐进式多轮工具调用**：支持多轮工具调用，根据执行结果动态决策下一步
- **并行工具调用**：LLM可一次请求多个工具并行执行，提高效率
- **上下文理解**：支持多轮对话，保持对话上下文记忆
- **流式响应**：支持实时流式输出，提升用户体验
- **智能错误处理**：自动识别BMC端点的无效响应，向用户提供清晰提示

### 🔧 BMC管理工具
| 模块 | 文件 | 功能 |
|------|------|------|
| **电源控制** | `bmc_power_control.py` | 开机、关机、重启、电源状态查询 |
| **告警管理** | `bmc_alarm_syslog.py` | 告警列表查询、事件类型查询、事件检索 |
| **系统监控** | `bmc_system_info.py` | 系统状态查询、BMC版本信息 |
| **热管理** | `bmc_thermal_control.py` | 温度信息查询、风扇转速控制 |
| **存储管理** | `bmc_storage.py` | 存储信息查询、存储摘要获取 |
| **用户管理** | `bmc_account.py` | 账户创建、删除、列表查询 |
| **网络设置** | `bmc_ntp.py` | NTP配置查询和设置 |
| **日志管理** | `bmc_syslog.py` | 系统日志配置查询和设置、日志下载 |
| **SEL日志** | `bmc_download_sel.py` | SEL日志下载、查询、覆盖策略管理 |
| **固件升级** | `bmc_update_service.py` | 升级服务信息、升级任务状态、固件信息、BMC镜像切换 |
| **事件管理** | `bmc_event_mode.py` | 事件模式查询和设置、事件清理 |
| **通用工具** | `bmc_utils.py` | BMC API通用调用、无效响应识别、结构化错误返回 |

### 📊 任务管理
- **任务模板**：支持自定义运维任务模板
- **任务调度**：灵活的任务执行计划
- **历史记录**：完整的操作日志追溯
- **前端任务触发**：点击任务模板可自动发起对应的LLM请求

### 📚 RAG知识库
- **文档管理**：支持知识库文档的增删改查操作
- **向量检索**：基于 Milvus 向量数据库的高效语义检索
- **元数据支持**：支持 doc_id、chunk_id 等元数据管理
- **可选加载**：RAG功能为可选模块，Milvus不可用时自动跳过

#### RAG工具接口

| 方法 | 功能 | 说明 |
|------|------|------|
| `add_document` | 添加文档 | 文本向量化后存入 Milvus |
| `delete_document` | 删除文档 | 根据 doc_id 删除文档及向量 |
| `search_documents` | 检索文档 | 向量相似度检索，返回相关内容 |
| `list_documents` | 列出文档 | 查看已入库的文档列表 |
| `get_document_info` | 获取文档信息 | 查看指定文档的详细信息 |

#### RAG配置要求（可选）

```env
# Milvus 向量数据库配置
MILVUS_HOST=localhost      # Milvus 服务器地址
MILVUS_PORT=19530          # Milvus 服务器端口
MILVUS_TOKEN=root:Milvus   # Milvus 认证令牌

# Embedding 服务配置
EMBEDDING_BASE_URL=http://localhost:8081/v1  # Embedding 服务地址
EMBEDDING_MODEL=bge-m3     # Embedding 模型名称
EMBEDDING_API_KEY=none     # Embedding 服务 API Key
```

---

## 🚀 快速开始

### 环境要求

- Python 3.10+
- FastAPI
- Uvicorn
- LangChain
- LangGraph
- Milvus（可选，用于RAG功能）

### 安装步骤

```bash
# 克隆项目
git clone https://github.com/your-org/ai-lang-openubmc.git
cd ai-lang-openubmc

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt
```

### 配置说明

复制并修改配置文件：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# LLM配置（必填）
OPENAI_API_KEY=your-api-key
OPENAI_API_BASE_URL=https://api.example.com/v1
OPENAI_MODEL=gpt-4o-mini

# 服务器配置
SERVER_PORT=8000

# 数据存储
DATA_DIR=data

# BMC服务配置
BMC_HOST=localhost
BMC_PORT=8090

# Milvus 向量数据库配置（可选）
MILVUS_HOST=localhost
MILVUS_PORT=19530
MILVUS_TOKEN=root:Milvus

# Embedding 服务配置（可选）
EMBEDDING_BASE_URL=http://localhost:8081/v1
EMBEDDING_MODEL=bge-m3
EMBEDDING_API_KEY=none
```

### 启动服务

```bash
# 开发模式（自动重载）
python main.py

# 生产模式
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
```

访问前端页面：`http://localhost:8000/static/chat.html`

---

## 📡 API接口

### 基础信息

| 接口 | 描述 |
|------|------|
| `GET /` | 服务信息（返回所有可用端点） |
| `GET /health` | 健康检查（含 BMC / LLM 连通性状态） |
| `GET /docs` | Swagger UI 自动文档（FastAPI 内置） |
| `GET /redoc` | ReDoc 自动文档（FastAPI 内置） |
| `GET /static/chat.html` | 前端交互页面 |

所有 API 的基础 URL：`http://localhost:8000`（取决于你的 `API_PORT` 配置）

---

### 聊天接口

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/chat/stream` | **流式聊天接口**（推荐前端使用，返回 SSE 流式响应） |
| POST | `/chat/send` | **同步聊天接口**（等待完整回答后一次性返回） |
| GET | `/chat/history/{id}` | 获取指定会话的历史记录 |
| GET | `/chat/conversations` | 获取所有会话列表 |
| DELETE | `/chat/history/{id}` | 删除指定会话 |
| DELETE | `/chat/clear` | 清空所有聊天记录 |

#### 请求体格式（聊天接口）

```json
{
  "message": "请查询服务器告警并分析状态",
  "conversation_id": "session_001"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `message` | string | ✅ | 用户输入的自然语言问题 |
| `conversation_id` | string | ❌ | 会话 ID，不填则随机生成 |

#### 响应格式（同步聊天）

```json
{
  "message": "根据查询结果，服务器当前存在 2 条严重告警：...",
  "conversation_id": "session_001"
}
```

#### 响应格式（流式聊天）

使用 Server-Sent Events (SSE) 协议，响应为多行文本：

```
data: 你好

data: 我可以帮你

data: [DONE]
```

每行以 `data: ` 开头，以 `\n\n` 结尾。`data: [DONE]` 表示流式传输完成。

---

### 任务模板接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/mission/list` | 获取任务模板列表 |
| POST | `/mission/add` | 添加任务模板 |
| GET | `/mission/{id}` | 获取指定任务详情 |
| PUT | `/mission/{id}` | 更新任务模板 |
| DELETE | `/mission/{id}` | 删除任务模板 |

#### 任务模板数据结构

```json
{
  "id": "uuid-string",
  "name": "查询服务器健康状况",
  "description": "查询告警、温度、系统状态并分析",
  "content": "请查询服务器的告警列表，然后查询温度信息，最后告诉我服务器是否健康",
  "created_at": "2025-01-15T10:30:00Z"
}
```

#### 创建任务模板请求示例

```bash
curl -X POST http://localhost:8000/mission/add \
  -H "Content-Type: application/json" \
  -d '{
    "name": "健康检查",
    "description": "查询告警、温度、系统状态",
    "content": "请帮我查询服务器的告警列表、温度信息和系统状态，然后分析服务器是否健康"
  }'
```

---

### 示例请求与响应

#### 1️⃣ 发送消息（流式）

```bash
curl -N -X POST http://localhost:8000/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "查看告警列表", "conversation_id": "test"}'
```

#### 2️⃣ 多轮工具调用（同步方式）

```bash
curl -X POST http://localhost:8000/chat/send \
  -H "Content-Type: application/json" \
  -d '{
    "message": "请查询服务器告警，然后查询系统状态，最后告诉我服务器是否健康",
    "conversation_id": "health_check"
  }'
```

LLM 会**自动调用多个工具**来完成任务：
1. 调用 `get_alarm_list` 查询告警
2. 调用 `get_system_status` 查询系统状态
3. 综合分析后给出回答

#### 3️⃣ 健康检查

```bash
curl http://localhost:8000/health
```

**响应示例：**

```json
{
  "status": "healthy",
  "service": "AI-Lang-OpenBMC",
  "version": "1.0.0",
  "bmc": {
    "host": "localhost",
    "port": 8090,
    "status": "reachable"
  },
  "llm": {
    "model": "gpt-4o-mini",
    "configured": true
  },
  "tools_available": 13
}
```

#### 4️⃣ 获取任务列表

```bash
curl http://localhost:8000/mission/list
```

---

### 全局错误响应格式

所有 API 在发生错误时统一返回以下格式：

```json
{
  "status": "error",
  "error": "TypeError",
  "message": "详细错误描述",
  "path": "/chat/send"
}
```

**404 Not Found** 时还会返回可用端点列表：

```json
{
  "status": "error",
  "error": "NotFound",
  "message": "Endpoint '/wrong/path' not found",
  "available_routes": [
    "/chat/send (POST)",
    "/chat/stream (POST)",
    "/mission/list (GET)",
    "/health (GET)",
    "/ (GET)"
  ]
}
```

---

## 🏗️ 架构设计

### 模块结构

```
src/
├── core/                    # 核心模块
│   ├── logging.py          # 日志系统
│   └── exceptions.py       # 异常处理
├── config/                  # 配置管理
│   └── settings.py         # 全局配置
├── tools/                   # 工具模块（核心）
│   ├── bmc_utils.py        # BMC API通用调用（含错误响应处理）
│   ├── bmc_power_control.py # 电源控制
│   ├── bmc_alarm_syslog.py # 告警与事件管理
│   ├── bmc_system_info.py  # 系统信息查询
│   ├── bmc_thermal_control.py # 热管理（温度/风扇）
│   ├── bmc_storage.py      # 存储管理
│   ├── bmc_account.py      # 用户账户管理
│   ├── bmc_ntp.py          # NTP配置
│   ├── bmc_syslog.py       # 系统日志
│   ├── bmc_download_sel.py # SEL日志下载
│   ├── bmc_sel_overwrite_policy.py # SEL覆盖策略
│   ├── bmc_update_service.py # 固件升级服务
│   ├── bmc_event_mode.py   # 事件模式
│   ├── email_tool.py       # 邮件工具
│   ├── time_tool.py        # 时间工具
│   └── rag_tool.py         # RAG检索工具（可选）
├── agent/                   # 智能体模块
│   ├── multi_agent_system.py    # 多智能体系统入口
│   ├── langgraph_multi_agent.py # LangGraph多智能体
│   ├── tool_manager.py          # 工具管理器（动态加载）
│   ├── tool_discovery_agent.py  # 工具发现智能体
│   ├── supervisor_agent.py      # 主管智能体（兼容保留）
│   ├── execution_agent.py       # 执行智能体（兼容保留）
│   └── monitor.py               # 监控模块
├── storage/                 # 数据存储
│   ├── chat_memory.py      # 聊天记忆
│   └── mission_store.py    # 任务存储
└── app/                     # API控制器
    └── controllers/
        ├── chat_controller.py    # 聊天接口
        └── mission_controller.py # 任务接口
```

### LangGraph多智能体架构

```
用户请求
    │
    ▼
┌─────────────────────────────────────┐
│         Supervisor (主管)           │
│  - 初始化流程                       │
│  - 加载对话上下文                   │
│  - 设置系统提示词（含多轮工具调用指导）│
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│           Agent (智能体)            │
│  - 分析用户意图                     │
│  - 决定是否调用工具                 │
│  - 支持一次请求多个工具（并行调用） │
│  - 根据工具返回结果继续决策         │
└─────────────────────────────────────┘
    │
    ├─ 需要工具 ──▶ ┌─────────────────────────────┐
    │                │           Tools             │
    │                │      (工具执行节点)          │
    │                │  - 执行工具调用             │
    │                │  - 返回结构化的JSON结果     │
    │                │  - 自动识别无效响应         │
    │                └─────────────────────────────┘
    │                          │
    │                          └──▶ 回到 Agent 继续决策
    │
    └─ 不需要工具 ──▶ ┌─────────────────────────────┐
                       │         Summary           │
                       │      (总结节点)            │
                       │  - 生成最终回答           │
                       │  - 返回给用户             │
                       └─────────────────────────────┘
```

### 渐进式多轮工具调用流程

```
supervisor → agent → tools → agent → ... → summary → END

特性：
- 迭代式执行：执行一个工具，查看结果，再决定下一步
- 动态决策：根据上一个工具的结果决定是否继续调用
- 最大调用限制：默认最多调用10次工具，可配置
- 循环调用：tools → agent 形成循环，直到不需要工具或达到最大次数
- 并行调用：Agent可一次请求多个工具并行执行
- 错误处理：工具返回的no_data/error会被LLM理解并智能处理
```

### BMC工具响应格式

BMC工具统一返回结构化JSON：

```json
{
  // 成功响应 - 真实数据
  "List": ["告警1", "告警2"],
  "TotalCount": 2,

  // 或无效响应 - BMC端点不可用
  "status": "no_data",
  "message": "BMC端点 /xxx/yyy 未返回有效数据",
  "endpoint": "/xxx/yyy",
  "raw_response": "请求已接收"
}

// 或请求失败 - 网络/服务异常
{
  "status": "error",
  "message": "调用BMC API失败: Connection refused",
  "endpoint": "/xxx/yyy",
  "method": "GET"
}
```

---

## 🔧 开发指南

### 添加新的BMC工具

1. 在 `src/tools/` 目录下创建新模块（命名为 `bmc_xxx.py`）
2. 使用 `@tool` 装饰器定义工具函数
3. 通过 `bmc_utils.py` 的 `call_bmc_api()` 调用BMC API（自动处理错误响应）
4. 在 `src/tools/__init__.py` 中导出工具

```python
from langchain_core.tools import tool
from .bmc_utils import call_bmc_api

@tool("get_xxx_info", description="获取XXX信息")
def get_xxx_info() -> str:
    """获取XXX信息"""
    return call_bmc_api("/UI/Rest/XXX/Info", "GET")

@tool("set_xxx_config", description="设置XXX配置")
def set_xxx_config(param: str) -> str:
    """设置XXX配置"""
    return call_bmc_api("/UI/Rest/XXX/Config", "POST", {"param": param})
```

### 添加新API

1. 在 `src/app/controllers/` 目录下创建控制器
2. 使用 FastAPI 的 `APIRouter` 定义路由
3. 在 `main.py` 中注册路由

### 自定义系统提示词

修改 `src/agent/langgraph_multi_agent.py` 中的系统提示词：

```python
system_prompt = """你是一个专业的**系统运维助手**...

【重要 - 多轮工具调用指南】
- 你的任务可能需要多步完成
- 可以一次请求多个工具（并行调用）
- 根据工具返回结果决定下一步

【重要 - 错误响应处理】
- status: "no_data" 表示BMC端点不可用
- 遇到这种情况请尝试其他工具或向用户说明
"""
```

---

## 🤝 贡献指南

欢迎贡献代码！请遵循以下流程：

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feature/your-feature`
3. 提交更改：`git commit -m 'Add some feature'`
4. 推送到分支：`git push origin feature/your-feature`
5. 创建 Pull Request

### 代码规范

- 遵循 PEP 8 编码规范
- 使用类型注解
- 添加单元测试
- 编写清晰的文档
- BMC工具返回值始终为JSON字符串

---

## 📄 许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

---

## 🙋‍♂️ 支持与反馈

如有问题或建议，请通过以下方式联系：

- 提交 [Issue](https://github.com/your-org/ai-lang-openubmc/issues)
- 发送邮件至 support@example.com

---

**Made with ❤️ by the AI-Lang-OpenBMC Team**

---

*如果这个项目对您有帮助，请给个 ⭐ Star！*