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

更新litemll

Browse Source
This commit is contained in:
zhanggangyong
2026-01-07 14:46:15 +00:00
parent bb719db8ed
commit 9f2ed20fa9
16 changed files with 2601 additions and 1523 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plans/Agent-Manager接口变动需求文档.md
+263
View File
@@ -0,0 +1,263 @@
# Agent-Manager 接口变动需求文档
> **版本**: v1.0.0
> **创建时间**: 2026-01-07
> **关联设计**: 模型供应商与租户模型使用设计方案 v5.0
---
## 1. 背景
根据「模型供应商与租户模型使用设计方案」，mcp-server 需要在创建 Agent 时注入 LiteLLM 相关的环境变量，使 Agent 能够通过 LiteLLM 网关访问模型。
**核心变更**：
- Agent 创建时需要支持注入额外的环境变量
- 环境变量包含敏感信息（API Key），需要安全处理
---
## 2. 接口变动清单
### 2.1 创建 Agent 接口
**接口路径**: `POST /agents`
**变更内容**: 请求体中的 `env_vars` 字段需要支持以下新的环境变量
| 环境变量 | 类型 | 必填 | 说明 |
|----------|------|------|------|
| `OPENAI_API_BASE` | string | 否 | LiteLLM 网关地址，如 `http://4.144.175.186` |
| `OPENAI_API_KEY` | string | 否 | 租户的 LiteLLM API Key（敏感信息） |
| `MODEL_NAME` | string | 否 | 模型名称，如 `azure/gpt-4` |
| `LITELLM_MODEL` | string | 否 | 同 MODEL_NAME，兼容不同框架 |
**请求示例**:
```json
{
"name": "my-custom-agent",
"template": "langchain-agent",
"config": {
"user_id": "user-uuid",
"cpu_request": "100m",
"cpu_limit": "500m",
"memory_request": "128Mi",
"memory_limit": "512Mi"
},
"env_vars": {
"OPENAI_API_BASE": "http://4.144.175.186",
"OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx",
"MODEL_NAME": "azure/gpt-4",
"LITELLM_MODEL": "azure/gpt-4",
"CUSTOM_VAR": "custom_value"
}
}
```
**安全要求**:
1. `OPENAI_API_KEY` 等敏感环境变量应作为 Kubernetes Secret 存储，而非明文写入 Pod spec
2. 建议使用 `secretKeyRef` 引用 Secret 中的值
3. 日志中不应打印敏感环境变量的值
---
### 2.2 创建平台 Agent 接口
**接口路径**: `POST /platform-agents`
**变更内容**: 同上，支持注入 LiteLLM 环境变量
---
### 2.3 创建自定义 Agent 接口
**接口路径**: `POST /custom-agents`
**变更内容**: 同上，支持注入 LiteLLM 环境变量
---
## 3. 实现建议
### 3.1 环境变量注入方式
**方式一：直接注入（简单但不够安全）**
```yaml
spec:
containers:
- name: agent
env:
- name: OPENAI_API_BASE
value: "http://4.144.175.186"
- name: OPENAI_API_KEY
value: "sk-xxxxxxxx" # 不推荐
```
**方式二：使用 Secret（推荐）**
```yaml
spec:
containers:
- name: agent
env:
- name: OPENAI_API_BASE
value: "http://4.144.175.186"
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: agent-{agent-name}-secrets
key: openai-api-key
```
### 3.2 Secret 管理
Agent-Manager 需要：
1. 在创建 Agent 前，先创建对应的 Secret
2. Secret 名称建议使用 `agent-{agent-name}-secrets`
3. 删除 Agent 时同时删除对应的 Secret
**创建 Secret 示例**:
```python
from kubernetes import client
def create_agent_secret(name: str, namespace: str, env_vars: dict):
"""创建 Agent 的 Secret"""
# 筛选敏感环境变量
sensitive_keys = ["OPENAI_API_KEY", "API_KEY", "SECRET_KEY"]
secret_data = {}
for key, value in env_vars.items():
if any(sk in key.upper() for sk in sensitive_keys):
secret_data[key.lower().replace("_", "-")] = base64.b64encode(value.encode()).decode()
if not secret_data:
return None
secret = client.V1Secret(
metadata=client.V1ObjectMeta(
name=f"agent-{name}-secrets",
namespace=namespace,
labels={"app": "agent", "agent-name": name}
),
type="Opaque",
data=secret_data
)
core_v1 = client.CoreV1Api()
return core_v1.create_namespaced_secret(namespace, secret)
```
---
## 4. mcp-server 调用示例
```python
# mcp-server 中创建 Agent 的代码
async def create_custom_agent(
name: str,
template: str,
user_id: str,
model_name: str,
db: AsyncSession
):
# 1. 查询租户的模型 Key
tenant_key = await get_tenant_model_key(user_id, model_name, db)
if not tenant_key:
raise HTTPException(403, f"您没有使用模型 {model_name} 的权限")
# 2. 解密 Key
decrypted_key = litellm_client.decrypt_key(tenant_key.litellm_key_hash)
# 3. 构建环境变量
env_vars = {
"OPENAI_API_BASE": settings.litellm_url,
"OPENAI_API_KEY": decrypted_key,
"MODEL_NAME": model_name,
"LITELLM_MODEL": model_name,
}
# 4. 调用 Agent Manager
result = await agent_manager_client.create_custom_agent(
name=name,
template=template,
user_id=user_id,
env_vars=env_vars,
config=agent_config
)
return result
```
---
## 5. 测试要点
### 5.1 功能测试
| 测试项 | 预期结果 |
|--------|----------|
| 创建 Agent 时传入 LiteLLM 环境变量 | Agent Pod 中能读取到这些环境变量 |
| Agent 使用注入的 Key 调用 LiteLLM | 请求成功，返回模型响应 |
| 不传入 LiteLLM 环境变量 | Agent 正常创建，但无法调用模型 |
### 5.2 安全测试
| 测试项 | 预期结果 |
|--------|----------|
| 查看 Pod spec | 敏感环境变量通过 secretKeyRef 引用 |
| 查看 Agent Manager 日志 | 不包含 API Key 明文 |
| 删除 Agent | 对应的 Secret 也被删除 |
---
## 6. 时间线
| 阶段 | 时间 | 内容 |
|------|------|------|
| 需求确认 | 2026-01-07 | 确认接口变动范围 |
| 开发实现 | 2026-01-08 ~ 2026-01-10 | Agent Manager 支持 Secret 管理 |
| 联调测试 | 2026-01-11 ~ 2026-01-12 | mcp-server 与 Agent Manager 联调 |
| 上线部署 | 2026-01-13 | 生产环境部署 |
---
## 7. 联系人
- **mcp-server 负责人**: [待填写]
- **Agent Manager 负责人**: [待填写]
---
## 附录 A: 现有 Agent Manager 接口参考
根据 `plans/agent-manager接口文档.md`，现有接口已支持 `env_vars` 参数，本次变更主要是：
1. **明确 LiteLLM 相关环境变量的命名规范**
2. **增加敏感环境变量的安全处理要求**
3. **确保 mcp-server 和 Agent Manager 的对接一致性**
---
## 附录 B: LiteLLM 环境变量说明
| 环境变量 | 用途 | 示例值 |
|----------|------|--------|
| `OPENAI_API_BASE` | LiteLLM 网关地址 | `http://4.144.175.186` |
| `OPENAI_API_KEY` | 租户的 LiteLLM API Key | `sk-xxxxxxxx` |
| `MODEL_NAME` | 要使用的模型名称 | `azure/gpt-4` |
| `LITELLM_MODEL` | 同 MODEL_NAME | `azure/gpt-4` |
**Agent 代码中使用示例**:
```python
import os
from openai import OpenAI
client = OpenAI(
base_url=os.getenv("OPENAI_API_BASE"),
api_key=os.getenv("OPENAI_API_KEY"),
)
response = client.chat.completions.create(
model=os.getenv("MODEL_NAME", "gpt-4"),
messages=[{"role": "user", "content": "Hello!"}]
)
```
plans/LiteLLM集成实现总结.md
+261
View File
@@ -0,0 +1,261 @@
# LiteLLM 集成实现总结
> **版本**: v1.0.0
> **完成时间**: 2026-01-07
> **状态**: ✅ 已完成
---
## 1. 实现概述
根据「模型供应商与租户模型使用设计方案 v5.0」，已完成 mcp-server 与 LiteLLM 的集成。
### 1.1 核心功能
| 功能 | 状态 | 说明 |
|------|------|------|
| 创建渠道时同步创建 LiteLLM team | ✅ 已完成 | 渠道 = LiteLLM team |
| 删除渠道时同步删除 LiteLLM team | ✅ 已完成 | 级联删除 |
| 分配模型给租户时创建 LiteLLM key | ✅ 已完成 | 包含 RPM/TPM/Budget 配额 |
| 取消模型分配时删除 LiteLLM key | ✅ 已完成 | 清理资源 |
| 更新租户配额时更新 LiteLLM key | ✅ 已完成 | 实时生效 |
| 租户查看可用模型 | ✅ 已完成 | 从 tenant_model_keys 表查询 |
| Agent 创建时注入 LiteLLM key | ✅ 已完成 | 环境变量注入 |
---
## 2. 新增/修改的文件
### 2.1 新增文件
| 文件路径 | 说明 |
|----------|------|
| `services/mcp-server/app/litellm_client.py` | LiteLLM Admin API 客户端（525行） |
| `services/mcp-server/migrations/011_add_litellm_integration.sql` | 数据库迁移脚本 |
| `services/mcp-server/migrations/run_011_migration.py` | 迁移执行脚本 |
| `plans/Agent-Manager接口变动需求文档.md` | Agent Manager 对接需求 |
### 2.2 修改文件
| 文件路径 | 修改内容 |
|----------|----------|
| `services/mcp-server/models.py` | 新增 `TenantModelKey` 模型，`Channel` 增加 `litellm_team_id` 字段 |
| `services/mcp-server/config.py` | 更新 LiteLLM master key 配置 |
| `services/mcp-server/app/routes/admin.py` | 渠道创建/删除时同步 LiteLLM team |
| `services/mcp-server/app/routes/channel.py` | 新增模型分配接口（4个端点） |
| `services/mcp-server/app/routes/user.py` | 新增租户模型查询接口，Agent 创建时注入 key |
| `docker-compose.yml` | 添加 LITELLM_URL 和 LITELLM_MASTER_KEY 环境变量 |
| `.env` | 更新 LiteLLM 配置 |
---
## 3. 数据库变更
### 3.1 新增表：tenant_model_keys
```sql
CREATE TABLE tenant_model_keys (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES users(id),
channel_id UUID REFERENCES channels(id),
model_name VARCHAR(100) NOT NULL,
litellm_key_id VARCHAR(255) NOT NULL,
litellm_key_hash TEXT NOT NULL, -- 加密存储
rpm_limit INTEGER DEFAULT 0,
tpm_limit INTEGER DEFAULT 0,
max_budget NUMERIC(12, 2),
budget_duration VARCHAR(20) DEFAULT 'monthly',
status VARCHAR(20) DEFAULT 'active',
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
CONSTRAINT uq_tenant_model UNIQUE(tenant_id, model_name)
);
```
### 3.2 修改表：channels
```sql
ALTER TABLE channels ADD COLUMN litellm_team_id VARCHAR(100);
```
---
## 4. API 接口清单
### 4.1 渠道管理（admin.py）
| 接口 | 方法 | 功能 | LiteLLM 操作 |
|------|------|------|-------------|
| `/api/admin/channels/create` | POST | 创建渠道 | 创建 team |
| `/api/admin/channels/{id}` | DELETE | 删除渠道 | 删除 team |
### 4.2 模型分配（channel.py）
| 接口 | 方法 | 功能 | LiteLLM 操作 |
|------|------|------|-------------|
| `/api/channel/tenants/{id}/models` | PUT | 分配模型给租户 | 创建 key |
| `/api/channel/tenants/{id}/models` | GET | 获取租户模型列表 | - |
| `/api/channel/tenants/{id}/models/{model}` | DELETE | 取消模型分配 | 删除 key |
| `/api/channel/tenants/{id}/models/{model}/quota` | PUT | 更新配额 | 更新 key |
### 4.3 租户接口（user.py）
| 接口 | 方法 | 功能 |
|------|------|------|
| `/api/user/models/available` | GET | 获取可用模型列表 |
| `/api/user/models/usage/stats` | GET | 获取用量统计 |
| `/api/user/custom-agents` | POST | 创建 Agent（注入 key） |
---
## 5. 配置说明
### 5.1 环境变量
| 变量名 | 说明 | 示例值 |
|--------|------|--------|
| `LITELLM_URL` | LiteLLM 网关地址 | `http://4.144.175.186` |
| `LITELLM_MASTER_KEY` | LiteLLM 管理密钥 | `sk-1f06b8f0d2e34c9b8a9f3d75a1c4e9b7-7e3a2c6bd9f441d8` |
| `LITELLM_KEY_ENCRYPTION_KEY` | Key 加密密钥 | Base64 编码的 32 字节密钥 |
### 5.2 .env 配置
```bash
# LiteLLM网关配置
LITELLM_MASTER_KEY=sk-1f06b8f0d2e34c9b8a9f3d75a1c4e9b7-7e3a2c6bd9f441d8
LITELLM_URL=http://4.144.175.186
```
---
## 6. 测试验证
### 6.1 测试流程
```
1. 超级管理员登录 ✅
2. 创建渠道 → LiteLLM team 创建成功 ✅
3. 分配模型给渠道 ✅
4. 渠道管理员登录 ✅
5. 创建租户 ✅
6. 分配模型给租户 → LiteLLM key 创建成功 ✅
7. 租户登录 ✅
8. 租户查看可用模型 ✅
```
### 6.2 测试结果
**创建渠道响应**:
```json
{
"success": true,
"data": {
"id": "6e147f61-e2a8-422a-ab86-17ebbf3eff7b",
"name": "LiteLLM集成测试渠道",
"litellmTeamId": "4fe022d7-f484-4cf7-ac91-de1ed06aa99c"
}
}
```
**分配模型响应**:
```json
{
"success": true,
"data": {
"tenantId": "7363295d-2a22-4f60-9298-ef65d2715731",
"modelName": "gpt-3.5-turbo",
"rpmLimit": 60,
"tpmLimit": 10000,
"maxBudget": 100.0,
"status": "active"
}
}
```
**LiteLLM 中的 Key 信息**:
```json
{
"models": ["gpt-3.5-turbo"],
"rpm_limit": 60,
"tpm_limit": 10000,
"max_budget": 100.0,
"budget_duration": "monthly",
"metadata": {
"tenant_id": "7363295d-2a22-4f60-9298-ef65d2715731",
"channel_id": "6e147f61-e2a8-422a-ab86-17ebbf3eff7b",
"tenant_name": "测试租户",
"channel_name": "LiteLLM集成测试渠道"
}
}
```
---
## 7. 待完成事项
### 7.1 Agent Manager 对接
需要 Agent Manager 支持：
1. 接收 `env_vars` 参数中的 LiteLLM 环境变量
2. 将敏感环境变量（如 `OPENAI_API_KEY`）存储为 Kubernetes Secret
3. 在 Pod spec 中通过 `secretKeyRef` 引用
详见：`plans/Agent-Manager接口变动需求文档.md`
### 7.2 充值功能
充值接口 `/api/user/billing/recharge` 需要：
1. 更新 `tenant_model_keys.max_budget`
2. 调用 LiteLLM `/key/update` 更新 budget
### 7.3 用量统计
用量统计接口需要：
1. 调用 LiteLLM `/spend/logs` 获取实际用量
2. 与本地记录对比
---
## 8. 架构图
```
┌─────────────────────────────────────────────────────────────────┐
│ mcp-server │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ admin.py │ │ channel.py │ │ user.py │ │
│ │ 创建/删除渠道│ │ 分配模型给租户│ │ 查询可用模型/创建Agent │ │
│ └──────┬──────┘ └──────┬──────┘ └───────────┬─────────────┘ │
│ │ │ │ │
│ └────────────────┼──────────────────────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ litellm_client│ │
│ │ (Admin API) │ │
│ └───────┬───────┘ │
└──────────────────────────┼───────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ LiteLLM Gateway │
│ http://4.144.175.186 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ /team/new │ │/key/generate│ │ /chat/completions │ │
│ │ /team/delete│ │ /key/update │ │ (Agent 调用) │ │
│ └─────────────┘ │ /key/delete │ └─────────────────────────┘ │
│ └─────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```
---
## 9. 总结
LiteLLM 集成已完成核心功能：
1. ✅ **渠道 = LiteLLM team**：创建渠道时自动创建 team
2. ✅ **租户模型 = LiteLLM key**：分配模型时创建带配额的 key
3. ✅ **配额管理**：RPM/TPM/Budget 由 LiteLLM 执行
4. ✅ **Key 加密存储**：使用 Fernet 加密存储 API Key
5. ✅ **实时生效**：配额更新后立即生效，无需重启
下一步：与 Agent Manager 联调，确保 Agent 能正确使用注入的 LiteLLM key 调用模型。
plans/LiteLLM集成接口变动清单.md
+406
View File
@@ -0,0 +1,406 @@
# LiteLLM 集成接口变动清单
> **版本**: v1.0.0
> **创建时间**: 2026-01-07
> **状态**: 已实现
---
## 1. 超级管理员端接口变动 (admin.py)
### 1.1 已修改接口
#### POST /api/admin/channels/create - 创建渠道
**变动说明**: 创建渠道时同步在 LiteLLM 中创建对应的 team
**请求参数**: 无变化
**响应变动**:
```json
{
"success": true,
"data": {
"id": "渠道ID",
"name": "渠道名称",
"email": "渠道邮箱",
"litellmTeamId": "LiteLLM team ID (新增)",
"litellmWarning": "LiteLLM 创建失败时的警告信息 (可选)"
},
"message": "渠道创建成功"
}
```
**新增响应字段**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `litellmTeamId` | string | LiteLLM 中创建的 team ID |
| `litellmWarning` | string | 可选，LiteLLM 操作失败时的警告信息 |
---
#### DELETE /api/admin/channels/{channel_id} - 删除渠道
**变动说明**: 删除渠道时同步删除 LiteLLM 中对应的 team
**请求参数**: 无变化
**响应变动**:
```json
{
"success": true,
"data": {
"id": "渠道ID",
"litellmWarning": "LiteLLM 删除失败时的警告信息 (可选)"
},
"message": "渠道已删除"
}
```
**新增响应字段**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `litellmWarning` | string | 可选，LiteLLM 操作失败时的警告信息 |
---
### 1.2 数据库变动
#### Channel 表新增字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `litellm_team_id` | VARCHAR(100) | LiteLLM 中对应的 team ID |
---
## 2. 渠道端接口变动 (channel.py)
### 2.1 新增接口
#### PUT /api/channel/tenants/{tenant_id}/models - 分配模型给租户
**功能**: 为租户创建 LiteLLM API Key，绑定指定的模型和配额
**请求参数** (Query):
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model_name` | string | 是 | 模型名称，如 `azure/gpt-4` |
| `rpm_limit` | int | 否 | 每分钟请求数限制，默认 60 |
| `tpm_limit` | int | 否 | 每分钟 Token 数限制，默认 10000 |
| `max_budget` | float | 否 | 最大预算，默认 100.0 |
| `budget_duration` | string | 否 | 预算周期，`monthly` 或 `total`，默认 `monthly` |
| `channel_id` | string | 否 | 渠道ID（超级管理员必填） |
**响应**:
```json
{
"success": true,
"data": {
"tenantId": "租户ID",
"tenantName": "租户名称",
"modelName": "模型名称",
"rpmLimit": 60,
"tpmLimit": 10000,
"maxBudget": 100.0,
"budgetDuration": "monthly",
"status": "active"
},
"message": "模型 'xxx' 分配成功"
}
```
**权限**: `manage:resources` (channel_admin, billing_admin, super_admin)
---
#### GET /api/channel/tenants/{tenant_id}/models - 获取租户的模型分配列表
**功能**: 返回租户已分配的所有模型及其配额信息
**请求参数** (Query):
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `channel_id` | string | 否 | 渠道ID（超级管理员必填） |
**响应**:
```json
{
"success": true,
"data": {
"tenantId": "租户ID",
"tenantName": "租户名称",
"models": [
{
"modelName": "azure/gpt-4",
"rpmLimit": 60,
"tpmLimit": 10000,
"maxBudget": 100.0,
"budgetDuration": "monthly",
"status": "active",
"createdAt": "2026-01-07T12:00:00",
"updatedAt": "2026-01-07T12:00:00"
}
]
}
}
```
**权限**: `view:resources` (channel_admin, billing_admin, operations_admin, super_admin)
---
#### DELETE /api/channel/tenants/{tenant_id}/models/{model_name} - 取消租户的模型分配
**功能**: 删除租户在 LiteLLM 中的 API Key，租户将无法再使用该模型
**请求参数** (Query):
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `channel_id` | string | 否 | 渠道ID（超级管理员必填） |
**响应**:
```json
{
"success": true,
"data": {
"tenantId": "租户ID",
"tenantName": "租户名称",
"modelName": "模型名称",
"litellmWarning": "LiteLLM Key 删除失败时的警告信息 (可选)"
},
"message": "模型 'xxx' 分配已取消"
}
```
**权限**: `manage:resources` (channel_admin, billing_admin, super_admin)
---
#### PUT /api/channel/tenants/{tenant_id}/models/{model_name}/quota - 更新租户的模型配额
**功能**: 更新租户在 LiteLLM 中的 API Key 配额，更新后立即生效
**请求参数** (Query):
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `rpm_limit` | int | 否 | 每分钟请求数限制 |
| `tpm_limit` | int | 否 | 每分钟 Token 数限制 |
| `max_budget` | float | 否 | 最大预算 |
| `budget_duration` | string | 否 | 预算周期，`monthly` 或 `total` |
| `channel_id` | string | 否 | 渠道ID（超级管理员必填） |
**响应**:
```json
{
"success": true,
"data": {
"tenantId": "租户ID",
"tenantName": "租户名称",
"modelName": "模型名称",
"rpmLimit": 120,
"tpmLimit": 20000,
"maxBudget": 200.0,
"budgetDuration": "monthly",
"status": "active"
},
"message": "模型配额更新成功，立即生效"
}
```
**权限**: `manage:resources` (channel_admin, billing_admin, super_admin)
---
### 2.2 数据库变动
#### 新增表: tenant_model_keys
```sql
CREATE TABLE tenant_model_keys (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES users(id),
channel_id UUID REFERENCES channels(id),
-- 模型信息
model_name VARCHAR(100) NOT NULL,
-- LiteLLM Key 信息
litellm_key_id VARCHAR(255) NOT NULL, -- LiteLLM 返回的完整 key
litellm_key_hash TEXT NOT NULL, -- 加密存储
-- 配额配置（与 LiteLLM 同步）
rpm_limit INTEGER DEFAULT 0,
tpm_limit INTEGER DEFAULT 0,
max_budget NUMERIC(12, 2),
budget_duration VARCHAR(20) DEFAULT 'monthly',
-- 状态
status VARCHAR(20) DEFAULT 'active',
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
UNIQUE(tenant_id, model_name)
);
```
---
## 3. 用户端接口变动 (user.py)
### 3.1 新增接口
#### GET /api/user/models/available - 获取可用模型列表
**功能**: 返回当前租户已分配的所有模型
**响应**:
```json
{
"success": true,
"data": {
"models": [
{
"modelName": "azure/gpt-4",
"rpmLimit": 60,
"tpmLimit": 10000,
"maxBudget": 100.0,
"budgetDuration": "monthly",
"status": "active"
}
]
}
}
```
**权限**: 已认证用户
---
#### GET /api/user/models/usage/stats - 获取模型用量统计
**功能**: 从 LiteLLM 获取当前租户的模型用量统计
**响应**:
```json
{
"success": true,
"data": {
"models": [
{
"modelName": "azure/gpt-4",
"rpmLimit": 60,
"tpmLimit": 10000,
"maxBudget": 100.0,
"budgetDuration": "monthly",
"spend": 25.50,
"budgetRemaining": 74.50,
"status": "active"
}
],
"totalSpend": 25.50,
"totalBudget": 100.0
}
}
```
**权限**: 已认证用户
---
### 3.2 已修改接口
#### POST /api/user/custom-agents - 创建自定义 Agent
**变动说明**: 创建 Agent 时自动注入 LiteLLM Key 环境变量
**新增逻辑**:
1. 查询租户的模型 Key
2. 如果租户有可用的模型 Key，自动注入以下环境变量：
- `OPENAI_API_BASE`: LiteLLM 网关地址
- `OPENAI_API_KEY`: 租户的 LiteLLM Key
- `MODEL_NAME`: 模型名称
---
## 4. 接口变动汇总
### 4.1 超级管理员端 (admin.py)
| 接口 | 方法 | 变动类型 | 说明 |
|------|------|----------|------|
| `/api/admin/channels/create` | POST | 修改 | 响应新增 `litellmTeamId` 字段 |
| `/api/admin/channels/{id}` | DELETE | 修改 | 同步删除 LiteLLM team |
### 4.2 渠道端 (channel.py)
| 接口 | 方法 | 变动类型 | 说明 |
|------|------|----------|------|
| `/api/channel/tenants/{id}/models` | PUT | **新增** | 分配模型给租户 |
| `/api/channel/tenants/{id}/models` | GET | **新增** | 获取租户的模型列表 |
| `/api/channel/tenants/{id}/models/{model}` | DELETE | **新增** | 取消模型分配 |
| `/api/channel/tenants/{id}/models/{model}/quota` | PUT | **新增** | 更新模型配额 |
### 4.3 用户端 (user.py)
| 接口 | 方法 | 变动类型 | 说明 |
|------|------|----------|------|
| `/api/user/models/available` | GET | **新增** | 获取可用模型列表 |
| `/api/user/models/usage/stats` | GET | **新增** | 获取模型用量统计 |
| `/api/user/custom-agents` | POST | 修改 | 自动注入 LiteLLM Key |
---
## 5. 前端对接注意事项
### 5.1 渠道管理员界面
1. **租户详情页** 需要新增"模型管理"标签页，包含：
- 模型列表展示
- 分配模型按钮
- 配额编辑功能
- 取消分配功能
2. **分配模型表单** 需要包含：
- 模型选择（下拉框，从渠道已有模型中选择）
- RPM 限制输入
- TPM 限制输入
- 预算限制输入
- 预算周期选择（月度/总计）
### 5.2 租户用户界面
1. **仪表板** 可以展示：
- 可用模型列表
- 各模型的配额使用情况
- 预算剩余
2. **创建 Agent** 时：
- 如果租户有可用模型，Agent 会自动获得访问权限
- 无需用户手动配置 API Key
### 5.3 超级管理员界面
1. **渠道列表** 可以展示 `litellmTeamId`（可选）
2. **创建渠道** 后检查响应中的 `litellmWarning` 字段
---
## 6. 错误处理
### 6.1 常见错误码
| 错误码 | 说明 |
|--------|------|
| 400 | 参数错误（如无效的渠道ID格式） |
| 403 | 权限不足（如渠道没有该模型的权限） |
| 404 | 资源不存在（如租户不存在、模型分配记录不存在） |
| 500 | LiteLLM 操作失败 |
### 6.2 LiteLLM 操作失败处理
- 创建渠道时 LiteLLM team 创建失败：渠道仍会创建成功，响应中包含 `litellmWarning`
- 删除渠道时 LiteLLM team 删除失败：渠道仍会删除成功，响应中包含 `litellmWarning`
- 分配模型时 LiteLLM Key 创建失败：返回 500 错误，分配失败
- 更新配额时 LiteLLM Key 更新失败：返回 500 错误，更新失败
plans/超级管理员控制台-后端接口需求清单(已人工审核).md
-1503
View File
File diff suppressed because it is too large Load Diff