model-management

模型管理

每次更改模型时，都使用此工作流。保持实现精简，除非用户明确批准更改，否则保留公开契约，并通过真实请求验证提供商行为。

首先加载上下文

1. 阅读仓库中的 AGENTS.md。
2. 阅读当前的注册表条目、运行时配置、处理程序、架构和测试。仓库是 Pollinations 当前所提供内容的事实来源。
3. 如有相关的本地有效计划，请阅读：
   • temp/manage_inference.md
   • temp/manage_inferenceport.md
   • temp/manage_gpus.md
   • temp/manage_azure_limits.md
4. 在 GitHub 上检查可能已经实现或与此工作冲突的未合并或已合并 PR。
5. 查阅当前官方提供商文档、目录、定价、可用性、配额和弃用通知。然后探测确切路由；实时响应优先于文档。

temp 计划属于被忽略的操作状态，不代表仓库的事实来源。在缺少这些文件的关联工作树中，使用 git worktree list 查找主检出目录，并在那里阅读这些计划。切勿将余额、价格、PR 状态、配额或候选项排名复制到此技能中。

在推荐路由或模型之前，请阅读 operating-policy.md。仅阅读任务所需的其他参考资料：

任务	必需的参考资料
查找代码或在本地运行	repository-and-local-testing.md
添加、更新、重新路由、重命名或移除	change-and-test-matrix.md
新模型、提供商、模型 ID 或价格	billing-verification.md

必须经过确认关卡

此关卡仅适用于拟议的受跟踪模型变更。不要将只读状态确认、对已有文档记录的规划决策的批准，或对操作事实的更正，转变为不同的变更。只有在完整契约已经展示的情况下，才将笼统的“确认”视为批准。

在用户确认模型的完整业务和推理契约之前，不要编辑任何模型。先检查代码和提供商；不要让用户替你查找各项值。

每个模型展示一行完整信息：

字段	必需值
规范名称	更改后的公开模型 ID
别名	所有兼容别名，或 none
priceMultiplier	提供商成本后的精确倍率
paidOnly	是否必须使用已购买套餐的余额
Pollinations GPU	仅当 Pollinations 运营生产硬件时填写 yes
注册表提供商	已配置的主提供商
主路由	提供商、部署/主机和精确的上游模型 ID
最佳备用候选项	提供商、部署/主机、精确的上游模型 ID，以及其成为最佳可行替代项的原因；若没有，则填写 none found 并列出已搜索的路由
Pollinations 备用方案	use <candidate> 或 none，并说明不采用该方案的原因或缺少可行候选项的原因

请询问：

请确认：规范名称 X、别名 A/none、价格倍率 M、仅付费 yes/no、Pollinations GPU yes/no、注册表提供商 P、主路由 R、最佳备用候选项 C/none found，以及 Pollinations 备用方案决定 use C/none。这些信息都正确吗？

答复仅批准所展示的值。如果某项值未知、推断得出、存在冲突或取决于路由，请标记为 UNKNOWN，说明依据，并等待用户针对该项作出明确决定。只有每行信息完整时，批量批准才有效。

公共 API 变更需要单独确认

模型审批并不授权添加、重命名、移除或更改公共端点、方法、传输方式、请求或响应架构、流式行为或事件协议。没有明确的用户或开发者问题需要解决时，不要提议更改 API 表面。

编辑前，请说明：

• 用户／开发者遇到的问题和当前公共契约；
• 拟议的具体路由、方法、传输方式、架构、流式行为和事件；
• 按照第 4 步中的顺序确定的兼容性参考；
• 此变更属于增量、行为变更、弃用还是破坏性变更，以及受影响的客户端；
• 迁移、共存和移除计划，或 none。

明确说明：This adds/changes the public API: ... 然后就这项具体的 API 变更征求明确确认。如果问题、标准或兼容性影响不明确，请勿编辑。

密钥需要单独审批

模型审批绝不授权添加、轮换、同步、部署、撤销或以其他方式变更凭据。请遵循 AGENTS.md 中明确规定的审批措辞、执行顺序、验证和回滚规则。不要在此处重复或弱化该流程。

工作流

1. 核对当前状态

• 将别名解析为规范注册表条目。
• API 密钥存储的是模型类别，而不是模型 ID，因此重命名不会影响密钥。模型类别发生变化时，能够访问该模型的受限密钥也会随之改变；请在 PR 中说明这一点。
• 审查自当前生产版本以来合并到 main 的所有模态注册表变更和模型变更；生产环境可能落后于 main。
• 如果注册表中缺少模型或提供方，请在重新添加前检查 git log --all -- <path> 和 gh pr list --state merged --search <model> — 它可能是被有意移除、添加后又撤销，或被替换。
• 追踪所有可达的运行时路由和任何已配置的回退方案。
• 区分已配置的提供方与实际处理观测请求的提供方。
• 将拟议变更与未关闭的 PR 和活跃计划条目进行比较。
• 生产验证通过后，将已交付的工作从活跃计划中移除；不要保留已完成的归档。

