Platform For AI：EAS中開啟LLM應用鏈路追蹤（Tracing）

背景資訊

隨著大語言模型（LLM）技術的廣泛應用，企業在構建基於LLM的應用時，面臨諸多挑戰，例如輸出不可預測、調用鏈路複雜、效能瓶頸難以發現以及缺乏細粒度的可觀測性等。為應對這些挑戰，EAS服務支援啟用鏈路追蹤功能。

鏈路追蹤功能的核心目標是提升應用可觀測性，協助您更好地評估LLM應用。啟用鏈路追蹤功能後，EAS服務會自動接入阿里雲的ARMS（應用即時監控服務），以實現以下功能：

• 調用鏈可視化：提供清晰的調用鏈日誌，協助您直觀瞭解請求的完整路徑。

• 效能監控：跟蹤關鍵效能指標（如回應時間、Token消耗和錯誤數等），及時發現效能瓶頸。

• 問題定位與根因分析：通過Trace ID快速定位問題，並結合上下文進行根因分析。

• 評估工具：基於調用鏈資料提供評估工具，用於驗證LLM應用輸出結果的準確性和可靠性。

基本概念

• 調用鏈（Trace）

  調用鏈是分布式系統中一次事務或請求的完整執行路徑，記錄了請求在各個服務或模組中的流轉過程。調用鏈由多個Span組成。通過調用鏈，可以直觀地瞭解請求的流轉路徑，快速定位效能瓶頸或錯誤來源。TraceID是調用鏈的唯一識別碼。通過TraceID，可查詢具體調用的詳情和日誌。

• 跨度（Span）

  Span是調用鏈中的一個基本單元，表示某個具體操作的執行片段，用於記錄每個操作的詳細資料，包括操作名稱、起始時間、結束時間等。

• Python探針

  Python 探針是一種工具，用於自動採集 Python 應用的調用鏈資料和效能指標。在部署 EAS 服務時，通過安裝 Python 探針啟用鏈路追蹤功能。

• 評估

  針對使用者提出的問題及LLM應用產生的答案，從多個維度進行綜合評價。具體的評估維度名稱可聯絡您的商務經理進行確認。

使用限制

本方案僅支援基於LangChain、Llama-index或Dashscope開發的Python版本LLM應用類型。

前提條件

• 已開通ARMS應用監控，詳情請參見開通ARMS。

• 已開通大模型應用開發（LangStudio），詳情請參見PAI服務帳號授權。

• 如果您使用RAM使用者或RAM角色，請在使用該功能前，為其授予AliyunPAILLMTraceFullAccess許可權。詳情請參見為RAM角色授權和為RAM使用者授權。

步驟一：準備工作

import os
import json
import flask
import dashscope

app = flask.Flask(__name__)

def run_query(query):
    """run a query."""

    response = dashscope.Generation.call(
        api_key=os.getenv('DASHSCOPE_API_KEY'),
        model="qwen-plus",
        messages=[
            {'role': 'system', 'content': 'You are a helpful assistant.'},
            {'role': 'user', 'content': query}
        ],
        result_format='message'
    )
    return response


@app.route('/api/trace_demo', methods=['POST'])
def query():
    """
    post data example:
    {
        "query": "capital of china"
    }
    """
    data = flask.request.get_data("utf-8")
    query = json.loads(data).get('query', '')
    response = run_query(query)
    return response.output.choices[0].message.content


if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8000)  

步驟二：開啟鏈路追蹤

在部署EAS服務時，可在服務功能地區通過開啟鏈路追蹤開關來啟用鏈路追蹤功能，並根據提示資訊判斷所用鏡像是否內建鏈路追蹤採集組件，按需配置安裝探針和使用ARMS Python探針啟動應用的相關命令。如需瞭解更多配置詳情，請參見手動安裝Python探針。

• 選擇已內建鏈路追蹤採集組件的鏡像：開啟鏈路追蹤開關後，即可一鍵啟用鏈路追蹤功能，無需額外配置參數。

• 選擇未內建鏈路追蹤採集組件的鏡像：開啟鏈路追蹤開關後，需根據提示資訊配置三方庫和運行命令：

  參數	描述
  運行命令	增加aliyun-bootstrap -a install && aliyun-instrument python app.py。該命令用於安裝探針和使用ARMS Python探針啟動應用，其中app.py是鏡像裡配置的用於提供預測服務的主檔案。三方庫配置需增加aliyun-bootstrap，用於從PyPI倉庫下載探針安裝器。
  三方庫配置	增加aliyun-bootstrap，用於從PyPI倉庫下載探針安裝器。

