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 |
必須。モデルの予測に起因する入力を含むテンソルの名前。名前を |
input_baselines |
<integer>|<simple list>
省略可。この特定の機能のベースラインまたはこの特定の機能の「情報が不足している」例の値。平均値または 0 を使用することを検討してください。 |
modality |
省略可。入力テンソルが画像の場合は、
|
output_tensor_name |
必須。モデルの予測が起因する出力を含むテンソルの名前。 |
framework |
必須。 |
可視化設定の構成
統合勾配または 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
}
構成と出力画像の例をご覧ください。
| フィールド | |
|---|---|
|
タイプ |
省略可。可視化のタイプ。有効な値は |
polarity |
省略可。表示されるアトリビューション値の方向性。有効な値は |
clip_below_percentile |
省略可。指定されたパーセンタイルを下回るアトリビューションを除外します。有効な値は、 |
clip_above_percentile |
省略可。指定されたパーセンタイルを上回るアトリビューションを除外します。有効な値は、 |
color_map |
省略可。有効な値は |
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 |
Required. The resource name of a model or a version. Authorization: requires the Authorization requires one or more of the following IAM permissions on the specified resource
|
Request body
The request body contains data with the following structure:
| JSON representation | |
|---|---|
{
"httpBody": {
object ( |
|
| Fields | |
|---|---|
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.