forked from xiaohei/taiji-AI-PAD
475 lines
13 KiB
Markdown
475 lines
13 KiB
Markdown
# 用户资源信息查询接口文档
|
||
|
||
> **版本**: 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`
|