OpenAI Agents Python 项目中流式输出时的 CompletionUsage 对象属性缺失问题解析

问题背景

在使用 OpenAI Agents Python 库进行流式输出处理时，开发者可能会遇到一个关于 CompletionUsage 对象属性缺失的异常。具体表现为当尝试通过 chat_completions API 进行流式输出时，系统抛出 'CompletionUsage' object has no attribute 'input_tokens' 的错误。

问题现象

当开发者使用以下典型代码进行流式输出处理时：

result = Runner.run_streamed(triage_agent, "问题内容")
async for event in result.stream_events():
    if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
        print(event.data.delta, end="", flush=True)

系统会抛出 AttributeError 异常，指出 CompletionUsage 对象缺少 input_tokens 属性。这个问题在使用 Azure GPT-4o-mini 模型（API 版本 2024-08-01-preview）时尤为常见。

技术分析

根本原因

该问题的根源在于 OpenAI Agents Python 库内部对 API 响应格式的预期与实际返回格式不一致。具体来说：

1. 库代码期望从 API 响应中获取的 usage 对象包含 input_tokens 和 output_tokens 属性
2. 但实际返回的 CompletionUsage 对象使用的是 prompt_tokens 而非 input_tokens 的命名约定
3. 这种命名差异导致了属性访问失败

影响范围

此问题主要影响以下使用场景：

• 使用 chat_completions API 进行流式输出处理
• 使用非标准 OpenAI 终结点（如 Azure OpenAI 服务）
• 使用某些第三方 LLM 提供商的服务

解决方案

官方推荐方案

OpenAI Agents Python 库在 v0.0.4 版本中已修复此问题。推荐开发者升级到最新版本：

pip install --upgrade openai-agents

临时解决方案

对于无法立即升级的情况，可以采取以下临时措施：

1. 修改本地库文件（不推荐长期使用）： 找到 CompletionUsage 类定义（通常在 .../openai/types/completion_usage.py），将 prompt_tokens 替换为 input_tokens 和 output_tokens

2. 禁用追踪功能： 在代码中添加以下设置可以规避此问题：

   set_tracing_disabled(disabled=True)
   

最佳实践建议

1. 始终使用最新稳定版本的库
2. 对于生产环境，建议明确指定 API 版本而非使用预览版
3. 处理流式输出时，添加适当的错误处理逻辑
4. 如果使用第三方 LLM 服务，确保其 API 响应格式与预期一致

总结

OpenAI Agents Python 库中的这个流式输出处理问题展示了 API 响应格式标准化的重要性。随着库版本的更新，这类问题通常会得到修复。开发者应当关注官方更新日志，并及时升级以获得最佳体验和稳定性。对于关键业务场景，建议在升级前进行充分的测试验证。