Langfuse入門指南 [2026版]

建立和部署使用大型語言模型 (LLM) 的應用程式會面臨一系列問題。LLM 具有非確定性，可能會生成看似合理但實則錯誤的資訊，而且追蹤其在複雜序列中的行為也可能非常困難。在本指南中，我們將瞭解 Langfuse 如何成為解決這些問題的關鍵工具，它為 LLM 應用程式的全面可觀測性、評估和快速處理提供了強大的基礎。

什麼是Langfuse？

Langfuse 是一個突破性的開源可觀測性和評估平臺，專為 LLM 應用程式而設計。它為追蹤、檢視和除錯 LLM 互動的所有階段奠定了基礎，從初始提示到最終響應，無論是簡單的呼叫還是代理之間複雜的多輪對話。

Langfuse 不僅是一款日誌記錄工具，更是一種系統性評估 LLM 效能、進行 A/B 測試以及收集使用者反饋的工具，從而有助於形成反饋閉環，實現迭代改進。其主要價值在於提升了 LLM 的透明度，使開發者能夠：

• 瞭解 LLM 的行為：準確瞭解已傳送的提示、已接收的響應以及多階段應用程式中的中間步驟。
• 查詢問題：快速定位錯誤、效能低下或意外輸出的根源。
• 質量評估：透過手動和自動方式，根據預定義的指標衡量 LLM 響應的有效性。
• 最佳化改進：利用資料驅動的洞察來完善提示、模型和應用程式邏輯。
• 管理提示：控制提示的版本並進行測試，以獲得最佳的 LLM 體驗。

主要特性和概念

Langfuse 提供以下主要特性：

1. 追蹤和監控：Langfuse 幫助我們捕獲 LLM 每次互動的詳細追蹤資訊。“追蹤”本質上是對端到端使用者請求或應用程式流程的表示。在追蹤中，邏輯工作單元用“跨度”（span）表示，對 LLM 的呼叫用“代”（generation）表示。
2. 評估：Langfuse 支援手動和程式設計兩種評估方式。開發人員可以定義自定義指標，用於對不同的資料集執行評估，並將其整合到基於 LLM 的評估器中。
3. 提示管理：Langfuse 提供對提示管理的直接控制，以及儲存和版本控制功能。可以透過 A/B 測試測試各種提示，同時在不同位置保持準確性，這為資料驅動的提示最佳化鋪平了道路。
4. 反饋收集：Langfuse 會收集使用者建議並將其融入到您的程式碼中。您可以將特定評論或使用者評分連結到產生輸出結果的 LLM 互動，從而為我們提供即時反饋，以便進行故障排除和改進。

為什麼選擇Langfuse？它解決了什麼問題？

傳統的軟體可觀測性工具特性迥異，在以下幾個方面無法滿足基於 LLM 的應用需求：

• 不確定性：即使輸入完全相同，LLM 也並非總能產生相同的結果，這使得除錯極具挑戰性。而 Langfuse 則會記錄每次互動的輸入和輸出，從而清晰地展現當時的執行狀態。
• 提示符敏感性：提示符的任何細微變化都可能徹底改變 LLM 的響應。Langfuse 能夠幫助跟蹤提示符版本及其效能指標。
• 複雜鏈：大多數 LLM 應用都包含多個 LLM 呼叫、不同的工具以及資料檢索（例如，RAG 架構）。追蹤是瞭解流程並精確定位瓶頸或錯誤所在位置的唯一方法。 Langfuse 為這些互動提供了一個視覺化的時間線。
• 主觀質量：LLM 響應的“好壞”通常等同於個人意見。Langfuse 支援客觀（例如，延遲、令牌計數）和主觀（人工反饋、基於 LLM 的評估）質量評估。
• 成本管理：呼叫 LLM API 會產生費用。如果使用 Langfuse 監控令牌使用情況和呼叫量，則更容易瞭解和最佳化成本。
• 缺乏可見性：開發人員無法瞭解其 LLM 應用程式在市場上的表現，因此由於缺乏可觀察性，他們很難逐步改進這些應用程式。

Langfuse 不僅提供了一種系統化的 LLM 互動方法，而且還將開發過程從試錯轉變為資料驅動的迭代工程方法。

Langfuse入門指南

在使用 Langfuse 之前，您必須先安裝客戶端庫，並將其配置為向 Langfuse 例項（可以是雲託管例項，也可以是自託管例項）傳輸資料。

安裝

Langfuse 提供 Python 和 JavaScript/TypeScript 客戶端庫。

Python 客戶端

pip install langfuse

JavaScript/TypeScript 客戶端

npm install langfuse

或

yarn add langfuse

配置

安裝完成後，請務必使用您的專案金鑰和主機配置客戶端。您可以在 Langfuse 專案設定中找到這些資訊。

• public_key：用於前端應用程式或僅傳送有限且非敏感資料的場景。
• secret_key：用於後端應用程式以及需要完全可觀測性（包括敏感輸入/輸出）的場景。
• host：指您的 Langfuse 例項的 URL（例如，https://cloud.langfuse.com）。
• environment：這是一個可選字串，可用於區分不同的環境（例如，生產環境、測試環境、開發環境）。

出於安全性和靈活性的考慮，建議將這些定義為環境變數。

export LANGFUSE_PUBLIC_KEY="pk-lf-..." 
export LANGFUSE_SECRET_KEY="sk-lf-..." 
export LANGFUSE_HOST="https://cloud.langfuse.com" 
export LANGFUSE_ENVIRONMENT="development"

然後，在您的應用程式中初始化 Langfuse 客戶端：

Python 示例

