模型接入与兼容性

Heicode 可以连接不同模型提供方，但“接口可调用”不等于“所有 Agent 能力都可用”。开发任务通常还依赖工具调用、结构化输出、长上下文、稳定流式响应和可控超时。

接入前检查

配置模型时，至少确认：

• API Base URL 与接口协议匹配；
• API Key 有效且权限足够；
• 模型名称与部署名称正确；
• 最大上下文和最大输出长度满足任务；
• 支持 Tool Calling 或结构化输出；
• 超时、重试和并发限制已知；
• 当前提供方是否返回 content、reasoning_content 或其他扩展字段。

能力矩阵

建议为每个模型记录：

思考模式与结构化输出

部分模型启用思考模式后，会把大量内容放入 reasoning_content，而最终 content 为空、过短或没有合法 JSON。此时不应把思考文本直接当作结构化结果解析。

对于需要 Function Calling、JSON Schema 或完整文件输出的执行调用，建议：

• 使用模型官方推荐的结构化输出配置；
• 必要时关闭思考模式；
• 明确要求最终结果进入 content；
• 对最终 JSON 进行严格校验；
• 解析失败时保留原始响应，但不要把思考散文误判为有效结果。

Qwen 系列在结构化输出场景中，应重点检查 enable_thinking 配置。若执行链依赖严格 JSON，可将执行调用配置为：

extra_body={"enable_thinking": False}

是否支持该参数及其具体行为，应以当前模型提供方和部署版本为准。

OpenAI-compatible 并非完全兼容

不同提供方即使使用 OpenAI-compatible 接口，也可能在以下方面存在差异：

• 工具调用字段；
• 流式事件格式；
• reasoning_content 扩展字段；
• JSON Schema 支持程度；
• system message 限制；
• Token 统计；
• 错误码与重试头；
• 模型部署名称与真实模型名称。

因此应对每个提供方执行最小兼容性测试，而不是只验证一次聊天请求。

推荐最小测试

1. 普通问答返回最终内容；
2. 单次 Tool Calling 参数合法；
3. 工具结果回传后能继续回答；
4. 严格 JSON 输出可解析；
5. 长输入不会静默截断关键指令；
6. 超时和限流错误可识别；
7. 多 Agent 并发时不会持续失败。

失败处理

模型请求失败时，应区分：

• 认证失败；
• 模型或部署不存在；
• 限流；
• 上下文超限；
• 工具调用不合法；
• 结构化输出解析失败；
• 只返回思考内容；
• 网络或网关超时。

不同原因应采用不同重试和降级策略，不能统一无限重试。