在 Spaces 上使用 Langfuse

本指南向您展示如何在 Hugging Face Spaces 上部署 Langfuse，并开始检测您的 LLM 应用程序以实现可观测性。此集成有助于您在 Hugging Face Hub 上试验 LLM API，在一个地方管理您的提示，并评估模型输出。

什么是 Langfuse？

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

Langfuse 的主要功能包括 LLM 跟踪，以捕获应用程序执行流程的完整上下文；提示管理，用于集中和协作的提示迭代；评估指标，用于评估输出质量；数据集创建，用于测试和基准测试；以及用于试验提示和模型配置的 Playground。

此视频是对 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. 启用 持久存储 以确保您的 Langfuse 数据在重启后仍然保留
5. 确保将 Space 设置为 公开 可见性，以便 Langfuse API/SDK 可以访问该应用程序（有关更多详细信息，请参见下面的注释）
6. [可选但推荐] 为了安全部署，请替换 环境变量 的默认值
   • NEXTAUTH_SECRET：用于验证登录会话 cookie，使用 openssl rand -base64 32 生成至少具有 256 位熵的密钥。
   • SALT：用于加盐哈希 API 密钥，使用 openssl rand -base64 32 生成密钥。
   • ENCRYPTION_KEY：用于加密敏感数据。必须为 256 位，十六进制格式的 64 个字符串字符，通过以下方式生成：openssl rand -hex 32。
7. 点击 创建 Space！

用户访问

您的 Langfuse Space 预先配置了 Hugging Face OAuth 以进行安全身份验证，因此您需要在首次登录时按照弹出窗口中的说明授权 read 访问您的 Hugging Face 帐户。

进入应用程序后，您可以使用 本地 Langfuse 功能 来管理组织、项目和用户。

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

您可以通过两种不同的方法阻止新用户注册和访问 Space

1. （推荐）Hugging Face 本机组织级别 OAuth 限制

如果您想将访问权限限制为仅限指定组织的成员，您只需在 Space 的 README.md 文件中设置 hf_oauth_authorized_org 元数据字段，如 此处 所示。

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

2. 手动访问控制

您还可以通过将 AUTH_DISABLE_SIGNUP 环境变量设置为 true 来按用户限制访问。在设置此变量之前，请确保您已首先登录并验证 Space，否则您自己的用户配置文件将无法进行身份验证。

步骤 2：使用 Langfuse

现在您已经运行了 Langfuse，您可以开始检测您的 LLM 应用程序以捕获跟踪并管理您的提示。让我们看看如何操作！

监控任何应用程序

Langfuse 是模型无关的，可用于跟踪任何应用程序。请按照 Langfuse 文档中的 入门指南 了解如何检测您的代码。

Langfuse 维护与许多流行的 LLM 框架的本机集成，包括 Langchain、LlamaIndex 和 OpenAI，并提供 Python 和 JS/TS SDK 来检测您的代码。Langfuse 还提供各种 API 端点来摄取数据，并已与其他开源项目集成，例如 Langflow、Dify 和 Haystack。

示例 1：跟踪对 HF Serverless API 的调用

作为一个简单的示例，以下是如何使用 Langfuse Python SDK 跟踪对 HF Serverless API 的 LLM 调用。

请务必首先配置您的 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="https://api-inference.huggingface.co/v1/",
    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 模板 Space，展示了如何使用 Hugging Face 模型创建一个简单的聊天应用程序，并在 Langfuse 中跟踪模型调用和用户反馈 - 无需离开 Hugging Face。

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

步骤 3：在 Langfuse 中查看跟踪

一旦您检测了您的应用程序，并将跟踪或用户反馈摄取到 Langfuse 中，您就可以在 Langfuse 中查看您的跟踪。

Langfuse UI 中的跟踪示例

其他资源和支持

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

如需更多帮助，请在 GitHub 讨论区 或 提出 issue。