故障排查与常见问题

如果在下面找不到你的问题,试试 Ask AI、开一个 GitHub issue,或联系支持。

身份验证问题

• 确保 LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY 和 LANGFUSE_BASE_URL 已设置为环境变量,或作为构造函数参数传给 Langfuse()。
• 在设置期间(而非生产环境)使用 langfuse.auth_check() 确认连接性。

没有 trace 出现

• 常见原因和解决方案参见 Missing traces。
• 确认 tracing_enabled 为 True,且 sample_rate 不为 0.0。
• 调用 langfuse.shutdown()(或在短生命周期作业中调用 langfuse.flush()),以便导出排队的数据。
• 启用调试日志(Python 上 debug=True 或 LANGFUSE_DEBUG="True",JS/TS 上 LANGFUSE_DEBUG="true" 或 LANGFUSE_LOG_LEVEL="DEBUG")以检查导出器输出。

嵌套不正确或缺少 spans

• 自托管用户需要 Langfuse 平台 >= 3.63.0 才能使用基于 OTel 的 SDK。
• 优先使用上下文管理器(with langfuse.start_as_current_observation(...))以维护 OTEL 上下文。
• 如果使用手动 spans(langfuse.start_observation()),务必调用 .end()。
• 在异步代码中,依赖 Langfuse 辅助函数,以避免在 await 边界丢失上下文。
• 如果一个 observation 引用了 Langfuse 从未收到的父节点,它会显示在 trace 根,而非其预期的父节点下。这可能发生在父节点被过滤掉、丢弃或从未发送时,因此请确保每个被引用的父 observation 确实被导出。

LangChain/OpenAI 集成问题

• 确保在 API 调用之前实例化 Langfuse 包装器(from langfuse.openai import openai 或 LangfuseCallbackHandler)。
• 检查 Langfuse、LangChain 和模型 SDK 之间的版本兼容性。

媒体未出现

• 对音频/图像负载使用 LangfuseMedia 对象,并检查调试日志以暴露上传错误(上传在后台线程运行)。

使用 @vercel/otel 时缺少 traces

• 确保你使用的是 @vercel/otel v2 或更高版本。v2 之前的版本基于 OpenTelemetry JS SDK v1 构建,无法识别基于 OpenTelemetry JS SDK v2 构建的 LangfuseSpanProcessor(vercel/otel#154)。使用 @vercel/otel v2+ 时,registerOTel() 能按预期导出 traces。
• 或者,通过 NodeSDK 使用手动 OpenTelemetry 设置并注册 LangfuseSpanProcessor。完整示例参见 TypeScript 埋点文档。