本方案以使用未內建鏈路追蹤採集組件的鏡像，並以運行範例程式碼為例進行說明。以下是自訂部署EAS服務時的關鍵參數配置說明，具體操作，請參見通過控制台部署。服務部署成功後，您可以：

• 在模型線上服務（EAS）頁面，查看服務部署狀態。

• 在ARMS控制台應用列表頁面，查看接入的應用。應用程式名稱與EAS服務名稱相同。

步驟三：查看鏈路追蹤

基於Trace鏈路提供評估工具，可以協助開發人員驗證LLM應用輸出結果的準確性和可靠性。具體操作步驟如下：

調用EAS服務

以線上調試為例，您也可以通過API調用EAS服務，詳情請參見API調用。

1. 在模型線上服務（EAS）頁面，單擊目標服務作業列下的>線上調試。

2. 在Body頁簽中，根據您定義的預測服務，向指定地址發送請求資料。

   本方案使用範例程式碼檔案app.py中定義的服務介面，樣本結果如下：

   

查看鏈路資訊

1. 切換到鏈路追蹤頁簽的鏈路查詢Tab頁，查看Trace鏈路資訊。

2. 單擊目標Trace操作列下的查看鏈路，進入Trace詳情頁面。

   該頁面提供的Trace資料支援您查看服務的輸入、輸出及相關日誌資訊。

   注意：如果您使用RAM使用者或RAM角色，請在使用該功能前，為其授予AliyunARMSReadOnlyAccess許可權。

   

3. 如需分享該條Trace詳情資料，可單擊下圖所示表徵圖產生一次性地址。

   注意：如果您使用RAM使用者或RAM角色，請在使用該功能前，為其授予cms:CreateTicket許可權。

   

步驟四：評估應用效果

EAS基於Trace鏈路提供了評估工具，用於驗證LLM應用輸出結果的準確性和可靠性。支援以下兩種評估方法：

• 方法一：單條Trace評估：手動選擇EAS服務中的某條鏈路資料進行評估。適用於開發或測試階段，對特定鏈路進行單獨調試，以確保其邏輯正確性和效能符合預期。

• 方法二：批量Trace線上評估：對EAS服務在運行中產生的鏈路資料，進行週期性、採樣形式的評估操作。適用於大規模效能測試或功能驗證情境，協助您全面瞭解系統整體運行狀態和鏈路協同效果。

方法一：單條Trace評估

1. 在鏈路追蹤頁簽的鏈路查詢Tab頁，單擊目標Trace操作列下的評估，然後在評估配置面板中，配置以下參數。

   • 評估指標：為固定配置，暫不支援更改。從以下維度進行評估。

     評估指標	描述
     正確性	判斷答案是否根據輸入和參考文本正確回答問題。
     真實性	判斷答案是否基於輸入和參考文本產生，是否存在幻覺。
     檢索相關性	判斷檢索結果是否與輸入問題相關。包含如下4個指標： nDCG：Normalized Discounted Cumulative Gain（歸一化折損累計增益） Hit Rate（命中率） Precision@K（精確度@K） MRR：Mean Reciprocal Rank（平均倒數排名）

   • 模型配置：評估Trace鏈路使用的大語言模型（LLM）。初始設定後，再次評估時將預設回填。

     參數	描述
     模型選擇	支援使用以下兩種模型： PAI球證模型 qwen-max（百鍊模型） 說明 使用百鍊模型，您需要給EAS配置公網串連。 百鍊模型調用需單獨計費，詳情請參見計費項目。
     模型Token	根據選擇的模型，填寫相應的Token： 球證模型：前往球證模型頁面，開通PAI球證模型並擷取Token。 qwen-max：如何擷取百鍊qwen-max模型Token，請參見首次調用通義千問API。

   • 提取配置：分別在Query提取配置、Answer提取配置和Context提取配置地區，通過配置下表參數來提取相應內容：

     • Query提取配置：提取使用者查詢內容（input）。

     • Answer提取配置：提取系統產生的回答資訊（output）。

     • Context提取配置：提取提供給系統的文本或背景資訊（documents）。

     參數	描述
     SpanName	用於尋找與SpanName匹配的span。
     JsonPathInSpan	格式為a.b.c，不允許為空白。表示從已經匹配的span的指定元素上提取值。
     JsonPathInSpanValue	格式為a.b.c，允許為空白。表示在找到與JsonPathInSpan對應的元素後，如果該元素內容是JSON字串格式，則進一步使用JsonPathInSpanValue來提取對應的值。

     您可以單擊操作列下的查看鏈路，從Trace詳情頁面擷取配置內容。配置樣本如下表所示：

     提取配置	如何擷取	樣本值
     Query提取配置	本方案樣本為JsonPathInSpanValue無值情況： JsonPathInSpanValue有值情況，請參考下圖樣本	JsonPathInSpanValue無值 SpanName：LLM JsonPathInSpan：attributes.input.value JsonPathInSpanValue：因JsonPathInSpan元素內容非JSON字串格式，此處為空白。 JsonPathInSpanValue有值 SpanName：LLM JsonPathInSpan：attributes.input.value JsonPathInSpanValue：因JsonPathInSpan元素內容為JSON字串格式，此處填寫text[0]。
     Answer提取配置		SpanName：LLM JsonPathInSpan：attributes.output.value JsonPathInSpanValue：此處為空白。
     Context提取配置	本方案樣本服務不包含Context提取配置。有關Context提取配置的樣本，請參考下圖：	SpanName：retrieve JsonPathInSpan：attributes.retrieval.documents[*].document.content 重要 僅Context配置支援使用星號（*）。 JsonPathInSpanValue：因JsonPathInSpan元素內容非JSON字串格式，此處為空白。

