注册模型与团队授权

Clouisle 的模型是两级结构：管理员先在管理后台的模型页登记全局模型（供应商、端点、凭据、能力、定价），再把模型授权给团队并设置配额。平台界面（模型页、Agent 与工作流的选择器）只展示当前团队已授权的模型。

注册全局模型

在管理后台 > 模型中选择添加模型，填写后先测试连接再保存。可写字段与约束：

示例：登记一个 OpenAI 对话模型。

{
  "name": "GPT-4 Turbo",
  "provider": "openai",
  "model_id": "gpt-4-turbo-preview",
  "model_type": "chat",
  "api_key": "sk-...",
  "context_length": 128000,
  "max_output_tokens": 4096,
  "input_price": 10.0,
  "output_price": 30.0,
  "default_params": {"temperature": 0.7, "top_p": 0.9},
  "capabilities": {"streaming": true, "function_call": true}
}

Azure OpenAI 的部署名与 API 版本通过 config 传递，model_id 填部署名：

{
  "name": "GPT-4 (Azure)",
  "provider": "azure_openai",
  "model_id": "gpt-4-deployment",
  "model_type": "chat",
  "base_url": "https://your-resource.openai.azure.com",
  "config": {"api_version": "2024-02-15-preview", "deployment": "gpt-4-deployment"}
}

发现供应商模型

创建表单在未保存状态下可点发现模型：填好 base_url 与 API Key 后，后台会调用供应商的模型列表接口（如 /v1/models、Ollama 的 /api/tags），把 id、name、上下文长度、最大输出与能力标记回填到表单，避免手写错了 model_id。16 个供应商支持发现，azure_openai、runway、pika、luma、kling、stability、midjourney 不支持。完整规则（路径、鉴权、15 秒超时、2 MiB 上限、TypeSafe 网关路径重写）见供应商、模型类型与模型发现。

凭据与端点

• api_key 由后端加密保存。读取模型的任何接口只返回 has_api_key: true/false，永远不会回显明文；轮换密钥时在编辑表单填入新值即可。
• API Key 格式会被校验：openai 必须以 sk- 开头，anthropic 必须以 sk-ant- 开头，否则报 invalid_api_key_format。ollama 是唯一不需要 API Key 的供应商。
• 实际请求地址由「模型 base_url → 类型专属默认 → 供应商默认」决定，见供应商标识与默认端点。选择用的端点必须是白名单内 Origin。

能力标记

capabilities 是驱动 UI 与运行时行为的能力开关，共四个：

Agent 启用工具前，务必确认所选对话模型真实支持 function_call；可先点发现模型读取供应商声明，再手工校正。

测试连接

两个测试端点，权限与用途不同：

测试按 model_type 走该类型的真实适配器发一次最小请求：

响应固定为 success、message、latency_ms。注意两点：

启用、禁用与默认模型

• is_enabled 是模型的唯一状态位：关闭后该模型不再出现在选择器中，但配置与团队授权都保留，重新打开即恢复。
• 没有 testing、deprecated 等中间状态，也没有弃用提示、EOL 日期或替代模型建议。
• is_default 按 model_type 唯一：调用 POST /api/v1/admin/models/{model_id}/set-default 时，会把同类型其他模型的默认标记清除。知识库的嵌入模型、Agent 未指定模型时的兜底都依赖它。

授权模型给团队

1. 进入管理后台 > 团队，打开目标团队。
2. 切到已授权模型标签页，选择添加模型。
3. 勾选一个或多个全局模型（下拉只列出尚未授权且全局启用的模型），可多选后一次提交。
4. 对每个授权填写每日/月度 Token 与请求限额，以及优先级；留空表示无限制。
5. 保存后团队成员在模型页即可看到该模型（详见下一节）。

授权是「团队 + 模型」的唯一约束：同一模型重复授权会返回「已授权」。批量授权 POST /teams/{team_id}/models/batch 只对新模型生效，已存在的授权会被跳过；批量撤销 DELETE /teams/{team_id}/models/batch 返回实际删除数量。

团队成员看到的模型页展示本团队全部授权（含 is_enabled: false 的停用项，可用状态筛选区分）；而在 Agent、工作流等选择模型的下拉里，只有「授权且启用」的模型可出现（GET /teams/{team_id}/available-models 只返回 is_enabled=true 且模型全局启用的授权）。

配额与用量

四项限额都可为 null（无限制），且 0 是合法值（等于立刻触顶）：

判定语义并不一致，配置时要注意：