2. 调研确切路由

• 使用提供商/模型的官方来源，核实发布时间、模型身份、定价、区域、预览状态、配额、速率限制、上下文、输入、输出、工具、缓存和弃用情况。
• 对跨提供商的同一规范模型去重。
• 列出重要的路由差异。模型名称相同并不能证明能力相同。
• 探测 Pollinations 将使用的确切部署和请求格式。
• 对每项新增或修改，都要在提供商目录和官方文档中执行一次全新的网络搜索，以发现可行的备用路由；不能只依赖仓库集成或记忆中的可用性。根据候选项当前的官方模型页面和定价核实每个重要候选项，然后探测确切路由。比较检查点身份、能力、参数、格式、安全性/隐私、可用性、延迟、价格、权限和计费。推荐最佳候选项，或注明 none found；即使主路由运行正常，也绝不能省略备用方案的评估。
• 检查提供商管理的路由/回退默认设置和控制项。报告身份、能力、定价、数据驻留和可观测性方面的权衡。

要直接查询 Novita，请使用受支持的 模型目录 和账户配额，并使用现有的授权密钥。配额查询要求 modal=llm；使用 productType=Public Endpoint 和确切模型作为 quotaObject，分别查询 RPM 和 TPM，然后检查返回的身份。OpenAI 兼容的基础 URL 是 https://api.novita.ai/openai/v1；使用 Chat Completions 探测确切的上游模型。通过本地 Gen，在路由流量前，请求 stream_options.include_usage 以用于流式传输，并验证终止时的用量、缓存/推理计费、能力和突发容量。网关可用并不能证明可直接访问或拥有独立容量：由 Novita 提供上游支持的 OpenRouter/Vercel 路由可能共用同一上游资源池。将直接提供商的归属和费用与网关计费的流量区分开；有关受支持的计费来源，请参阅 Economics Novita connector guide。保留现有的公共契约和回退机制。

3. 确认契约

提交必需的条目，并在编辑前获得明确确认。如果有意更改能力或访问权限，请明确说明。

4. 实施最小的完整改动

