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

快速结论：该问题通常出现在同时使用 LiteLLM 的 Cloudflare chat provider 与 decisions provider 时：chat provider 会把以 /ai/run 结尾的 api_base 改写为 /ai/v1 并提示 /ai/run 是 legacy 路径，而 decisions provider 仍直接使用 /ai/run/{model}，导致两处路由不一致、文档缺失，容易被误判为配置错误。优先排查应放在“是否把 Clef 决策模型误当成 chat 模型走 /ai/v1/chat/completions”，以及路由与提示文案是否已按 PR #48265 更新。

适用环境：LiteLLM proxy v1.106.0（Issue 作者同时对照过 v1.106.2）；已启用 Workers AI 的 Cloudflare 账号；涉及模型 @cf/cloudflare/clef-omni、@cf/cloudflare/clef、@cf/cloudflare/clef-flash。Issue 未提供操作系统、Python、CUDA 或显卡信息。

最快修复方案：暂无确认的一步修复方案。Issue 明确说明这是文档/一致性缺陷，而不是功能缺陷，且“endpoint routing stays unchanged”；修复以 PR #48265 中的提示文案与注释说明为主，并在 LiteLLM 文档 PR #2597 中补充 provider 说明。可优先尝试升级到包含 PR #48265 的 LiteLLM 版本，并确认 decisions provider 的说明注释已存在。

注意事项：不要为了“统一路径”而手动把 decisions 部署改到 /ai/v1：Issue 中的验证显示 Clef 系列模型只能走原生 /ai/run/{model}，改到 OpenAI 兼容端点会返回 400。该 Issue 的修复仅调整提示文案与文档，不改变实际路由行为。

问题场景

用户在 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、显卡等信息，无需据此排查。

解决步骤

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