Langfuse 可观测性：Trace、Session 与 Agent Graph 怎么看

2026/06/03 10:27:58

Langfuse Observability Trace Session Agent LLMOps

第一章

为什么 LLM 应用需要新的可观测性

传统服务的可观测性通常围绕日志、指标和调用链展开；LLM 应用的问题则更复杂：一次错误回答可能来自错误 prompt、检索结果偏移、工具调用失败、模型版本变化、上下文过长、temperature 设置不当，或者用户输入本身含糊。Langfuse Observability 的目标，就是把这些 LLM 原生因素纳入同一条 trace 中，让团队能追问“这次回答到底经历了什么”。#Langfuse Docs, 2026

关键点：Langfuse 不是只记录模型调用，而是记录 LLM 应用链路中所有相关步骤，包括 retrieval、embedding、API call、agent action 和自定义逻辑。

对象模型：Trace、Observation、Session、User

对象	含义	适合回答的问题
Trace	一次请求或任务的完整执行链路	这次回答为什么错？总成本和总耗时是多少？
Observation	Trace 中的一个步骤，如 LLM 调用、检索、工具调用	哪个环节最慢、最贵、最容易失败？
Session	多轮对话或长流程任务	多轮交互中上下文如何累积或漂移？
User	用户维度的成本、用量和质量视角	哪些用户触发了异常成本或低质量结果？

这组对象的价值在于层级清楚。Trace 解决“单次任务发生了什么”；Observation 解决“哪个步骤出了问题”；Session 解决“多轮交互如何演化”；User 解决“不同用户群体的成本和质量差异”。#Langfuse Docs, 2026

接入方式：从 SDK 到 OpenTelemetry

Langfuse 支持 Python/JS SDK，也支持 OpenAI、LangChain、LlamaIndex、LiteLLM、Vercel AI SDK 等框架集成，还可以通过 OpenTelemetry 或公共 API 接入。这意味着团队不必从零设计埋点协议，而是可以先从最接近现有技术栈的入口开始。#Langfuse GitHub, 2026

pip install langfuse openai

export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"

接入顺序建议

先接入最外层业务 trace，再补齐关键 observation。不要一开始就把所有内部函数都打点，否则数据会很多，但问题定位仍然困难。更好的起点是：用户请求、检索、模型调用、工具调用、最终输出和错误处理。

Trace Schema：不要只“接入”，还要“设计”

很多团队接入可观测性后仍然很难分析问题，原因是 metadata 设计太随意。Langfuse 能接住 trace，不代表 trace 天然可分析。真正有用的 trace，应该让你按业务场景、模型版本、prompt 版本、检索配置、实验组、用户类型和错误类型切分。

字段	建议内容	用途
业务维度	app、feature、tenant、scenario	区分不同产品场景
模型维度	model、provider、temperature、max_tokens	比较模型配置影响
Prompt 维度	prompt_name、prompt_version、label	追踪线上 prompt 发布
检索维度	retriever、top_k、chunk_version、reranker	定位 RAG 质量问题
实验维度	experiment_id、variant	支持 A/B 与离线实验回溯

四类典型 Trace：Chat、RAG、Agent、Batch

不同 LLM 应用的 trace 不应该长得一样。Chatbot、RAG、Agent 和批处理任务的核心风险不同，因此 observation 的层级也应该不同。把所有调用都拍平成一串日志，会让排查变慢；更好的做法是让 trace 结构直接反映业务流程。

应用类型	建议 Trace 结构	重点观察
Chatbot	用户输入 → 安全检查 → LLM → 输出后处理	多轮上下文、拒答、成本、延迟
RAG	query rewrite → retrieval → rerank → context assembly → LLM	召回质量、chunk 版本、引用缺失、幻觉
Agent	planner → tool call → observation → reflection → final answer	工具循环、错误恢复、agent graph、超时
Batch	任务切分 → 并发调用 → 规则校验 → 汇总	失败率、重试、吞吐、单位成本

Trace 命名原则

Trace name 应该描述业务动作，而不是技术动作。例如用 answer_customer_question、generate_contract_summary，不要只写 openai_call。技术步骤放在 observation name 中。

排查问题时怎么看 Langfuse Dashboard

一个实用的排查顺序是先看聚合，再下钻到单条 trace。先确认问题是整体性退化还是少数样本异常；再按模型、prompt 版本、用户类型、场景、时间窗口切片；最后打开代表性 trace 观察每个 observation 的输入、输出、耗时、token 和 score。

现象	优先看什么	可能原因
成本突然升高	token usage、模型版本、prompt 版本、上下文长度	prompt 变长、检索塞入过多 chunk、模型切到更贵版本
延迟突然升高	timeline、慢 observation、tool call 次数	检索慢、工具超时、agent 循环、模型响应慢
质量下降	scores、失败样本、prompt label、retrieval metadata	prompt 发布回归、召回质量下降、模型行为变化
用户投诉集中	userId、session、场景标签	特定租户数据、特定业务流程或长对话失效

从观测走向改进

flowchart LR
    Trace[收集 Trace] --> Slice[按 metadata 切片]
    Slice --> Diagnose[定位失败模式]
    Diagnose --> Dataset[沉淀 Dataset]
    Dataset --> Eval[运行 Evaluation]
    Eval --> Prompt[改进 Prompt / Model / Code]
    Prompt --> Trace

观测本身不是终点。Langfuse 的强项在于 trace 可以继续进入 dataset、score 和 experiment。也就是说，线上暴露的问题不只是被“看到”，还可以被沉淀成后续回归测试的一部分。

总览Langfuse 系列导读下一篇Prompt Management 与 Evaluation

参考来源

Langfuse. (2026). Langfuse Overview. https://langfuse.com/docs
Langfuse. (2026). langfuse/langfuse GitHub Repository. https://github.com/langfuse/langfuse