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

测试状态与查询

执行占用与测试结果分开处理：若原同步请求的最终结果仍未知，但已有服务商核查凭证确认执行结束、计费已结算，超级管理员可通过 POST /api/admin/ai-models/providers/{providerId}/verifications/{verificationId}/release-execution 登记执行结束。JSON 必须包含原 requestId、executionEnded: true、billingFinalized: true、reference、详细 note 与 confirmed: true。此操作仅新增审计，不修改原验证记录、请求号或幂等键，不开放模型，也不解除该模型的禁重发限制。其它模型可继续测试；进行中记录、异步任务或凭证不匹配时拒绝。

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

异步生图先持久化上游任务编号，再查询同一任务。OpenAI Chat Completions、Anthropic Messages 和已接入的同步图片协议，在已有客户请求编号、连接及路由仍匹配时，也可通过原 Key 只读取回原响应。恢复不发送生成正文或新的幂等头，不占用新的生成名额。文字联合测试取回一次原响应后，仍独立校验并保存两种用途的结果。

HTTP 410“未留存”、访问失败、格式或模型身份无法核对时，原结果仍保持待核查，不代表执行失败。不能取回原响应时，管理员必须先取得原请求最终状态的凭证，再在详情内填写核查记录；核查只关闭未知状态，不会通过接口测试或自动开放用途。进行中的请求不能核查关闭，仍可查询的原异步任务也不能人工跳过。连接不可用时可核查原请求，不需先重新启用上游。迟到的调用结果不会覆盖已关闭记录或写入虚假的通过审计。

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

联合测试的两个用途记录共享请求编号、执行编号和参考图检查点，只占一个执行名额；分析和文案各自保留验证上下文及通过证据。结果未知时暂停整次请求，核查提交须找到完整的两条记录，核查结束时在同一事务关闭两条记录；原请求仍可查询时只查询该请求。重新测试不会自动开放用途，旧单项测试和旧上游任务仍可按原方式核查。

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

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

图片用途的展开详情还显示参考图字段、内联或文件上传方式、提示词长度限制及当前实际请求参数。未传的可选参数明确使用上游默认值，不用示例或模型名称声称已指定尺寸和画质。此处是只读诊断，展开不会调用模型或保存设置。

同步目录时，若同一服务范围明确提供可接收私有参考图的异步图片任务，则优先绑定该任务协议，先保存任务编号再读取同一任务结果。尺寸、比例、分辨率及其它已适配参数按对应公开 Schema 校验后传入；不向异步任务强加同步 Images 接口的 n 或 response_format。明确像素尺寸与可选 resolution 不重复发送；固定约束冲突或必填参数尚未适配时拒绝该路由。协议或参数改变会使相应模型需要重新测试，不会自动转移旧通过记录或扩大开放范围。原任务查询严格只允许 GET，不接受新的正文、幂等键或路由覆盖。

当前适配协议

用途	已实现的协议适配	实际测试检查
资料分析	支持图片输入的 OpenAI Chat Completions 或 Anthropic Messages	能读取测试图片，并正确返回指定位置的颜色 JSON。
卖点文案	OpenAI Chat Completions 或 Anthropic Messages	返回符合详情页大纲校验的一屏 JSON。
分析与文案联合测试	同一路由、支持图片输入的 OpenAI Chat Completions 或 Anthropic Messages	一次请求返回 analysis、copy；两部分独立校验，分别保存通过或失败结果。
图片生成	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。

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

项目中的服务配置版本保留作审计。仅调整其它模型的开放用途或默认值，不会使当前模型身份不变的项目失效，也不要求重复付费分析。执行前仍检查当前权限、用途可用性、服务地址、协议指纹及密钥对应的验证记录；真正更换连接、密钥、协议或验证记录时，原模型快照仍会被拒绝。

详情页资料分析与文案恢复

POST /api/detail-generator/jobs/{id}/recover 复用登录鉴权，当前数据库超级管理员资格与任务创建者资格均须通过，且必须发送 Content-Type: application/json。

操作	请求正文	行为
取回原结果	{"action":"query"}	仅 GET 原客户请求的留存响应；原请求号不可替换。
补充已核实编号	{"action":"query","requestId":"已核实的原客户请求UUID"}	仅在此前未保存编号时使用；不是重发生成。
继续或重试文案	{"action":"continue"}	只允许已取回分析、或已确定结束的文案失败；复用已完成的事实分析，仅启动未完成的文案。

项目版本、原请求身份、任务租约和模型快照均保持校验。查询分析成功时，以单条状态更新保存事实并暂停，用户点击“继续文案”前不会产生新的文案调用。查询大纲成功时直接恢复项目大纲。已确定失败的文案可明确重试，服务端先持久化新尝试的幂等编号；未知结果不能借此更换编号重发。

新阶段启动时清除上一阶段的请求号，防止把分析请求误当成文案请求查询。恢复前的本地检查失败、410、连接中断或读取权限失败都不能当作原请求执行失败。截断、工具调用要求、非 JSON 或不符合结构的已完成响应则明确记为未通过，不执行模型要求的工具，也不自动重试。分析警告会带入文案，不能被文案模型悄悄删除。

逐模型参数、公开声明、实际适配与已有测试记录见 2026-10-16 模型合同核查。本次恢复验收与未完成项见 资料分析和文案恢复验收记录。公开 Schema 的透传字段不等于该模型的功能已经验收。

2026-10-16 下午通过 98k 对外接口复核恢复：公开目录、鉴权模型列表和此前已提交的异步图片任务结果均可读取，原任务已由生产 Worker 恢复完成，未重发生图。隔离验收中，Nano Banana 2、GPT Image 2.5 均通过四张独立参考图逐张内容校验，原结果可重新下载；GPT 6.1 的一次联合请求分别通过分析与文案校验，测试后的用途启用、默认值保存及权限拦截均已检查。GPT Image 2 的新测试返回 524，未返回客户请求号，保持结果未知且禁止自动重发；这不代表所有线路都已恢复。本轮隔离测试不改写生产用途验证记录，也不把测试数据库的记录复制为生产通过证据。证据见 output/98k-integration-recovery-20261016/。