调用接口时同一个模型经常有好几个名字：有的带日期后缀，有的是不带后缀的短名，改一个字符跑出来的结果就可能不一样。这篇不讨论哪个模型更强，只讲命名规则本身：别名怎么指向最新、快照怎么固定版本、怎么查清手里这个名字实际会路由到哪一版，以及它什么时候会变。
调用接口时一个模型经常有好几个名字：有的带日期后缀，有的是不带后缀的短名，改一个字符跑出来的结果就可能不一样。这篇不讨论哪个模型更强，只讲命名规则本身：别名怎么指向最新、快照怎么固定版本、怎么查清手里这个名字实际会路由到哪一版，以及它什么时候会变。
先说清楚它解决的问题：名字不是给模型贴标签，而是给你和平台之间定一份契约。你写进请求体的那串字符串决定平台把请求发给谁，而平台随时可能让某些名字改指向。下面按「为什么会有多个名字、名字里能读出什么、怎么确认、什么时候会变、团队怎么记」的顺序讲。
同一个模型为什么会有好几个名字
厂商通常同时提供两类名字。一类固定在某个时点，行为不再变，叫快照；一类永远指向当前最新，会随官方更新漂移，叫别名。别名的意义是让接入方少改配置，代价是你没法预知下一次调用是不是同一版；快照的意义是可复现，代价是它迟早会被下线或降级维护。
- 别名
- 永远指向当前最新版的名字，省事但会漂移
- 快照
- 固定在某个时点的名字，稳定但会到期
- 回显版本
- 响应体里平台真实使用的版本标识，比请求名更可信
两者不是新旧关系，而是两种契约：一个卖省事，一个卖稳定。选哪个取决于这个调用出错后你愿不愿意重跑一遍。另外，模型名只是一层路由标签，同名在不同平台、不同渠道可能落到不同后端，这也是同一名字效果不一致的常见原因，渠道差异可以到 /sites 对照着看。
从模型 ID 里能读出什么、读不出什么
名字里通常能读出系列名、能力档位、输入输出类型，有时还有发布批次。但这些字段的具体含义以模型库里的条目说明为准，别只看名字猜。名字读不出的东西反而更关键：上下文窗口、计费口径、限流档位、是否开启推理模式，这些得逐项查资料库。
- 能读出：系列归属、能力档位、模态类型、部分版本批次
- 读不出：上下文窗口、计费方式、限流档位、是否推理模式
- 易错点：把营销名当请求参数、大小写和连字符写错、误以为带后缀就是快照
- 正确做法：以 /models 条目定义为准，计费与限制去 /official-api 核对
还要区分模型名和请求体里的模型参数：前者是展示用的，后者才是你写进去的字符串。抄错大小写、连字符常导致 404，排查顺序可以按 /api-errors 里的清单走：先看请求体字符串、再看路径、最后看渠道配置。
三步确认你手上的名字现在对应哪一版
- 固定证据把当前调用的模型名、响应里的模型字段、请求时间记下来存一段时间。多数接口会在响应里回显真正使用的版本标识，这是最直接的对照物。
- 查条目到 /models 看这个名字被标为别名还是快照、指向哪条、有无下线计划；再到 /official-api 核对计费与限制，避免名字没变但口径变了。
- 做差异自测用同一段固定输入和参数，间隔一段时间重复跑，比较输出结构是否稳定。这一步只看行为是否漂移，不评判质量高低。
如果响应里没有回显版本、资料库也没写清，就按它会变来设计：把关键流程做成可切换模型名，别把某个名字硬编码在业务里。判断类内容都有前提——这套三步在你只做文本摘要、对格式不敏感时够用，但一旦涉及结构化输出或函数调用，就必须把自测频率提高。
| 名字类型 | 稳定性 | 适合场景 | 风险 |
|---|---|---|---|
| 别名 | 会随官方更新漂移 | 内部实验、追新尝鲜 | 静默变版，行为不可复现 |
| 快照 | 固定不变 | 生产、有回归测试的流程 | 到期下线或降级维护 |
| 带能力后缀 | 取决于厂商定义 | 特定能力变体 | 被误当成快照使用 |
| 渠道别名 | 随渠道路由变化 | 多站比价与备用 | 同名不同后端，效果不一致 |
什么时候会变、变了怎么办
会触发变化的典型时点有几类：官方发新一版并让别名跟随、快照到期下线、平台侧路由到不同供应商、渠道分组调整。前两类看官方公告与 /news/daily，后两类往往没有公告，只能靠自测发现。所以变更监测和价格监测一样，是日常动作不是一次性动作。
- 先分类影响面：只影响输出风格可以观察，影响返回格式或字段结构就先回归测试再切量
- 处置顺序：切回上一个已验证的快照，再排查是新版行为差异还是渠道问题
- 保留开关：业务里留一个可配置的模型名入口，别散落在代码各处
- 记录变更：把切换时间、原因、验证结果写进同一份记录，方便下次对比
也有不适用的情况：如果你的调用本来就对输出做严格校验、随时容错，那么别名漂移的代价可能很小，不必为稳定去承担快照下线的迁移成本。反过来，只要流程里有人工不复查的环节，稳定就该优先。
给团队定一条命名与记录约定
命名约定不复杂，关键是执行。生产环境写全名并注明用途，测试和实验环境才用别名追新，两边分开，避免一次升级把线上带崩。用量日志里多记一个字段：接口回显的版本标识，而不是只记你请求时写的名字。
- 在用量日志字段里加入回显版本，字段清单可参考 /usage-log-fields
- 定期对账：把 /price-watch 的价格变动、/models 的条目变更和自测结果放一起看
- 小团队最低标准：一份表，列出每个在用的模型名、用途、是否允许自动跟随更新、最近一次验证时间
- 触发条件写清楚：哪些名字允许自动跟新，哪些必须人工确认后才能改
定期对账的目的不是追求零变化，而是让变化在你知情的情况下发生。具体价格和条目数字随时间变动，到 /price-watch 核对当时的数字即可，别用记忆里的旧值做决策。
下一步把你现在正在用的模型名挨个查一遍：哪些是别名、哪些是快照、响应里回显的是哪一版。对照资料库和价格追踪页确认一遍，比事后排查线上问题省事得多。→常见问题
带日期后缀的名字一定不会变吗？
不一定。后缀只能说它当初是按某个时点发布的，不代表永久冻结。是否仍会更新或下线，要看 /models 里该条目的说明和官方公告。稳妥做法是把「带后缀等于稳定」当假设而不是事实，用响应回显的版本标识去验证。
别名指向的最新版更新了，我需要做什么？
先别急着改配置，先跑一轮固定输入的对比测试，看输出结构和格式有没有变化。只影响文风可以先观察；影响字段、长度、工具调用行为就要评估回归成本。确认有影响时，切回上一个已验证的快照，再决定要不要跟上新版。
请求里写的模型名和返回里的模型名不一样，正常吗？
常见。请求名是路由用的别名，返回里的字段往往是真正执行的版本或后端标识。两者不一致本身不代表出错，但它正好是你确认版本的主要依据。如果返回里完全没有版本信息，就去 /models 查条目说明，仍查不到就按会漂移来设计。
