Skip to main content

在 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 生成至少 256 位熵的密钥。
    • ENCRYPTION_KEY：用于加密敏感数据。必须是 256 位，64 个十六进制格式的字符串字符，通过 openssl rand -hex 32 生成。
  7. 点击Create Space！

克隆 Langfuse Space

用户访问​

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

进入应用后，你可以使用原生 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，否则你自己的用户配置文件将无法进行身份验证。

tip

注意： 如果你已将 AUTH_DISABLE_SIGNUP 环境变量设置为 true 以限制访问，并希望授予新用户对 Space 的访问权限，你需要首先将其设置回 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 调用。

请确保首先配置 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://router.huggingface.co/hf-inference/models/meta-llama/Llama-3.3-70B-Instruct/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 中查看你的追踪。

Gradio 示例追踪

在 Langfuse UI 中查看示例追踪

其他资源和支持​

如需更多帮助，请在 GitHub discussions 上打开支持线程或提交问题。

Last updated on