[Bug]: Static type checking issues with completion and acompletion methods.

该报错不是运行时错误,而是在使用 Pyright 等静态类型检查器对 litellm.completion / litellm.acompletion 做类型检查时触发。优先排查点应放在类型存根的返回类型声明上,尤其是 stream 参数是否区分了 Literal[True] 与 Literal[F

快速结论:该报错不是运行时错误,而是在使用 Pyright 等静态类型检查器对 litellm.completion / litellm.acompletion 做类型检查时触发。优先排查点应放在类型存根的返回类型声明上,尤其是 stream 参数是否区分了 Literal[True] 与 Literal[False] 的重载。

适用环境:Issue 中报告者使用 LiteLLM v1.60.5,评论者表示在 v1.68.0–v1.70.0 附近也遇到同样问题;触发工具为 pyright;Python、CUDA、显卡、操作系统信息 Issue 未注明。

最快修复方案:暂无确认的一步修复方案。Issue 讨论中提出的修复方向是为 completion / acompletion 增加基于 stream: Literal[False] 与 stream: Literal[True] 的 @overload,但该 PR 尚未合并,未经验证。

注意事项:在修复合并前,可在报错行使用 # type: ignore,或自己在外部做一层类型包装;这些都属于绕过手段,会增加忽略范围或与实际返回对象不符的风险。

问题场景

用户在 Pyright 下调用 litellm.completion 或 litellm.acompletion 时,类型检查器依据返回类型 ModelResponse | CustomStreamWrapper 推断结果,导致访问 response["choices"]、response.choices、response.message 或使用 async for 遍历时被报类型错误。即使运行时实际为非流式调用并返回 ModelResponse,Pyright 仍可能提示无法访问 CustomStreamWrapper 上不存在的属性,或提示该类型不可迭代。

报错原文

"__getitem__" method not defined on type "CustomStreamWrapper"
(variable) response: ModelResponse | CustomStreamWrapper

Cannot access attribute "choices" for class "CustomStreamWrapper"
Attribute "choices" is unknown
(variable) choices: List[Choices | StreamingChoices] | Unknown
Cannot access attribute "message" for class "StreamingChoices"
Attribute "message" is unknown

"ModelResponse" is not iterable
"__aiter__" method not defined
(variable) response: ModelResponse | CustomStreamWrapper

原因分析

可能原因是 completion / acompletion 的类型签名没有根据 stream 的取值做精确重载:非流式调用与流式调用都被声明为 Union[ModelResponse, CustomStreamWrapper] 的联合类型。于是 Pyright 在做属性访问和中括号取值时会按联合类型逐一检查,任一分支持不支持该操作即报错;对 async for 的场景,则会因为联合类型里包含非异步可迭代的 ModelResponse 而报 __aiter__ 缺失。Issue 评论中的建议是通过 @overload 让 stream: Literal[False] 返回 ModelResponse、stream: Literal[True] 返回 CustomStreamWrapper,从类型层面消除歧义。

环境排查

  • 确认 LiteLLM 版本:Issue 中报告为 v1.60.5,评论中另提到 v1.68.0–v1.70.0 附近仍有问题。
  • 确认类型检查工具为 Pyright,以及编辑器中 Pyright 的配置与版本。
  • 确认调用处是否显式传入 stream=True;未传或传 False 时应走非流式分支。
  • 确认报错是静态检查报错而非运行时异常,运行代码本身可能正常。
  • Python、CUDA、PyTorch、显卡、操作系统等运行时信息 Issue 未提供,暂不作为排查条件。

解决步骤

  1. 先区分报错类型:如果代码能正常执行,只是编辑器或 Pyright 标红,则属于类型签名问题,不是运行时故障。
  2. 临时绕过(可优先尝试):在报错行添加 # type: ignore,Issue 评论者表示用此方式作为临时 workaround。
  3. 如不希望逐行忽略,可参考评论中的思路,在项目内写一层薄封装,用于向类型检查器声明非流式调用返回 ModelResponse、流式调用返回可异步迭代的对象;注意评论者明确说明这样做返回类型是“声明成”某些类型,可能与 LiteLLM 特有字段不完全一致。
  4. 关注 completion / acompletion 的 @overload 改造是否合入 LiteLLM;Issue 中提到的 PR 曾在 #8456 中尝试,但尚未完成,不要把它当成已发布修复。
  5. 升级 LiteLLM 前,先在本地用 Pyright 对同一段调用做复检,确认新版类型存根是否已区分流式与非流式返回类型。

验证方法

在 Pyright 下重新检查最小复现代码:非流式调用后访问 response["choices"][0]["message"]["content"] 或 response.choices[0].message.content 不再提示 CustomStreamWrapper 相关错误;流式 acompletion(stream=True) 的返回值可通过 async for chunk in response 遍历且不提示 ModelResponse is not iterable。同时确认代码运行时返回内容与预期一致,避免只消除了类型报错而引入新的封装层偏差。

参考来源

BerriAI/litellm #8304

GamsGo AI

AI 工具推荐

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

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

了解 GamsGo AI

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

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 36451

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注