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

更新外部数据工具和工具集

Browse Source
This commit is contained in:
zhanggangyong
2026-01-23 10:57:13 +00:00
parent d59dcfa941
commit fe69a70a3a
23 changed files with 3782 additions and 2630 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Docs/项目文档/用户资源信息查询接口文档.md
+474
View File
@@ -0,0 +1,474 @@
# 用户资源信息查询接口文档
> **版本**: 2026-01-14 v3
> **认证方式**: Bearer Token（JWT）
> **更新说明**: 新增域名访问支持（externalIp、domain、domainUrl、accessUrl 字段）
---
## 📋 接口概述
本文档包含两个接口：
| 接口路径 | 描述 |
|---------|------|
| `GET /api/user/resources/info` | 获取用户的 LiteLLM 密钥信息 |
| `GET /api/user/resources/agents` | 获取用户已部署的 Agent 列表 |
---
# 接口一：LiteLLM 密钥查询
## 📋 接口概述
| 项目 | 值 |
|------|-----|
| **接口路径** | `GET /api/user/resources/info` |
| **接口描述** | 获取用户的 LiteLLM 密钥信息 |
| **认证方式** | Bearer Token（JWT） |
| **Content-Type** | application/json |
### 功能说明
该接口用于获取当前用户的 LiteLLM 密钥信息：
- **LiteLLM 密钥**：解密后的完整 API Key，可直接用于调用 AI 模型
---
## 📥 请求参数
### 请求头（Headers）
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|:----:|------|
| `Authorization` | string | ✅ | Bearer Token，格式：`Bearer <JWT Token>` |
### 请求体（Body）
无
### 查询参数（Query）
无
---
## 📤 请求示例
```http
GET /api/user/resources/info HTTP/1.1
Host: api.taiji-ai.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
```
---
## 📊 响应参数
### 响应结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 请求是否成功 |
| `message` | string | 响应消息 |
| `data` | object | 响应数据 |
### data 对象
| 字段 | 类型 | 说明 |
|------|------|------|
| `litellmKeys` | array | LiteLLM 密钥列表 |
| `litellmApiBase` | string | LiteLLM 网关地址（全局） |
| `summary` | object | 汇总统计信息 |
---
### litellmKeys 数组元素
| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `modelName` | string | 模型名称 | `"taiji/gpt-4o-mini"` |
| `apiKey` | string | **解密后的完整 API Key**（用于调用模型） | `"sk-cqlSIMr1v4H3PC1LiOuXKg"` |
| `apiBase` | string | LiteLLM 网关地址 | `"https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io"` |
| `rpmLimit` | integer | 每分钟请求数限制 | `10` |
| `tpmLimit` | integer | 每分钟 Token 数限制 | `10` |
| `maxBudget` | number \| null | 最大预算（美元） | `500.0` |
| `budgetDuration` | string | 预算周期 | `"monthly"` |
| `status` | string | 密钥状态 | `"active"` |
| `createdAt` | string | 创建时间（ISO 8601） | `"2026-01-09T06:20:12.334386"` |
| `error` | string | 错误信息（仅解密失败时返回） | `"密钥解密失败"` |
---
### summary 对象
| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `totalLitellmKeys` | integer | LiteLLM 密钥总数 | `2` |
---
## 📝 响应示例
### 成功响应
```json
{
"success": true,
"data": {
"litellmKeys": [
{
"modelName": "taiji/gpt-4o-mini",
"apiKey": "sk-cqlSIMr1v4H3PC1LiOuXKg",
"apiBase": "https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io",
"rpmLimit": 10,
"tpmLimit": 10,
"maxBudget": 500.0,
"budgetDuration": "monthly",
"status": "active",
"createdAt": "2026-01-09T06:20:12.334386"
},
{
"modelName": "taiji/gpt-5",
"apiKey": "sk-Cjw3WZ7w3XMH5LjXnYw2ZA",
"apiBase": "https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io",
"rpmLimit": 100,
"tpmLimit": 100,
"maxBudget": 500.0,
"budgetDuration": "monthly",
"status": "active",
"createdAt": "2026-01-09T08:35:09.780817"
}
],
"litellmApiBase": "https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io",
"summary": {
"totalLitellmKeys": 2
}
},
"message": "LiteLLM 密钥信息获取成功"
}
```
### 无密钥时的响应
```json
{
"success": true,
"data": {
"litellmKeys": [],
"litellmApiBase": "https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io",
"summary": {
"totalLitellmKeys": 0
}
},
"message": "LiteLLM 密钥信息获取成功"
}
```
### 认证失败响应
**HTTP Status Code**: `401 Unauthorized`
```json
{
"detail": "Not authenticated"
}
```
---
## 🔧 使用说明
### LiteLLM 密钥使用方式
获取到的 `apiKey` 可以直接用于调用 AI 模型（OpenAI 兼容格式）：
```python
import openai
# 从接口返回的数据中获取
api_key = response["data"]["litellmKeys"][0]["apiKey"]
api_base = response["data"]["litellmKeys"][0]["apiBase"]
client = openai.OpenAI(
api_key=api_key,
base_url=api_base
)
response = client.chat.completions.create(
model="taiji/gpt-4o-mini",
messages=[{"role": "user", "content": "Hello!"}]
)
```
---
# 接口二：Agent 列表查询
## 📋 接口概述
| 项目 | 值 |
|------|-----|
| **接口路径** | `GET /api/user/resources/agents` |
| **接口描述** | 获取用户已部署的平台 Agent 和自定义 Agent 列表 |
| **认证方式** | Bearer Token（JWT） |
| **Content-Type** | application/json |
### 功能说明
该接口用于获取当前用户的 Agent 资源信息：
1. **平台 Agent**：已部署的平台 Agent 列表，包含域名、外网IP和访问地址
2. **自定义 Agent**：已部署的自定义 Agent 列表，包含域名、外网IP和访问地址
> 💡 **新特性**：每个 Agent 现在会自动分配域名和外网 IP，推荐使用域名访问 Agent 服务。
---
## 📥 请求参数
### 请求头（Headers）
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|:----:|------|
| `Authorization` | string | ✅ | Bearer Token，格式：`Bearer <JWT Token>` |
### 请求体（Body）
无
### 查询参数（Query）
无
---
## 📤 请求示例
```http
GET /api/user/resources/agents HTTP/1.1
Host: api.taiji-ai.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
```
---
## 📊 响应参数
### 响应结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 请求是否成功 |
| `message` | string | 响应消息 |
| `data` | object | 响应数据 |
### data 对象
| 字段 | 类型 | 说明 |
|------|------|------|
| `platformAgents` | array | 已部署的平台 Agent 列表 |
| `customAgents` | array | 已部署的自定义 Agent 列表 |
| `summary` | object | 汇总统计信息 |
---
### platformAgents / customAgents 数组元素
| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `name` | string | Agent 实例名称 | `"echo-agent-b00a7b8e-5507d7"` |
| `template` | string | Agent 类型/模板 | `"echo_agent"` |
| `templateName` | string | 模板名称 | `"echo_agent"` |
| `status` | string | 运行状态 | `"Running"` / `"Pending"` / `"Failed"` / `"unknown"` |
| `healthStatus` | string | 健康状态 | `"healthy"` / `"degraded"` / `"unhealthy"` / `"unknown"` |
| `podIp` | string \| null | Pod 内部 IP 地址 | `"10.244.3.5"` |
| `externalIp` | string \| null | **🆕 外网 IP 地址** | `"20.195.113.211"` |
| `domain` | string \| null | **🆕 域名**（推荐访问方式） | `"echo-agent-b00a7b8e-5507d7.taijiagnet.com"` |
| `domainUrl` | string \| null | **🆕 域名访问地址** | `"http://echo-agent-b00a7b8e-5507d7.taijiagnet.com"` |
| `accessUrl` | string \| null | **🆕 推荐访问地址**（域名优先） | `"http://echo-agent-b00a7b8e-5507d7.taijiagnet.com"` |
| `servicePort` | integer \| null | 服务端口 | `8000` |
| `namespace` | string | K8s 命名空间 | `"agent-echo-agent-b00a7b8e-5507d7"` |
| `hostIp` | string \| null | 宿主机 IP | `"10.224.0.7"` |
| `nodeName` | string \| null | K8s 节点名称 | `"aks-taijipod-34569487-vmss00000b"` |
| `cpu` | string | CPU 配置 | `"100m"` |
| `memory` | string | 内存配置 | `"256Mi"` |
| `replicas` | integer | 副本数量 | `1` |
| `startTime` | string | 启动时间（ISO 8601） | `"2026-01-14T13:36:22.443568"` |
| `runningSeconds` | integer | 已运行秒数 | `3600` |
| `endpoints` | array \| undefined | 端点 URL 列表 | `["http://10.244.3.5:8000"]` |
---
### summary 对象
| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `totalPlatformAgents` | integer | 已部署的平台 Agent 数量 | `2` |
| `totalCustomAgents` | integer | 已部署的自定义 Agent 数量 | `4` |
---
## 📝 响应示例
### 成功响应
```json
{
"success": true,
"data": {
"platformAgents": [
{
"name": "echo-agent-b00a7b8e-5507d7",
"template": "echo_agent",
"templateName": "echo_agent",
"status": "Running",
"healthStatus": "healthy",
"podIp": "10.244.3.5",
"externalIp": "20.195.113.211",
"domain": "echo-agent-b00a7b8e-5507d7.taijiagnet.com",
"domainUrl": "http://echo-agent-b00a7b8e-5507d7.taijiagnet.com",
"accessUrl": "http://echo-agent-b00a7b8e-5507d7.taijiagnet.com",
"servicePort": 8000,
"namespace": "agent-echo-agent-b00a7b8e-5507d7",
"hostIp": "10.224.0.7",
"nodeName": "aks-taijipod-34569487-vmss00000b",
"cpu": "100m",
"memory": "256Mi",
"replicas": 1,
"startTime": "2026-01-14T13:36:22.443568",
"runningSeconds": 3600
}
],
"customAgents": [
{
"name": "my-mysql-agent",
"template": "mysql_agent",
"templateName": "MCP",
"status": "Running",
"healthStatus": "healthy",
"podIp": "10.244.1.61",
"externalIp": "20.6.66.41",
"domain": "my-mysql-agent.taijiagnet.com",
"domainUrl": "http://my-mysql-agent.taijiagnet.com",
"accessUrl": "http://my-mysql-agent.taijiagnet.com",
"servicePort": 8000,
"namespace": "agent-my-mysql-agent",
"hostIp": "10.224.0.5",
"nodeName": "aks-taijipod-34569487-vmss00000a",
"cpu": "500m",
"memory": "1Gi",
"replicas": 1,
"startTime": "2026-01-14T10:00:00.000000",
"runningSeconds": 14400
}
],
"summary": {
"totalPlatformAgents": 1,
"totalCustomAgents": 1
}
},
"message": "Agent 列表获取成功"
}
```
### 无 Agent 时的响应
```json
{
"success": true,
"data": {
"platformAgents": [],
"customAgents": [],
"summary": {
"totalPlatformAgents": 0,
"totalCustomAgents": 0
}
},
"message": "Agent 列表获取成功"
}
```
### 认证失败响应
**HTTP Status Code**: `401 Unauthorized`
```json
{
"detail": "Not authenticated"
}
```
---
## 🔧 使用说明
### Agent 访问方式
#### 🌐 推荐：使用域名访问（稳定）
通过 `domain` 或 `accessUrl` 访问 Agent 服务，域名不会因 Pod 重启而变化：
```bash
# 使用域名访问（推荐）
curl http://echo-agent-b00a7b8e-5507d7.taijiagnet.com/api/chat
# 或使用 accessUrl 字段的值
curl http://echo-agent-b00a7b8e-5507d7.taijiagnet.com/health
```
#### 🔗 使用外网 IP 访问
```bash
# 使用外网 IP 访问
curl http://20.195.113.211/api/chat
```
#### 📍 集群内部访问（仅限 K8s 集群内）
```bash
# 使用 Pod IP 访问（仅集群内部）
curl http://10.244.3.5:8000/api/chat
```
### 访问方式优先级
| 优先级 | 访问方式 | 字段 | 稳定性 | 说明 |
|:---:|---------|------|:---:|------|
| 1 | 域名 | `domain` / `accessUrl` | ⭐⭐⭐ | **推荐**，Pod 重启后不变 |
| 2 | 外网 IP | `externalIp` | ⭐⭐ | LoadBalancer IP，较稳定 |
| 3 | Pod IP | `podIp` | ⭐ | Pod 重启后会变化 |
---
## 📌 数据来源说明
| 数据类型 | 来源 | 实时性 |
|---------|------|--------|
| LiteLLM 密钥 | PostgreSQL 数据库 | 静态（创建时存储） |
| Agent 基本信息（名称、模板、CPU/内存） | PostgreSQL 数据库 | 静态（创建时存储） |
| Agent 访问信息（domain、externalIp） | PostgreSQL 数据库 | 静态（创建时存储） |
| Agent 状态（status, healthStatus） | AKS 集群（通过 Agent Manager） | **实时查询** |
| Agent Pod 信息（podIp、hostIp） | AKS 集群（通过 Agent Manager） | **实时查询** |
### 调用链路
```
前端 → mcp-server → Agent Manager → AKS (Kubernetes API)
↓
查询 Pod/Service 真实状态
```
---
## ⚠️ 注意事项
1. **密钥安全**：返回的 `apiKey` 是完整的解密密钥，请妥善保管，不要泄露
2. **推荐域名访问**：使用 `domain` 或 `accessUrl` 访问 Agent，比 Pod IP 更稳定
3. **DNS 生效时间**：新创建的 Agent 域名可能需要 1-5 分钟 DNS 传播时间
4. **实时性**：`status`、`podIp` 等信息是实时从 AKS 查询的，可能有轻微延迟
5. **服务可用性**：如果 Agent Manager 服务不可用，实时信息将显示为 `null` 或 `unknown`
6. **旧 Agent 兼容**：在 2026-01-14 之前创建的 Agent，`domain`、`externalIp` 等字段可能为 `null`