LLM 供应商错误排查-ChengOS 可视化工作流编排 · MCP 原生支持

适用版本：ChengOS v0.1.0+ ｜最后核对：2026-08-13 ｜来源：deploy/config/providers.toml、crates/cheng-llm/src/error.rs

模型相关的失败分成两类，需要完全相反的应对：瞬时故障值得重试，而能力或配置不匹配则永远会以同样的方式失败。错误类型会告诉你是哪一种。

能重试吗？

可重试	不可重试
`NetworkError`	`ProviderNotFound`
`Timeout`	`ConfigError`
`RateLimitExceeded`	`InvalidModel`
状态码为 5xx 的 `ApiError`	其他 4xx 的 `ApiError`
状态码为 429 的 `ApiError`	`UnsupportedCapability`
`StreamError`（按网络类问题处理）	`UnsupportedInputModality`
	`InvalidProviderProfile`
	`RequestLimitExceeded`
	`ToolCallProtocolViolation`
	`ParseError`、`UnsupportedFeature`

如果你在重试右列里的东西，那是在为一个不可能成功的请求烧配额。该改的是配置。

最常见的失败：没有原生工具调用

智能体不产生任何工具调用，或者用散文描述它「本来会做什么」，几乎总是这个原因。

agent/react_agent 默认 use_function_calling = true，这要求供应商声明 native_tool_calling。在随附的 providers.toml 中：

声明了 `native_tool_calling`	没有声明
OpenAI、Gemini、DeepSeek、LM Studio、vLLM	Anthropic、Ollama

Anthropic 的条目里带着明确注释：当前的 provider 实现没有编码 tools 与 JSON mode，因此不声明该能力。Ollama 的实现支持 format: "json"，但不支持 tools。

解决办法：换一个声明了该能力的供应商，或者关掉 use_function_calling 并接受不那么可靠的文本解析式工具协议。见大语言模型与模型配置。

能力类错误详解

错误	含义	处理
`UnsupportedCapability`	解析出的档案里，该供应商／模型缺少 tools、JSON mode 或 chat	换供应商或换模型；不要重试
`UnsupportedInputModality`	你把图片、音频或文件发给了档案未声明该模态的模型	检查 `input_modalities`——Anthropic 声明 `["text", "image"]`，Ollama 只有 `["text"]`
`RequestLimitExceeded`	工具数量、工具名长度或输入预算超过了声明的上限；错误信息里给出 `allowed` 和 `actual`	缩小请求——用 Tool Hub 减少工具，或减少上下文
`InvalidProviderProfile`	档案自身不自洽——模式非法、能力互相矛盾、覆盖项重复——并在注册表加载时暴露	修 `providers.toml`；这不是运行时状况
`ToolCallProtocolViolation`	模型返回了格式错误的参数 JSON、未注册的工具名，或有歧义的文本调用	在 LLM 层是不可重试的；是否重新提问由智能体策略决定

ToolCallProtocolViolation 值得多说一句：LLM 层把它报为终结性错误，但智能体仍可能重新提问。所以在轨迹里看到它，并不意味着这一回合失败了。

供应商配置

供应商是 providers.toml 里的白名单。每个条目声明它的凭证 Schema、支持什么、以及行为方式。

凭证 Schema：

Schema	字段
`api_key_only`	`api_key`（密文）
`api_key_with_endpoint`	`api_key`（密文）、可选 `endpoint`
`endpoint_only`	`endpoint`——用于自托管服务
`custom_llm`	`provider_name`、`api_key`、`endpoint`、可选 `compatibility_profile`

随附十六个供应商：openai、anthropic、ollama、lm-studio、vllm、gemini、deepseek、minimax、zhipu、dashscope、moonshot、hunyuan、qianfan、cohere、jina 和 custom。

custom 接受 compatibility_profile——conservative、openai、deepseek、minimax 或 zhipu。面对一个未知的 OpenAI 兼容端点，先用 conservative：它假设最少，因此失败得最不令人困惑。

行为按供应商声明：protocol_family（open_ai_chat_completions、anthropic_messages、ollama_chat、gemini_generate_content 等）、tool_call_recovery，以及像 Gemini 的 force_non_streaming_with_tools 这类开关。

model_overrides 按模式收窄能力——例如 gpt-3.5-turbo* 被修正为真实的 16K 上下文，而不是继承 128K；Gemini 的 imagen-* 和 gemini-2.5-flash-image* 被标记为图像输出模型。

症状对照表

现象	可能原因
`Provider not found: X`	不在 `providers.toml` 白名单里，或节点的 provider 字段拼错了
`Configuration error: …`	缺 API 密钥或端点；检查凭证是否已绑定、Schema 的必填字段是否填齐
`Invalid model: X is not supported by provider Y`	模型名与该供应商不匹配，或动态模型列表拉取失败正在用默认值
`API error (status 401/403)`	密钥错误或过期。不可重试——换凭证
`API error (status 429)` / `Rate limit exceeded`	配额问题。可重试；降低并发（见子流程上限）
`API error (status 5xx)`	供应商故障。可重试
`Request timed out`	模型慢或网络慢；在怪供应商之前先调高节点超时
`Parse error`	端点返回的不是预期协议——自定义端点上通常是 `compatibility_profile` 不匹配
上下文长度类错误	模型真实窗口比你以为的小；查一下有没有对应的 `model_overrides` 条目
在对话供应商上做向量嵌入失败	`supports_embedding = false`——Anthropic、DeepSeek、vLLM 等都是
重排失败	只有 Cohere 和 Jina 声明了 `supports_reranker`

自托管端点

Ollama、LM Studio 和 vLLM 使用 endpoint_only，是常见的本地选择。先做两项检查：

端点必须从后端可达，而不是从你的浏览器可达。在 Docker 模式下，容器里的 localhost 指的是容器自己。
fetch_models_enabled 表示模型列表是实时拉取的；端点不可达时界面会回落到 default_chat_models，而那份列表里的模型未必真的加载了。

要在本地模型上跑智能体，请记住 Ollama 没有声明原生工具调用——LM Studio 和 vLLM 声明了。

诊断顺序

读执行轨迹——错误变体就在里面。
依上表判断可否重试。
遇到能力类错误，把节点的供应商与模型和 providers.toml 对照。
自定义端点先试 compatibility_profile = "conservative"。
最后才去调提示词。能力不匹配永远不可能靠改措辞解决。

下一步

大语言模型与模型配置——把供应商配对。
执行失败排查——问题不在模型时。
第一个 ReAct 智能体——工具调用这个坑最先咬人的地方。

文章版权归作者所有，未经允许请勿转载。

THE END

故障排查与FAQ

LLM 供应商错误排查