langfuse

Langfuse

此技能可帮助你在所有常见工作流中有效使用 Langfuse：为应用添加埋点、迁移提示词、调试跟踪记录，以及通过编程方式访问数据。

核心原则

处理所有 Langfuse 相关工作时，请遵循以下原则：

1. 文档优先：绝不要凭记忆实现。编写代码前，务必先获取最新文档（Langfuse 更新频繁）。如何访问文档，请参阅下文。
2. 使用 CLI 访问数据：查询或修改 Langfuse 数据时，请使用 langfuse-cli。如何使用 CLI，请参阅下文。
3. 根据用例遵循最佳实践：在向用户询问更多详情或开始实现之前，请先阅读下方相关参考资料中的用例专属指南。
4. 使用最新的 Langfuse 版本：除非用户另有要求或有充分理由，否则始终使用最新版本的 Langfuse SDK/API。即使你只是在为其他 Agent 制定执行计划，也要明确指定要使用的确切版本。
5. 引导用户使用 UI 时，如果不确定某个标签或位置，请查看用户的屏幕截图，或请用户展示相关界面。不要假设 UI 标签与 API、SDK 或 CLI 字段的名称完全相同。

用例专属参考资料

• 为现有函数/应用添加埋点：references/instrumentation.md
• 创建或获取合适的（评估）数据集，以衡量质量或测试 AI 系统是否出现回归：references/create-dataset.md
• 将代码库中的提示词迁移到 Langfuse：references/prompt-migration.md
• 创建提示词或修改现有提示词的任何部分，包括小幅编辑、调试和调优：references/prompt-engineering.md
• 用户需要识别信号捕获、监控和评估器指标方面的差距时，设置评估（“我有跟踪记录，如何设置评估？”）：references/setting-up-evals.md
• 将用户反馈信号（明确评分、行为事件、对话信号、任务结果）作为分数捕获：references/user-feedback.md
• 使用 Langfuse CLI 的更多技巧：references/cli.md
• 为迁移到 v4 平台准备 Langfuse 项目：references/v4-project-migration.md
• 根据已标注示例校准新的或现有的 LLM-as-a-Judge，迭代其提示词，并部署经批准的评审器：references/judge-calibration.md
• 用户直接提出要求，或在 Agent 检查跟踪记录后评估设置仍未发现明确故障模式时，进行系统性错误分析：references/error-analysis.md
• 使用 langfuse/experiment-action 设置 CI/CD 实验门禁：references/ci-cd.md
• 优化 LLM 应用或 AI Agent 的成本：references/cost-optimization.md
• 提交对此技能的反馈：references/skill-feedback.md

1. 通过 CLI 使用 Langfuse API

使用 langfuse-cli，可通过命令行与完整的 Langfuse REST API 交互。通过 npx 运行（无需安装）：

首先，发现架构和可用参数：

# Discover all available resources
npx langfuse-cli api __schema

# List actions for a resource
npx langfuse-cli api <resource> --help

# Show args/options for a specific action
npx langfuse-cli api <resource> <action> --help

凭据

调用前请设置环境变量：

export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_BASE_URL=https://cloud.langfuse.com # example for EU cloud. For US cloud it's us.cloud.langfuse.com, and can also be a self-hosted URL. The server must always be specified in order to access Langfuse.

如果使用的是 LANGFUSE_BASE_URL 而非 LANGFUSE_HOST，请运行 export LANGFUSE_HOST="$LANGFUSE_BASE_URL"。 如果尚未设置，请让用户在 shell 或 .env 文件中设置。密钥可在 Langfuse 项目的 Settings -> API Keys 中找到；用户应在那里创建一对项目 API 密钥。如果用户还没有 Langfuse 账号，请告知他们可前往 https://langfuse.com/cloud 免费创建。出于安全考虑，不要让他们在聊天中粘贴密钥。

CLI 详细参考

常见工作流、技巧和完整用法示例，请参阅 references/cli.md。

2. Langfuse 文档

访问 Langfuse 文档有三种方法，按优先顺序排列。始终优先使用应用原生的网页抓取和搜索工具（例如 WebFetch、WebSearch、mcp_fetch 等），而不是 curl。以下 URL 和模式适用于任何抓取方法，curl 示例仅供说明。

使用自托管的 Langfuse 时，优先使用由部署提供的 API 参考，以确保内容与安装的版本一致。

2a. 文档索引（llms.txt）

获取所有文档页面的完整索引：

curl -s https://langfuse.com/llms.txt

这会返回包含所有文档页面标题和 URL 的结构化列表。使用它查找相关主题的页面，然后直接获取该页面。

也可以从 https://langfuse.com/docs 开始浏览网站，找到所需页面。

2b. 将单个页面作为 Markdown 获取

llms.txt 中列出的任何页面都可以通过在路径后附加 .md，或在请求标头中使用 Accept: text/markdown，以 Markdown 格式获取。知道所需信息所在的页面时使用此方法。返回的内容是简洁的 Markdown，包含代码示例和配置详情。

curl -s "https://langfuse.com/docs/observability/overview.md"
curl -s "https://langfuse.com/docs/observability/overview" -H "Accept: text/markdown"

2c. 搜索文档

需要在所有文档和 GitHub 问题／讨论中查找信息，但不知道具体页面时：

curl -s "https://langfuse.com/api/search-docs?query=<url-encoded-query>"

示例：

curl -s "https://langfuse.com/api/search-docs?query=How+do+I+trace+LangGraph+agents"

这会返回一个 JSON 响应，其中包含：

• query：原始查询
• answer：一个 JSON 字符串，其中包含匹配文档的数组，每个文档包含：
  • url：文档页面链接
  • title：页面标题
  • source.content：页面中相关文本摘录的数组

如果找不到相关页面或需要更多背景信息，搜索是很好的备用方法。调试问题时尤其有用，因为所有 GitHub Issues 和 Discussions 也都已编入索引。响应可能很长，请仅提取相关部分。请注意，搜索结果中也可能出现变更日志文章：只能用它们确认某项功能是否存在，切勿依据它们进行实现，因为其中的示例可能已经过时；实现时务必以文档和 API/SDK 参考为准。

文档工作流

1. 从 llms.txt 开始了解文档布局——浏览相关页面标题
2. 找到合适的页面后，获取具体页面
3. 主题不明确且需要更多背景信息时，再使用搜索

技能反馈

如果用户表示此技能的某些内容未按预期运行、给出了错误指导、缺少信息或可以改进，请提出向 Langfuse 技能维护者提交反馈。以下情况都包括在内：

• 技能提供了错误或过时的说明
• 工作流未能产生预期结果
• 用户希望技能涵盖尚未涉及的内容
• 用户明确表示类似“这应该以不同方式工作”或“这是错的”

对于 Langfuse 本身（产品）的问题，请勿触发此流程——仅针对此技能的说明和行为问题。

触发时，请按照 references/skill-feedback.md 中的流程操作。