Spaces 上的 Langfuse

本指南将演示如何在 Hugging Face Spaces 上部署 Langfuse，并开始为你的 LLM 应用添加可观测性埋点。此集成可帮助你在 Hugging Face Hub 上实验 LLM API、集中管理提示词，并评估模型输出。

什么是 Langfuse？

Langfuse 是一个开源的 LLM 工程平台，帮助团队协同调试、评估并迭代其 LLM 应用。

Langfuse 的主要功能包括：LLM 追踪，用于捕获应用程序执行流程的完整上下文；提示词管理，支持集中式和协作式的提示词迭代；评估指标，用于衡量输出质量；数据集创建，用于测试和基准测试；以及一个实验场，用于尝试不同的提示词和模型配置。

本视频是 Langfuse 功能的 10 分钟演示：

为什么需要 LLM 可观测性？

• 随着语言模型日益普及，理解其行为和性能变得至关重要。
• LLM 可观测性是指通过 LLM 应用的输出来监控和理解其内部状态。
• 对于应对以下挑战至关重要：
  • 包含重复或链式调用的复杂控制流，使得调试变得困难。
  • 非确定性输出，增加了进行一致质量评估的复杂性。
  • 多样化的用户意图，需要深入理解以提升用户体验。
• 构建 LLM 应用涉及复杂的工作流程，而可观测性有助于管理这些复杂性。

步骤 1：在 Spaces 上设置 Langfuse

Langfuse Hugging Face Space 允许您通过几次点击即可快速部署并运行 Langfuse 的已部署版本。

要开始使用，请单击上方的按钮或按照以下步骤操作：

1. 创建一个 新的 Hugging Face Space
2. 选择 Docker 作为 Space SDK
3. 选择 Langfuse 作为 Space 模板
4. 将 Storage Bucket 附加到项目中，以确保 Langfuse 数据在重启后得以持久化
5. 确保空间设置为 public 可见性，以便 Langfuse API/SDK 能够访问该应用（有关更多详细信息，请参阅下方的说明）
6. [（可选但推荐）为了安全部署，请替换以下 环境变量:
   • NEXTAUTH_SECRET：用于验证登录会话 Cookie，请使用 openssl rand -base64 32 生成至少具有 256 位熵的密钥。
   • SALT：用于对哈希后的 API 密钥加盐，请使用 openssl rand -base64 32 生成至少具有 256 位熵的密钥。
   • ENCRYPTION_KEY：用于加密敏感数据。必须为 256 位，即 64 个十六进制字符串字符，可通过以下命令生成：openssl rand -hex 32。
7. 点击 创建 Space！

用户访问

您的 Langfuse Space 已预配置 Hugging Face OAuth 以实现安全身份验证，因此首次登录时，您需要按照弹出窗口中的说明授权对您的 Hugging Face 账户的 read 访问权限。

进入应用后，您可以使用Langfuse 的原生功能来管理组织、项目和用户。

Langfuse 空间必须设置为public可见性，以便 Langfuse API/SDK 能够访问该应用。这意味着默认情况下，任何已登录的 Hugging Face 用户都可以访问该 Langfuse 空间。

您可以通过以下两种不同的方法阻止新用户注册并访问该空间：

1. （推荐）Hugging Face 原生组织级 OAuth 限制

如果希望将访问权限限制为仅允许指定组织（一个或多个）的成员，只需在 Space 的 README.md 文件中设置 hf_oauth_authorized_org 元数据字段即可，具体操作如此处所示。

配置完成后，只有指定组织的成员才能访问该空间。

2. 手动访问控制

你还可以通过将 AUTH_DISABLE_SIGNUP 环境变量设置为 true 来按用户限制访问权限。请务必先登录并验证该空间，然后再设置此变量，否则你自己的用户资料将无法通过身份验证。

注意： 如果你已将 AUTH_DISABLE_SIGNUP 环境变量设置为 true 以限制访问，并希望授予新用户对该空间的访问权限，你需要先将其改回 false（等待重建完成），添加该用户并让其通过 OAuth 进行身份验证，然后再将其改回 true。

步骤 2：使用 Langfuse

现在 Langfuse 已经运行起来了，你可以开始为 LLM 应用添加埋点，以捕获追踪数据并管理提示词。让我们来看看具体怎么做！

监控任意应用程序

Langfuse 与模型无关，可用于追踪任何应用程序。请遵循 Langfuse 文档中的 入门指南，了解如何为代码添加埋点。

Langfuse 与许多流行的 LLM 框架（包括 Langchain、LlamaIndex 和 OpenAI）保持原生集成，并提供 Python 和 JS/TS SDK 以便对代码进行插桩。Langfuse 还提供多种 API 端点用于摄取数据，并已被 Langflow、Dify 和 Haystack 等其他开源项目集成。

示例 1：跟踪对推理提供商的调用

作为一个简单的示例，以下是如何使用 Langfuse Python SDK 将 LLM 调用追踪到 Inference Providers。

请务必先配置 LANGFUSE_HOST、LANGFUSE_PUBLIC_KEY 和 LANGFUSE_SECRET_KEY 环境变量，并确保您已使用 Hugging Face 账户完成身份验证。

from langfuse.openai import openai
from huggingface_hub import get_token

client = openai.OpenAI(
    base_url="/static-proxy?url=https%3A%2F%2Frouter.huggingface.co%2Fhf-inference%2Fmodels%2Fmeta-llama%2FLlama-3.3-70B-Instruct%2Fv1%26quot%3B%3C%2Fspan%3E%2C
    api_key=get_token(),
)

messages = [{"role": "user", "content": "What is observability for LLMs?"}]

response = client.chat.completions.create(
    model="meta-llama/Llama-3.3-70B-Instruct",
    messages=messages,
    max_tokens=100,
)

示例 2：监控 Gradio 应用程序

我们创建了一个 Gradio 模板空间，展示了如何使用 Hugging Face 模型创建一个简单的聊天应用，并在 Langfuse 中追踪模型调用和用户反馈——全程无需离开 Hugging Face。

要开始使用，请复制此 Gradio 模板空间，并按照README中的说明进行操作。

步骤 3：在 Langfuse 中查看 Traces

在您的应用程序完成插桩，并将追踪数据或用户反馈导入 Langfuse 之后，您可以在 Langfuse 中查看这些追踪数据。

Langfuse UI 中的示例跟踪

其他资源和支持

• Langfuse 文档
• Langfuse GitHub 仓库
• Langfuse Discord
• Langfuse 模板 Space

如需更多帮助，请在 GitHub discussions 上发起支持讨论或 提交 issue。