from langfuse import Langfuse
import os
langfuse = Langfuse(public_key=os.environ.get("LANGFUSE_PUBLIC_KEY"),    secret_key=os.environ.get("LANGFUSE_SECRET_KEY"),    host=os.environ.get("LANGFUSE_HOST"))

JavaScript/TypeScript 示例

import { Langfuse } from "langfuse";
const langfuse = new Langfuse({  publicKey: process.env.LANGFUSE_PUBLIC_KEY,  secretKey: process.env.LANGFUSE_SECRET_KEY,  host: process.env.LANGFUSE_HOST});

設定您的第一個跟蹤

Langfuse 中可觀測性的基本單元是跟蹤 (trace)。跟蹤通常代表一次使用者互動或一個完整的請求生命週期。在跟蹤中，您可以記錄單個 LLM 呼叫（生成）和任意計算步驟（跨度）。

讓我們使用 OpenAI 的 API 透過一個簡單的 LLM 呼叫來演示。

Python 示例

import os
from openai import OpenAI
from langfuse import Langfuse
from langfuse.model import InitialGeneration
# Initialize Langfuse
langfuse = Langfuse(
public_key=os.environ.get("LANGFUSE_PUBLIC_KEY"),
secret_key=os.environ.get("LANGFUSE_SECRET_KEY"),
host=os.environ.get("LANGFUSE_HOST"),
)
# Initialize OpenAI client
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
def simple_llm_call_with_trace(user_input: str):
# Start a new trace
trace = langfuse.trace(
name="simple-query",
input=user_input,
metadata={"user_id": "user-123", "session_id": "sess-abc"},
)
try:
# Create a generation within the trace
generation = trace.generation(
name="openai-generation",
input=user_input,
model="gpt-4o-mini",
model_parameters={"temperature": 0.7, "max_tokens": 100},
metadata={"prompt_type": "standard"},
)
# Make the actual LLM call
chat_completion = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": user_input}],
temperature=0.7,
max_tokens=100,
)
response_content = chat_completion.choices[0].message.content
# Update generation with the output and usage
generation.update(
output=response_content,
completion_start_time=chat_completion.created,
usage={
"prompt_tokens": chat_completion.usage.prompt_tokens,
"completion_tokens": chat_completion.usage.completion_tokens,
"total_tokens": chat_completion.usage.total_tokens,
},
)
print(f"LLM Response: {response_content}")
return response_content
except Exception as e:
# Record errors in the trace
trace.update(
level="ERROR",
status_message=str(e)
)
print(f"An error occurred: {e}")
raise
finally:
# Ensure all data is sent to Langfuse before exit
langfuse.flush()
# Example call
simple_llm_call_with_trace("What is the capital of France?")

執行此程式碼後，下一步是訪問 Langfuse 介面。介面上會顯示一個新的跟蹤記錄“simple-query”，它包含一個生成記錄“openai-generation”。您可以點選它來檢視輸入、輸出、使用的模型和其他後設資料。

核心功能詳解

學習如何使用跟蹤、跨度和生成物件是充分利用 Langfuse 的主要前提。

跟蹤LLM呼叫

Source: Langfuse

• langfuse.trace()：此命令啟動一個新的跟蹤記錄。它是整個操作的頂級容器。
  • name：跟蹤記錄的描述性名稱。
  • input：整個過程的第一個輸入。
  • metadata：用於過濾和分析的鍵值對字典（例如，user_id、session_id、AB_test_variant）。
  • session_id：（可選）來自同一使用者會話的所有跟蹤共享的識別符號。
  • user_id：（可選）特定使用者的所有互動共享的識別符號。

• trace.span()：這是跟蹤中的一個邏輯步驟或次要操作，它不是與 LLM 的直接輸入輸出互動。工具呼叫、資料庫查詢或複雜計算都可以透過這種方式進行跟蹤。
  • name：span 的名稱（例如，“retrieve-docs”、“parse-json”）。
  • input：與此 span 相關的輸入。
  • output：此 span 建立的輸出。
  • metadata：span 後設資料的格式為 additional。
  • level：嚴重級別（INFO、WARNING、ERROR、DEBUG）。
  • status_message：與狀態關聯的訊息（例如，錯誤詳情）。
  • parent_observation_id：將此 span 連線到巢狀結構的父 span 或 trace。

• trace.generation()：表示特定的 LLM 呼叫。
  • name：生成名稱（例如，“initial-response”、“refinement-step”）。
  • input：傳遞給 LLM 的提示或訊息。
  • output：從 LLM 收到的回覆。
  • model：所使用的具體 LLM 模型（例如，“gpt-4o-mini”、“claude-3-opus”）。
  • model_parameters：特定模型引數的字典（例如 temperature, max_tokens, top_p）。
  • usage：顯示所用標記數的字典（prompt_tokens, completion_tokens, total_tokens）。
  • metadata：LLM 呼叫的附加後設資料。
  • parent_observation_id：將當前生成與父級 span 或 trace 關聯起來。
  • prompt：（可選）可以標識 Langfuse 中正在管理的特定提示模板。

小結

Langfuse 將基於 LLM 的應用程式的開發和維護轉變為結構化和資料驅動的過程，從而減輕了其工作負擔。它透過廣泛的跟蹤、系統化的評估和強大的提示管理，使開發人員能夠以前所未有的方式訪問與 LLM 的互動。

此外，它還鼓勵開發人員自信地除錯工作，加快迭代過程，並不斷提升其 AI 產品的質量和效能。因此，無論您開發的是基本的聊天機器人還是複雜的自主代理，Langfuse 都能提供必要的工具，確保 LLM 應用程式值得信賴、經濟高效且功能強大。