forked from xiaohei/taiji-AI-PAD
更新mode网关
This commit is contained in:
Ubuntu
+32
@@ -0,0 +1,32 @@
|
||||
# Taiji AI-PAD 环境变量配置
|
||||
|
||||
# 数据库配置
|
||||
ASYNC_DATABASE_URL=postgresql+asyncpg://taiji:By%40123456.@taijipda.postgres.database.azure.com:5432/postgres
|
||||
DATABASE_URL=postgresql://taiji:By%40123456.@taijipda.postgres.database.azure.com:5432/postgres?sslmode=require
|
||||
|
||||
# Redis配置 (暂未启用)
|
||||
REDIS_URL=redis://redis:6379
|
||||
|
||||
# NATS消息队列配置
|
||||
NATS_URL=nats://nats:4222
|
||||
|
||||
# LiteLLM网关配置
|
||||
LITELLM_MASTER_KEY=sk-1234567890abcdef
|
||||
LITELLM_URL=http://litellm-gateway:4000
|
||||
|
||||
# OpenRouter配置
|
||||
OPENROUTER_API_KEY=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
|
||||
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
|
||||
|
||||
# RapidAPI配置
|
||||
RAPIDAPI_KEY=33902cc39dmsha572ec6ae920fb5p13c196jsn8a11209a7e67
|
||||
RAPIDAPI_HOST=rapidapi.com
|
||||
|
||||
# JWT配置
|
||||
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
|
||||
JWT_ALGORITHM=HS256
|
||||
JWT_EXPIRE_MINUTES=1440
|
||||
|
||||
# 应用配置
|
||||
APP_ENV=development
|
||||
LOG_LEVEL=INFO
|
||||
@@ -0,0 +1,33 @@
|
||||
# Taiji AI-PAD 环境变量配置
|
||||
|
||||
# 数据库配置
|
||||
ASYNC_DATABASE_URL=postgresql+asyncpg://taiji:By%40123456.@taijipda.postgres.database.azure.com:5432/postgres
|
||||
DATABASE_URL=postgresql://taiji:By%40123456.@taijipda.postgres.database.azure.com:5432/postgres?sslmode=require
|
||||
|
||||
# Redis配置 (暂未启用)
|
||||
# REDIS_URL已禁用（无本地Redis）
|
||||
REDIS_URL=
|
||||
|
||||
# NATS消息队列配置
|
||||
NATS_URL=nats://nats:4222
|
||||
|
||||
# LiteLLM网关配置
|
||||
LITELLM_MASTER_KEY=sk-1234567890abcdef
|
||||
LITELLM_URL=http://litellm-gateway:4000
|
||||
|
||||
# OpenRouter配置
|
||||
OPENROUTER_API_KEY=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
|
||||
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
|
||||
|
||||
# RapidAPI配置
|
||||
RAPIDAPI_KEY=33902cc39dmsha572ec6ae920fb5p13c196jsn8a11209a7e67
|
||||
RAPIDAPI_HOST=rapidapi.com
|
||||
|
||||
# JWT配置
|
||||
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
|
||||
JWT_ALGORITHM=HS256
|
||||
JWT_EXPIRE_MINUTES=1440
|
||||
|
||||
# 应用配置
|
||||
APP_ENV=development
|
||||
LOG_LEVEL=INFO
|
||||
@@ -164,6 +164,8 @@ curl -X POST "http://localhost:8001/openapi/parse?url=https://api.example.com/op
|
||||
|
||||
使用 APILLAMA 处理 API 文档，生成结构化 Schema。
|
||||
|
||||
> **说明**: APILLAMA 使用 OpenRouter API 调用 Llama 3.1 8B Instruct 模型进行文档处理。如果 OpenRouter 不可用或账户余额不足，系统会自动使用 fallback 处理逻辑。
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
@@ -197,6 +199,16 @@ curl -X POST "http://localhost:8001/openapi/parse?url=https://api.example.com/op
|
||||
- `enhance_descriptions` (bool, 可选): 是否增强描述
|
||||
- `validate_schema` (bool, 可选): 是否校验 Schema
|
||||
|
||||
**环境配置**:
|
||||
- `OPENROUTER_API_KEY`: OpenRouter API Key（必需，用于 LLM 增强处理）
|
||||
- `OPENROUTER_BASE_URL`: OpenRouter API 基础 URL（默认: `https://openrouter.ai/api/v1`）
|
||||
|
||||
**处理流程**:
|
||||
1. 如果 OpenRouter 可用，使用 Llama 3.1 8B Instruct 模型进行智能分析和增强
|
||||
2. 如果 OpenRouter 不可用或返回错误，自动切换到 fallback 处理逻辑
|
||||
3. Fallback 处理使用规则引擎提取参数和生成基础 Schema
|
||||
4. 结果会缓存 24 小时（Redis）
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
@@ -213,14 +225,47 @@ curl -X POST "http://localhost:8001/openapi/parse?url=https://api.example.com/op
|
||||
"required": ["location"]
|
||||
},
|
||||
"description": "Weather API for getting current weather information",
|
||||
"parameters": [],
|
||||
"examples": [],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "location",
|
||||
"type": "string",
|
||||
"description": "City name",
|
||||
"required": true,
|
||||
"location": "query"
|
||||
}
|
||||
],
|
||||
"examples": [
|
||||
{
|
||||
"name": "basic_example",
|
||||
"description": "Basic example request",
|
||||
"value": {
|
||||
"location": "example_location"
|
||||
}
|
||||
}
|
||||
],
|
||||
"processing_time": 1.234,
|
||||
"confidence_score": 0.95,
|
||||
"completeness_score": 0.88
|
||||
"completeness_score": 0.88,
|
||||
"from_cache": false
|
||||
}
|
||||
```
|
||||
|
||||
**响应字段说明**:
|
||||
- `processed` (boolean): 是否成功处理
|
||||
- `schema` (object): 生成的 Schema（格式取决于 `output_format`）
|
||||
- `description` (string): 增强后的 API 描述
|
||||
- `parameters` (array): 提取的参数列表
|
||||
- `examples` (array): 生成的示例数据
|
||||
- `processing_time` (float): 处理耗时（秒）
|
||||
- `confidence_score` (float): 置信度分数（0-1）
|
||||
- `completeness_score` (float): 完整性分数（0-1）
|
||||
- `from_cache` (boolean): 是否来自缓存
|
||||
|
||||
**错误处理**:
|
||||
- 如果 OpenRouter API 返回错误（如余额不足），系统会自动使用 fallback 处理
|
||||
- Fallback 处理仍能生成有效的 Schema，但质量可能略低
|
||||
- 所有处理结果都会缓存，减少重复调用
|
||||
|
||||
---
|
||||
|
||||
## 6. 生成工具定义
|
||||
@@ -16,6 +16,7 @@
|
||||
3. [获取 Agent 列表](#3-获取-agent-列表)
|
||||
4. [获取特定 Agent](#4-获取特定-agent)
|
||||
5. [执行 Agent 工具](#5-执行-agent-工具)
|
||||
- [LLM 工具调用](#llm-工具调用)
|
||||
6. [获取工具列表](#6-获取工具列表)
|
||||
7. [Prometheus Metrics](#7-prometheus-metrics)
|
||||
|
||||
@@ -241,7 +242,80 @@ curl -X GET "http://localhost:8002/agents/d7b0a5c2-5f6a-4c27-9ef9-8d51b94f7a1b"
|
||||
| 哈希 | `hash_md5`, `hash_sha256` |
|
||||
| Base64 | `base64_encode`, `base64_decode` |
|
||||
|
||||
> **说明**: 执行会自动记录到数据库，并进行EU计费（1 EU = 10秒）。
|
||||
#### LLM 工具调用
|
||||
|
||||
MCP Server 支持通过 LiteLLM 网关调用 LLM 模型。LLM 工具会自动路由到 `http://litellm-gateway:4000`。
|
||||
|
||||
**LLM 工具请求示例**:
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-002",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {
|
||||
"name": "llm_chat",
|
||||
"category": "llm"
|
||||
},
|
||||
"arguments": {
|
||||
"model": "openrouter-gpt-3.5-turbo",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "解释一下什么是 MCP 协议"
|
||||
}
|
||||
],
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 150
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**LLM 工具响应示例**:
|
||||
```json
|
||||
{
|
||||
"execution_id": "exec-llm-001",
|
||||
"success": true,
|
||||
"result": {
|
||||
"id": "chatcmpl-abc123",
|
||||
"object": "chat.completion",
|
||||
"created": 1677652288,
|
||||
"model": "openrouter-gpt-3.5-turbo",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"content": "MCP (Model Context Protocol) 是一个..."
|
||||
},
|
||||
"finish_reason": "stop"
|
||||
}
|
||||
],
|
||||
"usage": {
|
||||
"prompt_tokens": 15,
|
||||
"completion_tokens": 45,
|
||||
"total_tokens": 60
|
||||
}
|
||||
},
|
||||
"execution_time": 1.234,
|
||||
"cost": 0.00015
|
||||
}
|
||||
```
|
||||
|
||||
**可用的 LLM 模型**:
|
||||
- `openrouter-gpt-3.5-turbo` - GPT-3.5 Turbo（推荐）
|
||||
- `gpt-3.5-turbo` - GPT-3.5 Turbo 别名
|
||||
- `openrouter-gpt-4o-mini` - GPT-4o Mini
|
||||
- `openrouter-claude-3.5-sonnet` - Claude 3.5 Sonnet
|
||||
- `openrouter-claude-3-opus` - Claude 3 Opus
|
||||
- `test-model` - 测试模型
|
||||
|
||||
> **说明**:
|
||||
> - LLM 工具调用通过 LiteLLM 网关进行，使用配置的 API Key (`sk-taiji-mcp-server`)
|
||||
> - 执行会自动记录到数据库，并进行EU计费（1 EU = 10秒）
|
||||
> - 如果 OpenRouter 账户余额不足，会返回 402 错误
|
||||
> - 更多模型信息请参考 [Model Gateway API 文档](./API-ModelGateway服务.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,441 @@
|
||||
# Model Gateway (LiteLLM) 服务 API
|
||||
|
||||
**基础URL**: `http://localhost:4000`
|
||||
|
||||
> **说明**: Model Gateway 使用 LiteLLM 代理网关，提供统一的模型访问接口，支持 OpenAI、Anthropic、OpenRouter 等多种模型提供商。
|
||||
|
||||
> 返回 [API接口文档](./API接口文档.md)
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [健康检查](#1-健康检查)
|
||||
2. [列出可用模型](#2-列出可用模型)
|
||||
3. [Chat Completions](#3-chat-completions)
|
||||
4. [流式 Chat Completions](#4-流式-chat-completions)
|
||||
5. [API Key 管理](#5-api-key-管理)
|
||||
6. [模型路由配置](#6-模型路由配置)
|
||||
|
||||
---
|
||||
|
||||
## 认证
|
||||
|
||||
所有 API 请求都需要在请求头中包含 API Key：
|
||||
|
||||
```
|
||||
Authorization: Bearer <api_key>
|
||||
```
|
||||
|
||||
### 可用的 API Keys
|
||||
|
||||
| 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` | 高级用户 | 所有高级模型 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 健康检查
|
||||
|
||||
**GET** `/health`
|
||||
|
||||
检查 LiteLLM 网关健康状态和所有模型端点状态。
|
||||
|
||||
**请求示例**:
|
||||
```bash
|
||||
curl -X GET "http://localhost:4000/health" \
|
||||
-H "Authorization: Bearer sk-taiji-master-key"
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"healthy_endpoints": [
|
||||
{
|
||||
"model": "openrouter/openai/gpt-3.5-turbo",
|
||||
"max_tokens": 1000,
|
||||
"temperature": 0.7
|
||||
}
|
||||
],
|
||||
"unhealthy_endpoints": [
|
||||
{
|
||||
"model": "openrouter/openai/gpt-4o-mini",
|
||||
"error": "Error code: 402 - Insufficient credits"
|
||||
}
|
||||
],
|
||||
"healthy_count": 1,
|
||||
"unhealthy_count": 1
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 列出可用模型
|
||||
|
||||
**GET** `/v1/models`
|
||||
|
||||
获取所有可用的模型列表。
|
||||
|
||||
**请求示例**:
|
||||
```bash
|
||||
curl -X GET "http://localhost:4000/v1/models" \
|
||||
-H "Authorization: Bearer sk-taiji-master-key"
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": "gpt-3.5-turbo",
|
||||
"object": "model",
|
||||
"created": 1677610602,
|
||||
"owned_by": "openai"
|
||||
},
|
||||
{
|
||||
"id": "openrouter-gpt-3.5-turbo",
|
||||
"object": "model",
|
||||
"created": 1677610602,
|
||||
"owned_by": "openai"
|
||||
},
|
||||
{
|
||||
"id": "openrouter-claude-3.5-sonnet",
|
||||
"object": "model",
|
||||
"created": 1677610602,
|
||||
"owned_by": "openai"
|
||||
},
|
||||
{
|
||||
"id": "test-model",
|
||||
"object": "model",
|
||||
"created": 1677610602,
|
||||
"owned_by": "openai"
|
||||
}
|
||||
],
|
||||
"object": "list"
|
||||
}
|
||||
```
|
||||
|
||||
### 可用模型列表
|
||||
|
||||
#### 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）
|
||||
|
||||
---
|
||||
|
||||
## 3. Chat Completions
|
||||
|
||||
**POST** `/v1/chat/completions`
|
||||
|
||||
发送聊天完成请求，获取模型响应。
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"model": "openrouter-gpt-3.5-turbo",
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"content": "You are a helpful assistant."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Hello, how are you?"
|
||||
}
|
||||
],
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 150,
|
||||
"stream": false
|
||||
}
|
||||
```
|
||||
|
||||
**请求参数说明**:
|
||||
- `model` (string, 必需): 模型名称
|
||||
- `messages` (array, 必需): 消息数组，每个消息包含 `role` 和 `content`
|
||||
- `temperature` (float, 可选, 默认: 0.7): 采样温度，范围 0-2
|
||||
- `max_tokens` (integer, 可选): 最大生成 token 数
|
||||
- `stream` (boolean, 可选, 默认: false): 是否流式返回
|
||||
|
||||
**请求示例**:
|
||||
```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": "Say hello in Chinese"}
|
||||
],
|
||||
"max_tokens": 50
|
||||
}'
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl-abc123",
|
||||
"object": "chat.completion",
|
||||
"created": 1677652288,
|
||||
"model": "openrouter-gpt-3.5-turbo",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"content": "你好！"
|
||||
},
|
||||
"finish_reason": "stop"
|
||||
}
|
||||
],
|
||||
"usage": {
|
||||
"prompt_tokens": 10,
|
||||
"completion_tokens": 2,
|
||||
"total_tokens": 12
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
**402 错误 - 余额不足**:
|
||||
```json
|
||||
{
|
||||
"detail": "Error code: 402 - {'error': {'message': 'Insufficient credits. Add more using https://openrouter.ai/settings/credits', 'code': 402}}"
|
||||
}
|
||||
```
|
||||
|
||||
**401 错误 - 认证失败**:
|
||||
```json
|
||||
{
|
||||
"detail": "invalid user key"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 流式 Chat Completions
|
||||
|
||||
**POST** `/v1/chat/completions`
|
||||
|
||||
设置 `stream: true` 启用流式响应。
|
||||
|
||||
**请求示例**:
|
||||
```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": "Tell me a short story"}
|
||||
],
|
||||
"stream": true
|
||||
}'
|
||||
```
|
||||
|
||||
**响应格式** (Server-Sent Events):
|
||||
```
|
||||
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"openrouter-gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":"Once"},"finish_reason":null}]}
|
||||
|
||||
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"openrouter-gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" upon"},"finish_reason":null}]}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. API Key 管理
|
||||
|
||||
### 5.1 创建 API Key
|
||||
|
||||
**POST** `/key/generate`
|
||||
|
||||
生成新的 API Key。
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"models": ["gpt-3.5-turbo", "openrouter-gpt-3.5-turbo"],
|
||||
"max_budget": 100.0,
|
||||
"budget_duration": "1d",
|
||||
"metadata": {
|
||||
"user_id": "user_123",
|
||||
"service": "custom-service"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"key": "sk-taiji-custom-abc123",
|
||||
"models": ["gpt-3.5-turbo", "openrouter-gpt-3.5-turbo"],
|
||||
"max_budget": 100.0,
|
||||
"budget_duration": "1d"
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 获取 API Key 信息
|
||||
|
||||
**GET** `/key/info`
|
||||
|
||||
获取当前 API Key 的信息。
|
||||
|
||||
**请求示例**:
|
||||
```bash
|
||||
curl -X GET "http://localhost:4000/key/info" \
|
||||
-H "Authorization: Bearer sk-taiji-master-key"
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"key": "sk-taiji-master-key",
|
||||
"models": ["*"],
|
||||
"max_budget": 1000.0,
|
||||
"budget_duration": "30d",
|
||||
"spent_budget": 245.50,
|
||||
"remaining_budget": 754.50
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 删除 API Key
|
||||
|
||||
**DELETE** `/key/delete`
|
||||
|
||||
删除指定的 API Key。
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"keys": ["sk-taiji-custom-abc123"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 模型路由配置
|
||||
|
||||
LiteLLM 支持模型组和路由策略，配置在 `litellm.yaml` 中。
|
||||
|
||||
### 模型组
|
||||
|
||||
- `gpt-3.5-group` - GPT-3.5 模型组
|
||||
- `gpt-4-group` - GPT-4 模型组
|
||||
- `claude-group` - Claude 模型组
|
||||
- `openrouter-group` - OpenRouter 模型组
|
||||
- `fast-models` - 快速响应模型组
|
||||
- `premium-models` - 高级模型组
|
||||
|
||||
### 路由策略
|
||||
|
||||
- `least-busy` - 最少繁忙（默认）
|
||||
- `round-robin` - 轮询
|
||||
- `latency-based` - 基于延迟
|
||||
|
||||
### 使用模型组
|
||||
|
||||
在请求中使用模型组名称：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "gpt-3.5-group",
|
||||
"messages": [...]
|
||||
}
|
||||
```
|
||||
|
||||
LiteLLM 会自动从模型组中选择合适的模型。
|
||||
|
||||
---
|
||||
|
||||
## 环境变量配置
|
||||
|
||||
### OpenRouter 配置
|
||||
|
||||
在 `.env` 文件中配置：
|
||||
|
||||
```bash
|
||||
OPENROUTER_API_KEY=your_openrouter_api_key
|
||||
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
|
||||
```
|
||||
|
||||
### LiteLLM 配置
|
||||
|
||||
```bash
|
||||
LITELLM_MASTER_KEY=sk-taiji-master-key
|
||||
LITELLM_CONFIG_PATH=/app/config/litellm_simple.yaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障转移
|
||||
|
||||
LiteLLM 支持自动故障转移。当主模型不可用时，会自动切换到备用模型。
|
||||
|
||||
**配置示例** (在 `litellm.yaml` 中):
|
||||
```yaml
|
||||
error_handling:
|
||||
fallback:
|
||||
enabled: true
|
||||
fallback_models:
|
||||
"gpt-4": ["openrouter-gpt-4", "gpt-4-turbo", "claude-3-sonnet"]
|
||||
"openrouter-gpt-4": ["gpt-4", "gpt-4-turbo", "openrouter-claude-3.5-sonnet"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 监控与日志
|
||||
|
||||
### Prometheus Metrics
|
||||
|
||||
**GET** `/metrics`
|
||||
|
||||
获取 Prometheus 格式的监控指标。
|
||||
|
||||
### 日志
|
||||
|
||||
LiteLLM 日志输出到容器日志，可通过以下命令查看：
|
||||
|
||||
```bash
|
||||
docker logs taiji-litellm-gateway --tail 100
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 为什么返回 402 错误？
|
||||
|
||||
A: OpenRouter 账户余额不足。请访问 https://openrouter.ai/settings/credits 充值。
|
||||
|
||||
### Q: 如何切换模型？
|
||||
|
||||
A: 在请求的 `model` 字段中指定不同的模型名称即可。
|
||||
|
||||
### Q: 如何查看模型使用情况？
|
||||
|
||||
A: 使用 `/key/info` 端点查看当前 API Key 的预算使用情况。
|
||||
|
||||
### Q: 支持哪些模型提供商？
|
||||
|
||||
A: 当前配置支持：
|
||||
- OpenAI（通过 OpenRouter）
|
||||
- Anthropic（通过 OpenRouter）
|
||||
- 其他 OpenRouter 支持的模型
|
||||
|
||||
---
|
||||
|
||||
> 返回 [API接口文档](./API接口文档.md)
|
||||
|
||||
@@ -15,18 +15,21 @@
|
||||
4. [更新租户计费设置](#4-更新租户计费设置)
|
||||
5. [为租户充值](#5-为租户充值)
|
||||
6. [设置租户授信额度](#6-设置租户授信额度)
|
||||
7. [删除租户](#7-删除租户) ✨ **新增**
|
||||
8. [更新租户状态](#8-更新租户状态) ✨ **新增**
|
||||
9. [更新租户权限](#9-更新租户权限) ✨ **新增**
|
||||
|
||||
### 资源申请相关
|
||||
7. [申请资源](#7-申请资源)
|
||||
10. [申请资源](#10-申请资源)
|
||||
|
||||
### 计费统计相关
|
||||
8. [获取渠道计费统计](#8-获取渠道计费统计)
|
||||
11. [获取渠道计费统计](#11-获取渠道计费统计)
|
||||
|
||||
### 供应商管理相关 ✨ **新增**
|
||||
9. [获取可用供应商列表](#9-获取可用供应商列表)
|
||||
10. [申请使用供应商](#10-申请使用供应商)
|
||||
11. [获取供应商申请列表](#11-获取供应商申请列表)
|
||||
12. [获取已授权供应商列表](#12-获取已授权供应商列表)
|
||||
### 供应商管理相关
|
||||
12. [获取可用供应商列表](#12-获取可用供应商列表)
|
||||
13. [申请使用供应商](#13-申请使用供应商)
|
||||
14. [获取供应商申请列表](#14-获取供应商申请列表)
|
||||
15. [获取已授权供应商列表](#15-获取已授权供应商列表)
|
||||
|
||||
---
|
||||
|
||||
@@ -287,9 +290,158 @@ curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/credit" \
|
||||
|
||||
---
|
||||
|
||||
### 7. 删除租户 ✨ **新增**
|
||||
|
||||
**DELETE** `/api/channel/tenants/{tenant_id}`
|
||||
|
||||
删除租户（软删除，仅标记为不活跃）。如果租户还有余额，将拒绝删除。
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数 | 类型 | 必填 | 描述 |
|
||||
|------|------|------|------|
|
||||
| tenant_id | string (UUID) | 是 | 租户ID |
|
||||
|
||||
**curl示例**:
|
||||
```bash
|
||||
curl -s -X DELETE "http://localhost:8002/api/channel/tenants/${TENANT_ID}" \
|
||||
-H "Authorization: Bearer $CHANNEL_TOKEN"
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "1327fe38-40e4-46a0-9eb2-29a58675e456",
|
||||
"name": "测试租户1"
|
||||
},
|
||||
"message": "租户已删除"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应（租户有余额）**:
|
||||
```json
|
||||
{
|
||||
"detail": "租户还有余额 1500.00，请先处理余额后再删除"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. 更新租户状态 ✨ **新增**
|
||||
|
||||
**PUT** `/api/channel/tenants/{tenant_id}/status`
|
||||
|
||||
更新租户的状态。
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数 | 类型 | 必填 | 描述 |
|
||||
|------|------|------|------|
|
||||
| tenant_id | string (UUID) | 是 | 租户ID |
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"status": "suspended"
|
||||
}
|
||||
```
|
||||
|
||||
**请求参数说明**:
|
||||
- `status` (string, 必需): 状态，可选值：
|
||||
- `active`: 正常使用
|
||||
- `inactive`: 已停用（软删除）
|
||||
- `suspended`: 暂停使用（临时停用，可恢复）
|
||||
|
||||
**curl示例**:
|
||||
```bash
|
||||
curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/status" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $CHANNEL_TOKEN" \
|
||||
-d '{"status": "suspended"}'
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"tenantId": "1327fe38-40e4-46a0-9eb2-29a58675e456",
|
||||
"name": "测试租户1",
|
||||
"oldStatus": "active",
|
||||
"newStatus": "suspended"
|
||||
},
|
||||
"message": "租户状态已更新为 suspended"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. 更新租户权限 ✨ **新增**
|
||||
|
||||
**PUT** `/api/channel/tenants/{tenant_id}/permissions`
|
||||
|
||||
更新租户的权限配置。
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数 | 类型 | 必填 | 描述 |
|
||||
|------|------|------|------|
|
||||
| tenant_id | string (UUID) | 是 | 租户ID |
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"permissions": ["use:platform_agents", "read:billing", "export:data"]
|
||||
}
|
||||
```
|
||||
|
||||
**请求参数说明**:
|
||||
- `permissions` (array, 必需): 权限列表，可选值：
|
||||
- `use:platform_agents`: 使用平台Agent
|
||||
- `use:custom_agents`: 使用自定义Agent
|
||||
- `create:agents`: 创建Agent
|
||||
- `read:billing`: 查看计费信息
|
||||
- `export:data`: 导出数据
|
||||
|
||||
**curl示例**:
|
||||
```bash
|
||||
curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/permissions" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $CHANNEL_TOKEN" \
|
||||
-d '{"permissions": ["use:platform_agents", "read:billing", "export:data"]}'
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"tenantId": "1327fe38-40e4-46a0-9eb2-29a58675e456",
|
||||
"name": "测试租户1",
|
||||
"permissions": [
|
||||
"use:platform_agents",
|
||||
"read:billing",
|
||||
"export:data"
|
||||
]
|
||||
},
|
||||
"message": "租户权限已更新"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应（无效权限）**:
|
||||
```json
|
||||
{
|
||||
"detail": "无效的权限: invalid:permission"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 资源申请相关
|
||||
|
||||
### 7. 申请资源
|
||||
### 10. 申请资源
|
||||
|
||||
**POST** `/api/channel/resources/apply`
|
||||
|
||||
@@ -320,7 +472,7 @@ curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/credit" \
|
||||
|
||||
## 计费统计相关
|
||||
|
||||
### 8. 获取渠道计费统计
|
||||
### 11. 获取渠道计费统计
|
||||
|
||||
**GET** `/api/channel/billing/stats`
|
||||
|
||||
@@ -353,9 +505,9 @@ curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/credit" \
|
||||
|
||||
---
|
||||
|
||||
## 供应商管理相关 ✨ **新增**
|
||||
## 供应商管理相关
|
||||
|
||||
### 9. 获取可用供应商列表
|
||||
### 12. 获取可用供应商列表
|
||||
|
||||
**GET** `/api/channel/providers`
|
||||
|
||||
@@ -409,7 +561,7 @@ curl -s -X PUT "http://localhost:8002/api/channel/tenants/${TENANT_ID}/credit" \
|
||||
|
||||
---
|
||||
|
||||
### 10. 申请使用供应商
|
||||
### 13. 申请使用供应商
|
||||
|
||||
**POST** `/api/channel/providers/apply`
|
||||
|
||||
@@ -460,7 +612,7 @@ curl -s -X POST "http://localhost:8002/api/channel/providers/apply" \
|
||||
|
||||
---
|
||||
|
||||
### 11. 获取供应商申请列表
|
||||
### 14. 获取供应商申请列表
|
||||
|
||||
**GET** `/api/channel/providers/applications`
|
||||
|
||||
@@ -494,7 +646,7 @@ curl -s -X POST "http://localhost:8002/api/channel/providers/apply" \
|
||||
|
||||
---
|
||||
|
||||
### 12. 获取已授权供应商列表
|
||||
### 15. 获取已授权供应商列表
|
||||
|
||||
**GET** `/api/channel/providers/access`
|
||||
|
||||
@@ -47,10 +47,13 @@
|
||||
22. [更新渠道供应商授权](#22-更新渠道供应商授权)
|
||||
23. [撤销渠道供应商授权](#23-撤销渠道供应商授权)
|
||||
|
||||
### 渠道管理员相关 ✨ **新增**
|
||||
24. [获取渠道管理员列表](#24-获取渠道管理员列表)
|
||||
25. [获取可用角色列表](#25-获取可用角色列表)
|
||||
|
||||
### 前端集成补充接口
|
||||
24. [获取可用角色列表](#24-获取可用角色列表)
|
||||
25. [供应商统计（展示用）](#25-供应商统计展示用)
|
||||
26. [后台简易渠道统计](#26-后台简易渠道统计)
|
||||
26. [供应商统计（展示用）](#26-供应商统计展示用)
|
||||
27. [后台简易渠道统计](#27-后台简易渠道统计)
|
||||
|
||||
---
|
||||
|
||||
@@ -865,26 +868,109 @@ curl -s -X PUT "http://localhost:8002/api/admin/providers/access/access-uuid-1?s
|
||||
|
||||
---
|
||||
|
||||
## 前端集成补充接口
|
||||
## 渠道管理员相关 ✨ **新增**
|
||||
|
||||
为了保证前端在轻量集成场景下可以持续迭代，`services/mcp-server/app/routes/frontend_integration.py` 还暴露了一组直接以 `/api` 前缀对外的超级管理员辅助接口，数据保存在内存 store 中，适合 UI 预览与模拟，调用仍需超级管理员身份。
|
||||
### 24. 获取渠道管理员列表
|
||||
|
||||
### 24. 获取可用角色列表
|
||||
**GET** `/api/admin/channels/{channel_id}/admins`
|
||||
|
||||
**GET** `/api/admin/roles`
|
||||
获取指定渠道下的所有管理员用户。
|
||||
|
||||
返回当前前端可选择的管理员角色列表：
|
||||
**路径参数**:
|
||||
|
||||
| 参数 | 类型 | 必填 | 描述 |
|
||||
|------|------|------|------|
|
||||
| channel_id | string (UUID) | 是 | 渠道ID |
|
||||
|
||||
**curl示例**:
|
||||
```bash
|
||||
curl -s "http://localhost:8002/api/admin/channels/${CHANNEL_ID}/admins" \
|
||||
-H "Authorization: Bearer $ADMIN_TOKEN"
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"items": ["billing_admin", "operations_admin", "super_admin"]
|
||||
"success": true,
|
||||
"data": {
|
||||
"channelId": "b5421325-80bd-40ba-8ce0-077d7004b5ae",
|
||||
"channelName": "测试渠道A",
|
||||
"admins": [
|
||||
{
|
||||
"id": "admin-uuid-1",
|
||||
"name": "渠道管理员张三",
|
||||
"email": "zhangsan@channel-a.com",
|
||||
"role": "channel_admin",
|
||||
"status": "active",
|
||||
"createdAt": "2025-12-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 25. 供应商统计（展示用）
|
||||
### 25. 获取可用角色列表
|
||||
|
||||
**GET** `/api/admin/roles`
|
||||
|
||||
返回系统中所有可用的角色类型及其详细信息。
|
||||
|
||||
**curl示例**:
|
||||
```bash
|
||||
curl -s "http://localhost:8002/api/admin/roles" \
|
||||
-H "Authorization: Bearer $ADMIN_TOKEN"
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"roles": [
|
||||
{
|
||||
"id": "super_admin",
|
||||
"name": "超级管理员",
|
||||
"description": "拥有系统所有权限",
|
||||
"permissions": ["*"]
|
||||
},
|
||||
{
|
||||
"id": "billing_admin",
|
||||
"name": "计费管理员",
|
||||
"description": "完整写入权限，可创建渠道、管理租户、计费操作",
|
||||
"permissions": ["read:*", "write:channels", "write:tenants", "write:billing"]
|
||||
},
|
||||
{
|
||||
"id": "operations_admin",
|
||||
"name": "运维管理员",
|
||||
"description": "只读权限，仅查看和监控",
|
||||
"permissions": ["read:*"]
|
||||
},
|
||||
{
|
||||
"id": "channel_admin",
|
||||
"name": "渠道管理员",
|
||||
"description": "渠道内部管理权限",
|
||||
"permissions": ["read:channel", "write:tenants", "read:billing"]
|
||||
},
|
||||
{
|
||||
"id": "user",
|
||||
"name": "普通用户",
|
||||
"description": "标准用户权限",
|
||||
"permissions": ["read:self", "use:agents"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 前端集成补充接口
|
||||
|
||||
为了保证前端在轻量集成场景下可以持续迭代，`services/mcp-server/app/routes/frontend_integration.py` 还暴露了一组直接以 `/api` 前缀对外的超级管理员辅助接口，数据保存在内存 store 中，适合 UI 预览与模拟，调用仍需超级管理员身份。
|
||||
|
||||
### 26. 供应商统计（展示用）
|
||||
|
||||
**GET** `/api/admin/providers/stats`
|
||||
|
||||
@@ -907,7 +993,7 @@ curl -s -X PUT "http://localhost:8002/api/admin/providers/access/access-uuid-1?s
|
||||
|
||||
---
|
||||
|
||||
### 26. 后台简易渠道统计
|
||||
### 27. 后台简易渠道统计
|
||||
|
||||
**GET** `/api/admin/channels/backend/stats`
|
||||
|
||||
@@ -0,0 +1,242 @@
|
||||
# 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](./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 文档。
|
||||
|
||||
@@ -1,330 +0,0 @@
|
||||
# taiji-AI-PAD API 接口文档
|
||||
|
||||
**版本**: v2.7.0
|
||||
**更新时间**: 2025年12月26日
|
||||
**基础URL**:
|
||||
- Data Ingestion 服务: `http://localhost:8001` (容器内8000→主机8001)
|
||||
- MCP Server 服务: `http://localhost:8002` (容器内8000→主机8002)
|
||||
- API Gateway: `http://localhost:80`
|
||||
- LiteLLM Gateway: `http://localhost:4000`
|
||||
|
||||
> **重要说明**: 本文档基于实际代码生成并经过完整API测试验证。所有端点均已实现并确认可用。
|
||||
|
||||
---
|
||||
|
||||
## 📋 文档索引
|
||||
|
||||
本文档已拆分为多个模块文档，便于维护和查阅：
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [Data Ingestion 服务 API](./API-DataIngestion服务.md) | 数据摄入服务相关接口 |
|
||||
| [MCP Server 服务 API](./API-MCPServer服务.md) | MCP服务器、监控、WebSocket接口 |
|
||||
| [认证模块 API](./API-认证模块.md) | 登录、登出、Token管理、API密钥 |
|
||||
| [用户侧平台 API](./API-用户侧平台.md) | 租户用户使用的接口 |
|
||||
| [渠道合作伙伴 API](./API-渠道合作伙伴.md) | 渠道管理员使用的接口 |
|
||||
| [超级管理员 API](./API-超级管理员.md) | 平台管理员使用的接口 |
|
||||
| [计费与资源管理 API](./API-计费与资源管理.md) | 配额、资源、事件、追踪、审计接口 |
|
||||
| [供应商管理 API](./API-供应商管理.md) | 模型供应商管理接口 |
|
||||
| [前端集成与测试](./API-前端集成与测试.md) | 集成示例、测试流程、预置账号 |
|
||||
|
||||
---
|
||||
|
||||
## 通用响应格式
|
||||
|
||||
所有API端点（除非另有说明）返回以下格式：
|
||||
|
||||
**成功响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {},
|
||||
"message": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应（FastAPI默认）**:
|
||||
```json
|
||||
{
|
||||
"detail": "错误描述"
|
||||
}
|
||||
```
|
||||
|
||||
**标准包装响应（SuccessResponse）**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "操作成功",
|
||||
"data": {},
|
||||
"timestamp": "2025-12-25T05:10:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误码说明
|
||||
|
||||
| HTTP 状态码 | 错误码 | 说明 |
|
||||
|------------|--------|------|
|
||||
| 400 | `BAD_REQUEST` | 请求参数错误 |
|
||||
| 401 | `UNAUTHORIZED` | 未授权 |
|
||||
| 403 | `FORBIDDEN` | 禁止访问 |
|
||||
| 404 | `NOT_FOUND` | 资源不存在 |
|
||||
| 500 | `INTERNAL_ERROR` | 服务器内部错误 |
|
||||
| 503 | `SERVICE_UNAVAILABLE` | 服务不可用 |
|
||||
|
||||
---
|
||||
|
||||
## 认证说明
|
||||
|
||||
### 认证方式
|
||||
|
||||
系统支持两种认证方式：
|
||||
|
||||
1. **JWT Bearer Token认证**
|
||||
- 通过 `/api/auth/login` 登录获取token
|
||||
- 在请求头中携带: `Authorization: Bearer <token>`
|
||||
- Token有效期: 24小时
|
||||
|
||||
2. **API Key认证**
|
||||
- 通过 `/api/auth/keys/info` 获取API密钥
|
||||
- 在请求头中携带: `X-API-Key: <api-key>`
|
||||
- API Key格式: `sk-xxxx...`
|
||||
|
||||
### 豁免路径
|
||||
|
||||
以下路径无需认证即可访问：
|
||||
- `/health` - 健康检查
|
||||
- `/metrics` - Prometheus指标
|
||||
- `/docs` - Swagger文档
|
||||
- `/redoc` - ReDoc文档
|
||||
- `/openapi.json` - OpenAPI规范
|
||||
- `/api/auth/login` - 登录接口
|
||||
|
||||
### 权限角色
|
||||
|
||||
系统支持以下角色：
|
||||
|
||||
| 角色 | 说明 | 登录role参数 |
|
||||
|------|------|-------------|
|
||||
| super_admin | 超级管理员 | super_admin |
|
||||
| billing_admin | 计费管理员 | billing_admin |
|
||||
| operations_admin | 运维管理员 | operations_admin |
|
||||
| channel_admin | 渠道管理员 | channel |
|
||||
| provider_admin | 供应商管理员 | provider |
|
||||
| user | 租户用户 | user |
|
||||
|
||||
### 权限矩阵
|
||||
|
||||
| 操作 | super_admin | billing_admin | operations_admin | channel_admin |
|
||||
|------|:-----------:|:-------------:|:----------------:|:-------------:|
|
||||
| **管理员管理** |
|
||||
| 查看管理员列表 | ✅ | ❌ | ❌ | ❌ |
|
||||
| 创建管理员 | ✅ | ❌ | ❌ | ❌ |
|
||||
| 删除管理员 | ✅ | ❌ | ❌ | ❌ |
|
||||
| **渠道管理** |
|
||||
| 查看渠道列表 | ✅ | ✅ | ✅ | ❌ |
|
||||
| 创建渠道 | ✅ | ✅ | ❌ | ❌ |
|
||||
| 编辑渠道 | ✅ | ✅ | ❌ | ❌ |
|
||||
| 删除渠道 | ✅ | ✅ | ❌ | ❌ |
|
||||
| **资源管理** |
|
||||
| 查看资源 | ✅ | ✅ | ✅ | ✅ |
|
||||
| 分配资源 | ✅ | ✅ | ❌ | ✅ |
|
||||
| 配置Agent | ✅ | ✅ | ❌ | ❌ |
|
||||
| **计费管理** |
|
||||
| 查看计费记录 | ✅ | ✅ | ✅ | ✅ |
|
||||
| 执行充值 | ✅ | ✅ | ❌ | ✅ |
|
||||
| **监控** |
|
||||
| 查看系统监控 | ✅ | ✅ | ✅ | ❌ |
|
||||
| 查看Agent状态 | ✅ | ✅ | ✅ | ❌ |
|
||||
| **申请审批** |
|
||||
| 查看申请 | ✅ | ✅ | ✅ | ❌ |
|
||||
| 审批申请 | ✅ | ✅ | ❌ | ❌ |
|
||||
|
||||
> **权限层级**: super_admin > billing_admin > operations_admin > channel_admin > user
|
||||
|
||||
### 示例
|
||||
|
||||
**使用JWT Token**:
|
||||
```bash
|
||||
# 1. 登录获取token
|
||||
TOKEN=$(curl -s -X POST "http://localhost:8002/api/auth/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"admin@taiji-ai.com","password":"admin123","role":"user"}' \
|
||||
| jq -r '.data.token')
|
||||
|
||||
# 2. 使用token访问API
|
||||
curl -X GET "http://localhost:8002/api/user/dashboard/stats" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
**使用API Key**:
|
||||
```bash
|
||||
curl -X GET "http://localhost:8002/api/user/dashboard/stats" \
|
||||
-H "X-API-Key: sk-aBcD1234EfGh5678IjKl9012MnOp3456"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 业务规则
|
||||
|
||||
### EU计算规则
|
||||
|
||||
**EU (Execution Unit)** 是系统的基本计费单位：
|
||||
|
||||
- **1 EU = 10秒调用时间**
|
||||
- **不足10秒按1 EU计算**
|
||||
- **计算公式**: `EU = CEILING(duration_seconds / 10)`
|
||||
|
||||
**示例**:
|
||||
```
|
||||
5秒 -> 1 EU
|
||||
10秒 -> 1 EU
|
||||
15秒 -> 2 EU
|
||||
60秒 -> 6 EU
|
||||
125秒 -> 13 EU
|
||||
```
|
||||
|
||||
### 计费价格
|
||||
|
||||
EU单价根据用户订阅等级自动确定：
|
||||
|
||||
| 档位 | 订阅等级 | EU 单价 | 核心定位 |
|
||||
|------|---------|---------|----------|
|
||||
| **入门级（Starter）** | `free` / `starter` | **$0.015 / EU** | 拉新、试用、轻 Agent |
|
||||
| **专业级（Pro）** | `pro` | **$0.02 / EU** | 主力商业用户 |
|
||||
| **企业级（Enterprise）** | `enterprise` | **$0.03 / EU** | 高复杂度 / 高 SLA |
|
||||
|
||||
**价格计算示例**：
|
||||
```
|
||||
用户订阅等级: pro
|
||||
调用时长: 45秒
|
||||
EU数量: CEILING(45 / 10) = 5 EU
|
||||
费用: 5 EU × $0.02 = $0.10
|
||||
```
|
||||
|
||||
### 余额与授信
|
||||
|
||||
**可用额度计算**:
|
||||
```
|
||||
可用额度 = 账户余额 + 授信额度
|
||||
```
|
||||
|
||||
**消费规则**:
|
||||
1. 优先扣除账户余额
|
||||
2. 余额不足时使用授信额度
|
||||
3. 授信额度用完后服务暂停
|
||||
|
||||
---
|
||||
|
||||
## 交互式 API 文档
|
||||
|
||||
### Swagger UI
|
||||
|
||||
- Data Ingestion: `http://localhost:8001/docs`
|
||||
- MCP Server: `http://localhost:8002/docs`
|
||||
|
||||
### ReDoc
|
||||
|
||||
- Data Ingestion: `http://localhost:8001/redoc`
|
||||
- MCP Server: `http://localhost:8002/redoc`
|
||||
|
||||
### OpenAPI JSON
|
||||
|
||||
- Data Ingestion: `http://localhost:8001/openapi.json`
|
||||
- MCP Server: `http://localhost:8002/openapi.json`
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **端口映射**:
|
||||
- Data Ingestion: 容器8000 → 主机8001
|
||||
- MCP Server: 容器8000 → 主机8002
|
||||
2. **CORS**: 当前配置允许所有来源，生产环境需要限制
|
||||
3. **认证**: `/api/*` 路径需要认证（除login等豁免路径）
|
||||
4. **限流**: 建议在生产环境添加限流保护
|
||||
5. **超时设置**: 建议设置合理的请求超时时间
|
||||
|
||||
---
|
||||
|
||||
## 更新日志
|
||||
|
||||
- **v2.7.0** (2025-12-26): **新增供应商授权管理系统** ✨
|
||||
- ✅ 新增渠道供应商授权模型 `ChannelProviderAccess`（记录渠道可使用的供应商）
|
||||
- ✅ 新增供应商申请模型 `ProviderApplication`（渠道申请使用供应商）
|
||||
- ✅ 渠道管理员API：
|
||||
- GET `/api/channel/providers` - 获取可用供应商列表（含授权状态）
|
||||
- POST `/api/channel/providers/apply` - 申请使用供应商
|
||||
- GET `/api/channel/providers/applications` - 获取申请列表
|
||||
- GET `/api/channel/providers/access` - 获取已授权供应商列表
|
||||
- ✅ 超级管理员API：
|
||||
- GET `/api/admin/providers/applications` - 获取所有供应商申请
|
||||
- PUT `/api/admin/providers/applications/{id}/review` - 审批供应商申请
|
||||
- GET `/api/admin/providers/access` - 获取所有渠道授权
|
||||
- PUT `/api/admin/providers/access/{id}` - 更新授权配置
|
||||
- DELETE `/api/admin/providers/access/{id}` - 撤销授权
|
||||
- ✅ 批准申请后自动创建渠道供应商授权记录
|
||||
- **v2.6.0** (2025-12-26): **新增计费与资源管理API**
|
||||
- ✅ 新增配额管理API（用户配额、渠道配额、配额预警）
|
||||
- ✅ 新增资源监控API（平台概览、用户资源、使用趋势、Agent统计）
|
||||
- ✅ 新增事件管理API（待处理事件、重试失败、事件统计）
|
||||
- ✅ 新增追踪管理API（执行追踪详情、追踪查询、追踪统计）
|
||||
- ✅ 新增审计日志API（日志查询、汇总统计、用户活动历史）
|
||||
- ✅ 新增供应商健康检查API（健康状态、健康详情、手动检查）
|
||||
- ✅ 新增模型定价管理API（定价列表、创建/更新定价、成本计算）
|
||||
- ✅ 新增数据模型：TokenBlacklist、ResourceUsage、QuotaAlert、ModelPricing、ProviderHealthCheck、AgentTrace、BillingEvent
|
||||
- ✅ 增强JWT认证：登出时将Token加入黑名单
|
||||
- **v2.5.0** (2025-12-26): **权限系统重构**
|
||||
- ✅ 重新设计权限系统，区分计费管理员和运维管理员
|
||||
- ✅ billing_admin（计费管理员）：完整写入权限（创建渠道、管理租户、计费操作、审批申请）
|
||||
- ✅ operations_admin（运维管理员）：只读权限（仅查看和监控）
|
||||
- ✅ 更新权限矩阵表格
|
||||
- ✅ 更新接口权限验证逻辑
|
||||
- ✅ 更新预置测试账号说明
|
||||
- **v2.4.0** (2025-12-26): **新增管理员管理接口**
|
||||
- ✅ 添加 GET /api/admin/admins - 获取管理员列表（仅超级管理员可用）
|
||||
- ✅ 添加 POST /api/admin/admins/create - 创建管理员（支持billing_admin/operations_admin角色）
|
||||
- ✅ 添加 DELETE /api/admin/admins/{admin_id} - 删除管理员（软删除）
|
||||
- ✅ 区分 super_admin（超级管理员）权限
|
||||
- ✅ 更新超级管理员API接口编号
|
||||
- **v2.3.0** (2025-12-25): **新增管理接口**
|
||||
- ✅ 添加 PUT /api/admin/channels/{channel_id} - 更新渠道信息
|
||||
- ✅ 添加 DELETE /api/admin/channels/{channel_id} - 删除渠道（软删除）
|
||||
- ✅ 添加 DELETE /api/admin/resources/agents/{agent_id} - 删除Agent资源（软删除）
|
||||
- ✅ 添加 PUT /api/admin/resources/agents/{agent_id}/config - 更新Agent资源配置
|
||||
- ✅ 更新超级管理员API接口编号
|
||||
- **v2.2.0** (2025-12-25): **完整API测试验证**
|
||||
- ✅ 添加完整API测试流程示例
|
||||
- ✅ 更新所有curl命令示例
|
||||
- ✅ 添加预置测试账号说明
|
||||
- ✅ 完善请求参数说明
|
||||
- ✅ 添加渠道登录响应示例
|
||||
- ✅ 验证所有接口可用性
|
||||
- **v2.1.0** (2025-12-25): **基于实际代码重写**
|
||||
- ✅ 根据实际代码完全重写文档
|
||||
- ✅ 修正所有端口信息（8001, 8002）
|
||||
- ✅ 更新认证机制说明
|
||||
- ✅ 完善实际实现的端点文档
|
||||
- ✅ 移除未实现的占位接口
|
||||
- ✅ 添加实际响应示例
|
||||
- ✅ 更新业务规则和认证说明
|
||||
- ✅ 添加前端集成示例
|
||||
- **v2.0.0** (2025-12-25): 基于需求文档的完整实现
|
||||
- **v1.3.0** (2025-12-24): 增加占位API文档
|
||||
- **v1.2.0** (2025-12-22): 初始版本
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- 完整需求文档: [BACKEND_REQUIREMENTS.md](../../BACKEND_REQUIREMENTS.md)
|
||||
- 实现总结: [BACKEND_IMPLEMENTATION_SUMMARY.md](../../BACKEND_IMPLEMENTATION_SUMMARY.md)
|
||||
- 部署指南: [services/mcp-server/DEPLOY_AZURE.md](../../services/mcp-server/DEPLOY_AZURE.md)
|
||||
- 快速开始: [QUICK_START.md](../../QUICK_START.md)
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v2.7.0
|
||||
**最后更新**: 2025年12月26日
|
||||
**维护者**: taiji-AI-PAD 项目组
|
||||
+8
-57
@@ -1,30 +1,10 @@
|
||||
# Docker Compose 会自动从 .env 文件读取环境变量
|
||||
# 所有 ${VAR} 形式的变量都会从 .env 文件中获取
|
||||
#
|
||||
# 注意：PostgreSQL 和 Redis 使用 Azure 云服务，不在本地部署
|
||||
# DATABASE_URL 和 REDIS_URL 通过 .env 文件配置
|
||||
|
||||
services:
|
||||
# PostgreSQL数据库
|
||||
postgres:
|
||||
image: postgres:15-alpine
|
||||
container_name: taiji-postgres
|
||||
ports:
|
||||
- "5432:5432"
|
||||
environment:
|
||||
- POSTGRES_USER=taiji_user
|
||||
- POSTGRES_PASSWORD=taiji_pass
|
||||
- POSTGRES_DB=taiji_db
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
- ./scripts/init.sql:/docker-entrypoint-initdb.d/01-init.sql
|
||||
- ./scripts/init_users.sql:/docker-entrypoint-initdb.d/02-init_users.sql
|
||||
networks:
|
||||
- taiji-network
|
||||
restart: unless-stopped
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U taiji_user -d taiji_db"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
# NATS消息队列
|
||||
nats:
|
||||
image: nats:2.10-alpine
|
||||
@@ -40,24 +20,6 @@ services:
|
||||
- taiji-network
|
||||
restart: unless-stopped
|
||||
|
||||
# Redis缓存
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
container_name: taiji-redis
|
||||
ports:
|
||||
- "6379:6379"
|
||||
volumes:
|
||||
- redis_data:/data
|
||||
command: redis-server --appendonly yes
|
||||
networks:
|
||||
- taiji-network
|
||||
restart: unless-stopped
|
||||
healthcheck:
|
||||
test: ["CMD", "redis-cli", "ping"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
# LiteLLM网关服务
|
||||
litellm-gateway:
|
||||
build:
|
||||
@@ -103,8 +65,6 @@ services:
|
||||
- ./services/data-ingestion:/app
|
||||
- ./logs:/app/logs
|
||||
depends_on:
|
||||
- postgres
|
||||
- redis
|
||||
- nats
|
||||
networks:
|
||||
- taiji-network
|
||||
@@ -128,8 +88,6 @@ services:
|
||||
- ./services/mcp-server:/app
|
||||
- ./logs:/app/logs
|
||||
depends_on:
|
||||
- postgres
|
||||
- redis
|
||||
- nats
|
||||
- litellm-gateway
|
||||
networks:
|
||||
@@ -145,15 +103,13 @@ services:
|
||||
# ports:
|
||||
# - "8003:8080"
|
||||
# environment:
|
||||
# - DATABASE_URL=postgresql://taiji_user:taiji_pass@postgres:5432/taiji_db
|
||||
# - REDIS_URL=redis://redis:6379
|
||||
# - DATABASE_URL=${DATABASE_URL}
|
||||
# - REDIS_URL=${REDIS_URL}
|
||||
# - NATS_URL=nats://nats:4222
|
||||
# volumes:
|
||||
# - ./services/agent-registry:/app
|
||||
# - ./logs:/app/logs
|
||||
# depends_on:
|
||||
# - postgres
|
||||
# - redis
|
||||
# - nats
|
||||
# networks:
|
||||
# - taiji-network
|
||||
@@ -168,15 +124,13 @@ services:
|
||||
# ports:
|
||||
# - "8004:8080"
|
||||
# environment:
|
||||
# - DATABASE_URL=postgresql://taiji_user:taiji_pass@postgres:5432/taiji_db
|
||||
# - REDIS_URL=redis://redis:6379
|
||||
# - NATS_URL=nats://nats:6379
|
||||
# - DATABASE_URL=${DATABASE_URL}
|
||||
# - REDIS_URL=${REDIS_URL}
|
||||
# - NATS_URL=nats://nats:4222
|
||||
# volumes:
|
||||
# - ./services/billing-engine:/app
|
||||
# - ./logs:/app/logs
|
||||
# depends_on:
|
||||
# - postgres
|
||||
# - redis
|
||||
# - nats
|
||||
# networks:
|
||||
# - taiji-network
|
||||
@@ -261,9 +215,6 @@ networks:
|
||||
- subnet: 172.20.0.0/16
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
redis_data:
|
||||
nats_data:
|
||||
prometheus_data:
|
||||
grafana_data:
|
||||
|
||||
|
||||
@@ -0,0 +1,220 @@
|
||||
# MCP Server 完善说明
|
||||
|
||||
根据 `Docs/前后端调试接口说明/API-MCPServer服务.md` 文档，已对 MCP Server 进行完善并创建完整示例。
|
||||
|
||||
## ✅ 完成的工作
|
||||
|
||||
### 1. 代码审查与验证
|
||||
- ✅ 验证了 Agent 管理 API 的完整实现
|
||||
- ✅ 验证了监控 API 的完整实现
|
||||
- ✅ 验证了 WebSocket 实时通信功能
|
||||
- ✅ 确认了 16 个内置函数工具正常工作
|
||||
- ✅ 验证了 MCP 协议处理器的实现
|
||||
|
||||
### 2. 示例代码创建
|
||||
|
||||
在 `examples/` 目录下创建了 10 个文件：
|
||||
|
||||
#### Python 示例 (6个)
|
||||
1. **01_basic_usage.py** - 基础 API 使用
|
||||
2. **02_agent_management.py** - Agent 完整生命周期管理
|
||||
3. **03_function_tools.py** - 所有函数工具演示
|
||||
4. **04_monitoring.py** - 监控 API 完整示例
|
||||
5. **05_websocket_client.py** - WebSocket 实时通信
|
||||
6. **test_all_functions.py** - 自动化测试工具
|
||||
|
||||
#### Shell 脚本 (1个)
|
||||
7. **curl_examples.sh** - 所有 API 的 cURL 示例
|
||||
|
||||
#### 文档 (3个)
|
||||
8. **README.md** - 示例项目总览
|
||||
9. **EXAMPLES_README.md** - 详细使用指南（含常见问题、性能优化）
|
||||
10. **requirements.txt** - Python 依赖
|
||||
|
||||
### 3. 文档创建
|
||||
|
||||
在 `mcp-server/` 根目录创建：
|
||||
|
||||
1. **README.md** - 项目总览和快速开始
|
||||
2. **QUICKSTART.md** - 完整的快速入门指南
|
||||
3. **IMPLEMENTATION_SUMMARY.md** - 详细的实现总结
|
||||
|
||||
## 📁 新增文件结构
|
||||
|
||||
```
|
||||
services/mcp-server/
|
||||
├── examples/ ← 新增示例目录
|
||||
│ ├── 01_basic_usage.py ← 基础示例
|
||||
│ ├── 02_agent_management.py ← Agent 管理
|
||||
│ ├── 03_function_tools.py ← 函数工具
|
||||
│ ├── 04_monitoring.py ← 监控 API
|
||||
│ ├── 05_websocket_client.py ← WebSocket
|
||||
│ ├── test_all_functions.py ← 自动化测试
|
||||
│ ├── curl_examples.sh ← Shell 示例
|
||||
│ ├── README.md ← 示例总览
|
||||
│ ├── EXAMPLES_README.md ← 详细指南
|
||||
│ └── requirements.txt ← 依赖文件
|
||||
├── README.md ← 更新/新增
|
||||
├── QUICKSTART.md ← 新增
|
||||
└── IMPLEMENTATION_SUMMARY.md ← 新增
|
||||
```
|
||||
|
||||
## 🎯 示例覆盖的功能
|
||||
|
||||
### REST API
|
||||
- ✅ 健康检查
|
||||
- ✅ Agent CRUD 操作
|
||||
- ✅ 工具执行（所有 16 个内置函数）
|
||||
- ✅ 系统监控指标
|
||||
- ✅ 服务统计
|
||||
- ✅ 性能趋势
|
||||
- ✅ 告警管理
|
||||
- ✅ 监控仪表盘
|
||||
|
||||
### WebSocket
|
||||
- ✅ 连接建立
|
||||
- ✅ Ping/Pong 心跳
|
||||
- ✅ 实时工具执行
|
||||
- ✅ 异步消息处理
|
||||
|
||||
### 所有内置函数
|
||||
- ✅ 数学函数 (5个)
|
||||
- ✅ 字符串函数 (4个)
|
||||
- ✅ 日期时间 (1个)
|
||||
- ✅ JSON 处理 (2个)
|
||||
- ✅ 哈希函数 (2个)
|
||||
- ✅ Base64 编解码 (2个)
|
||||
|
||||
## 🚀 如何使用
|
||||
|
||||
### 1. 查看快速入门
|
||||
|
||||
```bash
|
||||
cat services/mcp-server/QUICKSTART.md
|
||||
```
|
||||
|
||||
### 2. 安装示例依赖
|
||||
|
||||
```bash
|
||||
cd services/mcp-server/examples
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 3. 运行示例
|
||||
|
||||
```bash
|
||||
# Python 示例
|
||||
python 01_basic_usage.py
|
||||
python 02_agent_management.py
|
||||
python 03_function_tools.py
|
||||
python 04_monitoring.py
|
||||
python 05_websocket_client.py
|
||||
python test_all_functions.py
|
||||
|
||||
# Shell 示例
|
||||
bash curl_examples.sh
|
||||
```
|
||||
|
||||
## 📊 API 实现对照表
|
||||
|
||||
| API 端点 | 方法 | 实现状态 | 示例文件 |
|
||||
|---------|------|---------|---------|
|
||||
| `/health` | GET | ✅ | 01, curl |
|
||||
| `/agents` | POST | ✅ | 01, 02, 03, curl |
|
||||
| `/agents` | GET | ✅ | 01, 02, curl |
|
||||
| `/agents/{id}` | GET | ✅ | 01, 02, curl |
|
||||
| `/agents/{id}/execute` | POST | ✅ | 02, 03, curl |
|
||||
| `/tools` | GET | ✅ | 01, curl |
|
||||
| `/metrics` | GET | ✅ | curl |
|
||||
| `/api/v1/monitoring/metrics` | GET | ✅ | 04, curl |
|
||||
| `/api/v1/monitoring/stats` | GET | ✅ | 04, curl |
|
||||
| `/api/v1/monitoring/trends` | GET | ✅ | 04, curl |
|
||||
| `/api/v1/monitoring/alerts` | GET | ✅ | 04, curl |
|
||||
| `/api/v1/monitoring/dashboard` | GET | ✅ | 04, curl |
|
||||
| `/ws/{agent}` | WS | ✅ | 05 |
|
||||
|
||||
## 🎓 文档说明
|
||||
|
||||
### README.md
|
||||
- 项目概述
|
||||
- 快速开始
|
||||
- 功能特性
|
||||
- API 端点列表
|
||||
- 架构说明
|
||||
|
||||
### QUICKSTART.md
|
||||
- 5 分钟快速上手
|
||||
- 基础概念讲解
|
||||
- 示例代码
|
||||
- 常见场景
|
||||
- 故障排查
|
||||
|
||||
### IMPLEMENTATION_SUMMARY.md
|
||||
- 详细的实现总结
|
||||
- 代码检查结果
|
||||
- API 对照表
|
||||
- 后续改进建议
|
||||
|
||||
### examples/README.md
|
||||
- 示例项目总览
|
||||
- 运行方法
|
||||
- 文件说明
|
||||
|
||||
### examples/EXAMPLES_README.md
|
||||
- 详细使用指南
|
||||
- 常见问题解答
|
||||
- 性能优化建议
|
||||
- 调试技巧
|
||||
|
||||
## 🔍 关键特性
|
||||
|
||||
### 代码质量
|
||||
- ✅ 完整的错误处理
|
||||
- ✅ 类型注解
|
||||
- ✅ 文档字符串
|
||||
- ✅ 日志记录
|
||||
|
||||
### 示例质量
|
||||
- ✅ 清晰的注释
|
||||
- ✅ 实用的场景
|
||||
- ✅ 完整的错误处理
|
||||
- ✅ 可直接运行
|
||||
|
||||
### 文档质量
|
||||
- ✅ 中文说明
|
||||
- ✅ 代码示例
|
||||
- ✅ 问题排查
|
||||
- ✅ 最佳实践
|
||||
|
||||
## 📝 下一步建议
|
||||
|
||||
### 短期
|
||||
1. 运行示例验证功能
|
||||
2. 根据实际需求调整示例
|
||||
3. 补充项目特定的文档
|
||||
|
||||
### 中期
|
||||
1. 添加更多实际场景示例
|
||||
2. 完善单元测试
|
||||
3. 添加性能测试
|
||||
|
||||
### 长期
|
||||
1. 创建交互式文档（Swagger UI）
|
||||
2. 集成到 CI/CD
|
||||
3. 添加 API 版本控制
|
||||
|
||||
## ✨ 总结
|
||||
|
||||
已完成：
|
||||
- ✅ 代码验证
|
||||
- ✅ 示例创建（10个文件）
|
||||
- ✅ 文档编写（3个文档）
|
||||
- ✅ 所有 API 覆盖
|
||||
- ✅ 所有函数工具测试
|
||||
|
||||
所有文件都可直接使用，无需额外修改。
|
||||
|
||||
---
|
||||
|
||||
**创建时间**: 2025-12-27
|
||||
**相关文档**: `Docs/前后端调试接口说明/API-MCPServer服务.md`
|
||||
@@ -0,0 +1,330 @@
|
||||
# MCP Server 完善总结
|
||||
|
||||
本文档总结了根据 API 文档对 MCP Server 服务的完善工作。
|
||||
|
||||
## 完成的工作
|
||||
|
||||
### 1. 代码检查与验证 ✓
|
||||
|
||||
检查了以下核心模块的实现：
|
||||
|
||||
#### ✅ Agent 管理 ([app/routes/agents.py](app/routes/agents.py))
|
||||
- ✓ POST `/agents` - 创建 Agent
|
||||
- ✓ GET `/agents` - 获取 Agent 列表（支持分页）
|
||||
- ✓ GET `/agents/{agent_id}` - 获取特定 Agent
|
||||
- ✓ POST `/agents/{agent_id}/execute` - 执行 Agent 工具
|
||||
- ✓ Redis 缓存支持（1小时）
|
||||
- ✓ NATS 事件发布
|
||||
- ✓ 会话管理集成
|
||||
- ✓ EU 计费和余额管理
|
||||
|
||||
#### ✅ 监控 API ([app/routes/monitoring.py](app/routes/monitoring.py))
|
||||
- ✓ GET `/api/v1/monitoring/metrics` - 系统性能指标
|
||||
- ✓ GET `/api/v1/monitoring/stats` - 服务统计信息
|
||||
- ✓ GET `/api/v1/monitoring/trends` - 性能趋势数据
|
||||
- ✓ GET `/api/v1/monitoring/alerts` - 系统告警
|
||||
- ✓ GET `/api/v1/monitoring/dashboard` - 监控仪表盘聚合
|
||||
|
||||
#### ✅ WebSocket API ([app/routes/websocket.py](app/routes/websocket.py))
|
||||
- ✓ WebSocket `/ws/{agent_name_or_id}` - MCP Protocol WebSocket
|
||||
- ✓ 连接池管理（最大1000连接）
|
||||
- ✓ 心跳机制（30秒间隔）
|
||||
- ✓ 消息队列（每个连接最多100条）
|
||||
- ✓ 自动超时清理（90秒无心跳）
|
||||
- ✓ Ping/Pong 支持
|
||||
- ✓ 实时工具执行
|
||||
|
||||
#### ✅ 函数注册表 ([function_registry.py](function_registry.py))
|
||||
内置函数工具：
|
||||
|
||||
**数学函数**
|
||||
- `math_add` - 加法
|
||||
- `math_subtract` - 减法
|
||||
- `math_multiply` - 乘法
|
||||
- `math_divide` - 除法
|
||||
- `math_power` - 幂运算
|
||||
|
||||
**字符串函数**
|
||||
- `string_upper` - 转大写
|
||||
- `string_lower` - 转小写
|
||||
- `string_length` - 字符串长度
|
||||
- `string_replace` - 替换子串
|
||||
|
||||
**日期时间**
|
||||
- `datetime_now` - 获取当前UTC时间
|
||||
|
||||
**JSON**
|
||||
- `json_parse` - 解析JSON
|
||||
- `json_stringify` - 序列化对象
|
||||
|
||||
**哈希**
|
||||
- `hash_md5` - MD5哈希
|
||||
- `hash_sha256` - SHA256哈希
|
||||
|
||||
**Base64**
|
||||
- `base64_encode` - Base64编码
|
||||
- `base64_decode` - Base64解码
|
||||
|
||||
#### ✅ MCP 协议处理 ([mcp_protocol.py](mcp_protocol.py))
|
||||
- ✓ JSON-RPC 2.0 协议支持
|
||||
- ✓ 工具调用执行
|
||||
- ✓ 错误处理和重试机制
|
||||
- ✓ 资源管理
|
||||
- ✓ LiteLLM 集成
|
||||
|
||||
### 2. 示例文件创建 ✓
|
||||
|
||||
在 `examples/` 目录下创建了完整的使用示例：
|
||||
|
||||
#### 📝 文档
|
||||
- `README.md` - 示例项目总览
|
||||
- `EXAMPLES_README.md` - 详细使用指南（包含常见问题、性能优化等）
|
||||
- `requirements.txt` - Python依赖
|
||||
|
||||
#### 🐍 Python 示例
|
||||
1. **01_basic_usage.py** - 基础使用示例
|
||||
- 健康检查
|
||||
- Agent CRUD操作
|
||||
- 工具列表查询
|
||||
|
||||
2. **02_agent_management.py** - Agent 管理完整示例
|
||||
- 数据处理 Agent
|
||||
- 数学计算 Agent
|
||||
- 安全处理 Agent
|
||||
- 批量操作
|
||||
|
||||
3. **03_function_tools.py** - 函数工具调用示例
|
||||
- 所有内置函数的使用演示
|
||||
- 结果验证
|
||||
|
||||
4. **04_monitoring.py** - 监控 API 示例
|
||||
- 系统指标查询
|
||||
- 服务统计
|
||||
- 性能趋势
|
||||
- 告警管理
|
||||
|
||||
5. **05_websocket_client.py** - WebSocket 客户端示例
|
||||
- 连接管理
|
||||
- 心跳机制
|
||||
- 实时工具调用
|
||||
- 消息处理
|
||||
|
||||
6. **test_all_functions.py** - 自动化测试工具
|
||||
- 测试所有内置函数
|
||||
- 验证结果正确性
|
||||
- 生成测试报告
|
||||
|
||||
#### 🔧 Shell 脚本
|
||||
- **curl_examples.sh** - cURL 命令示例集合
|
||||
- 所有 REST API 的 cURL 调用
|
||||
- 适合快速测试和 CI/CD 集成
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
services/mcp-server/
|
||||
├── examples/ # 新增示例目录
|
||||
│ ├── README.md # 示例总览
|
||||
│ ├── EXAMPLES_README.md # 详细使用指南
|
||||
│ ├── requirements.txt # Python依赖
|
||||
│ ├── 01_basic_usage.py # 基础示例
|
||||
│ ├── 02_agent_management.py # Agent管理示例
|
||||
│ ├── 03_function_tools.py # 函数工具示例
|
||||
│ ├── 04_monitoring.py # 监控API示例
|
||||
│ ├── 05_websocket_client.py # WebSocket示例
|
||||
│ ├── test_all_functions.py # 自动化测试
|
||||
│ └── curl_examples.sh # cURL示例脚本
|
||||
├── app/
|
||||
│ ├── routes/
|
||||
│ │ ├── agents.py # ✓ Agent路由（已完善）
|
||||
│ │ ├── monitoring.py # ✓ 监控路由（已完善）
|
||||
│ │ ├── websocket.py # ✓ WebSocket路由（已完善）
|
||||
│ │ └── ...
|
||||
│ └── ...
|
||||
├── function_registry.py # ✓ 函数注册表（已完善）
|
||||
├── mcp_protocol.py # ✓ MCP协议处理（已完善）
|
||||
├── main.py # 服务入口
|
||||
└── ...
|
||||
```
|
||||
|
||||
## API 实现对照
|
||||
|
||||
### 基础 API
|
||||
| 端点 | 方法 | 状态 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `/health` | GET | ✅ | 健康检查 |
|
||||
| `/agents` | POST | ✅ | 注册Agent |
|
||||
| `/agents` | GET | ✅ | 获取Agent列表 |
|
||||
| `/agents/{agent_id}` | GET | ✅ | 获取特定Agent |
|
||||
| `/agents/{agent_id}/execute` | POST | ✅ | 执行Agent工具 |
|
||||
| `/tools` | GET | ✅ | 获取工具列表 |
|
||||
| `/metrics` | GET | ✅ | Prometheus指标 |
|
||||
|
||||
### 监控 API
|
||||
| 端点 | 方法 | 状态 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `/api/v1/monitoring/metrics` | GET | ✅ | 系统性能指标 |
|
||||
| `/api/v1/monitoring/stats` | GET | ✅ | 服务统计信息 |
|
||||
| `/api/v1/monitoring/trends` | GET | ✅ | 性能趋势数据 |
|
||||
| `/api/v1/monitoring/alerts` | GET | ✅ | 系统告警 |
|
||||
| `/api/v1/monitoring/dashboard` | GET | ✅ | 监控仪表盘 |
|
||||
|
||||
### WebSocket API
|
||||
| 端点 | 协议 | 状态 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `/ws/{agent_name_or_id}` | WS | ✅ | MCP Protocol WebSocket |
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 1. 安装示例依赖
|
||||
|
||||
```bash
|
||||
cd services/mcp-server/examples
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. 启动 MCP Server
|
||||
|
||||
```bash
|
||||
cd /home/taiji/tools/taiji-AI-PAD
|
||||
docker-compose up -d mcp-server
|
||||
```
|
||||
|
||||
### 3. 运行示例
|
||||
|
||||
```bash
|
||||
# Python 示例
|
||||
python 01_basic_usage.py
|
||||
python 02_agent_management.py
|
||||
python 03_function_tools.py
|
||||
python 04_monitoring.py
|
||||
python 05_websocket_client.py
|
||||
python test_all_functions.py
|
||||
|
||||
# Shell 示例
|
||||
bash curl_examples.sh
|
||||
```
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 1. Agent 管理
|
||||
- ✅ 完整的 CRUD 操作
|
||||
- ✅ Redis 缓存支持
|
||||
- ✅ NATS 事件发布
|
||||
- ✅ 会话管理
|
||||
- ✅ 统计信息（执行次数、成功率、平均执行时间）
|
||||
|
||||
### 2. 工具执行
|
||||
- ✅ 16个内置函数工具
|
||||
- ✅ JSON-RPC 2.0 协议
|
||||
- ✅ EU 计费自动计算
|
||||
- ✅ 执行历史记录
|
||||
- ✅ 余额管理
|
||||
|
||||
### 3. 监控系统
|
||||
- ✅ 系统资源监控（CPU、内存、磁盘）
|
||||
- ✅ 服务统计（Agent、执行、用户）
|
||||
- ✅ 性能趋势分析
|
||||
- ✅ 告警管理
|
||||
- ✅ 仪表盘聚合
|
||||
|
||||
### 4. WebSocket 通信
|
||||
- ✅ 连接池管理（最大1000连接）
|
||||
- ✅ 心跳保活（30秒间隔）
|
||||
- ✅ 消息队列（每连接100条）
|
||||
- ✅ 自动超时清理（90秒）
|
||||
- ✅ 实时工具执行
|
||||
|
||||
## 测试建议
|
||||
|
||||
### 1. 单元测试
|
||||
|
||||
```bash
|
||||
cd services/mcp-server
|
||||
python -m pytest tests/
|
||||
```
|
||||
|
||||
### 2. 功能测试
|
||||
|
||||
```bash
|
||||
# 测试所有内置函数
|
||||
python examples/test_all_functions.py
|
||||
|
||||
# 测试基础功能
|
||||
python examples/01_basic_usage.py
|
||||
```
|
||||
|
||||
### 3. 性能测试
|
||||
|
||||
使用 `curl_examples.sh` 进行压力测试：
|
||||
|
||||
```bash
|
||||
# 并发测试
|
||||
for i in {1..100}; do
|
||||
bash examples/curl_examples.sh &
|
||||
done
|
||||
wait
|
||||
```
|
||||
|
||||
### 4. WebSocket 测试
|
||||
|
||||
```bash
|
||||
python examples/05_websocket_client.py
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 1. 认证
|
||||
- 开发环境使用 `X-API-Key: test-api-key`
|
||||
- 生产环境需要通过 `/api/v1/auth/login` 获取 JWT Token
|
||||
|
||||
### 2. 限制
|
||||
- WebSocket 连接池最大1000个连接
|
||||
- 消息队列每个连接最多100条
|
||||
- 心跳超时90秒
|
||||
|
||||
### 3. 性能
|
||||
- Agent 信息缓存在 Redis 中（1小时）
|
||||
- 使用连接池提高性能
|
||||
- 批量操作建议使用异步方式
|
||||
|
||||
### 4. 错误处理
|
||||
- 所有示例都包含完整的错误处理
|
||||
- WebSocket 支持自动重连
|
||||
- HTTP 请求支持重试机制
|
||||
|
||||
## 后续改进建议
|
||||
|
||||
### 1. 功能增强
|
||||
- [ ] 添加 Agent 更新（PUT）和删除（DELETE）接口
|
||||
- [ ] 支持自定义函数注册
|
||||
- [ ] 添加工具执行历史查询接口
|
||||
- [ ] 支持批量工具执行
|
||||
|
||||
### 2. 性能优化
|
||||
- [ ] 添加查询结果分页
|
||||
- [ ] 优化数据库查询
|
||||
- [ ] 添加更多缓存策略
|
||||
- [ ] 实现请求限流
|
||||
|
||||
### 3. 监控改进
|
||||
- [ ] 添加更详细的性能指标
|
||||
- [ ] 实现实时告警推送
|
||||
- [ ] 添加日志聚合
|
||||
- [ ] 集成 Grafana 仪表盘
|
||||
|
||||
### 4. 文档完善
|
||||
- [ ] 添加 OpenAPI/Swagger 文档
|
||||
- [ ] 创建交互式 API 文档
|
||||
- [ ] 添加架构设计文档
|
||||
- [ ] 创建部署指南
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [API 接口文档](../../Docs/前后端调试接口说明/API-MCPServer服务.md)
|
||||
- [示例使用指南](examples/EXAMPLES_README.md)
|
||||
- [项目文档](../../Docs/项目文档/)
|
||||
|
||||
## 更新日期
|
||||
|
||||
2025-12-27
|
||||
@@ -0,0 +1,565 @@
|
||||
# MCP Server 快速入门指南
|
||||
|
||||
欢迎使用 taiji-AI-PAD MCP Server！本指南将帮助你快速开始使用 MCP Server 的各种功能。
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [简介](#简介)
|
||||
- [快速开始](#快速开始)
|
||||
- [基础概念](#基础概念)
|
||||
- [示例代码](#示例代码)
|
||||
- [常见场景](#常见场景)
|
||||
- [故障排查](#故障排查)
|
||||
|
||||
## 🎯 简介
|
||||
|
||||
MCP Server 是一个基于 Model Context Protocol 的 Agent 管理服务，提供：
|
||||
|
||||
- **Agent 管理**：创建、查询、执行 AI Agent
|
||||
- **工具执行**：16个内置函数工具（数学、字符串、JSON、哈希等）
|
||||
- **实时通信**：WebSocket 支持实时双向通信
|
||||
- **监控系统**：完整的系统监控和告警
|
||||
- **计费管理**：基于 EU（执行单元）的资源计费
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1️⃣ 启动服务
|
||||
|
||||
```bash
|
||||
# 进入项目目录
|
||||
cd /home/taiji/tools/taiji-AI-PAD
|
||||
|
||||
# 启动 MCP Server
|
||||
docker-compose up -d mcp-server
|
||||
|
||||
# 检查服务状态
|
||||
curl http://localhost:8002/health
|
||||
```
|
||||
|
||||
期望输出：
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"timestamp": "2025-12-27T...",
|
||||
"version": "1.0.0",
|
||||
"services": {
|
||||
"database": "healthy",
|
||||
"redis": "healthy",
|
||||
"nats": "healthy"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2️⃣ 创建第一个 Agent
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8002/agents \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: test-api-key" \
|
||||
-d '{
|
||||
"name": "my-first-agent",
|
||||
"description": "我的第一个Agent",
|
||||
"role": "assistant",
|
||||
"goal": "帮助用户完成任务",
|
||||
"tools": ["math_add", "string_upper"],
|
||||
"config": {},
|
||||
"capabilities": ["calculation", "text_processing"]
|
||||
}'
|
||||
```
|
||||
|
||||
保存返回的 `agent_id`，后续会用到。
|
||||
|
||||
### 3️⃣ 执行第一个工具
|
||||
|
||||
使用刚创建的 Agent 执行一个简单的加法：
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8002/agents/{agent_id}/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: test-api-key" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-001",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {
|
||||
"name": "math_add",
|
||||
"function_name": "math_add"
|
||||
},
|
||||
"arguments": {
|
||||
"a": 10,
|
||||
"b": 20
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
期望输出：
|
||||
```json
|
||||
{
|
||||
"execution_id": "...",
|
||||
"success": true,
|
||||
"result": 30.0,
|
||||
"execution_time": 0.001,
|
||||
"eu_consumed": 0.0001,
|
||||
"cost": 0.0001
|
||||
}
|
||||
```
|
||||
|
||||
### 4️⃣ 运行 Python 示例
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
cd services/mcp-server/examples
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 运行基础示例
|
||||
python 01_basic_usage.py
|
||||
|
||||
# 测试所有函数
|
||||
python test_all_functions.py
|
||||
```
|
||||
|
||||
## 📚 基础概念
|
||||
|
||||
### Agent（智能体）
|
||||
|
||||
Agent 是 MCP Server 中的核心概念，代表一个具有特定能力的智能体。
|
||||
|
||||
**Agent 属性：**
|
||||
- `name`: Agent 名称（唯一）
|
||||
- `description`: 描述
|
||||
- `role`: 角色（assistant, user, system）
|
||||
- `goal`: 目标
|
||||
- `tools`: 可用工具列表
|
||||
- `capabilities`: 能力标签
|
||||
|
||||
**生命周期：**
|
||||
1. 创建 → 2. 执行工具 → 3. 监控统计 → 4. 更新/删除
|
||||
|
||||
### 工具（Tools）
|
||||
|
||||
工具是 Agent 可以调用的函数，分为三类：
|
||||
|
||||
1. **函数工具**：内置 Python 函数（数学、字符串等）
|
||||
2. **API 工具**：调用外部 API
|
||||
3. **LLM 工具**：调用大语言模型
|
||||
|
||||
**内置工具列表：**
|
||||
|
||||
| 类别 | 工具名称 | 功能 |
|
||||
|------|---------|------|
|
||||
| 数学 | `math_add`, `math_subtract`, `math_multiply`, `math_divide`, `math_power` | 基础数学运算 |
|
||||
| 字符串 | `string_upper`, `string_lower`, `string_length`, `string_replace` | 字符串处理 |
|
||||
| 日期 | `datetime_now` | 获取当前时间 |
|
||||
| JSON | `json_parse`, `json_stringify` | JSON 处理 |
|
||||
| 哈希 | `hash_md5`, `hash_sha256` | 哈希计算 |
|
||||
| Base64 | `base64_encode`, `base64_decode` | Base64 编解码 |
|
||||
|
||||
### EU（执行单元）
|
||||
|
||||
EU 是资源消耗的计量单位：
|
||||
- 1 EU = 10 秒执行时间
|
||||
- 执行完成后自动计算和扣费
|
||||
- 可查询余额和消费历史
|
||||
|
||||
### 会话（Session）
|
||||
|
||||
会话用于维护上下文和对话历史：
|
||||
- 每个 Agent 执行可关联到会话
|
||||
- 会话保存最近 50 次执行历史
|
||||
- 支持会话上下文传递
|
||||
|
||||
## 💻 示例代码
|
||||
|
||||
### Python 示例
|
||||
|
||||
#### 创建并使用 Agent
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
BASE_URL = "http://localhost:8002"
|
||||
HEADERS = {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-Key": "test-api-key"
|
||||
}
|
||||
|
||||
# 1. 创建 Agent
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/agents",
|
||||
json={
|
||||
"name": "calculator",
|
||||
"description": "数学计算器",
|
||||
"role": "assistant",
|
||||
"goal": "执行数学计算",
|
||||
"tools": ["math_add", "math_multiply"],
|
||||
"config": {},
|
||||
"capabilities": ["calculation"]
|
||||
},
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
agent = response.json()
|
||||
agent_id = agent['id']
|
||||
print(f"Agent 创建成功: {agent_id}")
|
||||
|
||||
# 2. 执行工具
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/agents/{agent_id}/execute",
|
||||
json={
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-001",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {
|
||||
"name": "math_add",
|
||||
"function_name": "math_add"
|
||||
},
|
||||
"arguments": {"a": 15, "b": 25}
|
||||
}
|
||||
},
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
result = response.json()
|
||||
print(f"计算结果: {result['result']}") # 40.0
|
||||
```
|
||||
|
||||
#### WebSocket 实时通信
|
||||
|
||||
```python
|
||||
import websocket
|
||||
import json
|
||||
|
||||
def on_message(ws, message):
|
||||
data = json.loads(message)
|
||||
print(f"收到消息: {data}")
|
||||
|
||||
def on_open(ws):
|
||||
# 发送工具执行请求
|
||||
ws.send(json.dumps({
|
||||
"type": "mcp_request",
|
||||
"payload": {
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-001",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {"name": "math_add", "function_name": "math_add"},
|
||||
"arguments": {"a": 10, "b": 20}
|
||||
}
|
||||
}
|
||||
}))
|
||||
|
||||
ws = websocket.WebSocketApp(
|
||||
f"ws://localhost:8002/ws/{agent_id}",
|
||||
on_open=on_open,
|
||||
on_message=on_message
|
||||
)
|
||||
|
||||
ws.run_forever()
|
||||
```
|
||||
|
||||
### JavaScript 示例
|
||||
|
||||
```javascript
|
||||
// 创建 Agent
|
||||
const createAgent = async () => {
|
||||
const response = await fetch('http://localhost:8002/agents', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'X-API-Key': 'test-api-key'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
name: 'js-agent',
|
||||
description: 'JavaScript Agent',
|
||||
role: 'assistant',
|
||||
goal: 'Process data',
|
||||
tools: ['string_upper', 'json_parse'],
|
||||
config: {},
|
||||
capabilities: ['text_processing']
|
||||
})
|
||||
});
|
||||
|
||||
const agent = await response.json();
|
||||
return agent.id;
|
||||
};
|
||||
|
||||
// WebSocket 连接
|
||||
const connectWebSocket = (agentId) => {
|
||||
const ws = new WebSocket(`ws://localhost:8002/ws/${agentId}`);
|
||||
|
||||
ws.onopen = () => {
|
||||
console.log('WebSocket 连接已建立');
|
||||
|
||||
// 发送工具执行请求
|
||||
ws.send(JSON.stringify({
|
||||
type: 'mcp_request',
|
||||
payload: {
|
||||
jsonrpc: '2.0',
|
||||
id: 'req-001',
|
||||
method: 'tools/call',
|
||||
params: {
|
||||
tool: {
|
||||
name: 'string_upper',
|
||||
function_name: 'string_upper'
|
||||
},
|
||||
arguments: {
|
||||
s: 'hello world'
|
||||
}
|
||||
}
|
||||
}
|
||||
}));
|
||||
};
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('收到消息:', data);
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## 🎨 常见场景
|
||||
|
||||
### 场景 1: 数据处理流水线
|
||||
|
||||
```python
|
||||
# 创建数据处理 Agent
|
||||
agent_id = create_agent(
|
||||
name="data-processor",
|
||||
tools=["string_upper", "string_replace", "json_stringify"]
|
||||
)
|
||||
|
||||
# 处理文本
|
||||
result1 = execute_tool(agent_id, "string_upper", {"s": "hello"})
|
||||
# → "HELLO"
|
||||
|
||||
# 替换字符
|
||||
result2 = execute_tool(agent_id, "string_replace", {
|
||||
"s": result1['result'],
|
||||
"old": "HELLO",
|
||||
"new": "WORLD"
|
||||
})
|
||||
# → "WORLD"
|
||||
|
||||
# 转换为 JSON
|
||||
result3 = execute_tool(agent_id, "json_stringify", {
|
||||
"obj": {"processed": result2['result']}
|
||||
})
|
||||
# → '{"processed": "WORLD"}'
|
||||
```
|
||||
|
||||
### 场景 2: 批量计算
|
||||
|
||||
```python
|
||||
# 创建计算 Agent
|
||||
agent_id = create_agent(
|
||||
name="batch-calculator",
|
||||
tools=["math_add", "math_multiply", "math_power"]
|
||||
)
|
||||
|
||||
# 批量执行计算
|
||||
results = []
|
||||
for i in range(10):
|
||||
result = execute_tool(agent_id, "math_add", {
|
||||
"a": i * 10,
|
||||
"b": i * 5
|
||||
})
|
||||
results.append(result['result'])
|
||||
|
||||
print(f"计算完成，结果: {results}")
|
||||
```
|
||||
|
||||
### 场景 3: 安全哈希生成
|
||||
|
||||
```python
|
||||
# 创建安全 Agent
|
||||
agent_id = create_agent(
|
||||
name="security-agent",
|
||||
tools=["hash_sha256", "base64_encode"]
|
||||
)
|
||||
|
||||
# 生成密码哈希
|
||||
password = "MySecurePassword123"
|
||||
hash_result = execute_tool(agent_id, "hash_sha256", {"s": password})
|
||||
password_hash = hash_result['result']
|
||||
|
||||
# Base64 编码
|
||||
encoded = execute_tool(agent_id, "base64_encode", {"s": password_hash})
|
||||
final_hash = encoded['result']
|
||||
|
||||
print(f"最终哈希: {final_hash}")
|
||||
```
|
||||
|
||||
### 场景 4: 实时监控告警
|
||||
|
||||
```python
|
||||
import requests
|
||||
import time
|
||||
|
||||
def check_system_health():
|
||||
while True:
|
||||
# 获取系统指标
|
||||
response = requests.get(
|
||||
"http://localhost:8002/api/v1/monitoring/metrics",
|
||||
headers=HEADERS
|
||||
)
|
||||
metrics = response.json()
|
||||
|
||||
# 检查 CPU 使用率
|
||||
cpu_usage = metrics['system']['cpu_usage_percent']
|
||||
if cpu_usage > 80:
|
||||
print(f"⚠️ CPU 使用率过高: {cpu_usage}%")
|
||||
|
||||
# 检查告警
|
||||
alerts_response = requests.get(
|
||||
"http://localhost:8002/api/v1/monitoring/alerts",
|
||||
headers=HEADERS
|
||||
)
|
||||
alerts = alerts_response.json()
|
||||
|
||||
if alerts['count'] > 0:
|
||||
print(f"🔥 发现 {alerts['count']} 个告警")
|
||||
for alert in alerts['alerts']:
|
||||
print(f" - [{alert['severity']}] {alert['message']}")
|
||||
|
||||
time.sleep(60) # 每分钟检查一次
|
||||
|
||||
check_system_health()
|
||||
```
|
||||
|
||||
## 🔧 故障排查
|
||||
|
||||
### 问题 1: 连接被拒绝
|
||||
|
||||
**症状：** `ConnectionRefusedError` 或 `Connection refused`
|
||||
|
||||
**解决方法：**
|
||||
```bash
|
||||
# 检查服务是否运行
|
||||
docker-compose ps mcp-server
|
||||
|
||||
# 查看服务日志
|
||||
docker-compose logs mcp-server
|
||||
|
||||
# 重启服务
|
||||
docker-compose restart mcp-server
|
||||
```
|
||||
|
||||
### 问题 2: 认证失败
|
||||
|
||||
**症状：** HTTP 401 或 403 错误
|
||||
|
||||
**解决方法：**
|
||||
```python
|
||||
# 确保使用正确的 API Key
|
||||
HEADERS = {
|
||||
"X-API-Key": "test-api-key" # 开发环境
|
||||
}
|
||||
|
||||
# 或获取 JWT Token
|
||||
response = requests.post(
|
||||
"http://localhost:8002/api/v1/auth/login",
|
||||
json={"username": "test_user", "password": "test_password"}
|
||||
)
|
||||
token = response.json()["access_token"]
|
||||
|
||||
HEADERS = {
|
||||
"Authorization": f"Bearer {token}"
|
||||
}
|
||||
```
|
||||
|
||||
### 问题 3: WebSocket 连接断开
|
||||
|
||||
**症状：** WebSocket 频繁断开
|
||||
|
||||
**解决方法：**
|
||||
```python
|
||||
# 实现心跳机制
|
||||
def send_ping():
|
||||
ws.send(json.dumps({"type": "ping"}))
|
||||
|
||||
# 定期发送心跳（每30秒）
|
||||
import threading
|
||||
def heartbeat():
|
||||
while True:
|
||||
send_ping()
|
||||
time.sleep(30)
|
||||
|
||||
threading.Thread(target=heartbeat, daemon=True).start()
|
||||
```
|
||||
|
||||
### 问题 4: Agent 找不到
|
||||
|
||||
**症状：** HTTP 404 - Agent not found
|
||||
|
||||
**解决方法：**
|
||||
```python
|
||||
# 1. 检查 Agent ID 是否正确
|
||||
response = requests.get(
|
||||
f"{BASE_URL}/agents",
|
||||
headers=HEADERS
|
||||
)
|
||||
agents = response.json()
|
||||
print("所有 Agent:")
|
||||
for agent in agents:
|
||||
print(f" - {agent['name']}: {agent['id']}")
|
||||
|
||||
# 2. 使用 Agent 名称而不是 ID（WebSocket）
|
||||
ws = websocket.WebSocketApp(
|
||||
f"ws://localhost:8002/ws/{agent_name}" # 可以使用名称
|
||||
)
|
||||
```
|
||||
|
||||
### 问题 5: 执行超时
|
||||
|
||||
**症状：** 工具执行超时
|
||||
|
||||
**解决方法：**
|
||||
```python
|
||||
# 增加请求超时时间
|
||||
response = requests.post(
|
||||
url,
|
||||
json=data,
|
||||
headers=headers,
|
||||
timeout=30 # 30秒超时
|
||||
)
|
||||
|
||||
# 或使用异步请求
|
||||
import asyncio
|
||||
import aiohttp
|
||||
|
||||
async def execute_with_timeout():
|
||||
timeout = aiohttp.ClientTimeout(total=30)
|
||||
async with aiohttp.ClientSession(timeout=timeout) as session:
|
||||
async with session.post(url, json=data) as response:
|
||||
return await response.json()
|
||||
```
|
||||
|
||||
## 📖 更多资源
|
||||
|
||||
- **完整 API 文档**: [API-MCPServer服务.md](../../Docs/前后端调试接口说明/API-MCPServer服务.md)
|
||||
- **示例代码**: [examples/](examples/)
|
||||
- **详细指南**: [examples/EXAMPLES_README.md](examples/EXAMPLES_README.md)
|
||||
- **实现总结**: [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md)
|
||||
|
||||
## 🤝 获取帮助
|
||||
|
||||
如果遇到问题：
|
||||
|
||||
1. 查看[故障排查](#故障排查)部分
|
||||
2. 查看服务日志：`docker-compose logs mcp-server`
|
||||
3. 运行测试：`python examples/test_all_functions.py`
|
||||
4. 查看 API 文档
|
||||
|
||||
## 🎉 下一步
|
||||
|
||||
现在你已经掌握了基础知识，可以：
|
||||
|
||||
1. 探索更多[示例代码](examples/)
|
||||
2. 阅读[详细 API 文档](../../Docs/前后端调试接口说明/API-MCPServer服务.md)
|
||||
3. 构建自己的 Agent 应用
|
||||
4. 集成到你的项目中
|
||||
|
||||
祝你使用愉快！🚀
|
||||
@@ -0,0 +1,284 @@
|
||||
# MCP Server
|
||||
|
||||
taiji-AI-PAD 的 Model Context Protocol (MCP) 服务器，提供 Agent 管理、工具执行、实时通信和系统监控功能。
|
||||
|
||||
## 🌟 主要功能
|
||||
|
||||
- **Agent 管理**：创建、查询和管理 AI Agent
|
||||
- **工具执行**：16个内置函数工具（数学、字符串、JSON、哈希等）
|
||||
- **实时通信**：基于 WebSocket 的实时双向通信
|
||||
- **监控系统**：完整的系统性能监控和告警
|
||||
- **计费管理**：基于 EU（执行单元）的资源计费
|
||||
|
||||
## 📚 文档
|
||||
|
||||
- **[快速入门](QUICKSTART.md)** - 5分钟快速上手指南
|
||||
- **[完整 API 文档](../../Docs/前后端调试接口说明/API-MCPServer服务.md)** - 所有 API 的详细说明
|
||||
- **[示例代码](examples/)** - Python、JavaScript、Shell 示例
|
||||
- **[实现总结](IMPLEMENTATION_SUMMARY.md)** - 功能实现详情
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 启动服务
|
||||
|
||||
```bash
|
||||
# 使用 Docker Compose
|
||||
cd /home/taiji/tools/taiji-AI-PAD
|
||||
docker-compose up -d mcp-server
|
||||
|
||||
# 验证服务
|
||||
curl http://localhost:8002/health
|
||||
```
|
||||
|
||||
### 创建你的第一个 Agent
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
"http://localhost:8002/agents",
|
||||
json={
|
||||
"name": "my-agent",
|
||||
"description": "我的第一个Agent",
|
||||
"role": "assistant",
|
||||
"goal": "帮助用户",
|
||||
"tools": ["math_add", "string_upper"],
|
||||
"config": {},
|
||||
"capabilities": ["calculation"]
|
||||
},
|
||||
headers={"X-API-Key": "test-api-key"}
|
||||
)
|
||||
|
||||
agent = response.json()
|
||||
print(f"Agent ID: {agent['id']}")
|
||||
```
|
||||
|
||||
### 执行工具
|
||||
|
||||
```python
|
||||
result = requests.post(
|
||||
f"http://localhost:8002/agents/{agent['id']}/execute",
|
||||
json={
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-001",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {"name": "math_add", "function_name": "math_add"},
|
||||
"arguments": {"a": 10, "b": 20}
|
||||
}
|
||||
},
|
||||
headers={"X-API-Key": "test-api-key"}
|
||||
)
|
||||
|
||||
print(f"结果: {result.json()['result']}") # 30.0
|
||||
```
|
||||
|
||||
## 📦 示例代码
|
||||
|
||||
我们提供了丰富的示例代码，帮助你快速上手：
|
||||
|
||||
```bash
|
||||
cd examples
|
||||
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 基础使用
|
||||
python 01_basic_usage.py
|
||||
|
||||
# Agent 管理
|
||||
python 02_agent_management.py
|
||||
|
||||
# 函数工具
|
||||
python 03_function_tools.py
|
||||
|
||||
# 监控 API
|
||||
python 04_monitoring.py
|
||||
|
||||
# WebSocket
|
||||
python 05_websocket_client.py
|
||||
|
||||
# 自动化测试
|
||||
python test_all_functions.py
|
||||
|
||||
# Shell 示例
|
||||
bash curl_examples.sh
|
||||
```
|
||||
|
||||
详见 [examples/README.md](examples/README.md)
|
||||
|
||||
## 🛠️ 内置工具
|
||||
|
||||
### 数学函数
|
||||
- `math_add` - 加法
|
||||
- `math_subtract` - 减法
|
||||
- `math_multiply` - 乘法
|
||||
- `math_divide` - 除法
|
||||
- `math_power` - 幂运算
|
||||
|
||||
### 字符串函数
|
||||
- `string_upper` - 转大写
|
||||
- `string_lower` - 转小写
|
||||
- `string_length` - 字符串长度
|
||||
- `string_replace` - 替换子串
|
||||
|
||||
### 其他工具
|
||||
- `datetime_now` - 获取当前时间
|
||||
- `json_parse` / `json_stringify` - JSON 处理
|
||||
- `hash_md5` / `hash_sha256` - 哈希计算
|
||||
- `base64_encode` / `base64_decode` - Base64 编解码
|
||||
|
||||
## 🔌 API 端点
|
||||
|
||||
### 基础 API
|
||||
|
||||
- `GET /health` - 健康检查
|
||||
- `POST /agents` - 创建 Agent
|
||||
- `GET /agents` - 获取 Agent 列表
|
||||
- `GET /agents/{agent_id}` - 获取特定 Agent
|
||||
- `POST /agents/{agent_id}/execute` - 执行工具
|
||||
- `GET /tools` - 获取工具列表
|
||||
- `GET /metrics` - Prometheus 指标
|
||||
|
||||
### 监控 API
|
||||
|
||||
- `GET /api/v1/monitoring/metrics` - 系统性能指标
|
||||
- `GET /api/v1/monitoring/stats` - 服务统计信息
|
||||
- `GET /api/v1/monitoring/trends` - 性能趋势数据
|
||||
- `GET /api/v1/monitoring/alerts` - 系统告警
|
||||
- `GET /api/v1/monitoring/dashboard` - 监控仪表盘
|
||||
|
||||
### WebSocket API
|
||||
|
||||
- `WS /ws/{agent_name_or_id}` - MCP Protocol WebSocket
|
||||
|
||||
详见 [API 文档](../../Docs/前后端调试接口说明/API-MCPServer服务.md)
|
||||
|
||||
## 🏗️ 架构
|
||||
|
||||
```
|
||||
mcp-server/
|
||||
├── app/ # 应用核心
|
||||
│ ├── routes/ # API 路由
|
||||
│ │ ├── agents.py # Agent 管理
|
||||
│ │ ├── monitoring.py # 监控接口
|
||||
│ │ ├── websocket.py # WebSocket
|
||||
│ │ └── ...
|
||||
│ ├── application.py # FastAPI 应用
|
||||
│ ├── metrics.py # Prometheus 指标
|
||||
│ └── ...
|
||||
├── examples/ # 示例代码 ✨ 新增
|
||||
│ ├── 01_basic_usage.py
|
||||
│ ├── 02_agent_management.py
|
||||
│ ├── 03_function_tools.py
|
||||
│ ├── 04_monitoring.py
|
||||
│ ├── 05_websocket_client.py
|
||||
│ ├── test_all_functions.py
|
||||
│ └── curl_examples.sh
|
||||
├── function_registry.py # 函数注册表
|
||||
├── mcp_protocol.py # MCP 协议处理
|
||||
├── main.py # 服务入口
|
||||
├── QUICKSTART.md # 快速入门 ✨ 新增
|
||||
└── README.md # 本文件
|
||||
```
|
||||
|
||||
## 🧪 测试
|
||||
|
||||
```bash
|
||||
# 单元测试
|
||||
pytest tests/
|
||||
|
||||
# 功能测试
|
||||
python examples/test_all_functions.py
|
||||
|
||||
# API 测试
|
||||
bash examples/curl_examples.sh
|
||||
```
|
||||
|
||||
## 📊 监控
|
||||
|
||||
访问监控仪表盘：
|
||||
|
||||
```bash
|
||||
# 系统指标
|
||||
curl http://localhost:8002/api/v1/monitoring/metrics
|
||||
|
||||
# Prometheus 格式
|
||||
curl http://localhost:8002/metrics
|
||||
|
||||
# 可视化仪表盘（需配置 Grafana）
|
||||
open http://localhost:3000
|
||||
```
|
||||
|
||||
## 🔐 认证
|
||||
|
||||
### 开发环境
|
||||
|
||||
使用测试 API Key：
|
||||
|
||||
```bash
|
||||
curl -H "X-API-Key: test-api-key" http://localhost:8002/agents
|
||||
```
|
||||
|
||||
### 生产环境
|
||||
|
||||
使用 JWT Token：
|
||||
|
||||
```python
|
||||
# 1. 登录获取 token
|
||||
response = requests.post(
|
||||
"http://localhost:8002/api/v1/auth/login",
|
||||
json={"username": "user", "password": "pass"}
|
||||
)
|
||||
token = response.json()["access_token"]
|
||||
|
||||
# 2. 使用 token
|
||||
headers = {"Authorization": f"Bearer {token}"}
|
||||
response = requests.get("http://localhost:8002/agents", headers=headers)
|
||||
```
|
||||
|
||||
## 🐛 故障排查
|
||||
|
||||
### 服务无法启动
|
||||
|
||||
```bash
|
||||
# 检查端口占用
|
||||
lsof -i :8002
|
||||
|
||||
# 查看日志
|
||||
docker-compose logs mcp-server
|
||||
|
||||
# 重启服务
|
||||
docker-compose restart mcp-server
|
||||
```
|
||||
|
||||
### 连接问题
|
||||
|
||||
```bash
|
||||
# 检查网络
|
||||
docker network ls
|
||||
docker network inspect taiji-ai-pad_default
|
||||
|
||||
# 检查防火墙
|
||||
sudo ufw status
|
||||
```
|
||||
|
||||
更多问题请查看 [故障排查指南](QUICKSTART.md#故障排查)
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
欢迎贡献代码和文档！
|
||||
|
||||
## 📄 许可
|
||||
|
||||
[MIT License](LICENSE)
|
||||
|
||||
## 🔗 相关链接
|
||||
|
||||
- [项目文档](../../Docs/)
|
||||
- [MCP 协议规范](https://modelcontextprotocol.io/)
|
||||
- [FastAPI 文档](https://fastapi.tiangolo.com/)
|
||||
|
||||
---
|
||||
|
||||
**需要帮助？** 查看 [快速入门指南](QUICKSTART.md) 或 [示例代码](examples/)
|
||||
@@ -36,14 +36,24 @@ def register_lifecycle_events(app: FastAPI) -> None:
|
||||
database_connections.set(1)
|
||||
logger.info("数据库初始化完成")
|
||||
|
||||
state.redis_client = redis.from_url(
|
||||
settings.redis_url,
|
||||
encoding="utf-8",
|
||||
decode_responses=True,
|
||||
)
|
||||
await state.redis_client.ping()
|
||||
redis_connections.set(1)
|
||||
logger.info("Redis连接成功")
|
||||
# Redis是可选的，连接失败不影响服务启动
|
||||
try:
|
||||
if settings.redis_url:
|
||||
state.redis_client = redis.from_url(
|
||||
settings.redis_url,
|
||||
encoding="utf-8",
|
||||
decode_responses=True,
|
||||
)
|
||||
await state.redis_client.ping()
|
||||
redis_connections.set(1)
|
||||
logger.info("Redis连接成功")
|
||||
else:
|
||||
state.redis_client = None
|
||||
logger.warning("未配置REDIS_URL，Redis功能已禁用")
|
||||
except Exception as redis_exc:
|
||||
state.redis_client = None
|
||||
redis_connections.set(0)
|
||||
logger.warning("Redis连接失败，服务将继续运行（无缓存功能）", error=str(redis_exc))
|
||||
|
||||
state.nats_client = await nats.connect(settings.nats_url)
|
||||
nats_connections.set(1)
|
||||
@@ -53,6 +63,7 @@ def register_lifecycle_events(app: FastAPI) -> None:
|
||||
redis_client=state.redis_client,
|
||||
nats_client=state.nats_client,
|
||||
litellm_url=settings.litellm_url,
|
||||
litellm_api_key=settings.litellm_api_key,
|
||||
)
|
||||
function_count = len(state.mcp_handler.function_registry.list_all())
|
||||
function_registry_size.set(function_count)
|
||||
|
||||
@@ -89,13 +89,15 @@ async def list_admins(
|
||||
):
|
||||
"""
|
||||
获取管理员列表（仅超级管理员可用）
|
||||
仅返回活跃状态的管理员
|
||||
"""
|
||||
_verify_super_admin_permission(principal)
|
||||
|
||||
# 查询所有管理员角色的用户
|
||||
# 查询所有活跃的管理员角色用户
|
||||
result = await db.execute(
|
||||
select(User).where(
|
||||
User.role.in_(["billing_admin", "operations_admin"])
|
||||
User.role.in_(["billing_admin", "operations_admin"]),
|
||||
User.status == "active" # 仅返回活跃管理员
|
||||
)
|
||||
)
|
||||
admins = result.scalars().all()
|
||||
@@ -1250,3 +1252,108 @@ async def revoke_provider_access(
|
||||
return SuccessResponse(message="授权已撤销")
|
||||
|
||||
|
||||
# ============= 渠道管理员 =============
|
||||
|
||||
@router.get("/channels/{channel_id}/admins", response_model=SuccessResponse)
|
||||
async def get_channel_admins(
|
||||
channel_id: str,
|
||||
principal: dict = Depends(require_auth),
|
||||
db: AsyncSession = Depends(get_db)
|
||||
):
|
||||
"""
|
||||
获取渠道管理员列表
|
||||
|
||||
返回指定渠道下的所有管理员用户
|
||||
"""
|
||||
_verify_read_permission(principal)
|
||||
|
||||
# 验证渠道存在
|
||||
result = await db.execute(
|
||||
select(Channel).where(Channel.id == channel_id)
|
||||
)
|
||||
channel = result.scalar_one_or_none()
|
||||
|
||||
if not channel:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_404_NOT_FOUND,
|
||||
detail="渠道不存在"
|
||||
)
|
||||
|
||||
# 查询渠道下的管理员（role为channel_admin的用户）
|
||||
result = await db.execute(
|
||||
select(User).where(
|
||||
and_(
|
||||
User.channel_id == channel_id,
|
||||
User.role == "channel_admin",
|
||||
User.status == "active"
|
||||
)
|
||||
)
|
||||
)
|
||||
admins = result.scalars().all()
|
||||
|
||||
data = [
|
||||
{
|
||||
"id": str(admin.id),
|
||||
"name": admin.name or admin.full_name,
|
||||
"email": admin.email,
|
||||
"role": admin.role,
|
||||
"status": admin.status,
|
||||
"createdAt": admin.created_at.isoformat() if admin.created_at else None,
|
||||
}
|
||||
for admin in admins
|
||||
]
|
||||
|
||||
return SuccessResponse(data={
|
||||
"channelId": str(channel.id),
|
||||
"channelName": channel.name,
|
||||
"admins": data
|
||||
})
|
||||
|
||||
|
||||
@router.get("/roles", response_model=SuccessResponse)
|
||||
async def get_admin_roles(
|
||||
principal: dict = Depends(require_auth),
|
||||
):
|
||||
"""
|
||||
获取可用角色列表
|
||||
|
||||
返回系统中所有可用的角色类型及其描述
|
||||
"""
|
||||
_verify_read_permission(principal)
|
||||
|
||||
roles = [
|
||||
{
|
||||
"id": "super_admin",
|
||||
"name": "超级管理员",
|
||||
"description": "拥有系统所有权限",
|
||||
"permissions": ["*"]
|
||||
},
|
||||
{
|
||||
"id": "billing_admin",
|
||||
"name": "计费管理员",
|
||||
"description": "完整写入权限，可创建渠道、管理租户、计费操作",
|
||||
"permissions": ["read:*", "write:channels", "write:tenants", "write:billing"]
|
||||
},
|
||||
{
|
||||
"id": "operations_admin",
|
||||
"name": "运维管理员",
|
||||
"description": "只读权限，仅查看和监控",
|
||||
"permissions": ["read:*"]
|
||||
},
|
||||
{
|
||||
"id": "channel_admin",
|
||||
"name": "渠道管理员",
|
||||
"description": "渠道内部管理权限",
|
||||
"permissions": ["read:channel", "write:tenants", "read:billing"]
|
||||
},
|
||||
{
|
||||
"id": "user",
|
||||
"name": "普通用户",
|
||||
"description": "标准用户权限",
|
||||
"permissions": ["read:self", "use:agents"]
|
||||
}
|
||||
]
|
||||
|
||||
return SuccessResponse(data={"roles": roles})
|
||||
|
||||
|
||||
|
||||
@@ -28,6 +28,8 @@ from app.schemas import (
|
||||
ResourceApplicationRequest,
|
||||
ChannelBillingResponse,
|
||||
ApplyProviderRequest,
|
||||
UpdateTenantStatusRequest,
|
||||
UpdateTenantPermissionsRequest,
|
||||
)
|
||||
|
||||
router = APIRouter(prefix="/api/channel", tags=["渠道合作伙伴"])
|
||||
@@ -357,6 +359,176 @@ async def set_tenant_credit_limit(
|
||||
)
|
||||
|
||||
|
||||
@router.delete("/tenants/{tenant_id}", response_model=SuccessResponse)
|
||||
async def delete_tenant(
|
||||
tenant_id: str,
|
||||
principal: dict = Depends(require_auth),
|
||||
db: AsyncSession = Depends(get_db)
|
||||
):
|
||||
"""
|
||||
删除租户（软删除）
|
||||
|
||||
将租户状态标记为inactive，保留数据但禁止使用
|
||||
"""
|
||||
_verify_channel_permission(principal)
|
||||
channel_id = principal.get("claims", {}).get("channelId")
|
||||
|
||||
# 验证租户属于该渠道
|
||||
result = await db.execute(
|
||||
select(User).where(
|
||||
and_(
|
||||
User.id == tenant_id,
|
||||
User.channel_id == channel_id
|
||||
)
|
||||
)
|
||||
)
|
||||
tenant = result.scalar_one_or_none()
|
||||
|
||||
if not tenant:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_404_NOT_FOUND,
|
||||
detail="租户不存在或不属于该渠道"
|
||||
)
|
||||
|
||||
# 检查租户是否还有余额
|
||||
if float(tenant.balance) > 0:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_400_BAD_REQUEST,
|
||||
detail=f"租户还有余额 {float(tenant.balance):.2f}，请先处理余额后再删除"
|
||||
)
|
||||
|
||||
# 软删除：标记为不活跃
|
||||
tenant.status = "inactive"
|
||||
await db.commit()
|
||||
|
||||
return SuccessResponse(
|
||||
data={
|
||||
"id": str(tenant.id),
|
||||
"name": tenant.name,
|
||||
},
|
||||
message="租户已删除"
|
||||
)
|
||||
|
||||
|
||||
@router.put("/tenants/{tenant_id}/status", response_model=SuccessResponse)
|
||||
async def update_tenant_status(
|
||||
tenant_id: str,
|
||||
req: UpdateTenantStatusRequest,
|
||||
principal: dict = Depends(require_auth),
|
||||
db: AsyncSession = Depends(get_db)
|
||||
):
|
||||
"""
|
||||
更新租户状态
|
||||
|
||||
可设置状态：
|
||||
- active: 正常使用
|
||||
- inactive: 已停用（软删除）
|
||||
- suspended: 暂停使用（临时停用，可恢复）
|
||||
"""
|
||||
_verify_channel_permission(principal)
|
||||
channel_id = principal.get("claims", {}).get("channelId")
|
||||
|
||||
# 验证租户属于该渠道
|
||||
result = await db.execute(
|
||||
select(User).where(
|
||||
and_(
|
||||
User.id == tenant_id,
|
||||
User.channel_id == channel_id
|
||||
)
|
||||
)
|
||||
)
|
||||
tenant = result.scalar_one_or_none()
|
||||
|
||||
if not tenant:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_404_NOT_FOUND,
|
||||
detail="租户不存在或不属于该渠道"
|
||||
)
|
||||
|
||||
old_status = tenant.status
|
||||
tenant.status = req.status
|
||||
await db.commit()
|
||||
|
||||
return SuccessResponse(
|
||||
data={
|
||||
"tenantId": str(tenant.id),
|
||||
"name": tenant.name,
|
||||
"oldStatus": old_status,
|
||||
"newStatus": req.status,
|
||||
},
|
||||
message=f"租户状态已更新为 {req.status}"
|
||||
)
|
||||
|
||||
|
||||
@router.put("/tenants/{tenant_id}/permissions", response_model=SuccessResponse)
|
||||
async def update_tenant_permissions(
|
||||
tenant_id: str,
|
||||
req: UpdateTenantPermissionsRequest,
|
||||
principal: dict = Depends(require_auth),
|
||||
db: AsyncSession = Depends(get_db)
|
||||
):
|
||||
"""
|
||||
更新租户权限
|
||||
|
||||
可配置的权限列表包括：
|
||||
- use:platform_agents - 使用平台Agent
|
||||
- use:custom_agents - 使用自定义Agent
|
||||
- create:agents - 创建Agent
|
||||
- read:billing - 查看计费信息
|
||||
- export:data - 导出数据
|
||||
"""
|
||||
_verify_channel_permission(principal)
|
||||
channel_id = principal.get("claims", {}).get("channelId")
|
||||
|
||||
# 验证租户属于该渠道
|
||||
result = await db.execute(
|
||||
select(User).where(
|
||||
and_(
|
||||
User.id == tenant_id,
|
||||
User.channel_id == channel_id
|
||||
)
|
||||
)
|
||||
)
|
||||
tenant = result.scalar_one_or_none()
|
||||
|
||||
if not tenant:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_404_NOT_FOUND,
|
||||
detail="租户不存在或不属于该渠道"
|
||||
)
|
||||
|
||||
# 有效权限列表
|
||||
valid_permissions = {
|
||||
"use:platform_agents",
|
||||
"use:custom_agents",
|
||||
"create:agents",
|
||||
"read:billing",
|
||||
"export:data",
|
||||
}
|
||||
|
||||
# 验证权限
|
||||
invalid_permissions = set(req.permissions) - valid_permissions
|
||||
if invalid_permissions:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_400_BAD_REQUEST,
|
||||
detail=f"无效的权限: {', '.join(invalid_permissions)}"
|
||||
)
|
||||
|
||||
# 更新用户的permissions字段（假设User模型有permissions JSON字段）
|
||||
# 如果没有该字段，可以存储在metadata或创建新表
|
||||
tenant.permissions = req.permissions
|
||||
await db.commit()
|
||||
|
||||
return SuccessResponse(
|
||||
data={
|
||||
"tenantId": str(tenant.id),
|
||||
"name": tenant.name,
|
||||
"permissions": req.permissions,
|
||||
},
|
||||
message="租户权限已更新"
|
||||
)
|
||||
|
||||
|
||||
# ============= 资源申请 =============
|
||||
|
||||
@router.post("/resources/apply", response_model=SuccessResponse)
|
||||
|
||||
@@ -564,6 +564,91 @@ async def channel_update_tenant_billing(tenant_id: str, payload: Dict[str, Any],
|
||||
}
|
||||
|
||||
|
||||
@router.delete("/channel/tenants/{tenant_id}")
|
||||
async def channel_delete_tenant(tenant_id: str, db: AsyncSession = Depends(get_db)) -> Dict[str, Any]:
|
||||
"""删除租户（软删除）"""
|
||||
tenant = await db.get(Tenant, uuid.UUID(tenant_id)) if tenant_id else None
|
||||
if not tenant:
|
||||
raise HTTPException(status_code=404, detail="tenant not found")
|
||||
|
||||
# 软删除：标记为不活跃
|
||||
tenant.status = "inactive"
|
||||
db.add(tenant)
|
||||
await db.commit()
|
||||
|
||||
return {
|
||||
"id": str(tenant.id),
|
||||
"name": tenant.name,
|
||||
"deleted": True,
|
||||
"message": "租户已删除"
|
||||
}
|
||||
|
||||
|
||||
@router.put("/channel/tenants/{tenant_id}/status")
|
||||
async def channel_update_tenant_status(tenant_id: str, payload: Dict[str, Any], db: AsyncSession = Depends(get_db)) -> Dict[str, Any]:
|
||||
"""更新租户状态"""
|
||||
tenant = await db.get(Tenant, uuid.UUID(tenant_id)) if tenant_id else None
|
||||
if not tenant:
|
||||
raise HTTPException(status_code=404, detail="tenant not found")
|
||||
|
||||
new_status = payload.get("status")
|
||||
if new_status not in ["active", "inactive", "suspended"]:
|
||||
raise HTTPException(status_code=400, detail="status must be active, inactive, or suspended")
|
||||
|
||||
old_status = tenant.status
|
||||
tenant.status = new_status
|
||||
db.add(tenant)
|
||||
await db.commit()
|
||||
await db.refresh(tenant)
|
||||
|
||||
return {
|
||||
"tenantId": str(tenant.id),
|
||||
"name": tenant.name,
|
||||
"oldStatus": old_status,
|
||||
"newStatus": new_status,
|
||||
}
|
||||
|
||||
|
||||
@router.put("/channel/tenants/{tenant_id}/permissions")
|
||||
async def channel_update_tenant_permissions(tenant_id: str, payload: Dict[str, Any], db: AsyncSession = Depends(get_db)) -> Dict[str, Any]:
|
||||
"""更新租户权限"""
|
||||
tenant = await db.get(Tenant, uuid.UUID(tenant_id)) if tenant_id else None
|
||||
if not tenant:
|
||||
raise HTTPException(status_code=404, detail="tenant not found")
|
||||
|
||||
permissions = payload.get("permissions", [])
|
||||
|
||||
# 有效权限列表
|
||||
valid_permissions = {
|
||||
"use:platform_agents",
|
||||
"use:custom_agents",
|
||||
"create:agents",
|
||||
"read:billing",
|
||||
"export:data",
|
||||
}
|
||||
|
||||
# 验证权限
|
||||
invalid_permissions = set(permissions) - valid_permissions
|
||||
if invalid_permissions:
|
||||
raise HTTPException(
|
||||
status_code=400,
|
||||
detail=f"无效的权限: {', '.join(invalid_permissions)}"
|
||||
)
|
||||
|
||||
# 更新权限（存储在metadata中如果没有专门的permissions字段）
|
||||
if hasattr(tenant, 'permissions'):
|
||||
tenant.permissions = permissions
|
||||
|
||||
db.add(tenant)
|
||||
await db.commit()
|
||||
|
||||
return {
|
||||
"tenantId": str(tenant.id),
|
||||
"name": tenant.name,
|
||||
"permissions": permissions,
|
||||
}
|
||||
|
||||
|
||||
@router.get("/channel/resources/agents")
|
||||
async def channel_resources_agents(db: AsyncSession = Depends(get_db)) -> Dict[str, Any]:
|
||||
quotas = (await db.execute(select(ChannelAgentQuota))).scalars().all()
|
||||
@@ -653,7 +738,8 @@ async def admin_login(payload: Dict[str, str], db: AsyncSession = Depends(get_db
|
||||
user.is_admin = True
|
||||
db.add(user)
|
||||
await db.commit()
|
||||
token = create_access_token({"sub": str(user.id), "email": email, "role": "super_admin"})
|
||||
# 使用用户的实际角色，而不是硬编码 super_admin
|
||||
token = create_access_token({"sub": str(user.id), "email": email, "role": user.role})
|
||||
return {"token": token, "tokenType": "bearer", "email": email, "expiresIn": 60 * 60}
|
||||
|
||||
|
||||
@@ -909,7 +995,77 @@ async def admin_billing_overview(db: AsyncSession = Depends(get_db)) -> Dict[str
|
||||
|
||||
@router.get("/admin/roles")
|
||||
async def admin_roles() -> Dict[str, Any]:
|
||||
return {"items": ["billing_admin", "operations_admin", "super_admin"]}
|
||||
"""获取可用角色列表"""
|
||||
return {
|
||||
"items": [
|
||||
{
|
||||
"id": "super_admin",
|
||||
"name": "超级管理员",
|
||||
"description": "拥有系统所有权限",
|
||||
"permissions": ["*"]
|
||||
},
|
||||
{
|
||||
"id": "billing_admin",
|
||||
"name": "计费管理员",
|
||||
"description": "完整写入权限，可创建渠道、管理租户、计费操作",
|
||||
"permissions": ["read:*", "write:channels", "write:tenants", "write:billing"]
|
||||
},
|
||||
{
|
||||
"id": "operations_admin",
|
||||
"name": "运维管理员",
|
||||
"description": "只读权限，仅查看和监控",
|
||||
"permissions": ["read:*"]
|
||||
},
|
||||
{
|
||||
"id": "channel_admin",
|
||||
"name": "渠道管理员",
|
||||
"description": "渠道内部管理权限",
|
||||
"permissions": ["read:channel", "write:tenants", "read:billing"]
|
||||
},
|
||||
{
|
||||
"id": "user",
|
||||
"name": "普通用户",
|
||||
"description": "标准用户权限",
|
||||
"permissions": ["read:self", "use:agents"]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
@router.get("/admin/channels/{channel_id}/admins")
|
||||
async def admin_get_channel_admins(channel_id: str, db: AsyncSession = Depends(get_db)) -> Dict[str, Any]:
|
||||
"""获取渠道管理员列表"""
|
||||
from models import User
|
||||
channel = await db.get(Channel, uuid.UUID(channel_id)) if channel_id else None
|
||||
if not channel:
|
||||
raise HTTPException(status_code=404, detail="channel not found")
|
||||
|
||||
# 查询渠道下的管理员
|
||||
admins = (await db.execute(
|
||||
select(User).where(
|
||||
User.channel_id == channel.id,
|
||||
User.role == "channel_admin",
|
||||
User.status == "active"
|
||||
)
|
||||
)).scalars().all()
|
||||
|
||||
items = [
|
||||
{
|
||||
"id": str(admin.id),
|
||||
"name": admin.name or admin.full_name,
|
||||
"email": admin.email,
|
||||
"role": admin.role,
|
||||
"status": admin.status,
|
||||
"createdAt": admin.created_at.isoformat() if admin.created_at else None,
|
||||
}
|
||||
for admin in admins
|
||||
]
|
||||
|
||||
return {
|
||||
"channelId": str(channel.id),
|
||||
"channelName": channel.name,
|
||||
"admins": items
|
||||
}
|
||||
|
||||
|
||||
@router.post("/admin/admins/create")
|
||||
|
||||
@@ -565,3 +565,39 @@ class ChannelProviderAccessInfo(BaseModel):
|
||||
approvedAt: Optional[str]
|
||||
expiresAt: Optional[str]
|
||||
|
||||
|
||||
# ============= 租户管理扩展 =============
|
||||
|
||||
class UpdateTenantStatusRequest(BaseModel):
|
||||
"""更新租户状态请求"""
|
||||
status: str = Field(..., pattern="^(active|inactive|suspended)$")
|
||||
|
||||
|
||||
class UpdateTenantPermissionsRequest(BaseModel):
|
||||
"""更新租户权限请求"""
|
||||
permissions: List[str] = Field(default_factory=list, description="租户权限列表")
|
||||
|
||||
|
||||
class TenantInfo(BaseModel):
|
||||
"""租户信息"""
|
||||
id: str
|
||||
name: str
|
||||
email: str
|
||||
subscriptionTier: str
|
||||
balance: float
|
||||
creditLimit: float
|
||||
status: str
|
||||
permissions: Optional[List[str]] = None
|
||||
createdAt: str
|
||||
|
||||
|
||||
class ChannelAdminInfo(BaseModel):
|
||||
"""渠道管理员信息"""
|
||||
id: str
|
||||
name: str
|
||||
email: str
|
||||
role: str
|
||||
status: str
|
||||
permissions: Optional[List[str]] = None
|
||||
createdAt: Optional[str] = None
|
||||
|
||||
|
||||
@@ -0,0 +1,176 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
MCP Server 基础使用示例
|
||||
演示健康检查、Agent 创建、查询和列表功能
|
||||
"""
|
||||
|
||||
import requests
|
||||
import json
|
||||
from typing import Optional
|
||||
|
||||
# 配置
|
||||
BASE_URL = "http://localhost:8002"
|
||||
API_KEY = "test-api-key" # 替换为实际的 API Key
|
||||
|
||||
# 请求头
|
||||
HEADERS = {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-Key": API_KEY
|
||||
}
|
||||
|
||||
|
||||
def health_check() -> dict:
|
||||
"""健康检查"""
|
||||
print("\n=== 1. 健康检查 ===")
|
||||
response = requests.get(f"{BASE_URL}/health")
|
||||
data = response.json()
|
||||
print(f"状态: {response.status_code}")
|
||||
print(f"响应: {json.dumps(data, indent=2, ensure_ascii=False)}")
|
||||
return data
|
||||
|
||||
|
||||
def create_agent() -> Optional[dict]:
|
||||
"""创建一个 Agent"""
|
||||
print("\n=== 2. 创建 Agent ===")
|
||||
|
||||
agent_data = {
|
||||
"name": "weather-agent",
|
||||
"description": "Weather information agent",
|
||||
"role": "assistant",
|
||||
"goal": "Provide real-time weather summaries",
|
||||
"tools": ["get_weather"],
|
||||
"config": {
|
||||
"default_model": "gpt-4o-mini"
|
||||
},
|
||||
"capabilities": ["weather_query", "location_search"]
|
||||
}
|
||||
|
||||
print(f"请求数据: {json.dumps(agent_data, indent=2, ensure_ascii=False)}")
|
||||
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/agents",
|
||||
json=agent_data,
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
print(f"状态: {response.status_code}")
|
||||
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
print(f"成功创建 Agent:")
|
||||
print(f" - ID: {data['id']}")
|
||||
print(f" - 名称: {data['name']}")
|
||||
print(f" - 状态: {data['status']}")
|
||||
print(f" - 端点:")
|
||||
for endpoint_type, url in data['endpoints'].items():
|
||||
print(f" {endpoint_type}: {url}")
|
||||
return data
|
||||
else:
|
||||
print(f"创建失败: {response.text}")
|
||||
return None
|
||||
|
||||
|
||||
def list_agents() -> list:
|
||||
"""获取 Agent 列表"""
|
||||
print("\n=== 3. 获取 Agent 列表 ===")
|
||||
|
||||
response = requests.get(
|
||||
f"{BASE_URL}/agents?skip=0&limit=20",
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
print(f"状态: {response.status_code}")
|
||||
|
||||
if response.status_code == 200:
|
||||
agents = response.json()
|
||||
print(f"找到 {len(agents)} 个 Agent:")
|
||||
for agent in agents:
|
||||
print(f" - {agent['name']} (ID: {agent['id']})")
|
||||
print(f" 状态: {agent['status']}, 执行次数: {agent['total_executions']}")
|
||||
return agents
|
||||
else:
|
||||
print(f"获取失败: {response.text}")
|
||||
return []
|
||||
|
||||
|
||||
def get_agent(agent_id: str) -> Optional[dict]:
|
||||
"""获取特定 Agent 的详细信息"""
|
||||
print(f"\n=== 4. 获取 Agent 详情 (ID: {agent_id}) ===")
|
||||
|
||||
response = requests.get(
|
||||
f"{BASE_URL}/agents/{agent_id}",
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
print(f"状态: {response.status_code}")
|
||||
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
print(f"Agent 详情:")
|
||||
print(json.dumps(data, indent=2, ensure_ascii=False))
|
||||
return data
|
||||
else:
|
||||
print(f"获取失败: {response.text}")
|
||||
return None
|
||||
|
||||
|
||||
def get_tools() -> list:
|
||||
"""获取工具列表"""
|
||||
print("\n=== 5. 获取工具列表 ===")
|
||||
|
||||
response = requests.get(
|
||||
f"{BASE_URL}/tools",
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
print(f"状态: {response.status_code}")
|
||||
|
||||
if response.status_code == 200:
|
||||
tools = response.json()
|
||||
print(f"工具列表: {json.dumps(tools, indent=2, ensure_ascii=False)}")
|
||||
return tools
|
||||
else:
|
||||
print(f"获取失败: {response.text}")
|
||||
return []
|
||||
|
||||
|
||||
def main():
|
||||
"""主函数"""
|
||||
print("=" * 60)
|
||||
print("MCP Server 基础使用示例")
|
||||
print("=" * 60)
|
||||
|
||||
try:
|
||||
# 1. 健康检查
|
||||
health_data = health_check()
|
||||
|
||||
# 2. 创建 Agent
|
||||
agent = create_agent()
|
||||
|
||||
# 3. 获取 Agent 列表
|
||||
agents = list_agents()
|
||||
|
||||
# 4. 获取 Agent 详情（使用刚创建的 Agent）
|
||||
if agent:
|
||||
get_agent(agent['id'])
|
||||
elif agents:
|
||||
get_agent(agents[0]['id'])
|
||||
|
||||
# 5. 获取工具列表
|
||||
get_tools()
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print("所有示例执行完成！")
|
||||
print("=" * 60)
|
||||
|
||||
except requests.exceptions.ConnectionError:
|
||||
print("\n❌ 错误: 无法连接到 MCP Server")
|
||||
print("请确保服务正在运行: docker-compose up -d mcp-server")
|
||||
except Exception as e:
|
||||
print(f"\n❌ 发生错误: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,362 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Agent 管理完整示例
|
||||
演示 Agent 的创建、更新、查询、执行和删除完整生命周期
|
||||
"""
|
||||
|
||||
import requests
|
||||
import json
|
||||
import time
|
||||
from typing import Optional
|
||||
|
||||
# 配置
|
||||
BASE_URL = "http://localhost:8002"
|
||||
API_KEY = "test-api-key"
|
||||
|
||||
HEADERS = {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-Key": API_KEY
|
||||
}
|
||||
|
||||
|
||||
class AgentManager:
|
||||
"""Agent 管理器"""
|
||||
|
||||
def __init__(self, base_url: str, api_key: str):
|
||||
self.base_url = base_url
|
||||
self.headers = {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-Key": api_key
|
||||
}
|
||||
|
||||
def create_agent(self, name: str, description: str, tools: list, **kwargs) -> Optional[dict]:
|
||||
"""创建 Agent"""
|
||||
print(f"\n创建 Agent: {name}")
|
||||
|
||||
agent_data = {
|
||||
"name": name,
|
||||
"description": description,
|
||||
"role": kwargs.get("role", "assistant"),
|
||||
"goal": kwargs.get("goal", ""),
|
||||
"tools": tools,
|
||||
"config": kwargs.get("config", {}),
|
||||
"capabilities": kwargs.get("capabilities", [])
|
||||
}
|
||||
|
||||
response = requests.post(
|
||||
f"{self.base_url}/agents",
|
||||
json=agent_data,
|
||||
headers=self.headers
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
agent = response.json()
|
||||
print(f"✓ 创建成功")
|
||||
print(f" ID: {agent['id']}")
|
||||
print(f" 状态: {agent['status']}")
|
||||
return agent
|
||||
else:
|
||||
print(f"✗ 创建失败: {response.text}")
|
||||
return None
|
||||
|
||||
def get_agent(self, agent_id: str) -> Optional[dict]:
|
||||
"""获取 Agent 详情"""
|
||||
print(f"\n获取 Agent: {agent_id}")
|
||||
|
||||
response = requests.get(
|
||||
f"{self.base_url}/agents/{agent_id}",
|
||||
headers=self.headers
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
agent = response.json()
|
||||
print(f"✓ 获取成功")
|
||||
print(f" 名称: {agent['name']}")
|
||||
print(f" 状态: {agent['status']}")
|
||||
print(f" 执行次数: {agent['total_executions']}")
|
||||
print(f" 成功率: {agent['success_rate']:.1f}%")
|
||||
return agent
|
||||
else:
|
||||
print(f"✗ 获取失败: {response.text}")
|
||||
return None
|
||||
|
||||
def list_agents(self, skip: int = 0, limit: int = 10) -> list:
|
||||
"""列出所有 Agent"""
|
||||
print(f"\n获取 Agent 列表 (skip={skip}, limit={limit})")
|
||||
|
||||
response = requests.get(
|
||||
f"{self.base_url}/agents?skip={skip}&limit={limit}",
|
||||
headers=self.headers
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
agents = response.json()
|
||||
print(f"✓ 找到 {len(agents)} 个 Agent")
|
||||
for i, agent in enumerate(agents, 1):
|
||||
print(f" {i}. {agent['name']} ({agent['id'][:8]}...) - {agent['status']}")
|
||||
return agents
|
||||
else:
|
||||
print(f"✗ 获取失败: {response.text}")
|
||||
return []
|
||||
|
||||
def execute_tool(self, agent_id: str, tool_name: str, arguments: dict) -> Optional[dict]:
|
||||
"""执行工具"""
|
||||
print(f"\n执行工具: {tool_name}")
|
||||
print(f" Agent: {agent_id[:8]}...")
|
||||
print(f" 参数: {json.dumps(arguments, ensure_ascii=False)}")
|
||||
|
||||
request_data = {
|
||||
"jsonrpc": "2.0",
|
||||
"id": f"req-{int(time.time())}",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {
|
||||
"name": tool_name,
|
||||
"function_name": tool_name
|
||||
},
|
||||
"arguments": arguments,
|
||||
"context": {}
|
||||
}
|
||||
}
|
||||
|
||||
response = requests.post(
|
||||
f"{self.base_url}/agents/{agent_id}/execute",
|
||||
json=request_data,
|
||||
headers=self.headers
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
result = response.json()
|
||||
print(f"✓ 执行成功")
|
||||
print(f" 结果: {result.get('result')}")
|
||||
print(f" 执行时间: {result.get('execution_time', 0):.3f}s")
|
||||
print(f" EU 消耗: {result.get('eu_consumed', 0):.4f}")
|
||||
return result
|
||||
else:
|
||||
print(f"✗ 执行失败: {response.text}")
|
||||
return None
|
||||
|
||||
def get_agent_statistics(self, agent_id: str) -> dict:
|
||||
"""获取 Agent 统计信息"""
|
||||
agent = self.get_agent(agent_id)
|
||||
if not agent:
|
||||
return {}
|
||||
|
||||
return {
|
||||
"total_executions": agent.get("total_executions", 0),
|
||||
"success_rate": agent.get("success_rate", 0),
|
||||
"avg_execution_time": agent.get("avg_execution_time", 0),
|
||||
}
|
||||
|
||||
|
||||
def demo_data_processing_agent():
|
||||
"""演示数据处理 Agent"""
|
||||
print("\n" + "=" * 70)
|
||||
print("示例 1: 数据处理 Agent")
|
||||
print("=" * 70)
|
||||
|
||||
manager = AgentManager(BASE_URL, API_KEY)
|
||||
|
||||
# 创建数据处理 Agent
|
||||
agent = manager.create_agent(
|
||||
name=f"data-processor-{int(time.time())}",
|
||||
description="Data processing and transformation agent",
|
||||
tools=["string_upper", "string_lower", "string_replace", "json_parse", "json_stringify"],
|
||||
role="assistant",
|
||||
goal="Process and transform data",
|
||||
capabilities=["text_processing", "json_handling"]
|
||||
)
|
||||
|
||||
if not agent:
|
||||
return
|
||||
|
||||
agent_id = agent['id']
|
||||
|
||||
# 执行一些数据处理任务
|
||||
print("\n执行数据处理任务...")
|
||||
|
||||
# 1. 文本转换
|
||||
manager.execute_tool(agent_id, "string_upper", {"s": "convert to uppercase"})
|
||||
|
||||
# 2. 文本替换
|
||||
manager.execute_tool(agent_id, "string_replace",
|
||||
{"s": "Hello World", "old": "World", "new": "Agent"})
|
||||
|
||||
# 3. JSON 处理
|
||||
manager.execute_tool(agent_id, "json_parse",
|
||||
{"s": '{"status": "success", "count": 42}'})
|
||||
|
||||
# 查看统计
|
||||
time.sleep(1)
|
||||
stats = manager.get_agent_statistics(agent_id)
|
||||
print(f"\nAgent 统计:")
|
||||
print(f" 执行次数: {stats.get('total_executions', 0)}")
|
||||
print(f" 成功率: {stats.get('success_rate', 0):.1f}%")
|
||||
|
||||
|
||||
def demo_math_calculator_agent():
|
||||
"""演示数学计算 Agent"""
|
||||
print("\n" + "=" * 70)
|
||||
print("示例 2: 数学计算 Agent")
|
||||
print("=" * 70)
|
||||
|
||||
manager = AgentManager(BASE_URL, API_KEY)
|
||||
|
||||
# 创建数学计算 Agent
|
||||
agent = manager.create_agent(
|
||||
name=f"calculator-{int(time.time())}",
|
||||
description="Mathematical calculation agent",
|
||||
tools=["math_add", "math_subtract", "math_multiply", "math_divide", "math_power"],
|
||||
role="assistant",
|
||||
goal="Perform mathematical calculations",
|
||||
capabilities=["arithmetic", "advanced_math"]
|
||||
)
|
||||
|
||||
if not agent:
|
||||
return
|
||||
|
||||
agent_id = agent['id']
|
||||
|
||||
# 执行一系列计算
|
||||
print("\n执行计算任务...")
|
||||
|
||||
# 计算: (10 + 20) * 3
|
||||
result1 = manager.execute_tool(agent_id, "math_add", {"a": 10, "b": 20})
|
||||
if result1:
|
||||
sum_val = result1.get('result')
|
||||
manager.execute_tool(agent_id, "math_multiply", {"a": sum_val, "b": 3})
|
||||
|
||||
# 计算: 2^10
|
||||
manager.execute_tool(agent_id, "math_power", {"a": 2, "b": 10})
|
||||
|
||||
# 计算: 100 / 4
|
||||
manager.execute_tool(agent_id, "math_divide", {"a": 100, "b": 4})
|
||||
|
||||
# 查看统计
|
||||
time.sleep(1)
|
||||
stats = manager.get_agent_statistics(agent_id)
|
||||
print(f"\nAgent 统计:")
|
||||
print(f" 执行次数: {stats.get('total_executions', 0)}")
|
||||
print(f" 平均执行时间: {stats.get('avg_execution_time', 0):.3f}s")
|
||||
|
||||
|
||||
def demo_security_agent():
|
||||
"""演示安全处理 Agent"""
|
||||
print("\n" + "=" * 70)
|
||||
print("示例 3: 安全处理 Agent")
|
||||
print("=" * 70)
|
||||
|
||||
manager = AgentManager(BASE_URL, API_KEY)
|
||||
|
||||
# 创建安全 Agent
|
||||
agent = manager.create_agent(
|
||||
name=f"security-agent-{int(time.time())}",
|
||||
description="Security and encryption agent",
|
||||
tools=["hash_md5", "hash_sha256", "base64_encode", "base64_decode"],
|
||||
role="assistant",
|
||||
goal="Perform security operations",
|
||||
capabilities=["hashing", "encoding"]
|
||||
)
|
||||
|
||||
if not agent:
|
||||
return
|
||||
|
||||
agent_id = agent['id']
|
||||
|
||||
# 执行安全任务
|
||||
print("\n执行安全任务...")
|
||||
|
||||
# 1. 生成密码哈希
|
||||
password = "MySecurePassword123"
|
||||
manager.execute_tool(agent_id, "hash_sha256", {"s": password})
|
||||
|
||||
# 2. Base64 编码/解码
|
||||
data = "Sensitive Data"
|
||||
result = manager.execute_tool(agent_id, "base64_encode", {"s": data})
|
||||
if result and result.get('success'):
|
||||
encoded = result.get('result')
|
||||
manager.execute_tool(agent_id, "base64_decode", {"s": encoded})
|
||||
|
||||
# 3. 文件校验
|
||||
file_content = "File content for verification"
|
||||
manager.execute_tool(agent_id, "hash_md5", {"s": file_content})
|
||||
|
||||
|
||||
def demo_batch_operations():
|
||||
"""演示批量操作"""
|
||||
print("\n" + "=" * 70)
|
||||
print("示例 4: 批量操作")
|
||||
print("=" * 70)
|
||||
|
||||
manager = AgentManager(BASE_URL, API_KEY)
|
||||
|
||||
# 创建批处理 Agent
|
||||
agent = manager.create_agent(
|
||||
name=f"batch-processor-{int(time.time())}",
|
||||
description="Batch processing agent",
|
||||
tools=["math_add", "string_upper", "datetime_now"],
|
||||
role="assistant",
|
||||
goal="Process multiple tasks in batch",
|
||||
capabilities=["batch_processing"]
|
||||
)
|
||||
|
||||
if not agent:
|
||||
return
|
||||
|
||||
agent_id = agent['id']
|
||||
|
||||
# 批量执行任务
|
||||
print("\n批量执行 10 个任务...")
|
||||
|
||||
for i in range(10):
|
||||
manager.execute_tool(agent_id, "math_add", {"a": i * 10, "b": i * 5})
|
||||
time.sleep(0.1) # 避免请求过快
|
||||
|
||||
# 查看最终统计
|
||||
time.sleep(1)
|
||||
stats = manager.get_agent_statistics(agent_id)
|
||||
print(f"\n批处理完成:")
|
||||
print(f" 总执行次数: {stats.get('total_executions', 0)}")
|
||||
print(f" 成功率: {stats.get('success_rate', 0):.1f}%")
|
||||
|
||||
|
||||
def main():
|
||||
"""主函数"""
|
||||
print("=" * 70)
|
||||
print("MCP Server Agent 管理完整示例")
|
||||
print("=" * 70)
|
||||
|
||||
try:
|
||||
manager = AgentManager(BASE_URL, API_KEY)
|
||||
|
||||
# 显示现有 Agent
|
||||
print("\n当前系统中的 Agent:")
|
||||
manager.list_agents(skip=0, limit=5)
|
||||
|
||||
# 运行各种示例
|
||||
demo_data_processing_agent()
|
||||
demo_math_calculator_agent()
|
||||
demo_security_agent()
|
||||
demo_batch_operations()
|
||||
|
||||
# 显示更新后的列表
|
||||
print("\n" + "=" * 70)
|
||||
print("更新后的 Agent 列表:")
|
||||
print("=" * 70)
|
||||
manager.list_agents(skip=0, limit=10)
|
||||
|
||||
print("\n" + "=" * 70)
|
||||
print("所有示例完成！")
|
||||
print("=" * 70)
|
||||
|
||||
except requests.exceptions.ConnectionError:
|
||||
print("\n❌ 错误: 无法连接到 MCP Server")
|
||||
print("请确保服务正在运行: docker-compose up -d mcp-server")
|
||||
except Exception as e:
|
||||
print(f"\n❌ 发生错误: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,241 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
MCP Server 函数工具调用示例
|
||||
演示如何调用内置的数学、字符串、日期时间等函数工具
|
||||
"""
|
||||
|
||||
import requests
|
||||
import json
|
||||
import time
|
||||
from typing import Optional, Dict, Any
|
||||
|
||||
# 配置
|
||||
BASE_URL = "http://localhost:8002"
|
||||
API_KEY = "test-api-key"
|
||||
|
||||
HEADERS = {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-Key": API_KEY
|
||||
}
|
||||
|
||||
|
||||
def execute_tool(agent_id: str, tool_name: str, arguments: Dict[str, Any]) -> Optional[dict]:
|
||||
"""
|
||||
执行工具函数
|
||||
|
||||
Args:
|
||||
agent_id: Agent ID
|
||||
tool_name: 工具名称（例如 'math_add'）
|
||||
arguments: 工具参数
|
||||
|
||||
Returns:
|
||||
执行结果
|
||||
"""
|
||||
request_data = {
|
||||
"jsonrpc": "2.0",
|
||||
"id": f"req-{int(time.time())}",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {
|
||||
"name": tool_name,
|
||||
"function_name": tool_name
|
||||
},
|
||||
"arguments": arguments,
|
||||
"context": {
|
||||
"session_id": "example_session"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
print(f"\n执行工具: {tool_name}")
|
||||
print(f"参数: {json.dumps(arguments, ensure_ascii=False)}")
|
||||
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/agents/{agent_id}/execute",
|
||||
json=request_data,
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
result = response.json()
|
||||
print(f"✓ 成功 | 结果: {result.get('result')}")
|
||||
print(f" 执行时间: {result.get('execution_time', 0):.3f}s")
|
||||
print(f" EU 消耗: {result.get('eu_consumed', 0):.4f}")
|
||||
return result
|
||||
else:
|
||||
print(f"✗ 失败: {response.text}")
|
||||
return None
|
||||
|
||||
|
||||
def test_math_functions(agent_id: str):
|
||||
"""测试数学函数"""
|
||||
print("\n" + "=" * 60)
|
||||
print("测试数学函数")
|
||||
print("=" * 60)
|
||||
|
||||
tests = [
|
||||
("math_add", {"a": 10, "b": 20}, "10 + 20"),
|
||||
("math_subtract", {"a": 50, "b": 15}, "50 - 15"),
|
||||
("math_multiply", {"a": 6, "b": 7}, "6 × 7"),
|
||||
("math_divide", {"a": 100, "b": 4}, "100 ÷ 4"),
|
||||
("math_power", {"a": 2, "b": 8}, "2^8"),
|
||||
]
|
||||
|
||||
for tool_name, args, description in tests:
|
||||
print(f"\n{description}:")
|
||||
execute_tool(agent_id, tool_name, args)
|
||||
|
||||
|
||||
def test_string_functions(agent_id: str):
|
||||
"""测试字符串函数"""
|
||||
print("\n" + "=" * 60)
|
||||
print("测试字符串函数")
|
||||
print("=" * 60)
|
||||
|
||||
tests = [
|
||||
("string_upper", {"s": "hello world"}, "转大写"),
|
||||
("string_lower", {"s": "HELLO WORLD"}, "转小写"),
|
||||
("string_length", {"s": "Hello, 世界!"}, "字符串长度"),
|
||||
("string_replace", {"s": "Hello World", "old": "World", "new": "MCP"}, "替换子串"),
|
||||
]
|
||||
|
||||
for tool_name, args, description in tests:
|
||||
print(f"\n{description}:")
|
||||
execute_tool(agent_id, tool_name, args)
|
||||
|
||||
|
||||
def test_datetime_functions(agent_id: str):
|
||||
"""测试日期时间函数"""
|
||||
print("\n" + "=" * 60)
|
||||
print("测试日期时间函数")
|
||||
print("=" * 60)
|
||||
|
||||
print("\n获取当前时间:")
|
||||
execute_tool(agent_id, "datetime_now", {})
|
||||
|
||||
|
||||
def test_json_functions(agent_id: str):
|
||||
"""测试 JSON 函数"""
|
||||
print("\n" + "=" * 60)
|
||||
print("测试 JSON 函数")
|
||||
print("=" * 60)
|
||||
|
||||
# JSON 解析
|
||||
print("\n解析 JSON:")
|
||||
json_str = '{"name": "test", "value": 123}'
|
||||
execute_tool(agent_id, "json_parse", {"s": json_str})
|
||||
|
||||
# JSON 序列化
|
||||
print("\n序列化对象:")
|
||||
obj = {"name": "test", "items": [1, 2, 3]}
|
||||
execute_tool(agent_id, "json_stringify", {"obj": obj})
|
||||
|
||||
|
||||
def test_hash_functions(agent_id: str):
|
||||
"""测试哈希函数"""
|
||||
print("\n" + "=" * 60)
|
||||
print("测试哈希函数")
|
||||
print("=" * 60)
|
||||
|
||||
test_string = "Hello, MCP Server!"
|
||||
|
||||
print("\nMD5 哈希:")
|
||||
execute_tool(agent_id, "hash_md5", {"s": test_string})
|
||||
|
||||
print("\nSHA256 哈希:")
|
||||
execute_tool(agent_id, "hash_sha256", {"s": test_string})
|
||||
|
||||
|
||||
def test_base64_functions(agent_id: str):
|
||||
"""测试 Base64 编码/解码"""
|
||||
print("\n" + "=" * 60)
|
||||
print("测试 Base64 编码/解码")
|
||||
print("=" * 60)
|
||||
|
||||
test_string = "Hello, MCP Server! 你好，世界！"
|
||||
|
||||
print("\nBase64 编码:")
|
||||
result = execute_tool(agent_id, "base64_encode", {"s": test_string})
|
||||
|
||||
if result and result.get("success"):
|
||||
encoded = result.get("result")
|
||||
print(f"\n编码结果: {encoded}")
|
||||
|
||||
print("\nBase64 解码:")
|
||||
execute_tool(agent_id, "base64_decode", {"s": encoded})
|
||||
|
||||
|
||||
def create_test_agent() -> Optional[str]:
|
||||
"""创建测试用的 Agent"""
|
||||
print("\n创建测试 Agent...")
|
||||
|
||||
agent_data = {
|
||||
"name": f"function-test-agent-{int(time.time())}",
|
||||
"description": "Agent for testing function tools",
|
||||
"role": "assistant",
|
||||
"goal": "Test all built-in function tools",
|
||||
"tools": [
|
||||
"math_add", "math_subtract", "math_multiply", "math_divide", "math_power",
|
||||
"string_upper", "string_lower", "string_length", "string_replace",
|
||||
"datetime_now", "json_parse", "json_stringify",
|
||||
"hash_md5", "hash_sha256", "base64_encode", "base64_decode"
|
||||
],
|
||||
"config": {},
|
||||
"capabilities": ["function_execution"]
|
||||
}
|
||||
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/agents",
|
||||
json=agent_data,
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
agent = response.json()
|
||||
agent_id = agent['id']
|
||||
print(f"✓ Agent 创建成功: {agent_id}")
|
||||
return agent_id
|
||||
else:
|
||||
print(f"✗ Agent 创建失败: {response.text}")
|
||||
return None
|
||||
|
||||
|
||||
def main():
|
||||
"""主函数"""
|
||||
print("=" * 60)
|
||||
print("MCP Server 函数工具测试")
|
||||
print("=" * 60)
|
||||
|
||||
try:
|
||||
# 创建测试 Agent
|
||||
agent_id = create_test_agent()
|
||||
|
||||
if not agent_id:
|
||||
print("\n无法创建测试 Agent，退出")
|
||||
return
|
||||
|
||||
# 运行所有测试
|
||||
test_math_functions(agent_id)
|
||||
test_string_functions(agent_id)
|
||||
test_datetime_functions(agent_id)
|
||||
test_json_functions(agent_id)
|
||||
test_hash_functions(agent_id)
|
||||
test_base64_functions(agent_id)
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print("所有函数工具测试完成！")
|
||||
print("=" * 60)
|
||||
print(f"\n测试 Agent ID: {agent_id}")
|
||||
print("可在监控面板查看详细的执行统计")
|
||||
|
||||
except requests.exceptions.ConnectionError:
|
||||
print("\n❌ 错误: 无法连接到 MCP Server")
|
||||
print("请确保服务正在运行: docker-compose up -d mcp-server")
|
||||
except Exception as e:
|
||||
print(f"\n❌ 发生错误: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,265 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
MCP Server 监控 API 使用示例
|
||||
演示如何使用监控接口获取系统指标、统计信息、趋势数据和告警
|
||||
"""
|
||||
|
||||
import requests
|
||||
import json
|
||||
from typing import Optional
|
||||
|
||||
# 配置
|
||||
BASE_URL = "http://localhost:8002"
|
||||
API_KEY = "test-api-key"
|
||||
|
||||
HEADERS = {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-Key": API_KEY
|
||||
}
|
||||
|
||||
|
||||
def get_system_metrics() -> Optional[dict]:
|
||||
"""获取系统性能指标"""
|
||||
print("\n=== 1. 获取系统性能指标 ===")
|
||||
|
||||
response = requests.get(
|
||||
f"{BASE_URL}/api/v1/monitoring/metrics",
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
print(f"状态: {response.status_code}")
|
||||
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
|
||||
# 系统指标
|
||||
system = data.get('system', {})
|
||||
print("\n系统资源:")
|
||||
print(f" CPU 使用率: {system.get('cpu_usage_percent', 0):.1f}%")
|
||||
print(f" 内存使用率: {system.get('memory_usage_percent', 0):.1f}%")
|
||||
print(f" 内存使用: {system.get('memory_used_mb', 0):.0f} MB / {system.get('memory_total_mb', 0):.0f} MB")
|
||||
print(f" 磁盘使用率: {system.get('disk_usage_percent', 0):.1f}%")
|
||||
print(f" 磁盘使用: {system.get('disk_used_gb', 0):.1f} GB / {system.get('disk_total_gb', 0):.1f} GB")
|
||||
|
||||
# 服务指标
|
||||
services = data.get('services', {})
|
||||
print("\n服务统计:")
|
||||
print(f" 活跃 Agent: {services.get('active_agents', 0)}")
|
||||
print(f" 24h 执行次数: {services.get('total_executions_24h', 0)}")
|
||||
print(f" 成功率: {services.get('success_rate_percent', 0):.1f}%")
|
||||
print(f" 平均执行时间: {services.get('avg_execution_time_ms', 0):.2f} ms")
|
||||
print(f" 日活用户: {services.get('daily_active_users', 0)}")
|
||||
|
||||
# 计费信息
|
||||
billing = data.get('billing', {})
|
||||
print("\n计费统计:")
|
||||
print(f" 24h EU 消耗: {billing.get('total_eu_consumed_24h', 0):.2f}")
|
||||
print(f" 24h 费用: ${billing.get('total_cost_24h', 0):.2f}")
|
||||
|
||||
return data
|
||||
else:
|
||||
print(f"获取失败: {response.text}")
|
||||
return None
|
||||
|
||||
|
||||
def get_service_stats(service: str = "all") -> Optional[dict]:
|
||||
"""获取服务统计信息"""
|
||||
print(f"\n=== 2. 获取服务统计 (service={service}) ===")
|
||||
|
||||
response = requests.get(
|
||||
f"{BASE_URL}/api/v1/monitoring/stats?service={service}",
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
print(f"状态: {response.status_code}")
|
||||
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
stats = data.get('stats', {})
|
||||
|
||||
# Agent 统计
|
||||
if 'agents' in stats:
|
||||
agents = stats['agents']
|
||||
print("\nAgent 统计:")
|
||||
print(f" 总数: {agents.get('total', 0)}")
|
||||
print(f" 活跃: {agents.get('active', 0)}")
|
||||
print(f" 非活跃: {agents.get('inactive', 0)}")
|
||||
print(f" 平均执行次数: {agents.get('avg_executions', 0):.1f}")
|
||||
print(f" 平均成功率: {agents.get('avg_success_rate', 0):.1f}%")
|
||||
|
||||
# 执行统计
|
||||
if 'executions' in stats:
|
||||
executions = stats['executions']
|
||||
print("\n执行统计 (7天):")
|
||||
print(f" 总执行次数: {executions.get('total_7d', 0)}")
|
||||
print(f" 已完成: {executions.get('completed', 0)}")
|
||||
print(f" 失败: {executions.get('failed', 0)}")
|
||||
print(f" 运行中: {executions.get('running', 0)}")
|
||||
|
||||
return data
|
||||
else:
|
||||
print(f"获取失败: {response.text}")
|
||||
return None
|
||||
|
||||
|
||||
def get_performance_trends(
|
||||
metric: str = "executions",
|
||||
period: str = "24h",
|
||||
interval: str = "1h"
|
||||
) -> Optional[dict]:
|
||||
"""获取性能趋势数据"""
|
||||
print(f"\n=== 3. 获取性能趋势 (metric={metric}, period={period}, interval={interval}) ===")
|
||||
|
||||
response = requests.get(
|
||||
f"{BASE_URL}/api/v1/monitoring/trends?metric={metric}&period={period}&interval={interval}",
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
print(f"状态: {response.status_code}")
|
||||
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
|
||||
print(f"\n指标: {data.get('metric')}")
|
||||
print(f"周期: {data.get('period')}")
|
||||
print(f"间隔: {data.get('interval')}")
|
||||
|
||||
trend_data = data.get('data', [])
|
||||
print(f"\n数据点数量: {len(trend_data)}")
|
||||
|
||||
# 显示最近几个数据点
|
||||
if trend_data:
|
||||
print("\n最近的趋势数据:")
|
||||
for item in trend_data[:5]: # 只显示前5个
|
||||
print(f" {item.get('timestamp')}: 次数={item.get('count', 0)}, "
|
||||
f"平均时间={item.get('avg_time_ms', 0):.2f}ms, "
|
||||
f"成功率={item.get('success_rate', 0):.1f}%")
|
||||
|
||||
return data
|
||||
else:
|
||||
print(f"获取失败: {response.text}")
|
||||
return None
|
||||
|
||||
|
||||
def get_system_alerts(severity: Optional[str] = None) -> Optional[dict]:
|
||||
"""获取系统告警"""
|
||||
print(f"\n=== 4. 获取系统告警 (severity={severity or 'all'}) ===")
|
||||
|
||||
url = f"{BASE_URL}/api/v1/monitoring/alerts"
|
||||
if severity:
|
||||
url += f"?severity={severity}"
|
||||
|
||||
response = requests.get(url, headers=HEADERS)
|
||||
|
||||
print(f"状态: {response.status_code}")
|
||||
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
alerts = data.get('alerts', [])
|
||||
|
||||
print(f"\n告警数量: {data.get('count', 0)}")
|
||||
|
||||
if alerts:
|
||||
print("\n当前告警:")
|
||||
for alert in alerts:
|
||||
severity_icon = {
|
||||
'info': 'ℹ️',
|
||||
'warning': '⚠️',
|
||||
'critical': '🔥'
|
||||
}.get(alert.get('severity'), '•')
|
||||
|
||||
print(f" {severity_icon} [{alert.get('severity', 'unknown').upper()}] {alert.get('type')}")
|
||||
print(f" {alert.get('message')}")
|
||||
print(f" 时间: {alert.get('timestamp')}")
|
||||
else:
|
||||
print("\n✓ 无告警")
|
||||
|
||||
return data
|
||||
else:
|
||||
print(f"获取失败: {response.text}")
|
||||
return None
|
||||
|
||||
|
||||
def get_monitoring_dashboard() -> Optional[dict]:
|
||||
"""获取监控仪表盘聚合数据"""
|
||||
print("\n=== 5. 获取监控仪表盘 ===")
|
||||
|
||||
response = requests.get(
|
||||
f"{BASE_URL}/api/v1/monitoring/dashboard",
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
print(f"状态: {response.status_code}")
|
||||
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
|
||||
# 健康状态
|
||||
health = data.get('health', {})
|
||||
print(f"\n健康状态: {health.get('status', 'unknown')}")
|
||||
|
||||
# 告警摘要
|
||||
alerts = data.get('alerts', {})
|
||||
total_alerts = alerts.get('count', 0)
|
||||
critical = alerts.get('critical_count', 0)
|
||||
warning = alerts.get('warning_count', 0)
|
||||
|
||||
print(f"\n告警摘要:")
|
||||
print(f" 总数: {total_alerts}")
|
||||
print(f" 严重: {critical}")
|
||||
print(f" 警告: {warning}")
|
||||
|
||||
# 详细数据在 metrics 和 stats 中
|
||||
print("\n完整仪表盘数据已获取，包含:")
|
||||
print(" - 系统指标 (CPU, 内存, 磁盘)")
|
||||
print(" - 服务统计 (Agent, 执行, 用户)")
|
||||
print(" - 告警详情")
|
||||
|
||||
return data
|
||||
else:
|
||||
print(f"获取失败: {response.text}")
|
||||
return None
|
||||
|
||||
|
||||
def main():
|
||||
"""主函数"""
|
||||
print("=" * 60)
|
||||
print("MCP Server 监控 API 示例")
|
||||
print("=" * 60)
|
||||
|
||||
try:
|
||||
# 1. 获取系统指标
|
||||
get_system_metrics()
|
||||
|
||||
# 2. 获取服务统计
|
||||
get_service_stats("all")
|
||||
get_service_stats("agents")
|
||||
get_service_stats("executions")
|
||||
|
||||
# 3. 获取性能趋势
|
||||
get_performance_trends("executions", "24h", "1h")
|
||||
get_performance_trends("eu_consumption", "7d", "1d")
|
||||
|
||||
# 4. 获取告警
|
||||
get_system_alerts()
|
||||
get_system_alerts("warning")
|
||||
get_system_alerts("critical")
|
||||
|
||||
# 5. 获取仪表盘聚合
|
||||
get_monitoring_dashboard()
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print("所有监控 API 示例执行完成！")
|
||||
print("=" * 60)
|
||||
|
||||
except requests.exceptions.ConnectionError:
|
||||
print("\n❌ 错误: 无法连接到 MCP Server")
|
||||
print("请确保服务正在运行: docker-compose up -d mcp-server")
|
||||
except Exception as e:
|
||||
print(f"\n❌ 发生错误: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,282 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
MCP Server WebSocket 客户端示例
|
||||
演示如何通过 WebSocket 与 Agent 进行实时通信
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
import time
|
||||
import websocket
|
||||
from typing import Optional
|
||||
import threading
|
||||
|
||||
# 配置
|
||||
WEBSOCKET_URL = "ws://localhost:8002/ws/{agent_id}"
|
||||
|
||||
|
||||
class MCPWebSocketClient:
|
||||
"""MCP WebSocket 客户端"""
|
||||
|
||||
def __init__(self, agent_id: str):
|
||||
self.agent_id = agent_id
|
||||
self.url = WEBSOCKET_URL.format(agent_id=agent_id)
|
||||
self.ws: Optional[websocket.WebSocketApp] = None
|
||||
self.connected = False
|
||||
self.messages = []
|
||||
|
||||
def on_message(self, ws, message):
|
||||
"""收到消息时的回调"""
|
||||
try:
|
||||
data = json.loads(message)
|
||||
msg_type = data.get('type')
|
||||
|
||||
print(f"\n📨 收到消息 [{msg_type}]:")
|
||||
|
||||
if msg_type == 'welcome':
|
||||
print(f" 欢迎连接到 Agent: {data.get('agent_name')}")
|
||||
print(f" Agent ID: {data.get('agent_id')}")
|
||||
print(f" 时间: {data.get('timestamp')}")
|
||||
|
||||
elif msg_type == 'heartbeat':
|
||||
print(f" 心跳: {data.get('timestamp')}")
|
||||
|
||||
elif msg_type == 'pong':
|
||||
print(f" Pong 响应: {data.get('timestamp')}")
|
||||
|
||||
elif msg_type == 'mcp_response':
|
||||
payload = data.get('payload', {})
|
||||
print(f" 执行结果:")
|
||||
print(f" 成功: {payload.get('success')}")
|
||||
print(f" 结果: {payload.get('result')}")
|
||||
print(f" 执行时间: {payload.get('execution_time', 0):.3f}s")
|
||||
|
||||
elif msg_type == 'error':
|
||||
print(f" ❌ 错误: {data.get('error')}")
|
||||
if 'request_id' in data:
|
||||
print(f" 请求 ID: {data.get('request_id')}")
|
||||
|
||||
else:
|
||||
print(f" 未知消息类型: {json.dumps(data, indent=2, ensure_ascii=False)}")
|
||||
|
||||
self.messages.append(data)
|
||||
|
||||
except json.JSONDecodeError:
|
||||
print(f" 无法解析消息: {message}")
|
||||
|
||||
def on_error(self, ws, error):
|
||||
"""错误回调"""
|
||||
print(f"\n❌ WebSocket 错误: {error}")
|
||||
|
||||
def on_close(self, ws, close_status_code, close_msg):
|
||||
"""关闭回调"""
|
||||
print(f"\n🔌 WebSocket 连接已关闭")
|
||||
print(f" 状态码: {close_status_code}")
|
||||
print(f" 消息: {close_msg}")
|
||||
self.connected = False
|
||||
|
||||
def on_open(self, ws):
|
||||
"""连接建立回调"""
|
||||
print(f"\n✓ WebSocket 连接已建立")
|
||||
print(f" URL: {self.url}")
|
||||
self.connected = True
|
||||
|
||||
def connect(self):
|
||||
"""连接到 WebSocket"""
|
||||
print(f"\n连接到 WebSocket: {self.url}")
|
||||
|
||||
self.ws = websocket.WebSocketApp(
|
||||
self.url,
|
||||
on_open=self.on_open,
|
||||
on_message=self.on_message,
|
||||
on_error=self.on_error,
|
||||
on_close=self.on_close
|
||||
)
|
||||
|
||||
# 在后台线程运行
|
||||
wst = threading.Thread(target=self.ws.run_forever)
|
||||
wst.daemon = True
|
||||
wst.start()
|
||||
|
||||
# 等待连接建立
|
||||
timeout = 5
|
||||
start_time = time.time()
|
||||
while not self.connected and (time.time() - start_time) < timeout:
|
||||
time.sleep(0.1)
|
||||
|
||||
if not self.connected:
|
||||
raise TimeoutError("WebSocket 连接超时")
|
||||
|
||||
def send_ping(self):
|
||||
"""发送 ping 消息"""
|
||||
if not self.connected:
|
||||
print("未连接，无法发送消息")
|
||||
return
|
||||
|
||||
message = {
|
||||
"type": "ping"
|
||||
}
|
||||
|
||||
print(f"\n📤 发送 Ping")
|
||||
self.ws.send(json.dumps(message))
|
||||
|
||||
def execute_tool(self, tool_name: str, arguments: dict):
|
||||
"""执行工具"""
|
||||
if not self.connected:
|
||||
print("未连接，无法发送消息")
|
||||
return
|
||||
|
||||
message = {
|
||||
"type": "mcp_request",
|
||||
"payload": {
|
||||
"jsonrpc": "2.0",
|
||||
"id": f"req-{int(time.time() * 1000)}",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {
|
||||
"name": tool_name,
|
||||
"function_name": tool_name
|
||||
},
|
||||
"arguments": arguments,
|
||||
"context": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
print(f"\n📤 发送工具执行请求:")
|
||||
print(f" 工具: {tool_name}")
|
||||
print(f" 参数: {json.dumps(arguments, ensure_ascii=False)}")
|
||||
|
||||
self.ws.send(json.dumps(message))
|
||||
|
||||
def close(self):
|
||||
"""关闭连接"""
|
||||
if self.ws:
|
||||
self.ws.close()
|
||||
|
||||
|
||||
def create_test_agent() -> Optional[str]:
|
||||
"""创建测试 Agent"""
|
||||
import requests
|
||||
|
||||
print("\n创建测试 Agent...")
|
||||
|
||||
agent_data = {
|
||||
"name": f"websocket-test-agent-{int(time.time())}",
|
||||
"description": "Agent for WebSocket testing",
|
||||
"role": "assistant",
|
||||
"goal": "Test WebSocket communication",
|
||||
"tools": ["math_add", "string_upper", "datetime_now"],
|
||||
"config": {},
|
||||
"capabilities": ["websocket_communication"]
|
||||
}
|
||||
|
||||
response = requests.post(
|
||||
"http://localhost:8002/agents",
|
||||
json=agent_data,
|
||||
headers={
|
||||
"Content-Type": "application/json",
|
||||
"X-API-Key": "test-api-key"
|
||||
}
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
agent = response.json()
|
||||
agent_id = agent['id']
|
||||
print(f"✓ Agent 创建成功: {agent_id}")
|
||||
return agent_id
|
||||
else:
|
||||
print(f"✗ Agent 创建失败: {response.text}")
|
||||
return None
|
||||
|
||||
|
||||
def main():
|
||||
"""主函数"""
|
||||
print("=" * 60)
|
||||
print("MCP Server WebSocket 客户端示例")
|
||||
print("=" * 60)
|
||||
|
||||
try:
|
||||
# 创建测试 Agent
|
||||
agent_id = create_test_agent()
|
||||
|
||||
if not agent_id:
|
||||
print("\n无法创建测试 Agent，退出")
|
||||
return
|
||||
|
||||
# 创建 WebSocket 客户端
|
||||
client = MCPWebSocketClient(agent_id)
|
||||
|
||||
# 连接
|
||||
client.connect()
|
||||
|
||||
print("\n开始测试...")
|
||||
|
||||
# 等待欢迎消息
|
||||
time.sleep(1)
|
||||
|
||||
# 测试 1: 发送 ping
|
||||
print("\n" + "=" * 60)
|
||||
print("测试 1: Ping/Pong")
|
||||
print("=" * 60)
|
||||
client.send_ping()
|
||||
time.sleep(1)
|
||||
|
||||
# 测试 2: 执行数学函数
|
||||
print("\n" + "=" * 60)
|
||||
print("测试 2: 执行数学函数 (math_add)")
|
||||
print("=" * 60)
|
||||
client.execute_tool("math_add", {"a": 15, "b": 25})
|
||||
time.sleep(2)
|
||||
|
||||
# 测试 3: 执行字符串函数
|
||||
print("\n" + "=" * 60)
|
||||
print("测试 3: 执行字符串函数 (string_upper)")
|
||||
print("=" * 60)
|
||||
client.execute_tool("string_upper", {"s": "hello websocket"})
|
||||
time.sleep(2)
|
||||
|
||||
# 测试 4: 获取当前时间
|
||||
print("\n" + "=" * 60)
|
||||
print("测试 4: 获取当前时间 (datetime_now)")
|
||||
print("=" * 60)
|
||||
client.execute_tool("datetime_now", {})
|
||||
time.sleep(2)
|
||||
|
||||
# 测试 5: 连续发送多个请求
|
||||
print("\n" + "=" * 60)
|
||||
print("测试 5: 连续发送多个请求")
|
||||
print("=" * 60)
|
||||
|
||||
for i in range(3):
|
||||
client.execute_tool("math_add", {"a": i * 10, "b": i * 5})
|
||||
time.sleep(0.5)
|
||||
|
||||
time.sleep(2)
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print("WebSocket 测试完成！")
|
||||
print("=" * 60)
|
||||
print(f"\n总共收到 {len(client.messages)} 条消息")
|
||||
print(f"测试 Agent ID: {agent_id}")
|
||||
|
||||
# 关闭连接
|
||||
print("\n关闭连接...")
|
||||
client.close()
|
||||
time.sleep(1)
|
||||
|
||||
except TimeoutError as e:
|
||||
print(f"\n❌ 超时错误: {e}")
|
||||
except ConnectionRefusedError:
|
||||
print("\n❌ 错误: 无法连接到 MCP Server")
|
||||
print("请确保服务正在运行: docker-compose up -d mcp-server")
|
||||
except Exception as e:
|
||||
print(f"\n❌ 发生错误: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
# 需要安装 websocket-client
|
||||
# pip install websocket-client
|
||||
main()
|
||||
@@ -0,0 +1,274 @@
|
||||
# MCP Server 示例项目
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 安装依赖
|
||||
|
||||
```bash
|
||||
cd examples
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. 确保 MCP Server 运行
|
||||
|
||||
```bash
|
||||
# 回到项目根目录
|
||||
cd /home/taiji/tools/taiji-AI-PAD
|
||||
|
||||
# 启动服务
|
||||
docker-compose up -d mcp-server
|
||||
|
||||
# 检查服务状态
|
||||
docker-compose ps mcp-server
|
||||
```
|
||||
|
||||
### 3. 运行示例
|
||||
|
||||
```bash
|
||||
cd services/mcp-server/examples
|
||||
|
||||
# 基础使用示例
|
||||
python 01_basic_usage.py
|
||||
|
||||
# Agent 管理示例
|
||||
python 02_agent_management.py
|
||||
|
||||
# 函数工具测试
|
||||
python 03_function_tools.py
|
||||
|
||||
# 监控 API 示例
|
||||
python 04_monitoring.py
|
||||
|
||||
# WebSocket 客户端
|
||||
python 05_websocket_client.py
|
||||
|
||||
# 自动化测试所有函数
|
||||
python test_all_functions.py
|
||||
|
||||
# cURL 示例（需要安装 jq）
|
||||
bash curl_examples.sh
|
||||
```
|
||||
|
||||
## 示例说明
|
||||
|
||||
### 01_basic_usage.py
|
||||
演示 MCP Server 的基础功能：
|
||||
- 健康检查
|
||||
- 创建 Agent
|
||||
- 查询 Agent 列表
|
||||
- 获取 Agent 详情
|
||||
- 获取工具列表
|
||||
|
||||
**适用场景**：快速了解 API 基本用法
|
||||
|
||||
### 02_agent_management.py
|
||||
完整的 Agent 管理示例：
|
||||
- 数据处理 Agent
|
||||
- 数学计算 Agent
|
||||
- 安全处理 Agent
|
||||
- 批量操作示例
|
||||
|
||||
**适用场景**：了解如何在实际应用中使用 Agent
|
||||
|
||||
### 03_function_tools.py
|
||||
测试所有内置函数工具：
|
||||
- 数学函数（加减乘除、幂运算）
|
||||
- 字符串函数（大小写转换、替换等）
|
||||
- 日期时间函数
|
||||
- JSON 处理函数
|
||||
- 哈希函数（MD5、SHA256）
|
||||
- Base64 编码/解码
|
||||
|
||||
**适用场景**：学习各种函数工具的使用方法
|
||||
|
||||
### 04_monitoring.py
|
||||
监控 API 完整示例：
|
||||
- 获取系统性能指标
|
||||
- 获取服务统计信息
|
||||
- 查看性能趋势
|
||||
- 获取系统告警
|
||||
- 查看监控仪表盘
|
||||
|
||||
**适用场景**：了解如何监控系统运行状态
|
||||
|
||||
### 05_websocket_client.py
|
||||
WebSocket 实时通信示例：
|
||||
- 建立 WebSocket 连接
|
||||
- 发送 Ping/Pong 心跳
|
||||
- 实时执行工具调用
|
||||
- 处理异步响应
|
||||
|
||||
**适用场景**：需要实时双向通信的场景
|
||||
|
||||
### test_all_functions.py
|
||||
自动化测试工具：
|
||||
- 自动测试所有内置函数
|
||||
- 验证结果正确性
|
||||
- 生成测试报告
|
||||
|
||||
**适用场景**：验证系统功能、回归测试
|
||||
|
||||
### curl_examples.sh
|
||||
cURL 命令行示例：
|
||||
- 所有 REST API 的 cURL 调用示例
|
||||
- 适合快速测试和调试
|
||||
|
||||
**适用场景**：命令行调试、CI/CD 集成
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 如何获取 API Key？
|
||||
|
||||
开发环境使用测试 API Key: `test-api-key`
|
||||
|
||||
生产环境需要通过认证接口获取 JWT Token：
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
"http://localhost:8002/api/v1/auth/login",
|
||||
json={
|
||||
"username": "your_username",
|
||||
"password": "your_password"
|
||||
}
|
||||
)
|
||||
|
||||
token = response.json()["access_token"]
|
||||
```
|
||||
|
||||
### Q: Agent ID 从哪里获取？
|
||||
|
||||
两种方式：
|
||||
1. 创建 Agent 时返回的 ID
|
||||
2. 通过列表接口查询现有 Agent
|
||||
|
||||
```python
|
||||
# 方式1：创建时获取
|
||||
response = requests.post(f"{BASE_URL}/agents", json=agent_data, headers=HEADERS)
|
||||
agent_id = response.json()['id']
|
||||
|
||||
# 方式2：查询列表
|
||||
response = requests.get(f"{BASE_URL}/agents", headers=HEADERS)
|
||||
agents = response.json()
|
||||
agent_id = agents[0]['id'] # 获取第一个 Agent
|
||||
```
|
||||
|
||||
### Q: 如何处理错误？
|
||||
|
||||
所有示例都包含错误处理：
|
||||
|
||||
```python
|
||||
try:
|
||||
response = requests.post(url, json=data, headers=headers)
|
||||
if response.status_code == 200:
|
||||
result = response.json()
|
||||
# 处理成功响应
|
||||
else:
|
||||
print(f"请求失败: {response.text}")
|
||||
except requests.exceptions.ConnectionError:
|
||||
print("无法连接到服务器")
|
||||
except Exception as e:
|
||||
print(f"发生错误: {e}")
|
||||
```
|
||||
|
||||
### Q: 如何调试 WebSocket 连接？
|
||||
|
||||
使用 `05_websocket_client.py` 中的详细日志：
|
||||
|
||||
```python
|
||||
# 启用详细日志
|
||||
import logging
|
||||
logging.basicConfig(level=logging.DEBUG)
|
||||
|
||||
# 查看所有收到的消息
|
||||
print(f"收到的消息: {client.messages}")
|
||||
```
|
||||
|
||||
### Q: 执行工具时如何传递参数？
|
||||
|
||||
参数通过 `arguments` 字段传递：
|
||||
|
||||
```python
|
||||
request_data = {
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-001",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {
|
||||
"name": "math_add",
|
||||
"function_name": "math_add"
|
||||
},
|
||||
"arguments": {
|
||||
"a": 10,
|
||||
"b": 20
|
||||
},
|
||||
"context": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 性能优化建议
|
||||
|
||||
### 1. 使用连接池
|
||||
|
||||
```python
|
||||
import requests
|
||||
from requests.adapters import HTTPAdapter
|
||||
from urllib3.util.retry import Retry
|
||||
|
||||
session = requests.Session()
|
||||
retry = Retry(total=3, backoff_factor=0.3)
|
||||
adapter = HTTPAdapter(max_retries=retry)
|
||||
session.mount('http://', adapter)
|
||||
|
||||
# 使用 session 发起请求
|
||||
response = session.get(f"{BASE_URL}/agents")
|
||||
```
|
||||
|
||||
### 2. 批量操作使用异步
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import aiohttp
|
||||
|
||||
async def execute_batch():
|
||||
async with aiohttp.ClientSession() as session:
|
||||
tasks = []
|
||||
for i in range(10):
|
||||
task = session.post(url, json=data, headers=headers)
|
||||
tasks.append(task)
|
||||
|
||||
results = await asyncio.gather(*tasks)
|
||||
return results
|
||||
```
|
||||
|
||||
### 3. WebSocket 重连机制
|
||||
|
||||
```python
|
||||
class AutoReconnectWebSocket:
|
||||
def __init__(self, url, max_retries=5):
|
||||
self.url = url
|
||||
self.max_retries = max_retries
|
||||
|
||||
def connect_with_retry(self):
|
||||
for attempt in range(self.max_retries):
|
||||
try:
|
||||
self.connect()
|
||||
return
|
||||
except Exception as e:
|
||||
if attempt < self.max_retries - 1:
|
||||
time.sleep(2 ** attempt) # 指数退避
|
||||
else:
|
||||
raise
|
||||
```
|
||||
|
||||
## 更多资源
|
||||
|
||||
- [API 完整文档](../../../Docs/前后端调试接口说明/API-MCPServer服务.md)
|
||||
- [项目架构文档](../../../Docs/项目文档/)
|
||||
- [MCP 协议规范](https://modelcontextprotocol.io/)
|
||||
|
||||
## 贡献
|
||||
|
||||
欢迎提交问题和改进建议！
|
||||
@@ -0,0 +1,115 @@
|
||||
# MCP Server 使用示例
|
||||
|
||||
本目录包含了 MCP Server 服务的完整使用示例，帮助开发者快速了解如何使用各种 API。
|
||||
|
||||
## 目录
|
||||
|
||||
- [基础示例](#基础示例)
|
||||
- [健康检查](#健康检查)
|
||||
- [Agent 管理](#agent-管理)
|
||||
- [工具执行](#工具执行)
|
||||
- [监控示例](#监控示例)
|
||||
- [WebSocket 示例](#websocket-示例)
|
||||
- [函数工具测试](#函数工具测试)
|
||||
|
||||
## 运行环境
|
||||
|
||||
确保 MCP Server 服务正在运行：
|
||||
|
||||
```bash
|
||||
# 使用 Docker Compose
|
||||
cd /home/taiji/tools/taiji-AI-PAD
|
||||
docker-compose up -d mcp-server
|
||||
|
||||
# 或直接运行
|
||||
cd services/mcp-server
|
||||
python main.py
|
||||
```
|
||||
|
||||
服务默认运行在 `http://localhost:8002`
|
||||
|
||||
## 快速开始
|
||||
|
||||
### Python 示例
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
pip install requests websocket-client
|
||||
|
||||
# 运行示例
|
||||
python examples/01_basic_usage.py
|
||||
python examples/02_agent_management.py
|
||||
python examples/03_function_tools.py
|
||||
python examples/04_monitoring.py
|
||||
python examples/05_websocket_client.py
|
||||
```
|
||||
|
||||
### cURL 示例
|
||||
|
||||
查看 `curl_examples.sh` 获取所有 REST API 的 cURL 示例。
|
||||
|
||||
```bash
|
||||
bash examples/curl_examples.sh
|
||||
```
|
||||
|
||||
## 示例文件说明
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `01_basic_usage.py` | 基础 API 使用示例（健康检查、Agent CRUD） |
|
||||
| `02_agent_management.py` | Agent 完整管理示例 |
|
||||
| `03_function_tools.py` | 函数工具调用示例（数学、字符串等） |
|
||||
| `04_monitoring.py` | 监控 API 使用示例 |
|
||||
| `05_websocket_client.py` | WebSocket 实时通信示例 |
|
||||
| `curl_examples.sh` | cURL 命令示例合集 |
|
||||
| `test_all_functions.py` | 所有内置函数的自动化测试 |
|
||||
|
||||
## 认证说明
|
||||
|
||||
大多数 API 需要认证：
|
||||
|
||||
- **API Key 方式**：在请求头中添加 `X-API-Key: your-api-key`
|
||||
- **JWT 方式**：在请求头中添加 `Authorization: Bearer your-jwt-token`
|
||||
|
||||
测试账号（仅用于开发环境）：
|
||||
- Username: `test_user`
|
||||
- Password: `test_password`
|
||||
|
||||
获取 Token 示例：
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
"http://localhost:8002/api/v1/auth/login",
|
||||
json={
|
||||
"username": "test_user",
|
||||
"password": "test_password"
|
||||
}
|
||||
)
|
||||
token = response.json()["access_token"]
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 连接被拒绝
|
||||
|
||||
确保 MCP Server 正在运行，并检查端口映射：
|
||||
|
||||
```bash
|
||||
docker ps | grep mcp-server
|
||||
```
|
||||
|
||||
### Q: 认证失败
|
||||
|
||||
确保使用正确的 API Key 或 JWT Token，查看示例代码中的认证部分。
|
||||
|
||||
### Q: WebSocket 连接失败
|
||||
|
||||
检查 Agent 是否存在，确保使用正确的 WebSocket URL 格式：`ws://localhost:8002/ws/{agent_id}`
|
||||
|
||||
## 更多文档
|
||||
|
||||
- [API 文档](../../Docs/前后端调试接口说明/API-MCPServer服务.md)
|
||||
- [MCP 协议规范](https://modelcontextprotocol.io/)
|
||||
- [项目文档](../../Docs/项目文档/)
|
||||
+156
@@ -0,0 +1,156 @@
|
||||
#!/bin/bash
|
||||
|
||||
# MCP Server API cURL 示例
|
||||
# 演示所有 REST API 的使用方法
|
||||
|
||||
set -e
|
||||
|
||||
# 配置
|
||||
BASE_URL="http://localhost:8002"
|
||||
API_KEY="test-api-key"
|
||||
|
||||
echo "======================================================================"
|
||||
echo "MCP Server API cURL 示例"
|
||||
echo "======================================================================"
|
||||
|
||||
# 颜色输出
|
||||
GREEN='\033[0;32m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# 1. 健康检查
|
||||
echo -e "\n${BLUE}=== 1. 健康检查 ===${NC}"
|
||||
curl -X GET "${BASE_URL}/health" \
|
||||
-H "Content-Type: application/json" \
|
||||
| jq '.'
|
||||
|
||||
# 2. 注册 Agent
|
||||
echo -e "\n${BLUE}=== 2. 注册 Agent ===${NC}"
|
||||
AGENT_RESPONSE=$(curl -X POST "${BASE_URL}/agents" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: ${API_KEY}" \
|
||||
-d '{
|
||||
"name": "curl-test-agent",
|
||||
"description": "Agent created via cURL",
|
||||
"role": "assistant",
|
||||
"goal": "Test API via cURL",
|
||||
"tools": ["math_add", "string_upper"],
|
||||
"config": {},
|
||||
"capabilities": ["api_testing"]
|
||||
}')
|
||||
|
||||
echo "$AGENT_RESPONSE" | jq '.'
|
||||
|
||||
# 提取 Agent ID
|
||||
AGENT_ID=$(echo "$AGENT_RESPONSE" | jq -r '.id')
|
||||
echo -e "\n${GREEN}Agent ID: ${AGENT_ID}${NC}"
|
||||
|
||||
# 3. 获取 Agent 列表
|
||||
echo -e "\n${BLUE}=== 3. 获取 Agent 列表 ===${NC}"
|
||||
curl -X GET "${BASE_URL}/agents?skip=0&limit=10" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: ${API_KEY}" \
|
||||
| jq '.'
|
||||
|
||||
# 4. 获取特定 Agent
|
||||
echo -e "\n${BLUE}=== 4. 获取特定 Agent ===${NC}"
|
||||
curl -X GET "${BASE_URL}/agents/${AGENT_ID}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: ${API_KEY}" \
|
||||
| jq '.'
|
||||
|
||||
# 5. 执行 Agent 工具 - 数学加法
|
||||
echo -e "\n${BLUE}=== 5. 执行工具 - 数学加法 ===${NC}"
|
||||
curl -X POST "${BASE_URL}/agents/${AGENT_ID}/execute" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: ${API_KEY}" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-001",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {
|
||||
"name": "math_add",
|
||||
"function_name": "math_add"
|
||||
},
|
||||
"arguments": {
|
||||
"a": 42,
|
||||
"b": 58
|
||||
},
|
||||
"context": {}
|
||||
}
|
||||
}' | jq '.'
|
||||
|
||||
# 6. 执行工具 - 字符串转大写
|
||||
echo -e "\n${BLUE}=== 6. 执行工具 - 字符串转大写 ===${NC}"
|
||||
curl -X POST "${BASE_URL}/agents/${AGENT_ID}/execute" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: ${API_KEY}" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": "req-002",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {
|
||||
"name": "string_upper",
|
||||
"function_name": "string_upper"
|
||||
},
|
||||
"arguments": {
|
||||
"s": "hello from curl"
|
||||
},
|
||||
"context": {}
|
||||
}
|
||||
}' | jq '.'
|
||||
|
||||
# 7. 获取工具列表
|
||||
echo -e "\n${BLUE}=== 7. 获取工具列表 ===${NC}"
|
||||
curl -X GET "${BASE_URL}/tools" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: ${API_KEY}" \
|
||||
| jq '.'
|
||||
|
||||
# 8. 获取系统性能指标
|
||||
echo -e "\n${BLUE}=== 8. 获取系统性能指标 ===${NC}"
|
||||
curl -X GET "${BASE_URL}/api/v1/monitoring/metrics" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: ${API_KEY}" \
|
||||
| jq '.'
|
||||
|
||||
# 9. 获取服务统计信息
|
||||
echo -e "\n${BLUE}=== 9. 获取服务统计 ===${NC}"
|
||||
curl -X GET "${BASE_URL}/api/v1/monitoring/stats?service=all" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: ${API_KEY}" \
|
||||
| jq '.'
|
||||
|
||||
# 10. 获取性能趋势
|
||||
echo -e "\n${BLUE}=== 10. 获取性能趋势 ===${NC}"
|
||||
curl -X GET "${BASE_URL}/api/v1/monitoring/trends?metric=executions&period=24h&interval=1h" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: ${API_KEY}" \
|
||||
| jq '.'
|
||||
|
||||
# 11. 获取系统告警
|
||||
echo -e "\n${BLUE}=== 11. 获取系统告警 ===${NC}"
|
||||
curl -X GET "${BASE_URL}/api/v1/monitoring/alerts" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: ${API_KEY}" \
|
||||
| jq '.'
|
||||
|
||||
# 12. 获取监控仪表盘
|
||||
echo -e "\n${BLUE}=== 12. 获取监控仪表盘 ===${NC}"
|
||||
curl -X GET "${BASE_URL}/api/v1/monitoring/dashboard" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: ${API_KEY}" \
|
||||
| jq '.'
|
||||
|
||||
# 13. Prometheus Metrics
|
||||
echo -e "\n${BLUE}=== 13. Prometheus Metrics ===${NC}"
|
||||
curl -X GET "${BASE_URL}/metrics" \
|
||||
-H "Content-Type: application/json" \
|
||||
| head -n 20
|
||||
|
||||
echo -e "\n${GREEN}======================================================================"
|
||||
echo "所有 API 测试完成！"
|
||||
echo -e "======================================================================${NC}"
|
||||
echo -e "\n${GREEN}创建的测试 Agent ID: ${AGENT_ID}${NC}"
|
||||
@@ -0,0 +1,3 @@
|
||||
# Requirements for MCP Server examples
|
||||
requests>=2.31.0
|
||||
websocket-client>=1.6.0
|
||||
@@ -0,0 +1,293 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
测试所有内置函数工具
|
||||
自动化测试所有函数的正确性
|
||||
"""
|
||||
|
||||
import requests
|
||||
import json
|
||||
import time
|
||||
from typing import List, Tuple, Any
|
||||
|
||||
# 配置
|
||||
BASE_URL = "http://localhost:8002"
|
||||
API_KEY = "test-api-key"
|
||||
|
||||
HEADERS = {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-Key": API_KEY
|
||||
}
|
||||
|
||||
|
||||
class FunctionTester:
|
||||
"""函数测试器"""
|
||||
|
||||
def __init__(self, agent_id: str):
|
||||
self.agent_id = agent_id
|
||||
self.passed = 0
|
||||
self.failed = 0
|
||||
self.tests: List[Tuple[str, bool, Any, Any]] = []
|
||||
|
||||
def test(self, name: str, tool_name: str, args: dict, expected: Any, validator=None):
|
||||
"""
|
||||
测试一个函数
|
||||
|
||||
Args:
|
||||
name: 测试名称
|
||||
tool_name: 工具名称
|
||||
args: 参数
|
||||
expected: 期望结果
|
||||
validator: 自定义验证函数
|
||||
"""
|
||||
print(f"\n测试: {name}")
|
||||
print(f" 工具: {tool_name}")
|
||||
print(f" 参数: {args}")
|
||||
print(f" 期望: {expected}")
|
||||
|
||||
try:
|
||||
request_data = {
|
||||
"jsonrpc": "2.0",
|
||||
"id": f"test-{int(time.time() * 1000)}",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"tool": {
|
||||
"name": tool_name,
|
||||
"function_name": tool_name
|
||||
},
|
||||
"arguments": args,
|
||||
"context": {}
|
||||
}
|
||||
}
|
||||
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/agents/{self.agent_id}/execute",
|
||||
json=request_data,
|
||||
headers=HEADERS,
|
||||
timeout=10
|
||||
)
|
||||
|
||||
if response.status_code != 200:
|
||||
print(f" ✗ 失败: HTTP {response.status_code}")
|
||||
print(f" {response.text}")
|
||||
self.failed += 1
|
||||
self.tests.append((name, False, None, expected))
|
||||
return
|
||||
|
||||
result = response.json()
|
||||
|
||||
if not result.get('success'):
|
||||
print(f" ✗ 失败: {result.get('error')}")
|
||||
self.failed += 1
|
||||
self.tests.append((name, False, None, expected))
|
||||
return
|
||||
|
||||
actual = result.get('result')
|
||||
|
||||
# 验证结果
|
||||
if validator:
|
||||
if validator(actual, expected):
|
||||
print(f" ✓ 通过: {actual}")
|
||||
self.passed += 1
|
||||
self.tests.append((name, True, actual, expected))
|
||||
else:
|
||||
print(f" ✗ 失败: 实际={actual}, 期望={expected}")
|
||||
self.failed += 1
|
||||
self.tests.append((name, False, actual, expected))
|
||||
else:
|
||||
if actual == expected:
|
||||
print(f" ✓ 通过: {actual}")
|
||||
self.passed += 1
|
||||
self.tests.append((name, True, actual, expected))
|
||||
else:
|
||||
print(f" ✗ 失败: 实际={actual}, 期望={expected}")
|
||||
self.failed += 1
|
||||
self.tests.append((name, False, actual, expected))
|
||||
|
||||
except Exception as e:
|
||||
print(f" ✗ 异常: {e}")
|
||||
self.failed += 1
|
||||
self.tests.append((name, False, None, expected))
|
||||
|
||||
def print_summary(self):
|
||||
"""打印测试摘要"""
|
||||
print("\n" + "=" * 70)
|
||||
print("测试摘要")
|
||||
print("=" * 70)
|
||||
|
||||
total = self.passed + self.failed
|
||||
success_rate = (self.passed / total * 100) if total > 0 else 0
|
||||
|
||||
print(f"\n总测试数: {total}")
|
||||
print(f"通过: {self.passed} ✓")
|
||||
print(f"失败: {self.failed} ✗")
|
||||
print(f"成功率: {success_rate:.1f}%")
|
||||
|
||||
if self.failed > 0:
|
||||
print("\n失败的测试:")
|
||||
for name, passed, actual, expected in self.tests:
|
||||
if not passed:
|
||||
print(f" ✗ {name}")
|
||||
print(f" 期望: {expected}")
|
||||
print(f" 实际: {actual}")
|
||||
|
||||
|
||||
def create_test_agent() -> str:
|
||||
"""创建测试 Agent"""
|
||||
print("创建测试 Agent...")
|
||||
|
||||
agent_data = {
|
||||
"name": f"function-test-{int(time.time())}",
|
||||
"description": "Automated function testing agent",
|
||||
"role": "assistant",
|
||||
"goal": "Test all built-in functions",
|
||||
"tools": [
|
||||
"math_add", "math_subtract", "math_multiply", "math_divide", "math_power",
|
||||
"string_upper", "string_lower", "string_length", "string_replace",
|
||||
"datetime_now", "json_parse", "json_stringify",
|
||||
"hash_md5", "hash_sha256", "base64_encode", "base64_decode"
|
||||
],
|
||||
"config": {},
|
||||
"capabilities": ["function_testing"]
|
||||
}
|
||||
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/agents",
|
||||
json=agent_data,
|
||||
headers=HEADERS
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
agent_id = response.json()['id']
|
||||
print(f"✓ Agent 创建成功: {agent_id}\n")
|
||||
return agent_id
|
||||
else:
|
||||
raise Exception(f"创建 Agent 失败: {response.text}")
|
||||
|
||||
|
||||
def test_math_functions(tester: FunctionTester):
|
||||
"""测试数学函数"""
|
||||
print("\n" + "=" * 70)
|
||||
print("数学函数测试")
|
||||
print("=" * 70)
|
||||
|
||||
tester.test("加法: 10 + 20", "math_add", {"a": 10, "b": 20}, 30.0)
|
||||
tester.test("减法: 50 - 15", "math_subtract", {"a": 50, "b": 15}, 35.0)
|
||||
tester.test("乘法: 6 × 7", "math_multiply", {"a": 6, "b": 7}, 42.0)
|
||||
tester.test("除法: 100 ÷ 4", "math_divide", {"a": 100, "b": 4}, 25.0)
|
||||
tester.test("幂运算: 2^8", "math_power", {"a": 2, "b": 8}, 256.0)
|
||||
tester.test("除以零: 10 ÷ 0", "math_divide", {"a": 10, "b": 0}, None)
|
||||
|
||||
|
||||
def test_string_functions(tester: FunctionTester):
|
||||
"""测试字符串函数"""
|
||||
print("\n" + "=" * 70)
|
||||
print("字符串函数测试")
|
||||
print("=" * 70)
|
||||
|
||||
tester.test("转大写", "string_upper", {"s": "hello"}, "HELLO")
|
||||
tester.test("转小写", "string_lower", {"s": "WORLD"}, "world")
|
||||
tester.test("字符串长度", "string_length", {"s": "Hello"}, 5)
|
||||
tester.test("替换子串", "string_replace",
|
||||
{"s": "Hello World", "old": "World", "new": "MCP"},
|
||||
"Hello MCP")
|
||||
|
||||
|
||||
def test_datetime_functions(tester: FunctionTester):
|
||||
"""测试日期时间函数"""
|
||||
print("\n" + "=" * 70)
|
||||
print("日期时间函数测试")
|
||||
print("=" * 70)
|
||||
|
||||
# 验证返回值是 ISO 格式字符串
|
||||
def is_iso_datetime(actual, expected):
|
||||
return isinstance(actual, str) and 'T' in actual and len(actual) > 10
|
||||
|
||||
tester.test("获取当前时间", "datetime_now", {}, None, is_iso_datetime)
|
||||
|
||||
|
||||
def test_json_functions(tester: FunctionTester):
|
||||
"""测试 JSON 函数"""
|
||||
print("\n" + "=" * 70)
|
||||
print("JSON 函数测试")
|
||||
print("=" * 70)
|
||||
|
||||
tester.test("解析 JSON", "json_parse",
|
||||
{"s": '{"name": "test", "value": 123}'},
|
||||
{"name": "test", "value": 123})
|
||||
|
||||
tester.test("序列化对象", "json_stringify",
|
||||
{"obj": {"name": "test", "value": 123}},
|
||||
'{"name": "test", "value": 123}')
|
||||
|
||||
|
||||
def test_hash_functions(tester: FunctionTester):
|
||||
"""测试哈希函数"""
|
||||
print("\n" + "=" * 70)
|
||||
print("哈希函数测试")
|
||||
print("=" * 70)
|
||||
|
||||
test_str = "Hello, World!"
|
||||
|
||||
# MD5: "65a8e27d8879283831b664bd8b7f0ad4"
|
||||
tester.test("MD5 哈希", "hash_md5",
|
||||
{"s": test_str},
|
||||
"65a8e27d8879283831b664bd8b7f0ad4")
|
||||
|
||||
# SHA256: "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f"
|
||||
tester.test("SHA256 哈希", "hash_sha256",
|
||||
{"s": test_str},
|
||||
"dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f")
|
||||
|
||||
|
||||
def test_base64_functions(tester: FunctionTester):
|
||||
"""测试 Base64 函数"""
|
||||
print("\n" + "=" * 70)
|
||||
print("Base64 函数测试")
|
||||
print("=" * 70)
|
||||
|
||||
test_str = "Hello, MCP!"
|
||||
encoded = "SGVsbG8sIE1DUCE="
|
||||
|
||||
tester.test("Base64 编码", "base64_encode", {"s": test_str}, encoded)
|
||||
tester.test("Base64 解码", "base64_decode", {"s": encoded}, test_str)
|
||||
|
||||
|
||||
def main():
|
||||
"""主函数"""
|
||||
print("=" * 70)
|
||||
print("MCP Server 函数工具自动化测试")
|
||||
print("=" * 70)
|
||||
|
||||
try:
|
||||
# 创建测试 Agent
|
||||
agent_id = create_test_agent()
|
||||
|
||||
# 创建测试器
|
||||
tester = FunctionTester(agent_id)
|
||||
|
||||
# 运行所有测试
|
||||
test_math_functions(tester)
|
||||
test_string_functions(tester)
|
||||
test_datetime_functions(tester)
|
||||
test_json_functions(tester)
|
||||
test_hash_functions(tester)
|
||||
test_base64_functions(tester)
|
||||
|
||||
# 打印摘要
|
||||
tester.print_summary()
|
||||
|
||||
print("\n" + "=" * 70)
|
||||
print(f"测试完成! Agent ID: {agent_id}")
|
||||
print("=" * 70)
|
||||
|
||||
except requests.exceptions.ConnectionError:
|
||||
print("\n❌ 错误: 无法连接到 MCP Server")
|
||||
print("请确保服务正在运行: docker-compose up -d mcp-server")
|
||||
except Exception as e:
|
||||
print(f"\n❌ 发生错误: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -87,11 +87,13 @@ class MCPProtocolHandler:
|
||||
self,
|
||||
redis_client: redis.Redis,
|
||||
nats_client: nats.NATS,
|
||||
litellm_url: str = "http://litellm-gateway:4000"
|
||||
litellm_url: str = "http://litellm-gateway:4000",
|
||||
litellm_api_key: str = "sk-taiji-master-key"
|
||||
):
|
||||
self.redis = redis_client
|
||||
self.nats = nats_client
|
||||
self.litellm_url = litellm_url
|
||||
self.litellm_api_key = litellm_api_key
|
||||
self.http_client = httpx.AsyncClient(timeout=30.0)
|
||||
|
||||
# MCP协议版本
|
||||
@@ -698,8 +700,9 @@ class MCPProtocolHandler:
|
||||
async def _execute_llm_tool(self, tool_info: Dict[str, Any], arguments: Dict[str, Any]) -> Any:
|
||||
"""执行LLM工具调用"""
|
||||
# 调用LiteLLM网关
|
||||
# 默认使用 openrouter-gpt-3.5-turbo，与 litellm_simple.yaml 配置保持一致
|
||||
payload = {
|
||||
"model": arguments.get("model", "gpt-3.5-turbo"),
|
||||
"model": arguments.get("model", "openrouter-gpt-3.5-turbo"),
|
||||
"messages": arguments.get("messages", []),
|
||||
"temperature": arguments.get("temperature", 0.7),
|
||||
"max_tokens": arguments.get("max_tokens", 150)
|
||||
@@ -708,7 +711,7 @@ class MCPProtocolHandler:
|
||||
response = await self.http_client.post(
|
||||
f"{self.litellm_url}/chat/completions",
|
||||
json=payload,
|
||||
headers={"Authorization": "Bearer sk-taiji-master-key"}
|
||||
headers={"Authorization": f"Bearer {self.litellm_api_key}"}
|
||||
)
|
||||
|
||||
response.raise_for_status()
|
||||
|
||||
@@ -86,6 +86,9 @@ class User(BaseModel, Base):
|
||||
|
||||
status = Column(String(20), default="active")
|
||||
|
||||
# 权限配置
|
||||
permissions = Column(JSON, default=list) # 用户权限列表，如 ["use:platform_agents", "read:billing"]
|
||||
|
||||
# 兼容旧字段
|
||||
username = Column(String(50))
|
||||
hashed_password = Column(String(255))
|
||||
|
||||
@@ -137,11 +137,11 @@ model_list:
|
||||
output_cost_per_token: 0.0
|
||||
|
||||
# OpenRouter 模型组 - 通过 OpenRouter 访问多种模型
|
||||
# 注意: 使用 openrouter/ 前缀时，LiteLLM 会自动使用 OpenRouter API
|
||||
- model_name: "openrouter-gpt-4"
|
||||
litellm_params:
|
||||
model: "openrouter/openai/gpt-4"
|
||||
api_key: "os.environ/OPENROUTER_API_KEY"
|
||||
api_base: "os.environ/OPENROUTER_BASE_URL"
|
||||
max_tokens: 8000
|
||||
temperature: 0.7
|
||||
model_info:
|
||||
@@ -157,7 +157,6 @@ model_list:
|
||||
litellm_params:
|
||||
model: "openrouter/openai/gpt-3.5-turbo"
|
||||
api_key: "os.environ/OPENROUTER_API_KEY"
|
||||
api_base: "os.environ/OPENROUTER_BASE_URL"
|
||||
max_tokens: 4000
|
||||
temperature: 0.7
|
||||
model_info:
|
||||
@@ -173,7 +172,6 @@ model_list:
|
||||
litellm_params:
|
||||
model: "openrouter/anthropic/claude-3.5-sonnet"
|
||||
api_key: "os.environ/OPENROUTER_API_KEY"
|
||||
api_base: "os.environ/OPENROUTER_BASE_URL"
|
||||
max_tokens: 4000
|
||||
temperature: 0.7
|
||||
model_info:
|
||||
@@ -189,7 +187,6 @@ model_list:
|
||||
litellm_params:
|
||||
model: "openrouter/anthropic/claude-3-opus"
|
||||
api_key: "os.environ/OPENROUTER_API_KEY"
|
||||
api_base: "os.environ/OPENROUTER_BASE_URL"
|
||||
max_tokens: 4000
|
||||
temperature: 0.7
|
||||
model_info:
|
||||
|
||||
@@ -15,22 +15,24 @@ general_settings:
|
||||
|
||||
# 模型配置 - 使用测试模型和 OpenRouter
|
||||
model_list:
|
||||
# 使用HuggingFace的免费模型进行测试
|
||||
# 测试模型 - 使用 OpenRouter 的 Qwen 模型
|
||||
- model_name: "test-model"
|
||||
litellm_params:
|
||||
model: "huggingface/microsoft/DialoGPT-medium"
|
||||
api_key: "test-key" # 不需要真实key
|
||||
model: "openrouter/qwen/qwen-2-7b-instruct"
|
||||
api_key: "os.environ/OPENROUTER_API_KEY"
|
||||
max_tokens: 500
|
||||
temperature: 0.7
|
||||
model_info:
|
||||
mode: "chat"
|
||||
supports_function_calling: false
|
||||
supports_vision: false
|
||||
|
||||
# OpenRouter 模型 - 通过 OpenRouter 访问
|
||||
# 注意: 使用 openrouter/ 前缀时，LiteLLM 会自动使用 OpenRouter API
|
||||
- model_name: "openrouter-gpt-4o-mini"
|
||||
litellm_params:
|
||||
model: "openrouter/openai/gpt-4o-mini"
|
||||
api_key: "os.environ/OPENROUTER_API_KEY"
|
||||
api_base: "os.environ/OPENROUTER_BASE_URL"
|
||||
max_tokens: 1000
|
||||
temperature: 0.7
|
||||
model_info:
|
||||
@@ -42,7 +44,6 @@ model_list:
|
||||
litellm_params:
|
||||
model: "openrouter/openai/gpt-3.5-turbo"
|
||||
api_key: "os.environ/OPENROUTER_API_KEY"
|
||||
api_base: "os.environ/OPENROUTER_BASE_URL"
|
||||
max_tokens: 1000
|
||||
temperature: 0.7
|
||||
model_info:
|
||||
@@ -50,11 +51,22 @@ model_list:
|
||||
supports_function_calling: true
|
||||
supports_vision: false
|
||||
|
||||
# gpt-3.5-turbo 别名 - 向后兼容
|
||||
- model_name: "gpt-3.5-turbo"
|
||||
litellm_params:
|
||||
model: "openrouter/openai/gpt-3.5-turbo"
|
||||
api_key: "os.environ/OPENROUTER_API_KEY"
|
||||
max_tokens: 4000
|
||||
temperature: 0.7
|
||||
model_info:
|
||||
mode: "chat"
|
||||
supports_function_calling: true
|
||||
supports_vision: false
|
||||
|
||||
- model_name: "openrouter-claude-3.5-sonnet"
|
||||
litellm_params:
|
||||
model: "openrouter/anthropic/claude-3.5-sonnet"
|
||||
api_key: "os.environ/OPENROUTER_API_KEY"
|
||||
api_base: "os.environ/OPENROUTER_BASE_URL"
|
||||
max_tokens: 4000
|
||||
temperature: 0.7
|
||||
model_info:
|
||||
@@ -72,10 +84,16 @@ router_settings:
|
||||
litellm_settings:
|
||||
api_keys:
|
||||
- key: "sk-test-key"
|
||||
models: ["test-model", "openrouter-gpt-4o-mini", "openrouter-gpt-3.5-turbo", "openrouter-claude-3.5-sonnet"]
|
||||
models: ["test-model", "openrouter-gpt-4o-mini", "openrouter-gpt-3.5-turbo", "openrouter-claude-3.5-sonnet", "gpt-3.5-turbo"]
|
||||
metadata:
|
||||
user_id: "test-user"
|
||||
service: "testing"
|
||||
|
||||
- key: "sk-taiji-master-key"
|
||||
models: ["test-model", "openrouter-gpt-4o-mini", "openrouter-gpt-3.5-turbo", "openrouter-claude-3.5-sonnet", "gpt-3.5-turbo"]
|
||||
metadata:
|
||||
user_id: "master"
|
||||
service: "all"
|
||||
|
||||
# 监控
|
||||
monitoring:
|
||||
|
||||
Reference in New Issue
Block a user