Method: projects.explain

Performs explanation on the data in the request.

AI Explanations は、HTTP POST メソッドにカスタム explain 動詞を実装します。explain メソッドは、リクエストのデータに対して予測を行います。

URL は、Google API HTTP アノテーション構文で説明されています。

POST https://ml.googleapis.com/v1/{name=projects/**}:explain

name パラメータは必須です。モデルの名前は必須で、バージョンは任意となります。バージョンなしでモデルを指定すると、そのモデルのデフォルト バージョンが使用されます。

モデルとバージョンの両方を指定する例:

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name/versions/your-version-name:explain

モデルのみを指定する例。そのモデルのデフォルト バージョンが使用されます。

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name:explain

このページでは、説明リクエストの本文とレスポンスの本文の形式について説明します。説明リクエストの送信方法を示すサンプルコードについては、機能の属性の使用に関するガイドをご覧ください。

リクエスト本文の詳細

TensorFlow

リクエストの本文には、次の構造を使用したデータが含まれています(JSON 表現)。

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ]
}

instances[] オブジェクトは必須であり、説明を取得するインスタンスのリストを含める必要があります。

インスタンスのリストに含まれる各要素の構造は、モデルの入力定義によって決まります。インスタンスには、名前付き入力を(オブジェクトとして)含めることも、ラベルなし値のみを含めることもできます。

すべてのデータに名前付き入力が含まれるわけではありません。インスタンスは、単純な JSON 値(ブール値、数値、文字列)の場合もあれば、単純な値のリスト、または複雑なネスト構造のリストの場合もあります。

以下にリクエスト本文の例を示します。

各行が文字列値としてエンコードされた CSV データ:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

書式なしテキスト:

{"instances": ["the quick brown fox", "the lazy dog"]}

単語のリスト(文字列のベクトル)としてエンコードされた文:

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

浮動小数点スカラー値:

{"instances": [0.0, 1.1, 2.2]}

整数のベクトル:

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

テンソル(この場合、2 次元のテンソル):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

画像は、さまざまな方法で表現できます。次のエンコード スキームでは、最初の 2 つの次元は画像の行と列を表し、3 つ目の次元に各ピクセルの R、G、B 値のリスト(ベクトル)が含まれます。

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

データのエンコード

JSON 文字列は UTF-8 としてエンコードする必要があります。バイナリデータを送信するには、データを Base64 エンコードし、バイナリとしてマークする必要があります。JSON 文字列をバイナリとしてマークするには、b64 という名前の単一の属性の JSON オブジェクトに置き換えます。

{"b64": "..."} 

次の例は、Base64 エンコードを必要とする 2 つのシリアル化された tf.Examples インスタンスを示しています(例示のための架空データ)。

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

次の例は、base64 エンコードを必要とする、JPEG 画像の 2 つのバイト文字列を示しています(例示のための架空のデータ)。

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

複数の入力テンソル

一部のモデルでは、基盤となる TensorFlow グラフで複数の入力テンソルが受け入れられます。この場合、JSON の名前と値のペアの名前を使用して入力テンソルを識別します。

入力テンソルの別名 "tag"(文字列)と "image"(Base64 でエンコードされた文字列)を持つグラフの場合:

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

入力テンソルの別名 "tag"(文字列)と "image"(8 ビット整数の 3 次元配列)を持つグラフの場合:

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

説明メタデータ

AI Explanations を使用する場合は、どのテンソルが実際の特徴、出力確率、出力予測に対応するかを指定する必要があります。これを行うには、AI Explanations にモデルをデプロイする前に、explanation_metadata.json という名前のファイルを SavedModel フォルダに追加します。

このプロセスを簡単にするには、TensorFlow グラフのテンソルに名前を割り当てます。モデルをトレーニングする前に、未加工のテンソルまたは Keras レイヤで以下のように name プロパティを設定します。

auxiliary_output = Dense(1, activation='sigmoid', name='aux_output')

ファイルの内容は、以下のスキーマと一致する必要があります。

{
  "inputs": {
    string <input feature key>: {
      "input_tensor_name": string,
      "input_baselines": [
        number,
      ],
      "modality": string
    }
    ...
  },
  "outputs": {
    string <output value key>:  {
      "output_tensor_name": string
    },
    ...
  },
  "framework": string
}
フィールド

出力値キーと入力特徴キー

一意の名前。システムは、このキーの下にリストされた特定の機能のアトリビューション スコアを含む辞書を出力します。
input_tensor_name

string

