[Bug]: Cloudflare decisions provider uses the /ai/run path the chat provider calls ‘legacy’ — inconsistent and undocumented

问题场景

用户在 LiteLLM 中配置 Cloudflare Workers AI 模型时触发。具体场景是：使用 cloudflare/... 的 chat 部署时，litellm/llms/cloudflare/chat/transformation.py 中的 _resolve_api_base 会把以 /ai/run 结尾的 api_base 改写为 /ai/v1，并记录提示称 /ai/run 是 legacy Workers AI 路径、不再提供 OpenAI 兼容请求；而 cloudflare/... 的 decisions 部署由 litellm/llms/cloudflare/decisions/transformation.py 的 get_default_api_base 返回 https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/run，并由 get_complete_url 拼接 /ai/run/{model}，既不改写也不告警。两处行为没有说明原因，阅读 chat provider 告警时容易误以为 /ai/run 整体已废弃。

报错原文

[Bug]: Cloudflare decisions provider uses the /ai/run path the chat provider calls 'legacy' — inconsistent and undocumented

Cloudflare api_base ending in '/ai/run' is the legacy Workers AI path and no longer serves OpenAI-compatible requests; rewriting to the '/ai/v1' endpoint

POST /ai/v1/chat/completions with @cf/cloudflare/clef-flash
-> HTTP 400
AiError: Bad input: Error: required properties at '/' are 'model,state,questions' (code 5006)

POST /ai/run/@cf/cloudflare/clef-flash
{"state":"...","questions":{"q":{"type":"noul","instructions":"..."}}}
-> HTTP 200 {"result":{"q":0.9646},"success":true}

原因分析

根本原因在于 Workers AI 的两个端点承载的请求形状不同，不可互换：

• /ai/v1/chat/completions 是 OpenAI chat 形状（messages），适合 chat 模型；
• /ai/run/{model} 是原生 Workers AI 形状（state、questions、images），Clef 决策模型只在此路径提供服务。

因此 chat provider 把 /ai/run 改写为 /ai/v1 对 chat 模型是正确的，但对决策模型并不适用；decisions provider 停留在 /ai/run 也是有意为之。问题出在两个文件都没有说明这一区别，且 chat provider 的告警文案把 /ai/run 描述为通用的 legacy 路径，属于误导性表述。Issue 作者将其定性为文档/一致性缺陷，而非功能缺陷。另外，若把 Clef 模型当作 chat 模型调用 /ai/v1/chat/completions，可能得到 HTTP 400 及 required properties at '/' are 'model,state,questions' (code 5006) 的报错。

环境排查

• 确认 LiteLLM proxy 版本：Issue 环境为 v1.106.0，并对照 v1.106.2 检查过；确认是否已包含 PR #48265。
• 确认 Cloudflare 账号已启用 Workers AI。
• 确认使用的模型属于决策模型（@cf/cloudflare/clef-omni、@cf/cloudflare/clef、@cf/cloudflare/clef-flash），而非 chat 模型。
• 检查 decisions 部署的 api_base 是否指向 /ai/run，以及是否有人为“统一路径”将其改成 /ai/v1。
• 检查 chat 部署的告警文案是否已按 PR #48265 限定为 chat completions 场景。
• Issue 未提供 Python、CUDA、PyTorch、显卡等信息，无需据此排查。

解决步骤

1. 先区分模型类型：Clef 系列是决策模型，应走原生 /ai/run/{model}，不要把它当作 OpenAI chat 模型调用 /ai/v1/chat/completions。
2. 检查 decisions provider 的 get_default_api_base 与 get_complete_url 是否保持返回 /ai/run 与 /ai/run/{model}；如曾被改为 /ai/v1，改回原生路径。
3. 检查 chat provider 中 _resolve_api_base 的改写逻辑与告警文案，确认告警已限定为 chat completions 场景，而不是笼统声明 /ai/run 已废弃。
4. 对照 PR #48265 的代码变更与 PR #2597 的文档更新，确认安装的 LiteLLM 版本已包含这些说明；端点路由本身不会变化。
5. 如果只是阅读告警产生困惑，无需修改路由配置，按上述说明理解两个 provider 的路径差异即可。

验证方法

对 Clef 决策模型发起原生 /ai/run/{model} 请求，携带 state 与 questions，应返回 HTTP 200 且响应形如 {"result":{"q":0.9646},"success":true}；同时对同一模型请求 /ai/v1/chat/completions，会得到 HTTP 400 与 required properties at '/' are 'model,state,questions' (code 5006)，说明该模型确实只由原生路径提供。修复后还应确认 chat provider 的告警文案已限定为 chat completions，decisions provider 已有说明为何保留 /ai/run 的注释。

参考来源

BerriAI/litellm #47965

BerriAI/litellm PR #48265（代码变更，已合并）

BerriAI/litellm-docs PR #2597（文档更新）

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。