• Token 限额：已用 + 本次预估 > 限额 才拒绝。因此恰好等于限额不会立刻失败，但只要再加一点就超。
• 请求次数限额：已用 >= 限额 即拒绝，即第 limit 次请求本身可以成功，第 limit + 1 次被拒。
• 用量按站点时区（TIMEZONE，默认 Asia/Shanghai）惰性重置：每日在当天 00:00 之后、每月在当月 1 日 00:00 之后，下一次配额检查时归零并写回。
• 超限时对话接口返回业务错误 6103、HTTP 429，消息为「模型配额已用尽」。

GET /teams/{team_id}/models/quota 返回每个授权的限额、已用值与百分比。注意 is_quota_exceeded 只根据 Token 限额计算（已用 >= 限额），请求次数是否超额要自己比对 daily_request_limit 与 daily_requests_used。

优先级

priority 默认为 0，仅影响同类型模型的排序，不改变可用性。团队模型列表按 -priority, created_at 排序，可用模型列表按 -priority 排序——数值越大越靠前，用于把推荐模型顶到选择器前列。修改任一项限额或优先级都在编辑弹窗中完成。

修改、撤销与删除

故障排除

连接测试失败

1. 检查白名单：自定义 Endpoint 的 scheme://host:port 是否已在站点设置 > 安全 > 模型端点白名单中。
2. 检查凭据格式：openai 需 sk- 前缀，anthropic 需 sk-ant- 前缀；确认密钥未过期且具备目标模型权限。
3. 检查供应商与类型匹配：如 anthropic + embedding、stability + text_to_video 会在调用期报不支持，而非保存期。
4. 检查网络：默认 15 秒超时、禁止重定向；内网端点确认可达且未被防火墙拦截。
5. 检查上游状态：供应商侧限流或故障会表现为测试失败，但限流通常仍返回 success: true。

提示配额已用尽（6103 / HTTP 429）

1. 调用 GET /teams/{team_id}/models/quota 查看哪个限额触顶。
2. 调大限额、换用未触顶的同类型模型，或等待次日/次月惰性重置。
3. 若疑似误判，检查是否有单次超大请求；Token 上限按「已用 + 预估」判断。

响应缓慢或超时

1. 核对模型的 context_length 与 max_output_tokens，过大的输出上限会显著拉长响应。
2. 降低 max_tokens、启用流式（capabilities.streaming）或改用更快的模型。
3. 视频类模型检查 config.poll_timeout_s，默认 120 秒可能短于供应商出片时间。

API 访问

管理端模型端点在 /api/v1/admin/models 下，按操作分别要求 admin:model:read、admin:model:create、admin:model:update、admin:model:delete。端点清单见 Models API。

# 列出模型（管理员）
models = api.get("/api/v1/admin/models")

# 创建模型
model = api.post("/api/v1/admin/models", json={
    "name": "GPT-4 Turbo",
    "provider": "openai",
    "model_id": "gpt-4-turbo-preview",
    "model_type": "chat",
    "api_key": "sk-...",
    "input_price": 10.0,   # 每百万 Token
    "output_price": 30.0
})

# 保存前测试配置（凭据不入库）
api.post("/api/v1/admin/models/test", json={
    "provider": "openai",
    "model_id": "gpt-4-turbo-preview",
    "model_type": "chat",
    "api_key": "sk-..."
})

# 测试已保存的模型
api.post(f"/api/v1/admin/models/{model_id}/test")

# 发现供应商可用模型
api.post("/api/v1/admin/models/discover", json={
    "provider": "openai",
    "base_url": "https://api.openai.com/v1",
    "api_key": "sk-..."
})

# 设为该类型的默认模型
api.post(f"/api/v1/admin/models/{model_id}/set-default")

# 授权给团队（仅超级管理员），并设置配额与优先级
api.post(f"/api/v1/teams/{team_id}/models", json={
    "model_id": str(model_id),
    "daily_token_limit": 1_000_000,
    "monthly_token_limit": 20_000_000,
    "daily_request_limit": 2000,
    "monthly_request_limit": 40000,
    "priority": 10
})

# 批量授权 / 批量撤销
api.post(f"/api/v1/teams/{team_id}/models/batch", json={
    "model_ids": [str(a), str(b)],
    "monthly_token_limit": 5_000_000
})
api.delete(f"/api/v1/teams/{team_id}/models/batch", json={"model_ids": [str(a)]})

# 查看配额使用状态
api.get(f"/api/v1/teams/{team_id}/models/quota")

相关页面

• 供应商、模型类型与模型发现 — 23 个供应商标识、默认端点与发现规则
• 模型 — 两级结构与配额概念
• 团队与权限 — 团队成员角色