一、模型目录里真正要看清的四处

模型目录动辄几十个条目，逐个点开看不现实。真正影响切换成败的字段只有四类。

1. 能力类型与适用任务

一是文本生成类，覆盖问答、写作、摘要、改写；二是推理取向类，适合需要多步推演的题目；三是多模态类，能读图或出图；四是向量与专用类，负责检索召回与特定领域任务。类型决定它能接什么活，也决定它接不了什么活。把推理取向的模型放到高并发短问答上，往往又慢又贵，这是选型时更易出现的错位。

2. 上下文长度上限

上限决定单次能塞进多少材料。核这一项要注意两个数字常常不一样：一个是模型本身支持的窗口，另一个是服务侧当前开放给你的窗口。前者写在能力说明里，后者可能在配额或服务组设置里。核对时以小的那个为准，别拿大数字去规划业务。

3. 支持的输入模态与格式

纯文本模型收到图片会怎么处理，是报错还是当作文本丢掉，各家做法不同。做图文混排、票据识别、截图问答的业务，这一项要在切换前明确下来，否则上线后才发现图根本没被读懂，排查会绕很远。

4. 版本与生命周期状态

同一系列往往并存多个版本，有正式版、有轻量版、有处于维护期的旧版。切换目标要选正式版，并且记下版本标识。配置里写版本标识，不要只写系列名，否则服务侧一升级，你的调用对象就悄悄换掉了，而代码一行没改。

二、接口兼容分四层，从外往内逐层核

调用能不能通，只看第一层；用得顺不顺，取决于后面三层。核对按这个顺序走，出问题才好定位。

1. 第一层：地址与鉴权

统一入口的服务，地址通常只有一处，换模型只改模型标识。这一层过起来相对轻松，也常被误当成全部。核这一层要确认两件事：密钥的权限范围是否覆盖目标模型，服务组是否已把目标模型加入可选列表。有些团队的密钥是按服务组划分的，换了模型却忘了加进组，报错会指向鉴权而不是模型，排查方向一开始就偏了。

2. 第二层：请求体结构与参数名

需要核三件事：必填字段有没有变化，可选参数是否同名同义，嵌套层级是否一致。多数统一规范在这层保持稳定，但模型特有参数不会凭空生出，传了不支持的参数会怎样，属于下一节单独讲的问题。

3. 第三层：响应结构，尤其是流式

非流式返回通常是一个完整对象，取文本字段即可。流式返回是一串分片，要关心三处：分片里的字段是否一致、结束标记长什么样、末尾那个分片有没有附带用量统计。切换后如果下游一直等不到结束信号，多半是结束判断被写死成了某个固定字符串。

4. 第四层：错误码与反馈

同一类错误，不同模型返回的码值可能不同。限流、超长、内容不合规这三类要特别核，因为处置动作完全不同：限流该退避等待，超长该切分或换窗口更大的模型，不合规该走改写而不是重试。如果把这三类都笼统当成失败就重试，重试风暴就是这样起来的。

三、参数落空比直接报错更难查

传了不支持的参数，有三种下场，只有第二种会在日志里留下明显痕迹。

1. 静默忽略

参数被接受但不生效。表现是能跑，效果不对。比如把温度值调得很低、期望输出稳定，目标模型未必照做，结果依旧发散。这类问题不报错，只能靠固定样例比对发现，所以核对必须带样例，不能只看调用是否成功。

2. 明确报错

参数名不被识别，请求直接失败。这种情况反而好办，去掉参数或换成目标模型支持的等价写法即可，改完再跑一遍样例就能确认。

3. 支持但语义偏移

参数名一样，含义有细微差别。同样的取值，在甲模型上表现为更保守，在乙模型上表现为更发散。这类差异只能靠回归比对摸出来，摸不出来就先取中间值保守起步，等积累一段时间再调。

核对时给每个参数标一个状态：支持、不支持、待验。待验的那几个务必用样例跑一遍定论，不要留在应该没问题的状态里上线。

