判断顺序通常取决于下游：如果应用侧要落库、要给前端固定字段、要按字段做分支，输出结构就是硬约束，调用方式应该围着它来选；如果反过来先跑通一次请求再回头改解析，常见结果是模型返回的自由文本被正则反复修补，结构约束和错误处理都堆在解析层。可以先从消费方倒推：谁读这份结果、读哪些字段、字段缺失时怎么降级，这三件事写清楚了，才能判断需不需要结构化约束、需不需要流式、单次调用允许占多少超时预算。
把 Xiaomi MiMo-V2.6 接进自有应用，建议的顺序是：先写应用侧需要的输出字段与必填项，再选部署形态和调用方式。适用场景是已有下游解析或存储逻辑的系统；操作动作是先定结果结构、再写一个能校验入参和处理超时的调用封装、最后做边界输入验证；验证方式是看日志能否区分入参校验失败、上游超时、上游错误码和输出结构不符；风险边界在于结构化约束、并发上限与鉴权方式会随部署形态变化，代码侧无法确认的部分按实际部署文档核对。
先写下应用侧真正需要的结果结构
先在需求侧写一张字段表，再决定调用参数。表里至少要有：字段名、类型、是否必填、字段来源（模型生成还是应用侧补全）、缺失时下游的行为。
{
"request_id": "应用侧生成，必填",
"title": "字符串，必填",
"tags": ["字符串数组，可选，缺省为空数组"],
"summary": "字符串，必填，纯文本",
"raw_text": "字符串，可选，保留模型原始输出便于回溯"
}必填与可选要分开写。必填字段缺失时应当直接判定这次调用失败，由应用侧决定重试还是降级；可选字段缺失时用默认值补全，不要在下游到处判空。把这两种情况混在一张表里，后面很难分清是模型没返回还是解析写错了。
结构化输出和自由文本的取舍看消费方：结果要入库、要驱动分支、要渲染固定 UI 时，优先要求结构化字段，并在应用侧对返回结构做一次校验；结果主要给人阅读、还要二次加工时，自由文本更省事，但建议同时保留一个 raw_text 字段，避免上游格式变化后无从追溯。折中做法是结构化外壳加一个纯文本字段，校验只卡外壳，文本字段不做强约束。
确认部署形态并据此确定调用方式
本地进程和自建独立服务在调用层面对应的写法差别不小，先确认形态，再写封装，比先写封装再改超时和鉴权更省事。
| 维度 | 本机部署（同机进程或本机端口） | 自建服务（独立部署，网络调用） |
|---|---|---|
| 超时 | 要考虑模型加载、首次调用变慢，超时预算通常留得更宽 | 网络往返叠加，建议把连接超时和读取超时分开设置 |
| 并发 | 并发上限受本机内存与进程模型限制，往往需要在应用侧排队 | 可在网关层限流，但要确认后端真实可承受的并发，避免限流形同虚设 |
| 鉴权 | 常在同机边界内，可弱化，但仍建议保留内部令牌 | 需要令牌或内网白名单，密钥不能下发到前端 |
| 流式返回 | 需要确认返回是否支持分块读取 | 需要确认网关是否缓冲响应，缓冲会让流式失去意义 |
| 错误语义 | 异常多为连接失败或进程异常，错误码需要自己约定 | 要注意区分传输层状态码和响应体里的业务错误码 |
接进应用前建议提前确认这些配置项：模型标识与版本号、单次输入长度上限、输出长度上限、并发上限、是否支持结构化输出约束、超时在哪一层生效（客户端、网关还是服务端）、鉴权方式与密钥轮换方式、上游能否透传应用侧生成的请求标识。无法从代码或配置中确认的部分，按实际部署文档核对，不要用猜测值写进封装。
写最小调用封装：入参校验、超时、重试与错误分支
下面是一段可替换的通用骨架，重点是入参校验前置、超时分类、重试只覆盖可重试错误，以及把错误分类返回给上游而不是抛裸异常。
def call_model(payload, *, connect_timeout=5.0, read_timeout=30.0, max_attempts=3):
# 1. 入参校验：本地能拦下的错误不占用上游调用
err = validate_payload(payload)
if err:
return {"ok": False, "code": "CLIENT_INVALID_INPUT", "retryable": False, "detail": err}
last = None
for attempt in range(1, max_attempts + 1):
try:
resp = session.post(ENDPOINT, json=payload, headers=headers,
timeout=(connect_timeout, read_timeout))
if resp.status_code >= 500:
last = ("UPSTREAM_5XX", True, resp.status_code) # 可重试
elif resp.status_code >= 400:
return {"ok": False, "code": "UPSTREAM_4XX", "retryable": False,
"status": resp.status_code} # 不重试
else:
parsed = parse_output(resp.json()) # 结构校验放这里
if not parsed.ok:
return {"ok": False, "code": "UPSTREAM_INVALID_OUTPUT", "retryable": False}
return {"ok": True, "data": parsed.data}
except ReadTimeout:
last = ("UPSTREAM_TIMEOUT", True, None)
except ConnectError:
last = ("UPSTREAM_UNREACHABLE", True, None)
if attempt < max_attempts:
sleep(backoff(attempt)) # 指数退避加抖动，避免重试叠在同一时刻
return {"ok": False, "code": last[0], "retryable": last[1], "attempts": max_attempts}取值理由：读取超时可以先给 30 秒左右，流式调用则改成首块超时加总时长上限；连接超时短一些，便于快速判断服务是否可达。重试上限建议先给两到三次，只覆盖连接失败、读取超时和 5xx，入参校验失败、4xx 和输出结构不符都不重试，否则容易把错误放大成流量。
错误分类回传给上游时，建议统一成固定结构：错误码、是否可重试、请求关联标识、简短说明。业务层只根据是否可重试决定退避或降级，不要依赖异常类型判断。
用空输入、超长文本、多模态字段缺失做边界验证
边界验证的目的不是跑通正常路径，而是确认封装在异常输入下不会把错误吞掉，变成看似成功的空结果。
| 边界输入 | 预期返回 | 日志中应出现的字段 |
|---|---|---|
| 空字符串或只有空白字符 | 入参校验失败，不发起上游调用 | 错误码、校验失败字段名、请求标识 |
| 超长文本（超过确认过的输入上限） | 入参校验失败或由上游返回长度类错误，两种情况都要有明确错误码 | 输入长度、输入上限、错误分类 |
| 多模态字段缺失（图片字段为 null、空数组，或只有文本） | 按接口约定返回字段缺失错误，不能静默按纯文本继续处理 | 缺失字段名、请求形态、错误分类 |
| 字段类型不符或必填项缺失（如数组字段传成字符串、返回内容不是可解析结构） | 本地校验失败或输出结构校验失败，标记为不可重试 | 期望类型、实际类型、结构校验结果 |
每类输入都建议单独跑一次，并核对日志里是否出现了对应的错误码和字段名，而不是只看到一条笼统的失败记录。
把失败情况落成日志字段以便线上回溯
线上问题最难的不是修，而是判断这次失败发生在哪一层。日志字段写全，才能不依赖复现运气。
- 请求标识：应用侧生成的 request_id，随请求透传；若上游返回了自己的请求标识，一并记录并与本地标识关联
- 部署信息：调用端点、部署形态、模型标识与版本号
- 输入特征：输入字符数或估算长度、是否包含多模态字段、命中的校验分支
- 调用参数：连接超时、读取超时、最大尝试次数
- 执行结果：每次尝试的耗时、是否重试及重试原因、总尝试次数
- 错误信息：错误分类、上游状态码或业务错误码、输出结构校验是否通过
排查时可以先看四个字段：错误分类，判断是本地校验、上游不可达还是结构不符；上游状态码或业务错误码；重试次数与每次重试原因；输出结构校验结果与输入长度。有了请求标识，就能把一次调用的入参、响应和重试记录串成一条链路，不必靠时间戳猜测对应关系。