关于 langfuse-observability
用于在 LLM 应用中添加或审查 Langfuse 跟踪的技能。它指导埋点选择，检查跟踪数据与敏感信息处理，并协助判断会话、用户和反馈等上下文是否有用。
主要功能
- 01评估现有 Langfuse 埋点
- 02检查跟踪名称、层级和模型数据
- 03记录 Token 用量及跟踪输入输出
- 04屏蔽敏感数据
- 05选择框架集成与跟踪上下文
适用场景
- 01为新的 LLM 应用添加跟踪
- 02审查现有集成中的跟踪数据
- 03为跟踪添加会话或用户上下文
- 04改善多步骤调用的调试
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/langfuse-observability确认已加载。
详细介绍
Langfuse 可观测性
使用 Langfuse 跟踪为大模型应用添加埋点，遵循最佳实践并根据你的使用场景进行定制。
适用场景
- 在新项目中设置 Langfuse
- 审查现有的 Langfuse 埋点
- 为大模型调用添加可观测性
工作流
1. 评估当前状态
检查项目：
- 是否已安装 Langfuse SDK？
- 使用了哪些大模型框架？（OpenAI SDK、LangChain、LlamaIndex、Vercel AI SDK 等）
- 是否已有埋点？
尚未集成： 如果有可用的框架集成，请使用它设置 Langfuse。与手动埋点相比，集成能自动捕获更多上下文，且所需代码更少。
已有集成： 根据下方的基准要求进行审查。
2. 验证基准要求
每条跟踪都应满足以下基本要求：
| 要求 | 检查 | 原因 |
|---|---|---|
| 模型名称 | 是否记录了大模型的模型名称？ | 支持模型对比和筛选 |
| Token 用量 | 是否跟踪了输入和输出 Token？ | 支持自动计算成本 |
| 合适的跟踪名称 | 名称是否具有描述性？（例如使用 chat-response，而不是 trace-1） | 便于查找和筛选跟踪 |
| Span 层级 | 多步骤操作是否正确嵌套？ | 显示哪个步骤耗时过长或失败 |
| 正确的观测类型 | 是否将生成标记为生成类型？ | 支持针对模型的分析 |
| 敏感数据脱敏 | 是否排除或屏蔽了个人身份信息／机密数据？ | 防止数据泄露 |
| 跟踪输入／输出 | 跟踪是否记录了作为输入处理的完整数据，以及作为输出生成的结果？ | 便于调试并了解处理了哪些数据 |
框架集成（OpenAI、LangChain 等）会自动处理模型名称、Token 和观测类型。优先使用集成，而不是手动埋点。
文档：https://langfuse.com/docs/tracing
3. 先查看跟踪
基准埋点正常工作后，请先引导用户在 Langfuse UI 中查看跟踪，再添加更多上下文：
“你的跟踪现在已显示在 Langfuse 中。查看几条跟踪，看看记录了哪些数据、哪些内容有用，以及还缺少什么。这有助于我们决定还要添加哪些上下文。”
这有助于用户：
- 了解目前已获取的信息
- 判断还缺少什么
- 更好地提出所需内容相关的问题
4. 发现其他上下文需求
确定哪些额外的埋点会有帮助。尽可能从代码中推断，只有不明确时才询问。
从代码中推断：
| 如果在代码中看到…… | 推断 | 建议 |
|---|---|---|
| 对话历史、聊天端点、消息数组 | 多轮应用 | session_id |
用户身份验证、user_id 变量 | 具备用户感知能力的应用 | 在跟踪记录中添加 user_id |
| 多个不同的端点／功能 | 多功能应用 | feature 标签 |
| 客户／租户标识符 | 多租户应用 | customer_id 或层级标签 |
| 收集反馈、评分 | 有用户反馈 | 记录为评分 |
仅在无法从代码中明确判断时询问：
- “你如何判断回复是好是坏？”→ 确定评分方式
- “你希望在仪表板中按什么条件筛选？”→ 找出不明显的标签
- “你是否希望比较不同的用户群体？”→ 客户层级、套餐等
添加项及其价值：
| 添加项 | 原因 | 文档 |
|---|---|---|
session_id | 将多个对话归为一组 | https://langfuse.com/docs/tracing-features/sessions |
user_id | 支持按用户筛选并归因成本 | https://langfuse.com/docs/tracing-features/users |
| 用户反馈评分 | 支持按质量筛选并查看趋势 | https://langfuse.com/docs/scores/overview |
feature 标签 | 按功能分析 | https://langfuse.com/docs/tracing-features/tags |
customer_tier 标签 | 按细分群体分析成本／质量 | https://langfuse.com/docs/tracing-features/tags |
这些都不是基线要求——只根据推断或用户输入添加相关项。
5. 引导用户使用界面
添加上下文后，向用户介绍相关的界面功能：
- 跟踪视图：查看单个请求
- 会话视图：查看分组后的对话（如果添加了 session_id）
- 仪表板：使用标签构建筛选视图
- 评分：按质量指标筛选
框架集成
优先使用以下集成，而非手动埋点：
| 框架 | 集成方式 | 文档 |
|---|---|---|
| OpenAI SDK | 即插即用替代方案 | https://langfuse.com/docs/integrations/openai |
| LangChain | 回调处理器 | https://langfuse.com/docs/integrations/langchain |
| LlamaIndex | 回调处理器 | https://langfuse.com/docs/integrations/llama-index |
| Vercel AI SDK | OpenTelemetry 导出器 | https://langfuse.com/docs/integrations/vercel-ai-sdk |
| LiteLLM | 回调或代理 | https://langfuse.com/docs/integrations/litellm |
完整列表：https://langfuse.com/docs/integrations
始终说明原因
建议添加内容时，解释这对用户有什么好处：
"I recommend adding session_id to your traces.
Why: This groups messages from the same conversation together.
You'll be able to see full conversation flows in the Sessions view,
making it much easier to debug multi-turn interactions.
Learn more: https://langfuse.com/docs/tracing-features/sessions"
常见错误
| 错误 | 问题 | 修复 |
|---|---|---|
脚本中未调用 flush() | 跟踪记录永远不会发送 | 退出前调用 langfuse.flush() |
| 跟踪记录结构扁平 | 无法查看哪个步骤失败 | 对不同步骤使用嵌套跨度 |
| 跟踪记录名称过于笼统 | 难以筛选 | 使用描述性名称：chat-response、doc-summary |
| 记录敏感数据 | 存在数据泄露风险 | 跟踪前对 PII 进行脱敏 |
| 已有集成却仍手动插桩 | 代码更多，上下文更少 | 使用框架集成 |
| 环境变量加载前导入 Langfuse | Langfuse 初始化时缺少或使用了错误的凭据 | 加载环境变量后再导入 Langfuse（例如，在 load_dotenv() 之后） |
| OpenAI 导入顺序错误 | Langfuse 无法修补 OpenAI 客户端 | 导入 OpenAI 客户端前先导入 Langfuse 并调用其设置 |
评论
支持 Markdown