LangSmith - 建立過程中的可視性與追蹤

隨著LLM（大規模語言模型）驅動的應用程式越來越複雜，了解系統背後的運作變得至關重要——這不僅對調試至關重要，還有助於持續優化和確保系統可靠性。在這方面，LangSmith發揮了重要作用，為開發者提供了強大的工具來追蹤、可視化和調試其AI工作流程。

在這篇文章中，我們將探討LangSmith如何通過追蹤功能為你的應用程式提供深度可觀察性，從而實現更高效且透明的開發過程。

使用 `@traceable` 進行追蹤

LangSmith追蹤功能的基石是 @traceable 裝飾器。這個裝飾器是一種簡單有效的方法，用來記錄Python函數的詳細追蹤信息。

它是如何運作的

通過將 @traceable 應用到一個函數，LangSmith會在每次調用該函數時自動生成一棵運行樹。這棵樹將所有函數調用鏈接到當前的追蹤，並捕捉以下重要信息：

函數輸入
函數名稱
執行元數據

此外，若函數引發錯誤或返回回應，LangSmith會捕捉到這些信息並將其添加到追蹤中。結果會實時發送到LangSmith，讓你可以監控應用程式的健康狀況。重要的是，這一切發生在後台執行緒中，確保應用程式的性能不受影響。

這種方法對於調試或識別問題的根源至關重要。詳細的追蹤數據讓你能夠追溯錯誤的源頭，並迅速修正代碼中的問題。

代碼範例：使用 `@traceable`

from langsmith.traceable import traceable
import random

# 將 @traceable 裝飾器應用到你想追蹤的函數
@traceable
def process_transaction(transaction_id, amount):
    """
    模擬處理金融交易。
    """
    # 模擬處理邏輯
    result = random.choice(["success", "failure"])

    # 模擬錯誤，演示使用
    if result == "failure":
        raise ValueError(f"交易 {transaction_id} 由於資金不足而失敗。")

    return f"交易 {transaction_id} 已處理，金額為 {amount}。"

# 調用函數
try:
    print(process_transaction(101, 1000))  # 預期成功
    print(process_transaction(102, 2000))  # 預期引發錯誤
except ValueError as e:
    print(e)

解釋：

@traceable 裝飾器會在每次調用 process_transaction 函數時記錄詳細的追蹤信息。
輸入（如 transaction_id 和 amount）會自動捕捉。
執行元數據（如函數名稱）也會被記錄。
如果發生錯誤（如第二次交易），LangSmith會捕捉錯誤並將其與追蹤關聯。

為更豐富的追蹤添加元數據

LangSmith允許你與每個追蹤一起發送任意元數據。這些元數據是一組鍵值對，可以附加到你的函數運行中，提供額外的上下文信息。以下是一些示例：

生成運行的應用程式版本
運行發生的環境（例如：開發、測試、上線）
與追蹤相關的 自定義數據

元數據在需要過濾或分組運行時特別有用，這可以讓你在LangSmith的UI中進行更精細的分析。例如，你可以按版本分組追蹤，監控特定變更對系統的影響。

代碼範例：添加元數據

from langsmith.traceable import traceable

@traceable(metadata={"app_version": "1.2.3", "environment": "production"})
def process_order(order_id, user_id, amount):
    """
    處理訂單並模擬交易完成。
    """
    # 模擬訂單處理邏輯
    if amount <= 0:
        raise ValueError("無效的訂單金額")
    return f"訂單 {order_id} 為用戶 {user_id} 處理，金額為 {amount}"

try:
    print(process_order(101, 1001, 150))
    print(process_order(102, 1002, -10))  # 這將引發錯誤
except ValueError as e:
    print(f"錯誤: {e}")

解釋：

元數據 參數被添加到裝飾器中，包含應用程式版本和環境。
這些元數據會與追蹤一起記錄，允許你在LangSmith的UI中按這些值進行過濾和分組。

LLM 聊天模型的運行

LangSmith提供了對LLM（大規模語言模型）追蹤的特別處理和渲染。為了充分利用這一功能，你需要按照特定格式記錄LLM的追蹤。

輸入格式

對於基於聊天的模型，輸入應該作為消息列表記錄，並以OpenAI兼容的格式表示。每條消息必須包含：

role：消息發送者的角色（例如：user，assistant）
content：消息的內容

輸出格式

LLM的輸出可以以以下幾種格式記錄：

包含 choices 的字典，choices 是字典列表，每個字典必須包含 message 鍵，該鍵對應消息對象（角色和內容）。
包含 message 鍵的字典，該鍵對應消息對象。
包含兩個元素的元組/數組，第一個元素是角色，第二個元素是內容。
包含 role 和 content 直接的字典。

此外，LangSmith還允許包含以下元數據：

ls_provider：模型提供者（例如：“openai”，“anthropic”）
ls_model_name：模型名稱（例如：“gpt-4o-mini”，“claude-3-opus”）

這些字段幫助LangSmith識別模型並計算相關的成本，確保追蹤的精確性。

LangChain 和 LangGraph 集成

LangSmith與 LangChain 和 LangGraph 無縫集成，使你的AI工作流程擁有更強大的功能。LangChain為管理LLM鏈提供了強大的工具，而LangGraph則提供了可視化的AI工作流程表示。結合LangSmith的追蹤工具，你可以深入了解你的鏈和圖的表現，從而更輕鬆地進行優化。

追蹤上下文管理器

有時候，你可能希望對追蹤過程有更多控制。這時，追蹤上下文管理器 可以派上用場。這個上下文管理器讓你能夠為特定的代碼區塊記錄追蹤，特別是當無法使用裝飾器或包裝器時。

使用上下文管理器，你可以在特定範圍內控制輸入、輸出和其他追蹤屬性。它與 @traceable 裝飾器和其他包裝器無縫集成，讓你根據需要混合使用不同的追蹤策略。

代碼範例：使用追蹤上下文管理器

from langsmith.traceable import TraceContext

def complex_function(data):
    # 開始追蹤特定代碼區塊
    with TraceContext() as trace:
        # 模擬處理邏輯
        result = sum(data)
        trace.set_metadata({"data_size": len(data), "processing_method": "sum"})
        return result

# 調用函數
print(complex_function([1, 2, 3, 4, 5]))

解釋：

使用 TraceContext 上下文管理器來開始追蹤特定代碼區塊（在此案例中是對一組數字求和）。
你可以使用 trace.set_metadata() 在上下文中設置附加的元數據。
這種方法讓你能夠精細控制在哪裡和何時記錄追蹤，提供了在無法使用 @traceable 裝飾器時的靈活性。

聊天會話追蹤

在許多LLM應用中，特別是聊天機器人，追蹤多輪對話至關重要。LangSmith的 會話（Threads） 功能允許你將多個追蹤組織為單一會話，並在會話進行過程中保持上下文。

追蹤分組

為了將追蹤關聯起來，你需要傳遞一個特殊的元數據鍵（session_id，thread_id，或 conversation_id）和唯一值（通常是UUID）。這個鍵確保與特定會話相關的所有追蹤會被分組在一起，便於追蹤每次交互的進展。

小結

LangSmith為開發者提供了前所未有的應用程式可見性，特別是在處理LLM時。通過利用 @traceable 裝飾器、添加豐富的元數據以及使用追蹤上下文管理器和會話追蹤等先進功能，你可以優化AI應用程式的性能、可靠性和透明度。

無論你是在構建複雜的聊天應用、調試深層次問題，還是單純監控系統的健康狀況，LangSmith都提供了確保開發過程順利進行所需的工具。祝你編程愉快！