Platform For AI:EAS での LLM アプリケーションにおけるトレーシングの有効化

概要

EAS は ARMS と統合し、LLM アプリケーションに可観測性を追加します。これにより、コールチェーンをトレースし、パフォーマンスボトルネックを特定し、エラーを検出できます。

トレーシングは、以下の機能を提供します：

• コールチェーンの可視化： 明確なログとともに、リクエストパス全体をマッピングします。

• パフォーマンスモニタリング： 応答時間、トークン消費量、エラー数を追跡して、ボトルネックを特定します。

• 問題の特定： トレース ID を使用し、コンテキストに基づいた根本原因分析で問題を特定します。

• 評価： トレースデータを使用して、LLM の出力の精度と信頼性を検証します。

主要な概念

• トレース

  分散システムにおけるリクエストの完全な実行パスで、複数のスパンで構成されます。各トレースには、リクエストフローの追跡、ボトルネックやエラーの特定に用いる一意の TraceID があります。

• スパン

  特定の操作を表すトレースの基本単位です。操作名、開始時刻、終了時刻を記録します。

• Python プローブ

  Python アプリケーションからコールチェーンデータとパフォーマンスメトリクスを自動的に収集します。EAS サービスをデプロイする際に Python プローブをインストールすると、トレーシングが有効になります。

• 評価

  LLM アプリケーションの回答を複数のディメンションで評価します。具体的な評価ディメンション名については、担当のビジネスマネージャーにお問い合わせください。

制限事項

この機能は、LangChain、LlamaIndex、または DashScope で開発された Python ベースの LLM アプリケーションにのみ対応しています。

前提条件

• ARMS Application Monitoring を有効化します。詳細については、「ARMSの有効化」をご参照ください。

• 「PAIサービスアカウントの承認」に従って LangStudio を有効化します。

• RAM ユーザーまたは RAM ロールを使用する場合は、そのユーザーまたはロールに AliyunPAILLMTraceFullAccess 権限を付与します。詳細については、「RAMロールの権限管理」および「RAMユーザーの権限管理」をご参照ください。

ステップ 1： サンプルコードの準備

import os
import json
import flask
import dashscope

app = flask.Flask(__name__)

