LangFuse 使用

目录

• 一、为什么你会看到「这么麻烦」的写法？
• 二、现实中的 3 个层级：从「透明」到「手动」
  • ✅ Level 1：完全透明（推荐，80% 场景）
  • ⚠️ Level 2：半透明（框架自动 + 少量补充）
  • ❌ Level 3：完全手动（你刚才看到的示例）
• 三、为什么「不可能 100% 全自动」？
  • 1️⃣ 框架无法理解“业务语义”
  • 2️⃣ 自动 ≠ 有用
• 四、给你一个「符合你场景的最佳实践结论」
  • ✅ 推荐方式（不折磨自己）
  • ❌ 不要做的事
• 五、一句话总结

结论先行：可以，而且“应该”做到大部分透明自动化；你现在看到的这套写法只是“兜底能力”，不是常态用法。

下面我从工程现实的角度，把这件事讲清楚。

---

一、为什么你会看到「这么麻烦」的写法？

你看到的这类代码：

with langfuse.start_as_current_observation(...)

本质上是 Langfuse 提供的 lowest-level API，目的只有一个：

当框架无法自动感知你在“干什么”时，给你一个100% 可控、必然生效的兜底方案。

它并不是希望你在每个 LLM 项目里都这么写。

---

二、现实中的 3 个层级：从「透明」到「手动」

✅ Level 1：完全透明（推荐，80% 场景）

如果你满足以下条件之一：

• 使用 LangChain / LangGraph
• 使用 OpenAI / Anthropic 官方 SDK
• LLM 调用路径是「标准的」

👉 Langfuse 已经可以自动做监控

典型方式只有一行：

from langfuse import observe

@observe
def call_llm(prompt):
    return client.chat.completions.create(...)

你能自动得到：

• Trace
• Generation
• Prompt / Output
• Token / Latency
• 错误

几乎 0 心智负担。

对你现在做的销售 Agent、LangGraph 应用来说，这一层就已经够用了。

---

⚠️ Level 2：半透明（框架自动 + 少量补充）

这是 Agent / Workflow / 决策系统 的真实情况，也是你现在所处的层级。

问题在于：

• 框架 只知道你“调了模型”
• 但它不知道你在“做决策”

比如：

• Objection 判断
• Rule Engine 命中
• 意图路由
• CTA 选择

这些都不是 LLM 行为，不可能被自动感知。

所以你通常只需要：

• LLM → 自动（Generation）
• 关键决策点 → 手动加 1 个 Span

真实代码量是这样的：

@observe
def sales_flow(input):
    decision = decide_objection(input)

    with langfuse.start_as_current_observation(
        as_type="span",
        name="objection-decision"
    ):
        ...

    return call_llm(...)

👉 不是“到处写”，而是“关键节点写”。

---

❌ Level 3：完全手动（你刚才看到的示例）

只有在以下情况才需要：

• 自研框架 / 多线程 / 多进程
• LLM 调用被深度封装
• 异步上下文丢失
• 非 Python 标准调用路径

也就是：

框架真的“看不见”你的行为

这时你才会用到你刚才看到的那套完整写法。

---

三、为什么「不可能 100% 全自动」？

这是一个不可回避的工程事实。

1️⃣ 框架无法理解“业务语义”

Langfuse 能自动识别：

• HTTP 调用
• LLM SDK
• 已知框架的 hook

但它不可能知道：

• 这是“价格异议”还是“物流异议”
• 这是“强转化 CTA”还是“软引导 CTA”
• 这是“失败的推荐”还是“策略保守”

这些 只有业务代码知道。

---

2️⃣ 自动 ≠ 有用

如果你真的“全自动”：

• Trace 会非常长

• 全是 token、prompt、response

• 你无法回答这些问题：

  • 哪个决策导致转化下降？
  • 哪类 Objection 命中率最低？
  • 哪条规则在 production 里经常误判？

所以 Langfuse 的设计理念其实是：

LLM 自动，决策手动，语义靠人补

---

四、给你一个「符合你场景的最佳实践结论」

结合你现在做的：

LangGraph + 销售智能体 + 决策逻辑

✅ 推荐方式（不折磨自己）

• 90% 用 @observe

• 10% 只在这些地方加 Span：

  • Intent / Objection 判定
  • Rule vs Model 决策融合点
  • CTA 选择
  • fallback / exception 分支

❌ 不要做的事

• 不要每个函数都写 start_as_current_observation
• 不要把 Langfuse 当日志系统
• 不要追求“每一行代码都有 Trace”

---

五、一句话总结

Langfuse 本身已经尽可能“透明自动”了；
剩下那一点“麻烦”，不是工具问题，而是业务语义无法被自动理解。

如果你愿意，下一步我可以直接帮你：

• 设计一套 “销售 Agent 标准埋点规范（5–7 个 Span）”
• 或给你一个 LangGraph + Langfuse 的最小、优雅模板

你现在这一步，已经问到点子上了。