什么是 ChatModel？
ChatModel 是一种框架层适配接口，它接收结构化对话请求，并返回经过归一化的模型消息、流、元数据、工具提议或错误。
工作原理
请求与响应契约
请求应标明供应商与模型修订版、有顺序和角色的消息、多模态部件、工具 schema、输出 schema、生成选项、超时与 Trace 上下文。响应应保留内容部件、工具调用 ID 和参数、拒答或安全状态、结束原因、用量、供应商请求 ID，以及诊断所需的原始扩展字段。不能把全部消息压成字符串，也不能丢弃控制下一轮流程的元数据。
能力协商
工具调用、严格结构化输出、图像、音频、推理块、Log Probability、服务端工具和流式输出都是独立能力。ChatModel 应在发送请求前声明或校验支持范围，对不支持能力返回类型化错误。Temperature、最大输出 token 等通用选项仍具有供应商特定范围与语义；当正确性依赖某字段时，不得静默忽略。
流式、取消与重试
Stream 是有顺序的局部内容、工具调用增量、用量更新、错误和唯一终态。消费者应按文档规定的标识规则组装 Chunk，传播取消，关闭 Reader，并且绝不能执行未完整生成的工具参数。只有已确认可恢复且重放安全的失败才能重试；可能已产生计费结果或副作用的请求，需要幂等或对账策略。
测试与供应商迁移
使用确定性 Fake 实现测试编排，通过录制的 Provider Fixture 验证请求翻译、流式组装、错误、工具调用、拒答和结束原因。随后还要针对准确的候选供应商与模型运行行为评测，因为统一接口不等于统一行为。供应商特有能力应通过显式 Escape Hatch 暴露，并让适配器版本进入发布契约。
主要特点
- 接收有顺序的类型化消息，而不是只接收拼接后的提示字符串
- 归一化模型响应，同时保留供应商特定诊断元数据
- 校验工具、schema、多模态、推理和流式等独立能力
- 传播 Context 取消、截止时间、类型化错误、结束状态和用量
- 支持确定性 Fake 和录制 Fixture 进行编排测试
- 显式暴露供应商扩展，因为该抽象必然存在泄漏
常见用途
- 把模型边界注入 Chain、Graph、Workflow 或 Agent 运行时
- 使用确定性 Fake 测试工具与结构化输出编排
- 统一记录用量、延迟、请求 ID、结束原因和错误
- 在应用自有接口后比较云模型与本地模型适配器
- 通过能力和行为回归测试迁移模型供应商
示例
Loading code...常见问题
ChatModel 和 LLM 是一回事吗？
不是。LLM 是学习得到的模型或部署后的模型服务；ChatModel 是框架适配器，把类型化消息和选项映射到该服务，并归一化响应。同一适配接口可以封装多个供应商，同一底层模型也可以通过不同 Adapter 暴露。
ChatModel 能让模型供应商完全互换吗？
只能统一接口层。供应商在角色优先级、工具、schema、多模态部件、推理数据、安全响应、token 计量、流式、错误和模型行为上仍有差异。切换前需要能力校验、供应商扩展出口和完整行为回归评测。
生产级 ChatModel 响应应该保留什么？
应保留类型化内容部件、工具调用 ID 与参数、拒答或安全状态、结束原因、用量、供应商请求 ID 和必要原始元数据。丢弃这些字段可能破坏后续工具 Turn、掩盖截断、误算成本，或让事故无法复现。
ChatModel 流式输出应该怎样处理？
把 Stream 视为有顺序的局部事件和唯一终态。按稳定 ID 组装文本与工具调用增量，传播取消，关闭 Stream，记录中途错误，并且绝不能执行未完整生成的工具参数。部分输出后发生 Fallback 也需要明确的用户可见策略。
ChatModel Adapter 应该如何测试？
用确定性 Fake 测试应用控制流，用录制 Fixture 验证请求翻译、响应归一化、流式、拒答、用量与错误；每个 Provider Adapter 都要有契约测试，准确模型版本还需行为回归测试，因为接口兼容不能证明输出等价。