必須。モデルの予測に起因する入力を含むテンソルの名前。名前を name:0 の形式にします。例: aux_output:0

input_baselines

<integer>|<simple list>

省略可。この特定の機能のベースラインまたはこの特定の機能の「情報が不足している」例の値。平均値または 0 を使用することを検討してください。
各ベースラインの形状は、エンコードされたテンソルの形状と一致する必要があります。スカラーを指定すると、エンコードされたテンソルと同じ形状にブロードキャストされます。
複数のベースラインを指定すると、ベースラインのアトリビューションが平均化されます。たとえば、完全な黒または白の画像とアトリビューションを比較できます。

modality

string

省略可。入力テンソルが画像の場合は、image に設定できます。その場合、アトリビューションの図が返されます。

input_tensor_name で指定されたテンソルは次のようになります。

  • カラー画像の場合: 要素が [0, 1] の範囲に正規化されたピクセルの RGB カラー値である、dtype float32 と形状 [batch_size, height, width, 3] の密集した 4D テンソル。
  • グレースケール画像の場合: 要素が [0, 1] の範囲に正規化されたピクセルの黒の値である、dtype float32 と形状 [batch_size, height, width] の密集した 3D テンソル。
output_tensor_name

string

必須。モデルの予測が起因する出力を含むテンソルの名前。

framework

string

必須。tensorflow に設定してください。

可視化設定の構成

統合勾配または XRAI メソッドを使用して画像データの説明を取得する場合は、結果を explanation_metadata.json ファイルに含めることで、結果の可視化設定を構成できます。これらの設定は省略可能です。

可視化設定を構成するには、可視化する入力オブジェクト内に可視化設定を含めます。

{
  "inputs": {
    string <input feature key>: {
      "input_tensor_name": string,
      "input_baselines": [
        number,
      ],
      "modality": string
      "visualization": {
        "type": string,
        "polarity": string,
        "clip_below_percentile": number,
        "clip_above_percentile": number,
        "color_map": string,
        "overlay_type": string
      }
    }
    ...
  },
  "outputs": {
    string <output value key>:  {
      "output_tensor_name": string
    },
    ...
  },
  "framework": string
}

可視化設定の詳細

可視化設定はすべて任意です。値の全部または一部を指定することも、指定しないこともできます。

"visualization": {
  "type": string,
  "polarity": string,
  "clip_below_percentile": number,
  "clip_above_percentile": number,
  "color_map": string,
  "overlay_type": string
}

構成と出力画像の例をご覧ください。

フィールド

タイプ

string

省略可。可視化のタイプ。有効な値は outlines または pixels です。統合勾配の場合は、どちらの値でも使用できます。デフォルトの設定は outlines です。
XRAI の場合、pixels がデフォルトの設定です。XRAI では outlines は推奨されません。

polarity

string

省略可。表示されるアトリビューション値の方向性。有効な値は positivenegative または both です。デフォルトは positive です。

clip_below_percentile

number

省略可。指定されたパーセンタイルを下回るアトリビューションを除外します。有効な値は、[0, 100] の範囲の小数値です。

clip_above_percentile

number

省略可。指定されたパーセンタイルを上回るアトリビューションを除外します。有効な値は、[0, 100] の範囲の小数値です。clip_below_percentile より大きくする必要があります。

color_map

string

省略可。有効な値は red_greenpink_greenviridis です。統合勾配のデフォルトは pink_green、XRAI のデフォルトは viridis です。

overlay_type

string

省略可。オーバーレイのタイプです。元の入力画像の上にアトリビューションをどのように表示するかを決定します。
有効な値は nonegrayscaleoriginalmask_black です。

  • none: アトリビューションは入力画像に重ねて表示されずに、黒い画像の上に単独で表示されます。
  • grayscale: アトリビューションは入力画像のグレースケール版に重ねて表示されます。
  • original: アトリビューションは元の入力画像に重ねて表示されます。
  • mask_black: アトリビューションはマスクとして使用され、画像の予測部分を強調します。元の画像のピクセルの不透明度は、対応するピクセルのアトリビューションの強度に対応します。

統合勾配のデフォルトは original、XRAI のデフォルトは grayscale です。

overlay_type を示すサンプル画像をご覧ください。

レスポンス本文の詳細

レスポンスはリクエストと非常によく似ています。

呼び出しが成功すると、レスポンスの本文には、リクエストの本文に同じ順序でインスタンスあたり 1 つの説明エントリが含まれます。

{
  "explanations": [
    {
      object
    }
  ]
}

