bug: instructions parameter (OpenAI Responses API) not captured/displayed properly

用户在 Langfuse 中通过以下两种方式使用 OpenAI Responses API 时触发:

bug: instructions parameter (OpenAI Responses API) not captured/displayed properly

bug: instructions parameter (OpenAI Responses API) not captured/displayed properly

快速结论:该报错出现在使用 OpenAI Responses API 并通过 Langfuse 进行追踪时,`instructions` 参数无法被正确捕获或在前端显示。优先排查 Langfuse Python SDK 版本是否为 4.9.1 或更高。

问题场景

用户在 Langfuse 中通过以下两种方式使用 OpenAI Responses API 时触发:

  • 通过 Pydantic AI agent 调用时,使用 `Agent.instrument_all()` 进行 OpenTelemetry 埋点,生成的 span 中包含两个 generation,但 `instructions` 参数显示不完整或在 UI 中渲染异常。
  • 直接通过 Langfuse 封装的 OpenAI 客户端调用 `client.responses.create()` 时,`instructions` 参数在 trace 中完全不显示。

报错原文

No explicit error message, but observed behavioral issues:
1. langfuse's automatic generation (via @observe()) does not contain instructions
2. When enabling open-telemetry instrumentation (via Agent.instrument_all()), instructions appear in gen_ai.system_instructions metadata but do not render input, output, or instructions nicely
3. When directly calling the langfuse wrapped openai client, instructions shows up nowhere in the trace

原因分析

可能原因:该问题是由于 Langfuse Python SDK 对 OpenAI Responses API 中新增的 `instructions` 参数支持不完整导致的。在 issue 讨论中,此问题被标记为重复/相关 issue(#8763, #7435),最终确认在 SDK 4.9.1 版本中已修复。低于此版本的 SDK 无法正确解析或传递 `instructions` 参数到生成 spans 中。

环境排查

  • Langfuse Python SDK 版本:需确认版本号是否 >= 4.9.1(原始环境为 3.6.1)。
  • pydantic-ai 版本:原始环境为 1.0.17,可尝试保持或更新。
  • openai 版本:原始环境为 2.1.0。
  • Langfuse 后端版本:原始环境为自部署 3.116.1,另有用户报告在 Cloud v3.123.1 上同样存在问题。

解决步骤

  1. 升级 Langfuse Python SDK 至 4.9.1 或更高版本(原始环境为 3.6.1)。
  2. 升级后重新运行原有代码,检查 `instructions` 参数是否在 UI 中正常显示。
  3. 如果仍存在问题,请确认 OpenTelemetry 埋点方式是否与 SDK 版本兼容,例如确保 `Agent.instrument_all()` 调用顺序正确。
  4. 如果使用的是直接调用方式(`client.responses.create(instructions=…)`),升级后应能自动捕获 instructions。

验证方法

在升级 SDK 后,运行原始示例代码(直接调用方式或 Pydantic AI agent),在 Langfuse UI 中检查对应 trace 的 generation 是否包含 `instructions` 参数,并且输入和输出是否正常渲染。如果问题已修复,应该能看到完整的 `instructions` 内容显示于正确的字段中。

参考来源

langfuse/langfuse #9775

GamsGo AI

AI 工具推荐

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

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

了解 GamsGo AI

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

celebrityanime
celebrityanime
文章: 9136

发表回复

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