故障排查与 FAQ

如果在下面找不到你的问题，请尝试 Ask AI、提一个 GitHub issue，或联系 support。

认证问题

• 确保 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()）以便排队的数据被导出。
• 启用 debug 日志（Python：debug=True 或 LANGFUSE_DEBUG="True"；JS/TS：LANGFUSE_DEBUG="true" 或 LANGFUSE_LOG_LEVEL="DEBUG"）以查看 exporter 输出。

嵌套不正确或 span 缺失

• 自托管用户需要 Litefuse 平台 >= 3.63.0 才能使用基于 OTel 的 SDK。
• 优先使用 context manager（with langfuse.start_as_current_observation(...)）以维护 OTEL context。
• 如果使用手动 span（langfuse.start_observation()），始终调用 .end()。
• 在异步代码中，依赖 Litefuse 的 helper 以避免在 await 边界丢失 context。

LangChain/OpenAI 集成问题

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

媒体未出现

• 对音频/图片载荷使用 LangfuseMedia 对象，并查看 debug 日志以排查上传错误（上传在后台线程中执行）。

使用 @vercel/otel 时缺少 trace

• 请使用通过 NodeSDK 进行的手动 OpenTelemetry 设置，并注册 LangfuseSpanProcessor。@vercel/otel 辅助库尚不支持 Litefuse 所依赖的 OpenTelemetry JS SDK v2。完整示例参见 TypeScript instrumentation 文档。