taijibaga/taiji-AI-PAD

Fork 0

forked from xiaohei/taiji-AI-PAD

Files

T

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

2026-01-23 10:57:13 +00:00

13 KiB

Raw Blame History

用户资源信息查询接口文档

版本: 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）

无

📤 请求示例

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`

📝 响应示例

成功响应

{
  "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 密钥信息获取成功"
}

无密钥时的响应

{
  "success": true,
  "data": {
    "litellmKeys": [],
    "litellmApiBase": "https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io",
    "summary": {
      "totalLitellmKeys": 0
    }
  },
  "message": "LiteLLM 密钥信息获取成功"
}

认证失败响应

HTTP Status Code: 401 Unauthorized

{
  "detail": "Not authenticated"
}

🔧 使用说明

LiteLLM 密钥使用方式

获取到的 apiKey 可以直接用于调用 AI 模型（OpenAI 兼容格式）：

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 资源信息：

平台 Agent：已部署的平台 Agent 列表，包含域名、外网IP和访问地址
自定义 Agent：已部署的自定义 Agent 列表，包含域名、外网IP和访问地址

💡 新特性：每个 Agent 现在会自动分配域名和外网 IP，推荐使用域名访问 Agent 服务。

📥 请求参数

请求头（Headers）

参数名	类型	必填	说明
`Authorization`	string	✅	Bearer Token，格式：`Bearer <JWT Token>`

请求体（Body）

无

查询参数（Query）

无

📤 请求示例

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`

📝 响应示例

成功响应

{
  "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 时的响应

{
  "success": true,
  "data": {
    "platformAgents": [],
    "customAgents": [],
    "summary": {
      "totalPlatformAgents": 0,
      "totalCustomAgents": 0
    }
  },
  "message": "Agent 列表获取成功"
}

认证失败响应

HTTP Status Code: 401 Unauthorized

{
  "detail": "Not authenticated"
}

🔧 使用说明

Agent 访问方式

🌐 推荐：使用域名访问（稳定）

通过 domain 或 accessUrl 访问 Agent 服务，域名不会因 Pod 重启而变化：

# 使用域名访问（推荐）
curl http://echo-agent-b00a7b8e-5507d7.taijiagnet.com/api/chat

# 或使用 accessUrl 字段的值
curl http://echo-agent-b00a7b8e-5507d7.taijiagnet.com/health

🔗 使用外网 IP 访问

# 使用外网 IP 访问
curl http://20.195.113.211/api/chat

📍 集群内部访问（仅限 K8s 集群内）

# 使用 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 真实状态

⚠️ 注意事项

密钥安全：返回的 apiKey 是完整的解密密钥，请妥善保管，不要泄露
推荐域名访问：使用 domain 或 accessUrl 访问 Agent，比 Pod IP 更稳定
DNS 生效时间：新创建的 Agent 域名可能需要 1-5 分钟 DNS 传播时间
实时性：status、podIp 等信息是实时从 AKS 查询的，可能有轻微延迟
服务可用性：如果 Agent Manager 服务不可用，实时信息将显示为 null 或 unknown
旧 Agent 兼容：在 2026-01-14 之前创建的 Agent，domain、externalIp 等字段可能为 null

13 KiB Raw Blame History Unescape Escape

用户资源信息查询接口文档

📋 接口概述

接口一：LiteLLM 密钥查询

📋 接口概述

功能说明

📥 请求参数

请求头（Headers）

请求体（Body）

查询参数（Query）

📤 请求示例

📊 响应参数

响应结构

data 对象

litellmKeys 数组元素

summary 对象

📝 响应示例

成功响应

无密钥时的响应

认证失败响应

🔧 使用说明

LiteLLM 密钥使用方式

接口二：Agent 列表查询

📋 接口概述

功能说明

📥 请求参数

请求头（Headers）

请求体（Body）

查询参数（Query）

📤 请求示例

📊 响应参数

响应结构

data 对象

platformAgents / customAgents 数组元素

summary 对象

📝 响应示例

成功响应

无 Agent 时的响应

认证失败响应

🔧 使用说明

Agent 访问方式

🌐 推荐：使用域名访问（稳定）

🔗 使用外网 IP 访问

📍 集群内部访问（仅限 K8s 集群内）

访问方式优先级

📌 数据来源说明

调用链路

⚠️ 注意事项

13 KiB

Raw Blame History