Langfuse 是一个开源 LLM 可观测性平台，本技能围绕其追踪、提示词管理、评估、数据集以及与 LangChain 等框架的集成展开。
用途
当应用已经需要 Langfuse 追踪、提示词管理或评估，或需要调试缺失/重复的 span 时使用。不要仅仅因为存在 LLM 就添加观测服务；应从数据必须支持的故障或产品决策出发。
输入与前置条件
已安装的 Python 或 JS SDK 版本、框架与运行时生命周期；明确授权的 Langfuse 项目/端点、通过项目密钥机制提供的凭据，以及数据保留/访问策略；可观测字段的允许列表，以及不含隐私内容的合成请求；已定义的验证器：预期的父/子 span、状态、时序、模型/提示词版本与 flush 行为。
使用方式
-
检查依赖锁定文件与现有埋点。在未查阅迁移指南的情况下，不要将旧的 langfuse.trace()、langfuse.decorators 或 langfuse.callback 示例与当前 SDK 混用。
-
选择一种集成层：直接 SDK span、框架回调或 OpenTelemetry 埋点。避免通过重叠的包装器对同一调用追踪两次。
-
在源码之外配置已批准的端点与凭据。运行示例前先验证导出权限：埋点可能将输入、输出、元数据和异常发送到外部。
-
从仅包含合成值或允许列表值的显式观测开始。仅当其作用域与隐私处理已定义时才添加关联 ID。
-
执行一次成功请求和一次失败请求；检查实际导出的 span 树，并验证没有敏感字段通过嵌套元数据或第三方埋点泄漏。
-
在短生命周期进程中执行 flush，并测试关闭/超时。SDK 调用返回本身并不证明数据已被摄取。
-
仅在追踪边界工作正常后再添加提示词/评估元数据。固定提示词版本或记录确切解析出的版本；可变的生产标签不是不可变的实验输入。
最小 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 包版本是各自独立的兼容性事实。追踪暴露的是可观测操作，而非隐藏的思维链或答案正确性的证明。对一个导出器做掩码并不能净化应用中的所有日志或导出器。采样、队列丢失与关闭行为会影响追踪完整性；应显式评估它们。本技能不会在未经任务授权的情况下创建账户、更改生产提示词标签、上传数据集或配置外部遥测。