• 规范公共 ID 使用 <publisher-slug>/<official-model-slug>。两个组成部分均使用小写，保留发布方的模型系列和版本，并在发布方存在公开 slug 时遵循该 slug。绝不臆造、删除或悄然升级版本。
• publisher 是人类可读的发布方（OpenAI、Anthropic、xAI），而非推理提供方。如果提供方部署 ID、大小写、标点和修订后缀属于路由细节，而非发布方公开模型身份，则将其保留在内部。
• 绝不在公共规范 ID 中编码推理提供方。通过注册表的有序回退关系声明自动路由，并在不同提供方之间将同一发布方模型去重为一个公共身份。
• 将隐藏的回退注册表条目命名为 <public-canonical-id>:<provider>。公共注册表键、目录、请求模型和权限均保留公共 ID。回退身份与优先级分开：绝不在这些 ID 中使用 :fallback、带编号的回退后缀或优先级标签。
• 对于固定的 OpenRouter 端点，从一开始就附加有意义的限定符：<public-canonical-id>:<provider>:<route-qualifier>，例如 google/gemini-2.5-flash-lite:openrouter:vertex-global 或 google/gemini-2.5-flash-lite:openrouter:ai-studio。明确区分通过同一提供方的多个部署。使用小写标签；绝不编码优先级或临时回退角色。更改顺序时保留回退注册表 ID。对于没有固定后端的提供方管理路由，不要臆造端点限定符。
• provider 字段和路由配置具有权威性；名称不会选择上游端点。仅用于回退的条目应保持隐藏、没有别名，并从目录和直接模型选择中排除。特定路由的成本应归属于服务定义；调用方保留所请求公共模型的价格。使用现有的共享回退机制。
• 规范名称变更时，保留现有的 resolved_model_requested、model_used、x-model-used、提供方、逐次尝试、社区和缓存归因语义。记录的 ID 可以采用新的拼写，包括隐藏的回退注册表 ID；不要强制将主要 ID 用作执行标识符。明确的主执行 ID 及其分析/标头约定推迟至 #14543。单独审查受影响的使用方和任何公共 API 变更；不要悄然改变 x-model-used 的用途或重写历史事件。
• 为内部路由命名时，保留完整的公共规范 ID，包括现有后缀。例如，google/gemini-2.5-flash-lite:search 的路由可以命名为 google/gemini-2.5-flash-lite:search:openrouter:ai-studio。这些只是命名示例，并不代表已配置的路由。通过明确的注册表键关联路由；不要拆分或去掉冒号后缀来推断提供方或回退关系。回退必须保留公共模型的行为，包括此例中的搜索功能。
• 如果用户必须有意选择同一发布方模型的单独定价或仅付费版本，则将其公开为 <public-canonical-id>:paid，绝不要在 slug 中使用推理提供方。将其视为具有独立价格、paidOnly 值、权限和别名的独立公共约定。不要将 :paid 用于自动回退路由。
• 当多个条目仅仅是同一发布方模型的操作或参数预设时，应将其合并到该模型身份下，并通过明确的端点或请求字段选择操作。不要创建第二个规范模型，也不要让别名选择行为。
• 复用现有处理程序、转换、提供方配置、架构和通用回退基础设施。
• 根据提供方随每次响应报告的用量计费：使用其用量区块或计费标头，例如 fal 的 x-fal-billable-units。不要根据请求重建提供方的计算公式（取整、最低值、每个参考项的用量、参数乘数）。当路由未报告用量时，根据请求推导用量，并与提供方的计费记录核对。
• 仅实现明确批准的回退决策。对于获批的模型对，使用共享通用回退系统；不要添加特定于模型的重试层或未经批准的回退。
• 按照上述 API 变更确认流程，确认新的公共能力后，通过由同一实现支持的两个入口公开该能力：一个是 /v1 之外的 Pollinations 原生路由，另一个是 /v1 下的标准兼容路由。
• 按以下顺序确定兼容性约定：（1）当前官方 OpenAI API；（2）如果 OpenAI 未定义等效能力，则使用当前已发布的 OpenRouter 约定——此处仅作为协议设计参考，而非推理提供方回退；（3）如果两者都未定义该能力，则停止并明确决定 API 约定。记录核查的具体参考资料。
• 将 /v1 视为兼容性命名空间：严格匹配所选标准的路由、传输、请求、响应、流式传输和事件约定，并将特定于提供方的协议置于路由适配器之后——绝不要在 /v1 下使用 Pollinations 特有或上游提供方的架构。
• Pollinations 原生路由也优先采用所选标准的架构；若有意采用不同的原生架构，则需单独明确确认 API 变更。
• 不要仅通过切换 model，就将输入、输出或传输存在实质差异的能力合并到一个端点中。应将不同操作分开，同时复用其内部处理程序、授权、计费和可观测性路径。
• 将别名仅视为身份标识：解析为规范模型后，丢弃请求中的别名，不让其影响行为。绝不要根据 -high、-search、-reasoning 或 -1080p 等别名拼写推断参数；仅使用明确的请求参数和规范默认值。如果必须保留旧行为，则保留单独的规范模型。
• 在通用处理程序中，使用已解析的注册表条目作为规范模型身份。绝不要在处理程序层维护模型 ID 列表来控制响应、跟踪、计费或路由行为。
• 在同一个 D1 迁移 PR 中，通过相同的全注册表审计，规范化所有发现的过时存储别名。替换旧 ID，保留无关字段和数组顺序，去重旧/新 ID 对，证明操作具有幂等性，并在部署后验证所有已审计旧 ID 的计数均为零。
• 每条迁移语句都必须符合 D1 的单查询 CPU 限制：每个别名一条语句，并在 CASE 中使用 instr() 进行预筛选，确保 JSON 函数不会在不匹配的行上运行。在整个表上执行单次 JSON 扫描会在生产规模（约 150k 个 apikey 行）下报错 7429。
• 不要使用今天可变的别名重写历史分析数据。
• 一次性更新所有使用发生变化的公共 ID 的使用方。
• 新模型（包括新版本和检查点）不得有别名。
• 删除前保留现有别名目标。
• 通过明确的迁移停用所有旧别名。
• 在 shared/registry/ 中维护模型名称和别名；公共列表使用实时模型目录，而不要维护重复的 Markdown 列表。
• OpenRouter 注册表成本包含 5.5% 的额度购买手续费：每个非零基础费率和成本变体费率都写为 baseRate * 1.055（例如 perMillion(0.75) * 1.055）。计入搜索、缓存存储和其他可计费调整，包括提供方报告的费用。保持 priceMultiplier 不变；价格根据包含手续费的成本计算。在注册表条目中声明这一点，不要对整个提供方进行统一转换。手续费恰好应用一次：同一提供方的回退可以继承包含手续费的费率；跨提供方回退则需要在继承会导致手续费被重复计入或漏计时，明确指定成本。
• 每个模型或紧密耦合的模型系列变更使用一个 PR。
• 绝不要编辑生成的 APIDOCS.md；更新源架构或路由。

