taijibaga/taiji-AI-PAD
9
0
Fork 0
forked from xiaohei/taiji-AI-PAD
Code Pull Requests Activity

更新资源监控

Browse Source
This commit is contained in:
Ubuntu
2025-12-31 09:22:51 +00:00
parent 178c563012
commit 11016b6667
2 changed files with 279 additions and 264 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Docs/前后端调试接口说明/API-MCPServer服务.md
+279 -17
View File
@@ -10,7 +10,7 @@
## 目录
### MCP Server 基础
### 一、创建工具
1. [健康检查](#1-健康检查)
2. [注册 Agent](#2-注册-agent)
3. [获取 Agent 列表](#3-获取-agent-列表)
@@ -20,27 +20,55 @@
6. [获取工具列表](#6-获取工具列表)
7. [Prometheus Metrics](#7-prometheus-metrics)
### K8s Agent 管理 API（新增）
### 二、平台Agent（K8s Agent管理）
8. [获取模板列表](#8-获取模板列表)
9. [获取模板详情](#9-获取模板详情)
10. [创建 K8s Agent](#10-创建-k8s-agent)
10. [创建平台 Agent](#10-创建-k8s-agent)
11. [删除 Agent](#11-删除-agent)
12. [获取 Agent 状态](#12-获取-agent-状态)
13. [获取 Agent 资源使用](#13-获取-agent-资源使用)
### MCP 监控 API
### 三、平台Agent监控（Agent健康状态）
12. [获取 Agent 状态](#12-获取-agent-状态)
13. [获取 Agent 资源配置](#13-获取-agent-资源配置)
### 四、系统监控（服务器级指标）
14. [获取系统性能指标](#14-获取系统性能指标)
15. [获取服务统计信息](#15-获取服务统计信息)
16. [获取性能趋势数据](#16-获取性能趋势数据)
17. [获取系统告警](#17-获取系统告警)
18. [获取监控仪表盘聚合](#18-获取监控仪表盘聚合)
### WebSocket API
19. [MCP Protocol WebSocket](#19-mcp-protocol-websocket)
### 五、资源监控（业务级统计）
19. [获取平台资源概览](#19-获取平台资源概览)
20. [获取用户资源使用汇总](#20-获取用户资源使用汇总)
21. [获取资源使用趋势](#21-获取资源使用趋势)
22. [获取Agent资源统计](#22-获取agent资源统计)
### 六、WebSocket API
23. [MCP Protocol WebSocket](#23-mcp-protocol-websocket)
---
## MCP Server 基础
## 监控API总览
为便于前端理解，以下表格汇总了所有监控相关的API及其用途：
| 分类 | 接口 | 用途 | 适用场景 |
|------|------|------|----------|
| **平台Agent监控** | `GET /agents/{id}/status` | 获取单个Agent的状态 | Agent详情页、健康检查 |
| **平台Agent监控** | `GET /agents/{id}/metrics` | 获取单个Agent的CPU/内存配置 | Agent详情页、资源配置展示 |
| **系统监控** | `GET /api/v1/monitoring/metrics` | 服务器CPU、内存、磁盘指标 | 运维仪表盘 |
| **系统监控** | `GET /api/v1/monitoring/stats` | Agent/执行/用户聚合统计 | 运维仪表盘 |
| **系统监控** | `GET /api/v1/monitoring/trends` | 执行次数/EU消耗趋势图 | 运维仪表盘 |
| **系统监控** | `GET /api/v1/monitoring/alerts` | 系统告警列表 | 告警中心 |
| **系统监控** | `GET /api/v1/monitoring/dashboard` | 聚合所有系统监控数据 | 运维仪表盘首页 |
| **资源监控** | `GET /api/billing-admin/resources/overview` | 平台整体资源概览 | 管理员仪表盘 |
| **资源监控** | `GET /api/billing-admin/resources/user/{id}` | 指定用户资源使用汇总 | 用户详情页 |
| **资源监控** | `GET /api/billing-admin/resources/trends` | 用户资源使用趋势 | 用户资源分析 |
| **资源监控** | `GET /api/billing-admin/resources/agent/{id}` | 指定Agent资源统计 | Agent资源分析 |
---
## 一、创建工具
### 1. 健康检查
@@ -353,9 +381,9 @@ curl -X GET "http://localhost:8002/metrics"
---
## K8s Agent 管理 API（新增）
## 二、平台Agent
> **说明**: 这些接口用于管理 Kubernetes 中的 AI Agent Pod，通过 AI Agent Manager 服务实现。
> **说明**: 这些接口用于 AI Agent Pod
### 8. 获取模板列表
@@ -576,12 +604,18 @@ curl -X DELETE "http://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1
---
## 三、平台Agent监控（Agent健康状态）
> **说明**: 这些接口用于监控单个 Agent 的健康状态和资源配置，适用于前端 Agent 详情页展示。
### 12. 获取 Agent 状态
**GET** `/agents/{agent_id}/status`
获取 Agent 的实时状态。如果 Agent 有关联的 K8s Pod，会从 Agent Manager 获取最新状态。
**用途**: 前端 Agent 详情页展示 Pod 运行状态、IP地址、节点信息等。
**路径参数**:
- `agent_id` (string, 必填): Agent ID
@@ -639,12 +673,14 @@ curl -X GET "http://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b/s
---
### 13. 获取 Agent 资源使用
### 13. 获取 Agent 资源配置
**GET** `/agents/{agent_id}/metrics`
获取 Agent 的 CPU 和内存资源配置信息。
**用途**: 前端 Agent 详情页展示资源配置（请求量和限制量）。
**路径参数**:
- `agent_id` (string, 必填): Agent ID
@@ -671,7 +707,9 @@ curl -X GET "http://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b/m
---
## MCP 监控 API
## 四、系统监控（服务器级指标）
> **说明**: 这些接口提供 MCP Server 服务器级别的监控数据，包括 CPU、内存、磁盘等系统指标，以及 Agent 执行的聚合统计。适用于运维仪表盘。
**基础URL**: `http://localhost:8002/api/v1/monitoring`
@@ -679,7 +717,9 @@ curl -X GET "http://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b/m
**GET** `/api/v1/monitoring/metrics`
提供 CPU、内存、磁盘以及核心业务指标。
提供服务器 CPU、内存、磁盘以及核心业务指标。
**用途**: 运维仪表盘展示服务器健康状态。
**请求示例**:
```bash
@@ -721,6 +761,8 @@ curl -X GET "http://localhost:8002/api/v1/monitoring/metrics"
按服务类型返回聚合统计。
**用途**: 运维仪表盘展示 Agent、执行、用户等维度的统计数据。
**查询参数**:
- `service` (string, 可选, 默认: `all`): 可选值 `all`, `agents`, `executions`, `tools`, `users`
@@ -759,6 +801,8 @@ curl -X GET "http://localhost:8002/api/v1/monitoring/stats?service=all"
按时间区间返回执行或消耗趋势。
**用途**: 运维仪表盘展示执行次数、EU消耗的趋势图。
**查询参数**:
- `metric` (string, 可选, 默认: `executions`): 可选值 `executions`, `eu_consumption`
- `period` (string, 可选, 默认: `24h`): 可选值 `24h`, `7d`, `30d`
@@ -794,6 +838,8 @@ curl -X GET "http://localhost:8002/api/v1/monitoring/trends?metric=executions&pe
返回当前系统告警列表。
**用途**: 告警中心展示系统级告警（如CPU过高、内存不足等）。
**查询参数**:
- `severity` (string, 可选): 过滤严重程度，可选 `info`, `warning`, `critical`
@@ -826,6 +872,8 @@ curl -X GET "http://localhost:8002/api/v1/monitoring/alerts?severity=warning"
聚合健康、指标、统计和告警信息。
**用途**: 运维仪表盘首页一次性获取所有系统监控数据。
**请求示例**:
```bash
curl -X GET "http://localhost:8002/api/v1/monitoring/dashboard"
@@ -853,9 +901,224 @@ curl -X GET "http://localhost:8002/api/v1/monitoring/dashboard"
---
## WebSocket API
## 五、资源监控（业务级统计）
### 19. MCP Protocol WebSocket
> **说明**: 这些接口提供业务级别的资源使用统计，包括平台整体概览、用户资源使用、Agent资源统计等。适用于管理员仪表盘和用户资源分析。
>
> **权限要求**: 需要 `super_admin`、`billing_admin` 或 `operations_admin` 角色。
**基础URL**: `http://localhost:8002/api/billing-admin/resources`
### 19. 获取平台资源概览
**GET** `/api/billing-admin/resources/overview`
获取平台整体资源使用概览（管理员视图）。
**用途**: 管理员仪表盘展示平台整体运营数据。
**请求头**:
```
Authorization: Bearer <token>
```
**请求示例**:
```bash
curl -X GET "http://localhost:8002/api/billing-admin/resources/overview" \
-H "Authorization: Bearer <admin_token>"
```
**响应示例**:
```json
{
"success": true,
"data": {
"todayCalls": 156,
"monthCalls": 4523,
"activeUsersToday": 28,
"activeAgents": 15,
"monthTotalEu": 234.56,
"timestamp": "2025-12-31T05:10:00Z"
}
}
```
**响应字段说明**:
| 字段 | 说明 |
|------|------|
| `todayCalls` | 今日API调用次数 |
| `monthCalls` | 本月API调用次数 |
| `activeUsersToday` | 今日活跃用户数 |
| `activeAgents` | 当前活跃Agent数 |
| `monthTotalEu` | 本月总EU消费 |
---
### 20. 获取用户资源使用汇总
**GET** `/api/billing-admin/resources/user/{user_id}`
获取指定用户在时间范围内的资源使用汇总。
**用途**: 用户详情页展示用户的资源消耗情况。
**请求头**:
```
Authorization: Bearer <token>
```
**路径参数**:
- `user_id` (string, 必填): 用户ID
**查询参数**:
- `start_date` (string, 必填): 开始日期 (ISO 8601格式)
- `end_date` (string, 必填): 结束日期 (ISO 8601格式)
**请求示例**:
```bash
curl -X GET "http://localhost:8002/api/billing-admin/resources/user/user-123?start_date=2025-12-01T00:00:00Z&end_date=2025-12-31T23:59:59Z" \
-H "Authorization: Bearer <admin_token>"
```
**响应示例**:
```json
{
"success": true,
"data": {
"totalCpuSeconds": 1234.56,
"totalMemoryMbSeconds": 56789.12,
"totalNetworkBytes": 1073741824,
"totalStorageBytes": 536870912,
"totalApiCalls": 456,
"startDate": "2025-12-01T00:00:00Z",
"endDate": "2025-12-31T23:59:59Z"
}
}
```
**响应字段说明**:
| 字段 | 说明 |
|------|------|
| `totalCpuSeconds` | CPU总使用时间（秒） |
| `totalMemoryMbSeconds` | 内存总使用量（MB·秒） |
| `totalNetworkBytes` | 网络总流量（字节） |
| `totalStorageBytes` | 存储总使用量（字节） |
| `totalApiCalls` | API总调用次数 |
---
### 21. 获取资源使用趋势
**GET** `/api/billing-admin/resources/trends`
获取用户资源使用趋势。
**用途**: 用户资源分析页面展示资源使用的时间趋势图。
**请求头**:
```
Authorization: Bearer <token>
```
**查询参数**:
- `user_id` (string, 必填): 用户ID
- `period` (string, 可选, 默认: `7d`): 时间范围，可选 `7d`, `30d`, `90d`
- `granularity` (string, 可选, 默认: `daily`): 粒度，可选 `hourly`, `daily`
**请求示例**:
```bash
curl -X GET "http://localhost:8002/api/billing-admin/resources/trends?user_id=user-123&period=7d&granularity=daily" \
-H "Authorization: Bearer <admin_token>"
```
**响应示例**:
```json
{
"success": true,
"data": {
"trends": [
{
"periodStart": "2025-12-25",
"periodEnd": "2025-12-25T23:59:59",
"cpuSeconds": 123.45,
"memoryMbSeconds": 5678.90,
"networkBytes": 107374182,
"apiCalls": 45
},
{
"periodStart": "2025-12-26",
"periodEnd": "2025-12-26T23:59:59",
"cpuSeconds": 156.78,
"memoryMbSeconds": 6789.01,
"networkBytes": 134217728,
"apiCalls": 52
}
]
}
}
```
---
### 22. 获取Agent资源统计
**GET** `/api/billing-admin/resources/agent/{agent_id}`
获取指定Agent在时间范围内的资源统计。
**用途**: Agent资源分析页面展示Agent的执行统计和资源消耗。
**请求头**:
```
Authorization: Bearer <token>
```
**路径参数**:
- `agent_id` (string, 必填): Agent ID
**查询参数**:
- `start_date` (string, 必填): 开始日期 (ISO 8601格式)
- `end_date` (string, 必填): 结束日期 (ISO 8601格式)
**请求示例**:
```bash
curl -X GET "http://localhost:8002/api/billing-admin/resources/agent/agent-456?start_date=2025-12-01T00:00:00Z&end_date=2025-12-31T23:59:59Z" \
-H "Authorization: Bearer <admin_token>"
```
**响应示例**:
```json
{
"success": true,
"data": {
"agentId": "agent-456",
"totalExecutions": 234,
"avgExecutionTime": 156.78,
"totalEuConsumed": 23.45,
"successRate": 96.58,
"startDate": "2025-12-01T00:00:00Z",
"endDate": "2025-12-31T23:59:59Z"
}
}
```
**响应字段说明**:
| 字段 | 说明 |
|------|------|
| `agentId` | Agent ID |
| `totalExecutions` | 总执行次数 |
| `avgExecutionTime` | 平均执行时间（毫秒） |
| `totalEuConsumed` | 总EU消耗 |
| `successRate` | 成功率（百分比） |
---
## 六、WebSocket API
### 23. MCP Protocol WebSocket
**WebSocket URL**: `ws://localhost:8002/ws/{agent_name_or_id}`
@@ -903,4 +1166,3 @@ ws.onmessage = (event) => {
---
> 返回 [API接口文档](./API接口文档.md)
Docs/前后端调试接口说明/API接口文档.md
-247
View File
@@ -1,247 +0,0 @@
# API 接口文档索引
本文档提供了 taiji-AI-PAD 平台所有 API 接口的索引和快速导航。
---
## 📚 服务 API 文档
### 核心服务
1. **[Model Gateway (LiteLLM) 服务](./API-ModelGateway服务.md)**
- 模型网关服务，提供统一的 LLM 访问接口
- 支持 OpenAI、Anthropic、OpenRouter 等多种模型提供商
- 基础 URL: `http://localhost:4000`
2. **[MCP Server 服务](./API-MCPServer服务.md)**
- MCP 协议服务器，提供 Agent 管理和工具执行
- 支持 API 工具、函数工具和 LLM 工具调用
- 基础 URL: `http://localhost:8002`
3. **[Data Ingestion 服务](./API-DataIngestion服务.md)**
- 数据接入服务，处理 OpenAPI/Swagger 解析
- RapidAPI 同步和工具生成
- APILLAMA 文档处理（使用 OpenRouter）
- 基础 URL: `http://localhost:8001`
---
## 🔐 业务 API 文档
### 用户侧平台
4. **[用户侧平台 API](./API-用户侧平台.md)**
- 用户仪表板、Agent 管理、工作流编排
- 服务网关配置、数据模板、计费管理
- 基础 URL: `http://localhost:8002/api/user`
### 认证与权限
5. **[认证模块 API](./API-认证模块.md)**
- 用户注册、登录、JWT Token 管理
- 多角色认证（user, channel_admin, billing_admin 等）
- 基础 URL: `http://localhost:8002/api/auth`
### 管理端 API
6. **[超级管理员 API](./API-超级管理员.md)**
- 系统配置、用户管理、服务监控
- 基础 URL: `http://localhost:8002/api/admin`
7. **[渠道合作伙伴 API](./API-渠道合作伙伴.md)**
- 租户管理、渠道统计、佣金管理
- 基础 URL: `http://localhost:8002/api/channel`
8. **[供应商管理 API](./API-供应商管理.md)**
- 供应商注册、API 管理、结算管理
- 基础 URL: `http://localhost:8002/api/provider`
9. **[计费与资源管理 API](./API-计费与资源管理.md)**
- EU 计费、资源配额、账单管理
- 基础 URL: `http://localhost:8002/api/billing`
10. **[资源管控完整指南](./API-资源管控完整指南.md)** ✨ **新增**
- 渠道资源配置、租户资源分配
- 自定义Agent资源管理、配额控制
- 完整工作流程和最佳实践
---
## 🧪 测试与集成
11. **[前端集成与测试 API](./API-前端集成与测试.md)**
- 前端集成指南、测试用例
- Mock 数据和测试工具
---
## 🔧 快速参考
### 认证方式
所有业务 API 都需要认证，支持两种方式：
1. **JWT Token**:
```
Authorization: Bearer <jwt_token>
```
2. **API Key**:
```
X-API-Key: <api_key>
```
### Model Gateway API Key
| API Key | 权限 | 可用模型 |
|---------|------|---------|
| `sk-taiji-master-key` | 全部模型 | 所有配置的模型 |
| `sk-taiji-mcp-server` | MCP Server | gpt-3.5-turbo, gpt-4, claude-3-haiku, claude-3-sonnet, openrouter-* |
| `sk-taiji-data-ingestion` | Data Ingestion | gpt-3.5-turbo, claude-3-haiku, llama-3-8b, openrouter-* |
| `sk-taiji-agent-dev` | Agent 开发 | 模型组访问权限 |
| `sk-taiji-premium` | 高级用户 | 所有高级模型 |
### 可用模型列表
#### OpenAI 模型（通过 OpenRouter）
- `gpt-3.5-turbo` - GPT-3.5 Turbo（别名，实际使用 OpenRouter）
- `openrouter-gpt-3.5-turbo` - GPT-3.5 Turbo
- `openrouter-gpt-4o-mini` - GPT-4o Mini
#### Anthropic 模型（通过 OpenRouter）
- `openrouter-claude-3.5-sonnet` - Claude 3.5 Sonnet
- `openrouter-claude-3-opus` - Claude 3 Opus
#### 测试模型
- `test-model` - 测试用模型（OpenRouter Qwen）
---
## 📝 环境配置
### 必需的环境变量
```bash
# OpenRouter 配置（用于 LLM 调用）
OPENROUTER_API_KEY=your_openrouter_api_key
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
# LiteLLM 配置
LITELLM_MASTER_KEY=sk-taiji-master-key
LITELLM_CONFIG_PATH=/app/config/litellm_simple.yaml
# 数据库配置
DATABASE_URL=postgresql+asyncpg://...
REDIS_URL=redis://...
# NATS 配置
NATS_URL=nats://nats:4222
```
---
## 🚀 快速开始
### 1. 检查服务健康状态
```bash
# Model Gateway
curl http://localhost:4000/health \
-H "Authorization: Bearer sk-taiji-master-key"
# MCP Server
curl http://localhost:8002/health
# Data Ingestion
curl http://localhost:8001/health
```
### 2. 调用 LLM 模型
```bash
curl -X POST http://localhost:4000/v1/chat/completions \
-H "Authorization: Bearer sk-taiji-master-key" \
-H "Content-Type: application/json" \
-d '{
"model": "openrouter-gpt-3.5-turbo",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
```
### 3. 执行 Agent 工具
```bash
curl -X POST http://localhost:8002/agents/{agent_id}/execute \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "req-001",
"method": "tools/call",
"params": {
"tool": {"name": "math_add"},
"arguments": {"a": 10, "b": 20}
}
}'
```
---
## 📊 监控与日志
### Prometheus Metrics
- Model Gateway: `http://localhost:4000/metrics`
- MCP Server: `http://localhost:8002/metrics`
- Data Ingestion: `http://localhost:8001/metrics`
### 查看日志
```bash
# Model Gateway
docker logs taiji-litellm-gateway --tail 100
# MCP Server
docker logs taiji-mcp-server --tail 100
# Data Ingestion
docker logs taiji-data-ingestion --tail 100
```
---
## ❓ 常见问题
### Q: OpenRouter 返回 402 错误？
A: OpenRouter 账户余额不足。请访问 https://openrouter.ai/settings/credits 充值。
### Q: 如何切换模型？
A: 在请求的 `model` 字段中指定不同的模型名称即可。参考 [Model Gateway API](./API-ModelGateway服务.md) 获取完整模型列表。
### Q: API Key 在哪里配置？
A: API Key 在 `litellm.yaml` 或 `litellm_simple.yaml` 中配置，通过环境变量 `LITELLM_MASTER_KEY` 设置主密钥。
### Q: 如何查看 API 使用情况？
A: 使用 Model Gateway 的 `/key/info` 端点查看当前 API Key 的预算使用情况。
---
## 📅 更新日志
### 2025-12-28
- ✅ 创建 Model Gateway API 文档
- ✅ 更新 MCP Server 文档，添加 LiteLLM 集成说明
- ✅ 更新 Data Ingestion 文档，说明 OpenRouter 使用
- ✅ 修复硬编码 API Key 问题
- ✅ 添加 `gpt-3.5-turbo` 别名支持
- ✅ 移除冗余的 `api_base` 配置
---
> 更多详细信息，请参考各服务的具体 API 文档。