豆包接入Langfuse观测全攻略
把豆包接进 Langfuse 可观测性：一步一坑的踩坑与拆解
目录
- 把豆包接进 Langfuse 可观测性：一步一坑的踩坑与拆解
- 一、干什么
- Langfuse 的**接入凭据 + 目标地址**
- 逐个拆解
- 三者配合起来的工作方式
- 每一个到底"锁定"了什么
- 一句话总结
- 二、逐段拆解
- 2.1 加载 `.env`——顺序是硬要求
- 2.2 启动即体检——`auth_check()`
- 2.3 用 `langfuse.openai.OpenAI` 顶替官方 OpenAI
- 2.4 `@observe` + OTEL 属性——这里坑最密集
- 2.5 出了 `@observe` 就拿不到 trace URL
- 2.6 调用点——generation 级字段
- 2.7 flush——异步上报的最后一公里
- 三、跑通后 Langfuse UI 里长什么样
- 四、坑一览（复习）
- 五、这份 80 行有多值得投产？
- 六、TL;DR（懒人版三行）
一、干什么
让每一次调用国内 LLM 都自动被 Langfuse 记录下来，能在 Web UI 里看、能筛用户、能算 token、能溯源问题。
拆开来是三件事：
- 模型侧：走火山方舟（Volces Ark）的 OpenAI 兼容协议调用豆包（
ep-2026...）——因为不能直连 OpenAI 官方。 - 观测侧：把这一次调用作为一个trace上报到自建 Langfuse。
- 业务标签：给这条 trace 打上
user.id / session.id / tags，方便运营看板筛选。
看起来只是"用 langfuse 包一层 OpenAI"，真动手会发现 Langfuse 4.x 的 API 语义和 3.x/示例文档大不一样——80 行里至少 3 个坑，这篇博客把它们全部标出来。
Langfuse 的接入凭据 + 目标地址
——相当于"我是谁 + 我发到哪儿"。缺一个，SDK 就上报不成功。
逐个拆解
| 变量 | 是什么 | 作用 |
|---|