追踪长什么样

Tracing 是 Langfuse 最核心的能力。一次用户请求会被解析成一颗嵌套的 trace 树，每个节点（Observation）都记录下输入、输出、耗时、token、成本等元数据：

Trace（一次完整用户交互）
 ├─ Generation（LLM 调用）── prompt、回答、model、token、成本
 │    ├─ Span（工具调用）── 函数名、参数、返回值、耗时
 │    └─ Span（子步骤）
 ├─ Generation（第二次 LLM 调用）
 └─ Event（任意自定义事件）

调试时不再是「猜」，而是直接点开 trace 树，看链路上哪一环出错、哪一步最慢、哪次调用最烧钱。

核心概念：Trace 与 Observation

在 Langfuse 的 v3 数据模型里，所有记录统一都叫 Observation（观测），按类型区分：

类型	含义
trace	顶层操作，通常对应一次用户请求
generation	一次 LLM 调用（含 token、成本、模型名）
span	通用步骤，如工具调用、检索、自定义逻辑
agent	Agent 一次完整运行
event	无持续时长的离散事件
embedding / retriever / chain / tool	更细分的语义类型

每个 observation 都可以带上：input / output、metadata、level（DEBUG 到 ERROR）、status、version、usage（token/成本）以及父节点关系。

接入方式

1. Python SDK

pip install langfuse

最省事的是 @observe() 装饰器，自动把函数变成 observation，并根据调用关系构造嵌套结构：

from langfuse.decorators import observe

@observe()                      # 顶层 → 自动成为 trace
def answer_question(question):
    docs = retrieve(question)
    return generate(question, docs)

@observe()                      # 成为 answer_question 的子 span
def retrieve(question):
    ...

@observe()                      # 嵌套的 generation
def generate(question, docs):
    ...

也可以在函数内部手工创建：

from langfuse import Langfuse
langfuse = Langfuse()

trace = langfuse.trace(name="chat")
gen = trace.generation(
    name="llm-call",
    model="gpt-4o",
    input=[{"role": "user", "content": "你好"}],
    output="你好！",
)
gen.end()

2. 框架回调（近零改动）

Langfuse 为常见框架提供了官方回调，只需把 handler 传进框架即可：

from langfuse.callback import CallbackHandler

langfuse_handler = CallbackHandler()

# LangChain 示例
chain.invoke(
    {"input": "..."},
    config={"callbacks": [langfuse_handler]},
)

支持 LangChain、LlamaIndex、Haystack、Vercel AI SDK、LiteLLM 等。

3. OpenAI SDK 无缝替换

from langfuse.openai import OpenAI   # 仅改一行 import

client = OpenAI()
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
)

调用会自动上报，几乎零侵入。

记录的关键信息

每个 generation 最值得看的是这几项：

• 成本与 token：input_tokens / output_tokens / total_cost
• 延迟：首次 token 时间（TTFT）、总耗时
• 模型与版本：model 名、prompt version、代码 version
• 自定义上下文：用户 id、会话 id、业务标签（通过 metadata 传入）

Analytics 看板

所有 trace 汇聚后，可以在 UI 里做聚合分析：

• 总 token、总成本、请求量、错误率、延迟分布
• 按 model / prompt 版本 / 用户 / 环境切分
• 识别「最烧钱的 prompt」「最慢的模型」「最高的错误率」在哪

User Feedback

可以在应用里加 👍👎 或者星级，反馈会自动关联到对应 trace：

from langfuse import Langfuse
langfuse = Langfuse()

langfuse.create_score(
    trace_id="trace-xxx",
    name="user_feedback",
    value=1,        # 分数
    comment="回答很有用",
)

这些反馈既能做质量监控，也能沉淀成评估数据集（见评估）。

小结

Tracing 把 LLM 应用从黑盒变成可观测对象。接入成本很低（一个装饰器或一行 import），但换回来的是定位问题、核算成本、优化链路的能力，是做生产级 LLM 应用的基础设施。

贡献者: Ra1n

上一页Langfuse

下一页Langfuse 评估（Evals）