いずれかのインスタンスの説明に失敗した場合、レスポンスの本文には説明が含まれません。代わりに、単一のエラーエントリが含まれています。

{
  "error": string
}

explanations[] オブジェクトには、リクエストのインスタンスごとに 1 つの説明からなるリストが含まれます。

エラーの場合、error 文字列には問題を説明するメッセージが含まれます。インスタンスの処理中にエラーが発生した場合は、説明リストではなくエラーが返されます。

インスタンスごとに 1 つの説明があっても、説明の形式はインスタンスの形式に直接関係しません。説明は、モデルで定義されている出力コレクションで指定されている形式が適用されます。説明のコレクションは、JSON リストで返されます。リストの各メンバーは、単純な値、リスト、または多様な複雑度の JSON オブジェクトのいずれかです。モデルに複数の出力テンソルがある場合、各説明は各出力の名前と値のペアを含む JSON オブジェクトになります。名前はグラフの出力エイリアスを識別します。

レスポンス本文の例

次の説明のレスポンスは、表形式データに対する個々の対象物の帰属に関するものです。これは、表形式データのノートブックの例の一部です。ノートブックでは、説明のレスポンスを解析し、属性データをプロットする方法を示します。

対象物の属性は attributions_by_label オブジェクト内に表示されます。

{
 "explanations": [
  {
   "attributions_by_label": [
    {
     "approx_error": 0.001017811509478243,
     "attributions": {
      "data": [
       -0.0,
       1.501250445842743,
       4.4058547498107075,
       0.016078486742916454,
       -0.03749384209513669,
       -0.0,
       -0.2621846305120581,
       -0.0,
       -0.0,
       0.0
      ]
      ...
     },
     "baseline_score": 14.049912452697754,
     "example_score": 19.667699813842773,
     "label_index": 0,
     "output_name": "duration"
    }
    ...
   ]
  }
 ]
}
  • approx_error は、特徴属性の近似誤差です。特徴属性は、Shapley 値の近似に基づいています。 近似誤差の詳細をご覧ください。
  • attributions オブジェクトには、説明をリクエストした各入力特徴の Key-Value ペアが含まれます。
    • 各入力機能のキーは、explanation_metadata.json ファイルに入力した入力機能キーと同じです。この例では、「data」です。
    • 値は各特徴の属性です。属性の形状は入力テンソルに一致します。この例では、スカラー値のリストです。詳しくは、これらの属性の値をご覧ください。
  • baseline_score は、設定したベースラインのモデル出力です。モデルに応じて、ベースラインをゼロ、ランダム値、中央値に設定できます。詳しくは、ベースラインの選択をご覧ください。
  • example_score は、指定した入力インスタンスの予測です。この例では、example_score はあるライドシェア自転車の予測走行時間(分単位)です。一般に、example_score はそのインスタンスの予測です。
  • label_indexは、説明される出力テンソルのインデックスです。
  • output_name は、explanation_metadata.json ファイルで設定した出力機能キーと同じです。この例では「duration」です。

個別の属性値

次の表に、これらの属性値の例に対応する機能の詳細を示します。正の属性値はその分だけ予測値を増やし、負の属性値はその分だけ予測値を下げます。自転車走行の開始地点と終了地点の間の euclidean 距離が自転車の予測走行時間(19.667 分)に最も大きな影響を与え、4.498 分増加させました。

機能名 特徴値 属性値
start_hr 19 0
平日 1 -0.0661425
ユークリッド 3920.76 4.49809
temp 52.5 0.0564195
dew_point 38.8 -0.072438
wdsp 0 0
max_temp 64.8 -0.226125
fog 0 -0
prcp 0.06 -0
rain_drizzle 0 0

詳しくは、表形式データのノートブックの例をご覧ください。

API 仕様

次のセクションでは、explain メソッドの仕様を AI Platform Training and Prediction API のディスカバリ ドキュメントの定義に従って説明します。メソッドの詳細については、このドキュメントの前のセクションをご覧ください。

HTTP request

POST https://{endpoint}/v1/{name=projects/**}:explain

Where {endpoint} is one of the supported service endpoints.

The URLs use gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The resource name of a model or a version.

Authorization: requires the predict permission on the specified resource.

Authorization requires one or more of the following IAM permissions on the specified resource name:

  • ml.models.predict
  • ml.versions.predict

Request body

The request body contains data with the following structure:

JSON representation
{
  "httpBody": {
    object (HttpBody)
  }
}
Fields
httpBody

object (HttpBody)

Required. The explanation request body.

Response body

If successful, the response is a generic HTTP response whose format is defined by the method.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.