8.5 KiB
AI 模型接入管理
入口：/admin → 超级管理员 → AI 模型接入。菜单和管理接口仅供当前数据库认定的在用、未归档超级管理员使用；撤权后的旧会话不能继续操作或请求上游。
管理流程
- 已有详情页上游可用“迁入当前连接”显式转为数据库配置；迁入操作只保存配置，不调用模型。凭据继续引用固定的服务端
DETAIL_GENERATOR_API_KEY，不复制到浏览器。 - 新增上游填写名称、HTTPS API 地址和 API Key。新增或替换凭据需已有专用
API_KEY_ENCRYPTION_KEY，最少 32 字节。凭据使用 AES-256-GCM 加密，接口只返回配置状态；编辑时密钥留空保持现状。 - “同步目录”请求上游
/v1/models。当前接入的api.vip98k.com还读取其公开的/api/v2/catalog/models结构化能力目录，只保留当前 Key 有权使用的模型。模型数量取决于上游目录、Key 权限和同步结果，不固定为某个数量。新发现模型默认未开放；同步不会调用生成接口，也不会自动批量测试。 - 搜索模型或上游，按对话、视觉理解、生图、语音合成、语音识别、音乐、视频、向量、图像工具、3D、其他或待识别筛选。分类由服务端读取能力及协议证据，不按模型名字猜测。类型已识别不代表当前详情页已接入该类型。
- 在模型行选择测试用途，点击“测试”。确认“将实际调用模型，可能产生上游费用”后，只测试当前模型的当前用途。资料分析、卖点文案、图片生成分别记录结果；一个用途通过，不会替另一个用途背书。存在未保存的配置时，先保存或撤销，再测试。
- 用途实际测试通过后，勾选允许用户使用的用途，再勾选“开放”。测试成功不会自动开放模型。为三个阶段选择默认模型，点击“保存配置”后生效；没有有效测试结果、能力不符或尚未适配的用途不能开放。
- 用户可在详情页“模型选择”中自行选择管理员已开放的模型，默认值只是新项目的初始选择。不同上游的同名模型以独立编号区分，实际请求仍使用上游原生模型 ID。详情页正式验收前仍只向超级管理员开放。
不再提供“确认接口兼容”人工勾选，配置接口也不接受 compatibility。是否可用由服务端的协议适配和当前用途的实际测试结果共同决定。后端在保存配置、设置默认值、提供用户候选列表及执行模型前共同复核，直接提交请求也无法越界。上游停用、能力撤销或验证失效后，旧项目和已排队任务也不能继续调用失效能力；已有内容仍可编辑、保存及导出。
测试状态与查询
| 界面状态 | 含义与操作 |
|---|---|
| 待测试 | 已有可执行的用途适配，尚无该用途的实际测试结果。 |
| 测试中 | 测试正在执行，禁止重复提交；“刷新测试状态”只重新读取平台记录。 |
| 已通过 | 当前连接、密钥、模型能力、协议路由和适配版本对应的用途测试通过，可由管理员开放。 |
| 未通过 | 已得到明确失败结果；查看测试详情，处理原因后再显式测试。 |
| 暂停核查 | 请求是否完成尚不明确，禁止直接重测，避免重复计费。 |
| 需重新测试 | 连接、密钥、能力、路由或适配版本已改变，原测试结果不能继续作为开放依据。 |
异步生图先持久化上游任务编号，再查询任务结果。仅当已有任务编号且当前连接及路由仍匹配时，显示“查询结果”；该操作只查询同一个上游任务，不重新发送生成请求。没有已知任务编号时，保持暂停，按测试详情中的请求编号核查上游记录。
浏览器丢失测试响应后只查询状态，不自动重发付费请求；如果状态仍是旧记录，当前页面保留暂停状态。重复的同一幂等请求也不会新建模型调用。真实测试与详情页生成共用执行额度：每人同时 1 个，全局同时 2 个。
模型行的详情按钮默认折叠。展开后可查看当前用途实际绑定的协议、接口路径，以及目录提供的服务范围、路由和操作标识；已有结果还显示测试时间、消息和请求编号。这里显示服务端绑定，不允许前端随意修改路由。
当前适配协议
| 用途 | 已实现的协议适配 | 实际测试检查 |
|---|---|---|
| 资料分析 | 支持图片输入的 OpenAI Chat Completions 或 Anthropic Messages | 能读取测试图片，并正确返回指定位置的颜色 JSON。 |
| 卖点文案 | OpenAI Chat Completions 或 Anthropic Messages | 返回符合详情页大纲校验的一屏 JSON。 |
| 图片生成 | OpenAI Images Edits；明确支持私有参考图内联输入的 Images Generations 或异步图片任务 | 请求可接受参考图，结果可解码、尺寸有效且非空白。 |
具体接口以每个模型的服务端协议绑定为准。同步时在目录明确的服务范围内选择可执行路由，并保留对应标识；执行时不会静默换路由。专用协议或异步接口只有符合已实现适配及私有参考图输入要求时，才可进入相应用途测试；纯文生图不因此获得产品参考图能力。
当前业务工作台仍只有详情页的三个用途。语音、音乐、视频、向量、图像工具及 3D 可以在目录中分类查看，但本次没有为它们增加生成工作台，也不能因出现在目录就勾选为生图用途。无可靠能力信息的模型保持“待识别”；明确不满足用途输入输出要求的模型不能通过人工确认绕过。
界面借鉴家具项目的连接编辑、获取目录和就近反馈方式。家具项目“测试并获取模型”的目录 GET 只证明目录连接，本项目另设的按用途真实调用才产生用途验证记录。目录同步、接口测试通过、真实产品生成质量和完整详情页验收是不同证据；这里不代表所有目录模型均已实测，也不代表品牌风格、PSD 可编辑性或 Photoshop 验收已经完成。
安全与数据
- 只接受 HTTPS 标准端口、无嵌入凭据或查询参数的服务地址；解析的全部 IP 都须为公网地址，并将已检查地址固定到实际 HTTPS 连接。拒绝跳转，防止 API Key 被带到其他地址。
- 修改 API 地址必须同时填写该服务的密钥，并清除原地址的目录配置。验证上下文包括连接、密钥、能力、协议路由及适配版本；任何相关变化都会使旧通过记录失效。密钥不会进入响应、审计元数据或项目快照。
- 上游、模型目录、阶段默认值及审计记录保存在
ai_model_providers、ai_model_catalog、ai_model_configuration、ai_model_audit。用途测试记录及任务检查点保存在ai_model_verifications。配置事务串行并核对版本，旧配置不能覆盖新修改。 - 调用上游前先持久化测试记录并复核数据库超级管理员权限。正在执行或结果未知的同一模型用途禁止重新提交；已知异步任务只恢复查询，不重新生成。
capability_metadata只持久化服务端归一化的能力证据，管理接口不接受客户端修改。公开能力目录无密钥请求，使用与私有请求相同的公网 DNS 固定、拒绝重定向和限时保护；公开目录限 8 MiB，私有模型列表保持 2 MiB。同步任一目录失败时不保存部分结果。- 详情项目保存可信的上游及模型绑定，模型执行前重新核对可用性、权限和绑定。旧裸模型名只对应显式迁入的原服务，不能静默改到另一供应商。
- 缺少阶段默认模型时暂停生成；已有项目仍可修改文案、保存和导出。
- 受控迁移：
20261012_ai_model_registry新增配置表，20261013_ai_model_capabilities新增能力证据列，20261013_ai_model_verifications新增用途测试记录及唯一约束，并替换原人工兼容检查约束。历史compatibility值保留但不再参与可用性判定；迁移不会将其转换为“已通过”，也不含真实凭据、自动上游导入或付费测试。生产发布仍遵循标准备份、受控迁移及精确提交验证；禁止对生产运行prisma db push。
是否可向用户开放，以当前服务端用途验证记录为准。实际执行过哪些模型及产品验收项目，须另附对应记录，不从目录数量、适配协议数量或部署成功推断。