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. 啟用持久儲存以確保您的 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. 點選建立 Space！

使用者訪問

您的 Langfuse Space 已預先配置 Hugging Face OAuth 以進行安全身份驗證，因此您首次登入時需要按照彈窗中的說明授權對您的 Hugging Face 帳戶的 read 訪問許可權。

進入應用程式後，您可以使用Langfuse 原生功能來管理組織、專案和使用者。

Langfuse 空間必須設定為公共可見，以便 Langfuse API/SDK 可以訪問該應用程式。這意味著預設情況下，任何已登入的 Hugging Face 使用者都將能夠訪問 Langfuse 空間。

您可以透過兩種不同的方法阻止新使用者註冊和訪問空間

1. （推薦）Hugging Face 原生組織級別 OAuth 限制

如果您想將訪問許可權限制為僅特定組織的成員，您只需在 Space 的 README.md 檔案中設定 hf_oauth_authorized_org 元資料欄位，如此處所示。

配置完成後，只有指定組織的成員使用者才能訪問該空間。

2. 手動訪問控制

您還可以透過將 AUTH_DISABLE_SIGNUP 環境變數設定為 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 模板空間，展示瞭如何使用 Hugging Face 模型建立簡單的聊天應用程式，並在 Langfuse 中跟蹤模型呼叫和使用者反饋——而無需離開 Hugging Face。

要開始，請複製此 Gradio 模板空間並按照README 中的說明進行操作。

步驟 3：在 Langfuse 中檢視跟蹤

一旦您配置了您的應用程式，並將跟蹤或使用者反饋攝取到 Langfuse 中，您就可以在 Langfuse 中檢視您的跟蹤。

Langfuse UI 中的跟蹤示例

其他資源和支援

• Langfuse 文件
• Langfuse GitHub 儲存庫
• Langfuse Discord
• Langfuse 模板 Space

如需更多幫助，請在GitHub discussions 上提出支援執行緒或提出問題。