Langfuse怎麼用 AI應用可觀測性工具教程

Langfuse是一個開源的AI應用可觀測性平臺，可以追蹤和除錯你的LLM應用，看每一步的輸入輸出和成本。你可以把一次使用者請求裡的提示詞、模型呼叫、檢索和工具執行串成trace，再在頁面裡檢查耗時、結果和費用。下面用Python舉例，從建立專案到檢視鏈路、分析質量，帶你跑通最基本的流程。

第一步：註冊並建立專案

開啟Langfuse並註冊帳號，進入控制檯後新建一個專案。專案可以按應用或環境來分，比如測試環境和生產環境分開，避免不同來源的資料混在一起。建立完成後，開啟專案設定裡的API金鑰頁面，複製Public Key和Secret Key；這兩項用於SDK把追蹤資料傳送到對應專案。

把金鑰放進應用的環境變數，不要直接寫進程式碼或提交到程式碼倉庫。使用Langfuse Cloud時，按專案所在區域配置服務地址；自託管部署則填寫自己的服務地址。Python專案可以在本地建立.env檔案，再透過環境變數載入工具讀取。先確認金鑰、地址和專案匹配，後續排查會省不少時間。

第二步：接入SDK記錄呼叫

在專案虛擬環境安裝Python SDK：pip install langfuse。接著配置LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY和LANGFUSE_BASE_URL。啟動程式後，使用SDK初始化客戶端；可呼叫auth_check()檢查連線是否正常。金鑰只放在服務端環境裡，前端程式碼不要暴露Secret Key。第一次接入建議先在開發環境驗證。

接下來在應用的請求處理函式外層建立trace，在裡面記錄模型生成、檢索或工具呼叫等步驟。每一步儘量寫清名稱，並補充input和output；模型步驟可記錄模型名、提示詞、返回內容和用量。若用LangChain，可配置Langfuse的CallbackHandler，讓鏈路中的LLM與檢索操作自動形成記錄。按實際框架選SDK或整合方式即可。

示例結構可以很簡單：收到請求時記錄使用者問題，呼叫模型後記錄模型輸出，再把最終回答寫入trace。還可以補上使用者ID、會話ID、標籤和環境等欄位，方便按使用者或功能篩選。記錄的資料應有助於定位問題，不必把無關內容全部塞進去；對敏感欄位可在應用側先脫敏，再傳送追蹤資訊。

檢視trace鏈路

啟動應用並實際發起一條請求，然後進入Langfuse專案的Trace頁面，按時間或名稱找到剛才的記錄。點開trace後檢查整體輸入輸出，並展開子步驟，確認模型呼叫、檢索和工具執行是否按預期排列。若暫時看不到記錄，先檢查金鑰、服務地址、網路和SDK初始化順序，再確認程式確實執行了被追蹤的程式碼。

檢視每個子步驟時，重點對照輸入與輸出：提示詞是否完整、檢索結果是否相關、模型是否返回異常內容。也可以檢查各步驟耗時，判斷延遲集中在哪個環節。複雜應用可用會話標識把多輪互動放在一起看；遇到問題時，按trace ID定位單次請求，通常比只看應用日誌更容易還原執行過程。

第三步：分析質量和成本

積累一定數量的trace後，開啟儀表盤檢視呼叫量、延遲和成本等趨勢。按模型、標籤、使用者或時間範圍篩選，比較不同版本的表現。若成本突然上升，可檢查模型選擇、輸入長度、重複呼叫和重試；若響應變慢，則沿trace時間線找出耗時最長的步驟。監控資料要結合業務場景判斷，不要只看單一指標。

質量分析可以從抽樣檢查開始：對照使用者問題與模型回答，標註正確性、相關性或是否遵循格式要求；也可採集使用者反饋，給trace新增評分。把常見失敗案例整理成資料集，用於離線比較提示詞或模型版本。每次調整後，用相同樣例複測，並觀察線上指標是否改善，這樣能避免只憑少數印象做決定。

實際使用時，先從一個關鍵請求鏈路開始，確認trace結構清楚、欄位有用，再逐步覆蓋其他流程。團隊可約定統一的命名、標籤和環境欄位，讓排查與對比更順手。若希望瞭解國內可選方案，也可以看看01Agent，官網地址：01agent.cgref.cn。潤滅也可作為相關工具資訊的查詢入口。