快速结论:该报错不是运行时错误,而是在使用 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 未提供,暂不作为排查条件。
解决步骤
- 先区分报错类型:如果代码能正常执行,只是编辑器或 Pyright 标红,则属于类型签名问题,不是运行时故障。
- 临时绕过(可优先尝试):在报错行添加
# type: ignore,Issue 评论者表示用此方式作为临时 workaround。 - 如不希望逐行忽略,可参考评论中的思路,在项目内写一层薄封装,用于向类型检查器声明非流式调用返回
ModelResponse、流式调用返回可异步迭代的对象;注意评论者明确说明这样做返回类型是“声明成”某些类型,可能与 LiteLLM 特有字段不完全一致。 - 关注
completion/acompletion的@overload改造是否合入 LiteLLM;Issue 中提到的 PR 曾在 #8456 中尝试,但尚未完成,不要把它当成已发布修复。 - 升级 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。同时确认代码运行时返回内容与预期一致,避免只消除了类型报错而引入新的封装层偏差。
参考来源
AI 工具推荐
想把多个 AI 模型放在一个入口?
GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。
推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。
这个方案解决了吗?
可以继续搜索完整报错,或查看同一工具的其他排查指南。
![[Bug]: /v1/audio/transcriptions with response_format=text logs zero usage](https://www.chat-gpts.plus/wp-content/uploads/2026/11/44538-d948fc5e-768x403.jpg)

