# 模型管理补全记录

日期：2026-07-07

## 本次目标

把管理后台的模型管理从“只保存一个 OpenAI 兼容地址”补全为可维护的第三方 LLM 配置能力。当前交互收敛为两个常用厂商快速添加，以及两种协议级通用添加。

## 参考口径

本次以各供应商公开接口文档的共同配置项为基础，不绑定某一个供应商 SDK：

- OpenAI 兼容类：统一使用 `chat/completions` 风格，支持 `model`、`messages`、`temperature`、`top_p`、`max_tokens`、`stream`、`response_format` 等常见参数。
- Anthropic Messages 类：统一使用 `/v1/messages` 风格，支持 `model`、`messages`、`system`、`max_tokens` 等常见参数。
- DeepSeek：作为快速添加厂商，默认走 OpenAI 兼容协议。
- MiniMax：作为快速添加厂商，默认走 Anthropic Messages 兼容协议。

## 已完成

### 后端

- 扩展 `sys_model` 数据结构，新增：
  - `display_name`
  - `api_type`
  - `base_url`
  - `auth_type`
  - `api_version`
  - `top_p`
  - `top_k`
  - `presence_penalty`
  - `frequency_penalty`
  - `context_window`
  - `stream_enabled`
  - `response_format`
  - `extra_params`
  - `remark`
- 新增 Alembic 迁移 `0002_expand_model_config`。
- 扩展模型创建接口，支持保存完整第三方 LLM 参数。
- 新增模型更新接口：
  - 编辑模型时如果 API Key 留空，则保留原 API Key。
  - 这样可以避免后台人员每次改参数都必须重新粘贴密钥。
- 新增模型测试接口：
  - 后台可直接发起一次轻量测试。
  - 返回可用状态、错误信息和部分模型回复。
- 扩展 `ModelClientService`：
  - `openai_compatible`：按 OpenAI 兼容 `chat/completions` 调用。
  - `anthropic_messages`：按 Anthropic Messages API 调用。
  - `gemini_generate_content`：按 Gemini generateContent 调用。
  - `extra_params` 支持 JSON 对象透传，用于补充供应商特有参数。

### 管理后台

- 模型管理表单改为“快速添加 + 按协议添加”两段。
- 新增快速添加：
  - DeepSeek：填写 API Key，选择 `deepseek-v4-pro` 或 `deepseek-v4-flash`。
  - MiniMax：填写 API Key，选择 MiniMax-M3、MiniMax-M2.7、MiniMax-M2.5 等模型。
- 通用添加只保留协议模板：
  - OpenAI 兼容协议。
  - Anthropic Messages 协议。
- 新增参数配置：
  - 协议类型
  - Base URL
  - API URL 覆盖
  - 鉴权方式
  - API Version
  - Temperature
  - Top P
  - Top K
  - Presence Penalty
  - Frequency Penalty
  - Max Tokens
  - 上下文窗口
  - 流式输出开关
  - 响应格式
  - 高级 JSON 参数
  - 备注
- 新增编辑模型、测试模型、启用模型操作。
- 前端保存前增加基础校验：
  - 新增模型必须填写 API Key。
  - 编辑模型允许 API Key 留空。
  - Base URL 和 API URL 至少填写一个。
  - 高级 JSON 参数必须是 JSON 对象。

## 默认工程决策

| 编号 | 决策 | 原因 |
| --- | --- | --- |
| M-001 | 第三方 LLM 分为 OpenAI 兼容协议和 Anthropic Messages 协议两类。 | 这两类是当前 Agent/LLM 配置中最常见的接入形态，后台不再为每个供应商堆大量预设。 |
| M-002 | `apiUrl` 可以为空，优先由 `baseUrl + apiType` 自动拼接。 | 后台人员更容易配置，只要填供应商 Base URL 和模型名即可；高级场景仍可用 API URL 覆盖。 |
| M-003 | 编辑模型时 API Key 留空表示不修改。 | 避免密钥频繁暴露和重复粘贴，降低误改风险。 |
| M-004 | 高级参数使用 JSON 对象透传。 | 保留不同供应商的扩展能力，同时避免每个小参数都单独改数据库结构。 |
| M-005 | Anthropic Messages 协议模板默认不强行填采样参数。 | 部分模型对非默认采样参数较敏感，协议模板应先保证能通，再由后台人员按需调整。 |
| M-006 | 模型测试接口直接调用真实供应商。 | 这是后台配置验收动作，应该真实发现 Key、URL、模型名和参数错误。 |
| M-007 | DeepSeek 和 MiniMax 作为快速添加厂商。 | 一期高频模型供应商不需要后台人员理解协议细节，只填 API Key 和模型即可。 |

## 当前边界

- API Key 当前仍存储在数据库字段中，生产环境建议后续升级为加密存储或环境变量引用。
- 流式输出字段已保存，但当前真实模型调用仍以非流式方式完成，用户端 SSE 分块由后端模拟输出。
- 不同供应商的费用、限流、区域和模型上下文窗口仍需要运营配置时自行确认。
- `extra_params` 由后台人员自行维护，系统只校验 JSON 对象格式，不校验供应商语义。
- 后端仍保留 Gemini generateContent 适配代码，但当前后台入口不再暴露 Gemini 协议模板；如后续确认为高频供应商，再单独设计快速入口。

## 本次验证

- 后端编译检查：通过。
- 后端 OpenAPI 检查：通过，当前 `paths` 数量为 34。
- Alembic MySQL 静态 SQL 检查：通过，迁移 SQL 生成成功。
- 用户端 H5 构建：通过。
- 管理后台构建：通过。
- Docker Compose 配置检查：通过。
- `git diff --check`：通过。

说明：模型管理补全后曾出现 Vite 单 chunk 过大提示，已在 `2026-07-07-admin-web-build-optimization.md` 中完成管理后台构建体积优化。

## 后续建议

1. 接入生产前补充密钥加密或密钥引用机制。
2. 增加“复制模型配置”能力，方便按环境复制供应商参数。
3. 增加模型测试结果记录，便于排查某个供应商近期是否不稳定。
4. 接入真实流式模型后，再把 `stream_enabled` 从配置字段升级为真实调用策略。
