bug: [python-sdk] langfuse does not capture responses.parse instructions + text_format

快速结论：该报错发生在使用 Langfuse Python SDK 包装 OpenAI responses.parse 接口时，instructions 和 text_format 参数不会被自动捕获到追踪记录中。优先排查是否使用了 responses.parse 而非 chat.completions.parse，后者可以正常捕获。

问题场景

用户在使用 Langfuse Python SDK（版本 3.8.1）包装 OpenAI SDK（版本 2.6.1）时，通过 responses.parse 调用模型，发现指令（instructions）和输出格式（text_format）未在 Langfuse 后端追踪中显示。而同样场景下 chat.completions.parse 的行为符合预期。

报错原文

# 问题表现为：Langfuse 追踪记录中缺少 instructions 和 text_format 字段
# 无显式异常，仅为数据缺失
# 对比：completions 可正常捕获，responses 不可

原因分析

这是 Langfuse Python SDK 的一个已知限制：SDK 的包装器（wrapper）在处理 responses.parse 时，没有像对 chat.completions.parse 那样提取 instructions 和 text_format 参数并发送到 Langfuse 后端。该问题在社区中已被追踪（参见 issue #8763 及相关讨论）。

环境排查

Langfuse SDK 版本：3.8.1（或其他版本，但 3.8.1 已确认会触发）
OpenAI SDK 版本：2.6.1
调用接口：responses.parse vs chat.completions.parse
Python 版本（建议确认）
Langfuse 后端：Cloud 或 self-hosted（问题在 Cloud 上发现，self-hosted 可能同样受影响）

解决步骤

优先验证：确认当前确实在使用 responses.parse 而非 chat.completions.parse。如果业务允许，切换到 chat.completions.parse 可以完整捕获参数。

手动补全数据：如果必须使用 responses.parse，可将 instructions 和 text_format 的值手动放入 input 或 metadata 参数中，例如：

# 示例：将 instructions 放入 metadata
from langfuse.openai import OpenAI
client = OpenAI(api_key="...")
response = client.responses.parse(
    model="gpt-4.1",
    instructions="You are Tom",
    input=[{"role": "user", "content": "What is your name?"}],
    text_format=YourPydanticModel,
    metadata={"instructions": "You are Tom", "text_format": "YourPydanticModel"}
)

这样可以在 Langfuse 中通过 metadata 查看这些值。

使用低级别 SDK 方法：如果上一步不够，可以利用 Langfuse 的低级别 SDK 手动记录输入和输出。例如，先通过 langfuse.trace() 创建追踪，然后调用 generation.update() 补充参数。
关注官方更新：查看 linked issue #8763 或 Langfuse 仓库的 Release Notes，等待官方支持 responses.parse 的自动捕获。

验证方法

在 Langfuse 控制台检查对应追踪记录的详情，确认 input 或 metadata 中是否包含了预期的 instructions 和 text_format 信息。如果切换到了 chat.completions.parse，则这些字段会自动出现在追踪中，无需额外操作。

参考来源

langfuse/langfuse #10143

AI 工具推荐

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

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

了解 GamsGo AI

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

bug: [python-sdk] langfuse does not capture responses.parse instructions + text_format