langfuse

Langfuse

为现有的 LLM 应用接入可追踪、最小化的观测数据以及带版本管理的评估输入。AAS 维护者于 2026-09-05 修改本文，将混杂的旧版 SDK 示例替换为当前、有明确边界的设置流程；原有来源署名予以保留。

何时使用

当应用已经需要 Langfuse 追踪、提示词管理或评估时使用，或在调试缺失/重复的 span 时使用。不要仅仅因为存在 LLM 就添加可观测性服务；应从数据必须支撑的事件或产品决策出发。

输入与前置条件

• 已安装的 Python 或 JS SDK 版本、框架与运行时生命周期。
• 明确授权的 Langfuse 项目/端点、通过项目密钥机制提供的凭据，以及数据保留/访问策略。
• 可观测字段的允许列表，以及不包含任何隐私内容的合成请求。
• 已定义的验证器：预期的父/子 span、状态、时序、模型/提示词版本与 flush 行为。

操作步骤

1. 检查依赖锁定文件与现有埋点。不要将旧的 langfuse.trace()、langfuse.decorators 或 langfuse.callback 示例与当前 SDK 混用，除非已查阅其迁移指南。
2. 选择一种集成层：直接使用 SDK span、框架回调或 OpenTelemetry 埋点。避免通过重叠的包装器对同一调用重复追踪。
3. 在源码之外配置已批准的端点与凭据。在运行示例前验证导出权限：埋点可能会将输入、输出、元数据与异常发送到外部。
4. 从仅包含合成值或允许列表值的显式观测开始。仅当其作用域与隐私处理方式已定义时，才添加关联 ID。
5. 执行一次成功请求和一次失败请求；检查实际导出的 span 树，确认没有敏感字段通过嵌套元数据或第三方埋点泄漏。
6. 在短生命周期进程中执行 flush，并测试关闭/超时。SDK 调用返回本身并不能证明数据已被摄取。
7. 仅在追踪边界正常工作后，再添加提示词/评估元数据。固定提示词版本或记录确切解析出的版本；可变的生产标签不是不可变的实验输入。

最小 Python 观测示例

当前的 Python SDK 概览 记录了 get_client() 与上下文管理的观测。请使用与已安装 SDK 匹配的 API。在完成配置与导出授权后，以下合成示例创建一个 span，且不进行任何 LLM 调用：

from langfuse import get_client

client = get_client()
with client.start_as_current_observation(as_type="span", name="synthetic-health-check") as span:
    span.update(output={"status": "ok"})
client.flush()

预期观测结果：在目标项目中出现一个已完成的 synthetic-health-check span，且状态值为固定值。本技能并不声称已运行实时摄取检查。端点错误、凭据缺失或导出器故障必须报告为检查失败/未验证。

隐私与脱敏

不要将截断视为脱敏。优先省略原始提示词、用户消息与工具载荷；检查所有已配置的导出器。当前的 Python SDK 提供 mask_otel_spans 用于导出时转换；旧版的 mask 钩子仅覆盖范围更窄的一组由 SDK 创建的属性。请参照脱敏文档选择与已安装版本匹配的机制，并用合成密钥在嵌套元数据与异常中进行测试。收集器侧的过滤发生在数据离开应用之后，因此应将其置于已批准的信任边界之内。

提示词管理与评估

记录数据集修订版本、提示词版本、模型标识符、工具配置与评估器定义。将评估器错误与低分区分开来。评判响应必须通过有界 schema 和有限范围验证；切勿直接用 float() 转换任意模型文本，并将其称为已测量的质量。根据经过审核的示例校准评判结果，并报告不一致情况。将用户反馈与自动评判得分分开。

对照示例：对提示词版本 A 和 B 运行相同的固定支持示例，记录每个输出和验证器结果，然后检查回归以及成本/延迟。预期：可复现的对比，且保留失败案例，而不是在平均分最高后自动更改生产标签。

局限性

• SDK 方法和集成会不断演进；服务版本、Python SDK 版本和 JS 包版本是各自独立的兼容性事实。
• Trace 暴露的是可观测操作，而不是隐藏的思维链或答案正确性的证明。
• 屏蔽一个导出器并不会清理应用中的每一个日志或导出器。
• 采样、队列丢失和关闭行为会影响 trace 的完整性；请明确评估它们。
• 本技能不会在未经任务授权的情况下创建账户、更改生产提示词标签、上传数据集或配置外部遥测。

参考

• Tracing 设置
• SDK 概览
• SDK 高级功能
• 屏蔽