5. 端到端验证

• 按照 change-and-test-matrix.md 执行相关行中的测试。
• 对于新模型以及提供商或模型 ID 变更，运行完整的声明模态矩阵和 billing-verification.md 中的验证。
• 测试别名、权限、错误、缓存、容量和 /models 元数据。
• 配置了回退时，直接探测回退模型，并通过强制回退运行同一套适用的端到端矩阵，包括能力、参数、权限、缓存行为、计费、提供商归属、错误和预期突发负载。未批准回退时，记录经过调研的候选方案及拒绝原因。
• 验证所有媒体都能在受支持的请求生命周期预算内完整返回；适用时，还要进行持久媒体检查。
• 在 PR 中记录确切的证据和不确定之处。

6. 创建 PR

发布前：

• 使用仓库格式化工具格式化有更改的文件。
• 对每个有改动的服务运行针对性测试和类型检查。
• 检查完整差异，确保没有无关更改和无用代码。
• 包含已批准的契约、确切的主要候选项和回退候选项、回退决定、定价来源、实时探测结果、端到端测试结果、计费证据、容量结果、限制以及弃用／配额门槛。
• 如果实时状态、配额、延迟、安全或产品决策仍未解决，请将 PR 保持为草稿。

PR 描述必须为每个受影响的模型提供用户可见的变更表，并使用其公开模型 ID：

模型	操作	变更	之前	之后	生效时间
<public ID>	NEW / UPDATE / RETIRE	价格 / 余额 / 能力 / 可用性	确切的原值	确切的新值	生产部署时间或预定日期及其时区

• 对新提供的公开模型 ID 使用 NEW，对现有模型的变更使用 UPDATE，对从可用状态中移除的模型使用 RETIRE，并在移除模型的 PR 中注明。注册表不保留退役日期；在受影响路由的代码注释中注明提供商的截止日期。
• 只有在确定退役后（其他提供商都不会继续提供该模型）才发布退役公告：合并一个表格中含有 RETIRE 行的 PR，并在 Effective 中填写未来日期和时区，例如 2026-11-02 00:00 UTC。移除模型的 PR 合并前，新闻会将其显示为即将退役。要推迟退役，请合并一条填写新日期的 RETIRE 行；要撤销退役，请将 Effective 设为 Cancelled。避免将日期提前。
• 只列出变更。根据基准代码和拟议代码／目录读取数值；不要从 PR 标题推断数值，也不要编造缺失的值。
• 对于价格，请注明货币、计费单位和每项变更的费率（例如每百万 Token 的输入／输出费率）。对于余额访问权限，请注明 Quest + Paid 或 Paid only。对于能力，请说明新增或移除的内容。
• 对于新模型，Before 使用 Unavailable，并在 After 中注明初始价格、余额访问权限和能力。对于退役模型，显示 Available → Retired；只有在明确配置或批准时才注明替代模型。
• 合并不等于部署。除非已知预定日期或经过验证的部署状态，否则使用 On production deployment (not live yet)。如适用，请链接现有公告及其 notice_id。
• 对于没有用户可见差异的纯提供商变更，请说明价格、余额访问权限、能力和可用性均未变化，而不要添加状态行。将提供商和验证证据单独列在摘要下方。

完成门槛

只有满足以下所有适用条件，模型变更才算完成：

• 已配置的模型、别名、提供方、路由、价格、访问权限、模态和能力均符合已批准的约定。
• 每个已声明的使用界面均已通过直接调用提供方和本地 E2E 请求测试。
• 已记录最佳备用候选项及采用／不采用的决定；每个已配置的备用方案均已通过直接调用和强制备用方案 E2E 验证。
• 除非已明确批准，否则不得移除任何现有能力。
• 所有非零用量字段均已核算，并按已确认的费率计费；如果路由报告了用量，则以提供方报告的用量为准。
• 格式错误或被拒绝的请求应返回有用的 4xx 响应，而不是含糊的 5xx 响应。
• 容量和媒体延迟满足预期的生产负载要求。
• 目录描述面向开发者，不重复标题，且发布方徽标可正常显示。
• 未经单独明确确认，不得添加或更改任何公共 API 接口。
• 未发生未经批准的密钥或部署变更。
• PR 仅包含此模型或紧密耦合的模型系列。