2. 參數配置完成後，單擊確定。

   當評估結果列出現如下圖樣本結果時，表明評估成功，您可以單擊評估結果查看詳情。

方法二：批量Trace線上評估

1. 在鏈路追蹤頁簽的線上評估Tab頁，單擊建立評估。

2. 在建立評估任務頁面，配置以下參數，然後單擊確定。

   參數	描述
   基礎配置
   任務名稱	參考介面提示，自訂配置任務名稱。
   評估配置
   評估指標	為固定配置，暫不支援更改。從以下維度進行評估： 正確性：判斷答案是否根據輸入和參考文本正確回答問題。 真實性：判斷答案是否基於輸入和參考文本產生，是否存在幻覺。 檢索相關性：判斷檢索內容是否與輸入問題相關。包含如下4個指標： nDCG：Normalized Discounted Cumulative Gain（歸一化折損累計增益） Hit Rate（命中率） Precision@K（精確度@K） MRR：Mean Reciprocal Rank（平均倒數排名）
   模型選擇	支援使用以下兩種模型： PAI球證模型 qwen-max（百鍊模型） 說明 使用百鍊模型，您需要給EAS配置公網串連。 百鍊模型調用需單獨計費，詳情請參見計費項目。
   模型Token	根據選擇的模型，填寫相應的Token： 球證模型：前往球證模型頁面，開通PAI球證模型並擷取Token。 qwen-max：如何擷取百鍊qwen-max模型Token，請參見首次調用通義千問API。
   採樣起止時間	選擇採樣的起始日期和結束日期。
   採樣策略	支援以下兩種採樣策略： 按時間視窗採樣：每隔x分鐘採樣一條Trace。 按機率採樣：隨機抽取指定百分比的Trace鏈路條數進行採樣。
   QCA提取配置：鏈路資料是JSON格式的字串，QCA提取配置用於指定QCA在鏈路資料JSON字串中的路徑（path），路徑對應的值即為QCA的具體內容。
   Query提取配置	Query提取配置：提取使用者查詢內容（input）。 Answer提取配置：提取系統產生的回答資訊（output）。 Context提取配置：提取提供給系統的文本或背景資訊（documents）。 通過配置SpanName、JsonPathInSpan和JsonPathInSpanValue參數來提取相應內容。關於參數的具體配置方法，請參見提取配置。
   Answer提取配置
   Context提取配置

   當評估任務狀態為已完成時，表明所有的採樣評估操作都已經結束，任務不會再產生任何新的採樣評估結果。

3. 評估完成後，您可以在評估任務的評估結果列，查看評估結果。也可以單擊任務名稱，查看任務詳情。

   • 查看評估結果：系統將動態計算並展示基於成功的鏈路資料評估結果的平均值。數值越接近1，表示相關性越強。

   • 查看評估詳情：

後續，您可以對評估任務執行一些管理操作，包括更新、停止、刪除以及複製（僅複製任務配置，建立一個新的評估任務）等。