gongxiangp2/docs/ai-model-management.md

AI 模型接入管理

入口：/admin → 超级管理员 → AI 模型接入。菜单和管理接口仅供当前数据库认定的在用、未归档超级管理员使用；撤权后的旧会话不能继续操作或请求上游。

管理流程

1. 已有服务端模型连接可用“迁入当前连接”显式转为数据库配置，默认名称为“平台模型服务”（旧默认名“现有详情页上游”）；这是连接名称，不是模型类别，也不限于详情页使用。迁入操作只保存配置，不调用模型。凭据继续引用固定的服务端 DETAIL_GENERATOR_API_KEY，不复制到浏览器。
2. 新增上游填写名称、HTTPS API 地址和 API Key。新增或替换凭据需已有专用 API_KEY_ENCRYPTION_KEY，最少 32 字节。凭据使用 AES-256-GCM 加密，接口只返回配置状态；编辑时密钥留空保持现状。
3. “同步目录”请求上游 /v1/models。当前接入的 api.vip98k.com 还读取其公开的 /api/v2/catalog/models 结构化能力目录，只保留当前 Key 有权使用的模型。模型数量取决于上游目录、Key 权限和同步结果，不固定为某个数量。新发现模型默认未开放；同步不会调用生成接口，也不会自动批量测试。
4. 搜索模型或上游，按对话、视觉理解、生图、语音合成、语音识别、音乐、视频、向量、图像工具、3D、其他或待识别筛选。分类由服务端读取能力及协议证据，不按模型名字猜测。类型已识别不代表当前详情页已接入该类型。
5. 在模型行选择测试用途，点击“测试”。确认“将实际调用模型，可能产生上游费用”后，只测试当前模型的当前用途。资料分析、卖点文案、图片生成分别记录结果；一个用途通过，不会替另一个用途背书。模型无需先开放即可测试；用户开放范围与默认值的未保存修改不阻止测试，结果刷新后保留草稿及原版本。上游连接必须已启用且配置密钥；编辑连接期间须先保存或取消，测试按钮旁显示阻止原因。
6. 用途实际测试通过后，勾选允许用户使用的用途，再勾选“开放”。测试成功不会自动开放模型。为三个阶段选择默认模型，点击“保存配置”后生效；没有有效测试结果、能力不符或尚未适配的用途不能开放。
7. 用户可在详情页“模型选择”中自行选择管理员已开放的模型，默认值只是新项目的初始选择。不同上游的同名模型以独立编号区分，实际请求仍使用上游原生模型 ID。详情页正式验收前仍只向超级管理员开放。

不再提供“确认接口兼容”人工勾选，配置接口也不接受 compatibility。是否可用由服务端的协议适配和当前用途的实际测试结果共同决定。后端在保存配置、设置默认值、提供用户候选列表及执行模型前共同复核，直接提交请求也无法越界。上游停用、能力撤销或验证失效后，旧项目和已排队任务也不能继续调用失效能力；已有内容仍可编辑、保存及导出。

测试状态与查询

界面状态	含义与操作
待测试	已有可执行的用途适配，尚无该用途的实际测试结果。
测试中	测试正在执行，自动只读刷新状态；禁止重复提交。
已通过	当前连接、密钥、模型能力、协议路由和适配版本对应的用途测试通过，可由管理员开放。
未通过	已得到明确失败结果；查看测试详情，处理原因后再显式测试。
暂停核查	请求是否完成尚不明确，禁止直接重测，避免重复计费。
已核查，可重测	有凭证证明原请求已结束；仍属于未通过，须重新进行实际测试。
需重新测试	连接、密钥、能力、路由或适配版本已改变，原测试结果不能继续作为开放依据。

异步生图先持久化上游任务编号，再查询任务结果。仅当结果未知、已有任务编号且当前连接及路由仍匹配时，显示“查询结果”；该操作只查询同一个上游任务，不重新发送生成请求。不能查询的未知结果显示“核查结果”：管理员在上游确认原请求未执行、失败或已完成后，填写凭证编号、核查说明并确认原请求已结束。服务端锁定记录，保存审计并将它关闭为未通过；不会变成已通过或自动开放。进行中的请求不能核查关闭，仍可查询的原任务也不能人工跳过。连接不可用时可核查原请求，不需先重新启用上游。迟到的调用结果不会覆盖已关闭记录或写入虚假的通过审计。

浏览器在提交前将请求编号保存在当前浏览器会话，丢失响应或重新加载后先恢复核查，不自动重发付费请求。“核查提交”与服务端受理共用事务锁：找到原记录就读取结果；没有受理记录就关闭该请求编号，拒绝其之后迟到的原提交。该操作不新建用途验证记录，也不会遮住其他未结束的测试。再次测试必须重新确认费用并使用新编号。真实测试与详情页生成共用执行额度：每人同时 1 个，全局同时 2 个；所有结果未知的测试在核查结束前保留占用。

2026-10-14 修复测试入口及异常恢复流程。测试、查询和刷新与未保存的开放设置独立，读取结果保留草稿及原版本；上层管理菜单也保护未保存修改与正在执行的操作。用途选择器与状态分开显示。真实隔离验收中，Gemini 3 Flash 的资料分析与文案、Nano Banana 2 的参考图生图通过；恢复查询沿用同一上游任务和测试编号，无新增生成受理。补充的 Claude Sonnet 4.6 请求结果未知，保持未开放，未重发。证据保存在 output/ai-workflow-20261014/；这不表示所有目录模型均已通过实测。

模型行的详情按钮默认折叠。展开后可查看当前用途实际绑定的协议、接口路径，以及目录提供的服务范围、路由和操作标识；已有结果还显示测试时间、消息和请求编号。这里显示服务端绑定，不允许前端随意修改路由。

当前适配协议

用途	已实现的协议适配	实际测试检查
资料分析	支持图片输入的 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。配置事务串行并核对版本，旧配置不能覆盖新修改。
• 调用上游前先持久化随机参考图检查点并复核数据库超级管理员与账号在用状态。分析须识别随机颜色及位置；生图须保留参考图颜色及相对位置，不能仅凭非空图片通过。验证规则变化使旧通过记录需重新测试，但不会阻断原异步任务的查询。正在执行或结果未知的同一模型禁止切换用途重复提交；已知异步任务只恢复查询。输出图片按公司需求限制在 1440px 内。
• capability_metadata 只持久化服务端归一化的能力证据，管理接口不接受客户端修改。公开能力目录无密钥请求，使用与私有请求相同的公网 DNS 固定、拒绝重定向和限时保护；公开目录限 8 MiB，私有模型列表保持 2 MiB。同步任一目录失败时不保存部分结果。
• 详情项目保存可信的上游及模型绑定，模型执行前重新核对可用性、权限和绑定。旧裸模型名只对应显式迁入的原服务，不能静默改到另一供应商。
• 缺少阶段默认模型时暂停生成；已有项目仍可修改文案、保存和导出。
• 受控迁移：20261012_ai_model_registry 新增配置表，20261013_ai_model_capabilities 新增能力证据列，20261013_ai_model_verifications 新增用途测试记录及唯一约束，并替换原人工兼容检查约束。历史 compatibility 值保留但不再参与可用性判定；迁移不会将其转换为“已通过”，也不含真实凭据、自动上游导入或付费测试。生产发布仍遵循标准备份、受控迁移及精确提交验证；禁止对生产运行 prisma db push。

是否可向用户开放，以当前服务端用途验证记录为准。实际执行过哪些模型及产品验收项目，须另附对应记录，不从目录数量、适配协议数量或部署成功推断。