四、用一份精简样例集去验，比读十页文档更有用

文档写的是通用行为，样例验的是你要用的那条路径。

1. 样例怎么选

五条足够起步：一条日常短问答，一条长文摘要，一条结构化抽取，一条边界输入，一条多轮对话。边界输入指超长、空值、夹杂特殊符号这类容易出事的内容；多轮对话用来验上下文是否按预期累积，以及累积到第几轮开始影响输出质量。

2. 比对什么

不止比对文本内容。要同时看四项：返回字段是否齐全、输出长度是否落在预期区间、结构化输出能否被解析、耗时是否可接受。四项里任何一项异常，都说明这一层还没通。

3. 怎么记

把新旧两个模型在同一批样例上的输出并排留存，标注差异点。这份记录在放量时能直接当基线用，日后出现效果争议也有据可查。

五、输出差异要连着下游一起看

模型换掉的是输出，真正受影响的是解析输出的人。

1. 字段与嵌套

有的模型把结果包在一层里，有的多包一层。下游若按固定路径取值，多一层就取到空值。核这一层要看真实返回，不要靠猜。

2. 结构化输出的稳定度

要求返回指定结构时，要验三条：字段名是否严格一致、类型是否稳定、有没有多余的包裹文本。模型在结构外面加一句客套话，解析就会失败。切换前用样例确认，切换后加一层容错剥离。

3. 截断与结束原因

输出被截断时，结束原因字段会给出区分。切换后要确认下游是否读了这一项。没读的话，被截断的内容会被当成完整结果入库，后续所有基于它的判断都跟着错，而错误在现场很难复现。

六、核出问题怎么判：三档结论

核对的目的不是挑毛病，是给出可执行的结论。

1. 第一档：可直接更换

四层全通，样例结果落在可接受区间，参数状态没有待验遗留。这类切换只需改配置，走一般变更流程即可。

2. 第二档：小改可换

接口通但下游要配合，比如加一层字段剥离、调整结束判断、给参数换一种等价写法。这类改动范围可控，列清楚改哪几处、谁改、什么时候上，就不算风险。

3. 第三档：需改造后再换

能力边界不符或长度上限不足，属于换模型解决不了的问题，得先调整业务方案。这种情况要明确讲出来，不要硬切上线再慢慢补。

判档的依据是样例和记录，不是感觉。三档结论都要写进切换单，让看单子的人一眼看清代价。

七、把核对做成一张固定的切换单

核对做一次靠运气，做成固定动作才是能力。

1. 单子上必须有六项

目标模型的版本标识、四类字段的核对结论、四层接口的通过情况、样例比对记录、三档判定结论、回退方案。六项齐了，这次切换才算核完。

2. 回退要提前想好

回退不只是把标识改回去。还要确认旧版本在这段时间里是否仍处于可用状态、下游为新模型做的改动是否兼容旧输出。新旧并行跑一段时间，是较为省事的回退保障。

3. 谁来核

写代码的人核接口层，用模型的人核效果层，负责稳定的人核错误码与反馈层。三个视角各过一遍，比一个人从头看到尾更容易发现问题。

4. 核完留档

每次切换留一份，累积下来就是团队自己的模型适配档案。下次再换同类模型，先翻旧档，大半核对工作可以省掉。

结语

模型切换这件事，难的从来不是改那一行标识，而是确认改完之后每个环节还按原样工作。息壤Token服务在模型覆盖上给出了完整的能力矩阵，通用文本生成、推理取向、多模态、向量与专用几类齐备，来源上既有可直接调用的预置模型，也支持自研模型接入，统一规范让调用逻辑保持稳定。但稳定的是接口，不是行为，能力边界、长度上限、参数支持与输出习惯的差异，只能靠一次有次序的核对去确认。四处字段看清、四层接口过一遍、五条样例跑通、三档结论落单，切换就从一次提心吊胆的操作，变成一件有据可依的日常事。