def run_query(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 データの例：
    {
        "query": "中国の首都"
    }
    """
    data = flask.request.get_data()
    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)  

ステップ 2：トレーシングの有効化

EAS サービスをデプロイする際、[サービス機能] で [トレーシング] を有効にします。イメージにトレーシングコンポーネントが組み込まれていない場合は、プローブのインストールと起動コマンドを設定します。詳細については、「Pythonプローブの手動インストール」をご参照ください。

• トレーシングが組み込まれたイメージ：[トレーシング] を有効にします。追加の設定は不要です。

• トレーシングが組み込まれていないイメージ：[トレーシング] を有効にし、サードパーティライブラリと起動コマンドを設定します。

  パラメーター	説明
  [コマンドの実行]	aliyun-bootstrap -a install && aliyun-instrument python app.py を追加します。これにより、ARMS Python プローブをインストールして起動します。app.py は予測サービスのメインファイルです。また、プローブインストーラー用に、サードパーティライブラリに aliyun-bootstrap を追加します。
  [サードパーティライブラリの設定]	プローブインストーラーをダウンロードするための aliyun-bootstrap と、アプリケーションで必要なその他のライブラリを追加します。

この例では、トレーシングが組み込まれていないイメージを使用します。主要なデプロイパラメーターを以下に示します。詳細については、「コンソールでのサービスのデプロイ」をご参照ください。デプロイ後：

• EAS ページでサービスのデプロイステータスを確認します。

• ARMS コンソールのアプリケーション一覧ページで登録されたアプリケーションを確認します。アプリケーション名は EAS サービス名と同じです。

ステップ 3：トレースの表示

トレースに基づく評価ツールは、開発者が LLM アプリケーションの出力の精度と信頼性を検証するのに役立ちます。

EAS サービスの呼び出し

この例ではオンラインデバッグを使用します。API 呼び出し によってサービスを呼び出すこともできます。

1. Elastic Algorithm Service (EAS) ページで、目的のサービスを探し、操作列の > オンラインデバッグ をクリックします。

2. [ボディ] タブで、定義した予測サービスに基づいて、指定されたアドレスにリクエストデータを送信します。

   このトピックでは、サンプル app.py ファイルで定義されたサービスインターフェースを使用します。リクエストとレスポンスの例は次のとおりです。

   [オンラインデバッグ] タブで、リクエストメソッドを POST に設定し、URL を http://xxx.com/api/predict/xxx/api/trace_demo に設定し、次のリクエストボディを入力します： {"query": "capital of china"} 。[リクエストを送信] をクリックします。レスポンスとして、ステータスコード 200 と次のボディコンテンツが返されます： The capital of China is Beijing.

トレース情報の表示

1. トレーシング分析 タブの トレースクエリ タブに切り替えて、トレース情報を表示します。

2. 目的のトレースを見つけ、操作 列の トレースの表示 をクリックして、[トレース詳細] ページに移動します。

   このページでは、サービスの入力、出力、ログの詳細を表示できます。

   注：RAM ユーザーまたは RAM ロールを使用する場合、この機能を使用するには AliyunARMSReadOnlyAccess 権限を付与する必要があります。

   [トレースの詳細] ページには、LLM の呼び出しの完全な呼び出しチェーン情報が表示されます。これには以下の情報が含まれます。

   • [Content] タブでは、左側の INPUT エリアにはシステムプロンプトとユーザーメッセージが表示され、右側の OUTPUT エリアにはアシスタントの応答が表示されます。

   • [ウォーターフォールチャート] では、LLM スパンの期間とトークンの統計が表示されます。

   • [スパンの詳細] パネルでは、アプリケーション名、インターフェース名、IP アドレス、開始時刻と終了時刻、スパン ID、ステータスコードなどの基本情報が表示されます。

   • [追加情報] エリアには、[属性]、[リソース]、[詳細] タブが含まれており、モデル名 (例： qwen-plus) および Input Messages と Output Messages の完全なコンテンツが表示されます。

3. トレースの詳細を共有するには、共有アイコン をクリックして、ワンタイムアドレスを生成します。

   注：RAM ユーザーまたは RAM ロールを使用する場合、この機能を使用するには cms:CreateTicket 権限を付与する必要があります。

ステップ 4：アプリケーションパフォーマンスの評価

EAS は、トレースに基づく 2 つの評価方法をサポートしています。

• 方法 1：単一トレースの評価： EAS サービスからトレースを手動で選択して評価します。開発または検証段階で、特定のトレースをデバッグし、そのロジックとパフォーマンスを検証するのに適しています。

• 方法 2：オンラインでのトレースの一括評価： 稼働中の EAS サービスからサンプリングされたトレースを定期的に評価します。大規模なパフォーマンステストや機能検証に適しており、システム全体のステータスを把握できます。

方法 1：単一トレースの評価

1. トレーシング分析 タブの トレースクエリ タブで、対象のトレースを見つけ、操作 列の 評価 をクリックします。次に、評価 設定パネルで、次のパラメーターを設定します。

   • [評価指標]：これは固定構成であり、変更できません。評価は、以下のディメンションに基づいて行われます。

     評価メトリクス	説明
     正確性	入力と参照テキストに基づいて、回答が質問に正しく対応しているかどうかを判定します。
     忠実性	入力と参照テキストに基づいて回答が生成されているかどうか、およびハルシネーションが含まれていないかどうかを判定します。
     検索関連性	検索結果が入力された質問に関連しているかどうかを判定します。以下の 4 つのメトリクスが含まれます。 nDCG： Normalized Discounted Cumulative Gain Hit Rate Precision@K MRR： Mean Reciprocal Rank

   • [モデルの構成]：トレースの評価に使用される LLM です。初期設定後、この設定は以降の評価では自動的にバックフィルされます。

     パラメータ	説明
     [モデルの選択]	以下の 2 つのモデルがサポートされています。 [PAI ジャッジモデル] [qwen-max] (Model Studio モデル) 説明 Model Studio モデルを使用するには、「EAS のインターネット接続の設定」をご参照ください。 Model Studio モデルの呼び出しは別途課金されます。「課金」をご参照ください。
     [モデルトークン]	選択したモデルのトークンを入力します。 ジャッジモデル：「ジャッジモデル」ページに移動し、PAI ジャッジモデルを有効化してトークンを取得します。 qwen-max：「Tongyi Qianwen API を初めて呼び出す」からトークンを取得します。

   • [抽出設定]： [クエリ抽出設定]、[回答抽出設定]、[コンテキスト抽出設定] のセクションで、以下の表のパラメータを設定して、対応するコンテンツを抽出します。

     • [クエリ抽出設定]： ユーザークエリコンテンツ (入力) を抽出します。

     • [回答抽出設定]： システムが生成した回答 (出力) を抽出します。

     • [コンテキスト抽出設定]： システムに提供されたテキストまたは背景情報 (ドキュメント) を抽出します。

     パラメータ	説明
     SpanName	SpanName と一致するスパンを検索します。
     JsonPathInSpan	形式は a.b.c です。このパラメータは空にできません。一致したスパンの指定された要素から値を抽出します。
     JsonPathInSpanValue	形式は a.b.c です。このパラメータは空にできます。[JsonPathInSpan] に対応する要素が見つかった後、その要素のコンテンツが JSON 文字列である場合、[JsonPathInSpanValue] を使用して対応する値を抽出します。

     操作 列の トレースの表示 をクリックすると、トレース詳細ページから設定内容を取得できます。 次の表に設定例を示します。

     抽出設定	取得方法	設定値の例
     クエリ抽出設定	このトピックでは、JsonPathInSpanValue に値がない例を示します。トレースの詳細ページで、以下のように JsonPathInSpan の値を取得します。 左側のウォーターフォールチャートで、LLM スパンを選択して、呼び出しチェーンの INPUT と OUTPUT のコンテンツおよび期間を表示します。 右側のスパンの詳細パネルで、[属性] タブをクリックして、GenAI 関連の属性リストを展開します。 input.value フィールドを確認します。その値は、role と content を含む JSON 配列です。例： [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "capital of china"}]。 JsonPathInSpanValue に値がある例については、[設定値の例] 列をご参照ください。	JsonPathInSpanValue に値がない場合 [SpanName]： LLM [JsonPathInSpan]： attributes.input.value [JsonPathInSpanValue]： [JsonPathInSpan] 要素のコンテンツが JSON 文字列ではないため、このパラメータは空です。 JsonPathInSpanValue に値がある場合 [SpanName]： LLM [JsonPathInSpan]： attributes.input.value [JsonPathInSpanValue]： [JsonPathInSpan] 要素のコンテンツが JSON 文字列であるため、ここに text[0] を入力します。
     回答抽出設定	[トレースの詳細] ページのウォーターフォールチャートで、[LLM] スパン (SpanName のソース) をクリックします。次に、右側のスパンの詳細パネルで、[属性] タブを開き、output.value フィールド (JsonPathInSpan に対応するパス) を見つけます。このフィールドには、モデルが返した完全な JSON レスポンスが含まれています。	[SpanName]： LLM [JsonPathInSpan]： attributes.output.value [JsonPathInSpanValue]： このパラメータは空です。
     コンテキスト抽出設定	このトピックのサンプルサービスには、コンテキスト抽出設定は含まれていません。例については、[設定値の例] 列をご参照ください。	[SpanName]： retrieve [JsonPathInSpan]： attributes.retrieval.documents[*].document.content 重要 アスタリスク (*) の使用は、コンテキスト抽出設定でのみサポートされています。 [JsonPathInSpanValue]： [JsonPathInSpan] 要素のコンテンツが JSON 文字列ではないため、このパラメータは空です。

2. パラメーターを設定した後、確認 をクリックします。

   スコア結果 (たとえば、「正確性」や「忠実度」ディメンションのスコアなど) が 評価結果 列に表示されると、評価は完了です。結果をクリックすると詳細が表示されます。

方法 2：オンラインでのトレースの一括評価

1. トレーシング分析 タブの オンライン評価 タブで、評価の新規作成 をクリックします。

2. 評価タスクの作成 ページで、次のパラメーターを設定し、確認 をクリックします。

   パラメータ	説明
   基本設定
   タスク名	カスタムタスク名を入力します。
   評価設定
   評価メトリクス	これは固定設定であり、変更できません。評価は以下のディメンションに基づいて実行されます。 正確性： 入力と参照テキストに基づいて、回答が質問に正しく対応しているかどうかを判定します。 忠実性： 入力と参照テキストに基づいて回答が生成されているかどうか、およびハルシネーションが含まれていないかどうかを判定します。 検索関連性： 検索されたコンテンツが入力された質問に関連しているかどうかを判定します。以下の 4 つのメトリクスが含まれます。 nDCG： Normalized Discounted Cumulative Gain Hit Rate Precision@K MRR： Mean Reciprocal Rank
   モデル選択	以下の 2 つのモデルがサポートされています。 [PAI ジャッジモデル] [qwen-max] (Model Studio モデル) 説明 Model Studio モデルを使用するには、「EAS のインターネット接続の設定」をご参照ください。 Model Studio モデルの呼び出しは別途課金されます。「課金」をご参照ください。
   モデルトークン	選択したモデルのトークンを入力します。 ジャッジモデル：「ジャッジモデル」ページに移動し、PAI ジャッジモデルを有効化してトークンを取得します。 qwen-max：「Tongyi Qianwen API を初めて呼び出す」からトークンを取得します。
   サンプリング開始・終了時刻	サンプリングの開始日と終了日を選択します。
   サンプリングポリシー	以下のサンプリングポリシーが利用可能です。 時間ウィンドウベースのサンプリング：一定間隔 (x 分ごと) で 1 つのトレースをキャプチャします。 確率ベースのサンプリング：指定された割合のトレースをランダムにキャプチャします。
   [QCA 抽出設定]： トレースデータは JSON 文字列としてフォーマットされます。QCA 抽出設定は、この JSON 構造内の QCA へのパスを定義します。このパスの値は、特定の QCA コンテンツを表します。
   [クエリ抽出設定]	[クエリ抽出設定]： ユーザークエリコンテンツ (入力) を抽出します。 [回答抽出設定]： システムが生成した回答 (出力) を抽出します。 [コンテキスト抽出設定]： システムに提供されたテキストまたは背景情報 (ドキュメント) を抽出します。 [SpanName]、[JsonPathInSpan]、[JsonPathInSpanValue] を設定して、対応するコンテンツを抽出します。設定の詳細については、「抽出設定」をご参照ください。
   [回答抽出設定]
   [コンテキスト抽出設定]

   タスクの [ステータス] が [完了] と表示されると、すべての評価が終了し、新しい結果は生成されません。

3. 評価が完了すると、評価タスクの [評価結果] 列で結果を表示できます。また、タスク名をクリックして詳細を表示することもできます。

   • 評価結果の表示： システムは、すべての成功した評価の平均スコアを計算して表示します。スコアが 1 に近いほど、品質が高いことを示します。

   • 評価詳細の表示： 評価タスク名をクリックすると、評価の詳細が表示されます。詳細ページには以下のセクションが含まれます。

     • 基本情報： タスク名、タスク ID、ステータス、作成時刻。

     • 評価設定情報： 評価メトリクス (忠実性、正確性、検索関連性)、モデル選択 (PAI ジャッジモデル)、サンプリング開始・終了時刻、サンプリングポリシー (サンプリングレート)、クエリ/コンテキスト/回答抽出設定 (SpanName パスを含む)。

     • 評価結果の概要： 各メトリクス (忠実性、正確性、nDCG、Hit Rate、MRR、Precision@K など) の平均スコア、およびサンプリングされたトレースの総数と評価に成功したトレースの数。

     • TraceId リスト： 各トレースの入力、出力、トレースごとの評価結果 (忠実性のハルシネーションなし、正確性の正解、検索関連性ラベルなど) および評価時刻を表示し、[トレースを表示] および [再評価] アクションをサポートします。

作成後、タスクの更新、停止、削除、またはクローニングによってタスクを管理できます。クローニングによって、設定が新しいタスクに複製されます。