Mengonfigurasi penjelasan berbasis fitur

Untuk menggunakan Vertex Explainable AI dengan model yang dilatih khusus, Anda harus mengonfigurasi opsi tertentu saat membuat resource Model yang rencananya akan Anda minta penjelasannya, saat men-deploy model itu, atau saat mengirimkan tugas penjelasan batch. Halaman ini menjelaskan konfigurasi opsi tersebut.

Jika ingin menggunakan Vertex Explainable AI dengan model tabel AutoML, Anda tidak perlu melakukan konfigurasi apa pun; Vertex AI akan otomatis mengonfigurasi model untuk Vertex Explainable AI. Lewati dokumen ini dan baca Mendapatkan penjelasan.

Kapan dan di mana mengonfigurasi penjelasan

Anda mengonfigurasi penjelasan saat membuat atau mengimpor model. Anda juga dapat mengonfigurasi penjelasan tentang model yang telah dibuat, meskipun sebelumnya tidak mengonfigurasi penjelasan.

Mengonfigurasi penjelasan saat membuat atau mengimpor model

Saat membuat atau mengimpor Model, Anda dapat menetapkan konfigurasi default untuk semua penjelasannya menggunakan kolom explanationSpec Model.

Anda dapat membuat Model yang dilatih khusus di Vertex AI dengan cara berikut:

Apa pun kasusnya, Anda dapat mengonfigurasi Model untuk mendukung Vertex Explainable AI. Contoh dalam dokumen ini mengasumsikan bahwa Anda mengimpor Model. Untuk mengonfigurasi Vertex Explainable AI saat membuat Model yang dilatih khusus menggunakan TrainingPipeline, gunakan setelan konfigurasi yang dijelaskan di bagian TrainingPipeline modelToUpload dalam dokumen ini.

Mengonfigurasi penjelasan saat men-deploy model atau mendapatkan prediksi batch

Saat men-deploy Model ke resource Endpoint, Anda dapat:

  • Mengonfigurasi penjelasan, terlepas dari apakah model dikonfigurasi sebelumnya untuk penjelasan atau tidak. Cara ini berguna jika Anda awalnya tidak berencana untuk mendapatkan penjelasan (dan menghilangkan explanationSpec saat membuat model), tetapi kemudian memutuskan bahwa Anda menginginkan penjelasan untuk Model tersebut, atau jika Anda ingin mengabaikan sebagian setelan penjelasan.
  • Menonaktifkan penjelasan. Hal ini berguna jika model Anda dikonfigurasikan untuk penjelasan, tetapi Anda tidak berencana untuk mendapatkan penjelasan dari endpoint. Untuk menonaktifkan penjelasan saat men-deploy model ke endpoint, hapus centang pada opsi Explainability di Konsol Cloud atau tetapkan DeployedModel.disableExplanations ke true.

Demikian pula, saat mendapatkan prediksi batch dari Model, Anda dapat mengonfigurasi penjelasan dengan mengisi kolom BatchPredictionJob.explanationSpec atau menonaktifkan penjelasan dengan menetapkan BatchPredictionJob.generateExplanation ke false.

Mengabaikan konfigurasi saat mendapatkan penjelasan online

Terlepas dari apakah Anda membuat atau mengimporModel dengan setelan penjelasan, dan terlepas dari apakah Anda mengonfigurasi setelan penjelasan selama deployment, Anda dapat mengabaikan setelan penjelasan awal Model saat mendapatkan penjelasan online.

Saat mengirim permintaan explain ke Vertex AI, Anda dapat mengabaikan beberapa konfigurasi penjelasan yang sebelumnya Anda tetapkan untuk Model atau DeployedModel.

Dalam permintaan explain, Anda dapat mengabaikan kolom berikut:

Abaikan setelan ini di kolom explanationSpecOverride permintaan penjelasan.

Mengimpor model dengan kolom explanationSpec

Bergantung pada apakah Anda menyajikan prediksi menggunakan container bawaan atau container kustom, tentukan detail yang sedikit berbeda untuk ExplanationSpec. Pilih tab yang cocok dengan container yang Anda gunakan:

Container bawaan TensorFlow

Anda dapat menggunakan salah satu metode atribusi berikut untuk Vertex Explainable AI. Baca perbandingan metode atribusi fitur untuk memilih metode yang sesuai bagi Model Anda:

Sampled Shapley

Bergantung pada alat yang ingin Anda gunakan untuk membuat atau mengimpor Model, pilih salah satu tab berikut:

Konsol

Ikuti panduan untuk mengimpor model menggunakan Konsol Google Cloud. Setelah sampai pada langkah Explainability, lakukan langkah berikut:

  1. Untuk metode atribusi fitur, pilih Sampled Shapely (for tabular models).

  2. Tetapkan jumlah jalur ke jumlah permutasi fitur yang akan digunakan untuk metode atribusi Sampled Shapley. Nilai ini harus berupa bilangan bulat dalam rentang [1, 50].

    Nilai yang lebih tinggi dapat mengurangi error perkiraan, tetapi lebih intensif secara komputasi. Jika Anda tidak tahu nilai apa yang sebaiknya digunakan, coba 25.

  3. Konfigurasikan setiap fitur input dalam model Anda:

    1. Isikan nama fitur input Anda.

    2. Jika ingin, Anda dapat menambahkan satu atau beberapa baseline input. Jika tidak, Vertex Explainable AI akan memilih baseline input default dari nilai nol semua, yang merupakan gambar hitam untuk data gambar.

    3. Jika Anda mengimpor model TensorFlow, ada kolom input tambahan:

      1. Isi Input tensor name.

      2. Jika berlaku, isi Indices tensor name dan/atau Dense shape tensor name.

      3. Modality tidak dapat diperbarui di sini. Parameter ini otomatis ditetapkan ke NUMERIC untuk model tabel, atau IMAGE untuk model gambar.

      4. Jika berlaku, tetapkan kolom Encoding. Nilai default-nya adalah IDENTITY, jika tidak ditetapkan.

      5. Jika berlaku, tetapkan kolom Group name.

  4. Jika Anda mengimpor model TensorFlow, tentukan kolom output:

    1. Tetapkan Output name fitur Anda.
    2. Tetapkan Output tensor name fitur Anda.
    3. Jika berlaku, tetapkan Index display name mapping.
    4. Jika berlaku, tetapkan Display name mapping key.

  5. Klik tombol Import setelah selesai mengonfigurasi setelan explainability.

gcloud

  1. Untuk TensorFlow 2, ExplanationMetadata bersifat opsional.

    Tulis ExplanationMetadata berikut ke file JSON di lingkungan lokal Anda. Nama file tidak menjadi masalah, tetapi untuk contoh ini, panggil file explanation-metadata.json:

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

    Ganti kode berikut:

    Jika ingin, Anda dapat menambahkan baseline input ke ExplanationMetadata. Jika tidak, Vertex AI akan memilih baseline input untuk Model.

  2. Jalankan perintah berikut untuk membuat resource Model yang mendukung Vertex Explainable AI. Flag yang paling relevan dengan Vertex Explainable AI akan disorot. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Ganti kode berikut:

    Untuk mempelajari nilai yang sesuai untuk placeholder lainnya, lihat upload dan Mengimpor model.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

Untuk mempelajari nilai yang sesuai untuk placeholder lainnya, lihat upload dan Mengimpor model.

Jika ingin, Anda dapat menambahkan baseline input ke ExplanationMetadata. Jika tidak, Vertex AI akan memilih baseline input untuk Model.

Untuk model TensorFlow 2, kolom metadata bersifat opsional. Jika dihilangkan, Vertex AI akan otomatis menginferensi inputs dan outputs dari model.

Metode HTTP dan URL: 

POST http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Isi JSON permintaan: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "sampledShapleyAttribution": {
          "pathCount": PATH_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Integrated Gradients

Bergantung pada alat yang ingin Anda gunakan untuk membuat atau mengimpor Model, pilih salah satu tab berikut:

Konsol

Ikuti panduan untuk mengimpor model menggunakan Konsol Google Cloud. Setelah sampai pada langkah Explainability, lakukan langkah berikut:

  1. Untuk metode atribusi fitur, pilih Integrated gradients (for tabular models) atau Integrated gradients (for image classification models), bergantung opsi yang lebih sesuai untuk model Anda.

  2. Jika Anda mengimpor model klasifikasi gambar, lakukan langkah berikut:

    1. Tetapkan Visualization type dan Color map.

    2. Anda dapat mempertahankan Clip below, Clip above, Overlay type, dan Number of integral steps pada setelan default-nya.

    Pelajari setelan visualisasi lebih lanjut.

  3. Tetapkan jumlah langkah yang akan digunakan untuk memperkirakan integral jalur selama atribusi fitur. Nilai ini harus berupa bilangan bulat dalam rentang [1, 100].

    Nilai yang lebih tinggi dapat mengurangi error perkiraan, tetapi lebih intensif secara komputasi. Jika Anda tidak tahu nilai apa yang sebaiknya digunakan, coba 50.

  4. Konfigurasikan setiap fitur input dalam model Anda:

    1. Isikan nama fitur input Anda.

    2. Jika ingin, Anda dapat menambahkan satu atau beberapa baseline input. Jika tidak, Vertex Explainable AI akan memilih baseline input default dari nilai nol semua, yang merupakan gambar hitam untuk data gambar.

    3. Jika Anda mengimpor model TensorFlow, ada kolom input tambahan:

      1. Isi Input tensor name.

      2. Jika berlaku, isi Indices tensor name dan/atau Dense shape tensor name.

      3. Modality tidak dapat diperbarui di sini. Parameter ini otomatis ditetapkan ke NUMERIC untuk model tabel, atau IMAGE untuk model gambar.

      4. Jika berlaku, tetapkan kolom Encoding. Nilai default-nya adalah IDENTITY, jika tidak ditetapkan.

      5. Jika berlaku, tetapkan kolom Group name.

  5. Jika Anda mengimpor model TensorFlow, tentukan kolom output:

    1. Tetapkan Output name fitur Anda.
    2. Tetapkan Output tensor name fitur Anda.
    3. Jika berlaku, tetapkan Index display name mapping.
    4. Jika berlaku, tetapkan Display name mapping key.

  6. Klik tombol Import setelah selesai mengonfigurasi setelan explainability.

gcloud

  1. Untuk TensorFlow 2, ExplanationMetadata bersifat opsional.

    Tulis ExplanationMetadata berikut ke file JSON di lingkungan lokal Anda. Nama file tidak menjadi masalah, tetapi untuk contoh ini, panggil file explanation-metadata.json:

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "modality": "MODALITY",
      "visualization": VISUALIZATION_SETTINGS
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

    Ganti kode berikut:

    • FEATURE_NAME: Nama yang mudah diingat untuk fitur input Anda.
    • INPUT_TENSOR_NAME: Nama tensor input di TensorFlow. Untuk menemukan nilai yang benar untuk kolom ini, baca Menggunakan TensorFlow dengan Vertex Explainable AI.
    • MODALITY: image jika Model menerima gambar sebagai input, atau numeric jika Model menerima data tabel sebagai input. Nilai default-nya adalah numeric.

    • VIZUALIZATION_OPTIONS: Opsi untuk memvisualisasikan penjelasan. Untuk mempelajari cara mengisi kolom ini, baca Mengonfigurasi setelan visualisasi untuk data gambar.

      Jika Anda menghapus kolom modality atau menetapkan kolom modality ke numeric, hapus kolom visualization seluruhnya.

    • OUTPUT_NAME: Nama yang mudah diingat untuk output model Anda.
    • OUTPUT_TENSOR_NAME: Nama tensor output di TensorFlow. Untuk menemukan nilai yang benar untuk kolom ini, baca Menggunakan TensorFlow dengan Vertex Explainable AI.

    Jika ingin, Anda dapat menambahkan baseline input ke ExplanationMetadata. Jika tidak, Vertex AI akan memilih baseline input untuk Model.

  2. Jalankan perintah berikut untuk membuat resource Model yang mendukung Vertex Explainable AI. Flag yang paling relevan dengan Vertex Explainable AI akan disorot. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=integrated-gradients \
  --explanation-step-count=STEP_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Ganti kode berikut:

    Untuk mempelajari nilai yang sesuai untuk placeholder lainnya, lihat upload dan Mengimpor model.

    Jika ingin, Anda dapat menambahkan flag untuk mengonfigurasi perkiraan SmoothGrad untuk gradien.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • IMAGE_URI: URI container bawaan TensorFlow untuk menyajikan prediksi.
  • STEP_COUNT: Jumlah langkah yang akan digunakan untuk memperkirakan integral jalur selama atribusi fitur. Harus berupa bilangan bulat dalam rentang [1, 100].

    Nilai yang lebih tinggi dapat mengurangi error perkiraan, tetapi lebih intensif secara komputasi. Jika Anda tidak tahu nilai apa yang sebaiknya digunakan, coba 50.

  • FEATURE_NAME: Nama yang mudah diingat untuk fitur input Anda.
  • INPUT_TENSOR_NAME: Nama tensor input di TensorFlow. Untuk menemukan nilai yang benar untuk kolom ini, baca Menggunakan TensorFlow dengan Vertex Explainable AI.
  • MODALITY: image jika Model menerima gambar sebagai input, atau numeric jika Model menerima data tabel sebagai input. Nilai default-nya adalah numeric.

  • VIZUALIZATION_OPTIONS: Opsi untuk memvisualisasikan penjelasan. Untuk mempelajari cara mengisi kolom ini, baca Mengonfigurasi setelan visualisasi untuk data gambar.

    Jika Anda menghapus kolom modality atau menetapkan kolom modality ke numeric, hapus kolom visualization seluruhnya.

  • OUTPUT_NAME: Nama yang mudah diingat untuk output model Anda.
  • OUTPUT_TENSOR_NAME: Nama tensor output di TensorFlow. Untuk menemukan nilai yang benar untuk kolom ini, baca Menggunakan TensorFlow dengan Vertex Explainable AI.

Untuk mempelajari nilai yang sesuai untuk placeholder lainnya, lihat upload dan Mengimpor model.

Jika ingin, Anda dapat menambahkan baseline input ke ExplanationMetadata. Jika tidak, Vertex AI akan memilih baseline input untuk Model.

Jika ingin, Anda dapat menambahkan kolom untuk mengonfigurasi perkiraan SmoothGrad untuk gradien ke ExplanationParameters.

Untuk model TensorFlow 2, kolom metadata bersifat opsional. Jika dihilangkan, Vertex AI akan otomatis menginferensi inputs dan outputs dari model.

Metode HTTP dan URL: 

POST http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Isi JSON permintaan: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "integratedGradientsAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "MODALITY",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

XRAI

Bergantung pada alat yang ingin Anda gunakan untuk membuat atau mengimpor Model, pilih salah satu tab berikut:

Konsol

Ikuti panduan untuk mengimpor model menggunakan Konsol Google Cloud. Setelah sampai pada langkah Explainability, lakukan langkah berikut:

  1. Untuk metode atribusi fitur, pilih XRAI (for image classification models).

  2. Tetapkan opsi visualisasi berikut:

    1. Tetapkan Color map.

    2. Anda dapat mempertahankan Clip below, Clip above, Overlay type, dan Number of integral steps pada setelan default-nya.

      Pelajari setelan visualisasi lebih lanjut.

  3. Tetapkan jumlah langkah yang akan digunakan untuk memperkirakan integral jalur selama atribusi fitur. Nilai ini harus berupa bilangan bulat dalam rentang [1, 100].

    Nilai yang lebih tinggi dapat mengurangi error perkiraan, tetapi lebih intensif secara komputasi. Jika Anda tidak tahu nilai apa yang sebaiknya digunakan, coba 50.

  4. Konfigurasikan setiap fitur input dalam model Anda:

    1. Isikan nama fitur input Anda.

    2. Jika ingin, Anda dapat menambahkan satu atau beberapa baseline input. Jika tidak, Vertex Explainable AI akan memilih baseline input default dari nilai nol semua, yang merupakan gambar hitam untuk data gambar.

    3. Jika Anda mengimpor model TensorFlow, ada kolom input tambahan:

      1. Isi Input tensor name.

      2. Jika berlaku, isi Indices tensor name dan/atau Dense shape tensor name.

      3. Modality tidak dapat diperbarui di sini. Parameter ini otomatis ditetapkan ke NUMERIC untuk model tabel, atau IMAGE untuk model gambar.

      4. Jika berlaku, tetapkan kolom Encoding. Nilai default-nya adalah IDENTITY, jika tidak ditetapkan.

      5. Jika berlaku, tetapkan kolom Group name.

  5. Jika Anda mengimpor model TensorFlow, tentukan kolom output:

    1. Tetapkan Output name fitur Anda.
    2. Tetapkan Output tensor name fitur Anda.
    3. Jika berlaku, tetapkan Index display name mapping.
    4. Jika berlaku, tetapkan Display name mapping key.

  6. Klik tombol Import setelah selesai mengonfigurasi setelan explainability.

gcloud

  1. Untuk TensorFlow 2, ExplanationMetadata bersifat opsional.

    Tulis ExplanationMetadata berikut ke file JSON di lingkungan lokal Anda. Nama file tidak menjadi masalah, tetapi untuk contoh ini, panggil file explanation-metadata.json:

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "modality": "image",
      "visualization": VISUALIZATION_SETTINGS
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

    Ganti kode berikut:

    Jika ingin, Anda dapat menambahkan baseline input ke ExplanationMetadata. Jika tidak, Vertex AI akan memilih baseline input untuk Model.

  2. Jalankan perintah berikut untuk membuat resource Model yang mendukung Vertex Explainable AI. Flag yang paling relevan dengan Vertex Explainable AI akan disorot. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=xrai \
  --explanation-step-count=STEP_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Ganti kode berikut:

    Untuk mempelajari nilai yang sesuai untuk placeholder lainnya, lihat upload dan Mengimpor model.

    Jika ingin, Anda dapat menambahkan flag untuk mengonfigurasi perkiraan SmoothGrad untuk gradien.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

Untuk mempelajari nilai yang sesuai untuk placeholder lainnya, lihat upload dan Mengimpor model.

Jika ingin, Anda dapat menambahkan baseline input ke ExplanationMetadata. Jika tidak, Vertex AI akan memilih baseline input untuk Model.

Jika ingin, Anda dapat menambahkan kolom untuk mengonfigurasi perkiraan SmoothGrad untuk gradien ke ExplanationParameters.

Untuk model TensorFlow 2, kolom metadata bersifat opsional. Jika dihilangkan, Vertex AI akan otomatis menginferensi inputs dan outputs dari model.

Metode HTTP dan URL: 

POST http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Isi JSON permintaan: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "xraiAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "image",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Container bawaan scikit-learn dan XGBoost

Jika Model menerima data tabel sebagai input dan menyajikan prediksi menggunakan container bawaan scikit-learn atau XGBoost untuk prediksi, Anda dapat mengonfigurasinya agar menggunakan metode atribusi Sampled Shapley untuk penjelasan.

Bergantung pada alat yang ingin Anda gunakan untuk membuat atau mengimpor Model, pilih salah satu tab berikut:

Konsol

Ikuti panduan untuk mengimpor model menggunakan Konsol Google Cloud. Setelah sampai pada langkah Explainability, lakukan langkah berikut:

  1. Untuk metode atribusi fitur, pilih Sampled Shapely (for tabular models).

  2. Tetapkan jumlah jalur ke jumlah permutasi fitur yang akan digunakan untuk metode atribusi Sampled Shapley. Nilai ini harus berupa bilangan bulat dalam rentang [1, 50].

    Nilai yang lebih tinggi dapat mengurangi error perkiraan, tetapi lebih intensif secara komputasi. Jika Anda tidak tahu nilai apa yang sebaiknya digunakan, coba 25.

  3. Konfigurasikan setiap fitur input dalam model Anda:

    1. Isikan nama fitur input Anda.

      Jika artefak model Anda tidak mencantumkan nama fitur, Vertex AI tidak akan dapat memetakan nama fitur input yang ditentukan ke model. Dalam hal ini, sebaiknya Anda hanya memberikan satu fitur input dengan sembarang nama yang mudah diingat, seperti input_features. Dalam respons penjelasan, Anda akan mendapatkan daftar atribusi dimensi N, di mana N adalah jumlah fitur dalam model, dan elemen dalam daftar ditampilkan dengan urutan yang sama seperti set data pelatihan.

    2. Jika ingin, Anda dapat menambahkan satu atau beberapa baseline input. Jika tidak, Vertex Explainable AI akan memilih baseline input default dari nilai nol semua, yang merupakan gambar hitam untuk data gambar.

  4. Tetapkan Output name fitur Anda.

  5. Klik tombol Import setelah selesai mengonfigurasi setelan explainability.

gcloud

  1. Tulis ExplanationMetadata berikut ke file JSON di lingkungan lokal Anda. Nama file tidak menjadi masalah, tetapi untuk contoh ini, panggil file explanation-metadata.json:

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
    }
  }
}

    Ganti kode berikut:

    • FEATURE_NAME: Nama yang mudah diingat untuk fitur input Anda.
    • OUTPUT_NAME: Nama yang mudah diingat untuk output model Anda.

    Jika Anda menentukan baseline input, pastikan baseline tersebut cocok dengan input model Anda, yang biasanya berupa daftar matriks 2-D. Jika tidak, nilai default untuk baseline input adalah matriks 2-D nilai 0 dari bentuk input.

  2. Jalankan perintah berikut untuk membuat resource Model yang mendukung Vertex Explainable AI. Flag yang paling relevan dengan Vertex Explainable AI akan disorot. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Ganti kode berikut:

    Untuk mempelajari nilai yang sesuai untuk placeholder lainnya, lihat upload dan Mengimpor model.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • IMAGE_URI: URI container bawaan untuk menyajikan prediksi.

  • PATH_COUNT: Jumlah permutasi fitur yang akan digunakan untuk metode atribusi Sampled Shapley. Harus berupa bilangan bulat dalam rentang [1, 50].

    Nilai yang lebih tinggi dapat mengurangi error perkiraan, tetapi lebih intensif secara komputasi. Jika Anda tidak tahu nilai apa yang sebaiknya digunakan, coba 25.

  • FEATURE_NAME: Nama yang mudah diingat untuk fitur input Anda.
  • OUTPUT_NAME: Nama yang mudah diingat untuk output model Anda.

Untuk mempelajari nilai yang sesuai untuk placeholder lainnya, lihat upload dan Mengimpor model.

Jika Anda menentukan baseline input, pastikan baseline tersebut cocok dengan input model Anda, yang biasanya berupa daftar matriks 2-D. Jika tidak, nilai default untuk baseline input adalah matriks 2-D nilai 0 dari bentuk input.

Metode HTTP dan URL: 

POST http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Isi JSON permintaan: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {
         }
       },
       "outputs": {
         "OUTPUT_NAME": {
         }
       }
    }
  }
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Container kustom

Jika Model menerima data tabel sebagai input dan menyajikan prediksi menggunakan container kustom, Anda dapat mengonfigurasinya agar menggunakan metode atribusi Sampled Shapley untuk penjelasan.

Menentukan nama fitur dan output

Pada langkah-langkah berikut, Anda harus memberi Vertex AI nama fitur yang diharapkan Model sebagai input. Anda juga harus menentukan kunci yang digunakan untuk output dalam prediksi Model.

Menentukan nama fitur

Jika Model mengharapkan setiap instance input memiliki kunci level teratas tertentu, kunci tersebut akan menjadi nama fitur Anda.

Misalnya, pertimbangkan Model yang mengharapkan setiap instance input memiliki format berikut:

{
  "length": <value>,
  "width": <value>
}

Dalam hal ini, nama fitur adalah length dan width. Meskipun nilai kolom ini berisi daftar atau objek bertingkat, length dan width adalah satu-satunya kunci yang Anda perlukan untuk langkah-langkah berikut. Saat Anda meminta penjelasan, Vertex Explainable AI akan menyediakan atribusi untuk setiap elemen bertingkat fitur Anda.

Jika Model Anda mengharapkan input tanpa kunci, Vertex Explainable AI akan menganggap Model memiliki satu fitur. Anda dapat menggunakan string apa pun yang mudah diingat untuk nama fitur.

Misalnya, pertimbangkan Model yang mengharapkan setiap instance input memiliki format berikut:

[
  <value>,
  <value>
]

Dalam hal ini, berikan satu nama fitur pilihan Anda kepada Vertex Explainable AI, misalnya dimensions.

Menentukan nama output

Jika Model menampilkan setiap instance prediksi online dengan output yang disertai kunci, kunci tersebut akan menjadi nama output Anda.

Misalnya, pertimbangkan Model yang menampilkan setiap prediksi dalam format berikut:

{
  "scores": <value>
}

Dalam hal ini, nama output adalah scores. Jika nilai kolom scores berupa array, saat Anda mendapatkan penjelasan, Vertex Explainable AI akan menampilkan atribusi fitur untuk elemen dengan nilai tertinggi di setiap prediksi. Untuk mengonfigurasi Vertex Explainable AI agar memberikan atribusi fitur untuk elemen lainnya di kolom output, Anda dapat menentukan kolom topK atau outputIndices dari ExplanationParameters. Namun, contoh dalam dokumen ini tidak menunjukkan opsi tersebut.

Jika Model menampilkan prediksi tanpa disertai kunci, Anda dapat menggunakan string yang mudah diingat untuk nama output. Misalnya, hal ini berlaku jika Model menampilkan array atau skala untuk setiap prediksi.

Membuat Model

Bergantung pada alat yang ingin Anda gunakan untuk membuat atau mengimpor Model, pilih salah satu tab berikut:

Konsol

Ikuti panduan untuk mengimpor model menggunakan Konsol Google Cloud. Setelah sampai pada langkah Explainability, lakukan langkah berikut:

  1. Untuk metode atribusi fitur, pilih Sampled Shapely (for tabular models).

  2. Tetapkan jumlah jalur ke jumlah permutasi fitur yang akan digunakan untuk metode atribusi Sampled Shapley. Nilai ini harus berupa bilangan bulat dalam rentang [1, 50].

    Nilai yang lebih tinggi dapat mengurangi error perkiraan, tetapi lebih intensif secara komputasi. Jika Anda tidak tahu nilai apa yang sebaiknya digunakan, coba 25.

  3. Konfigurasikan setiap fitur input dalam model Anda:

    1. Isikan nama fitur input Anda.

      Jika artefak model Anda tidak mencantumkan nama fitur, Vertex AI tidak akan dapat memetakan nama fitur input yang ditentukan ke model. Dalam hal ini, sebaiknya Anda hanya memberikan satu fitur input dengan sembarang nama yang mudah diingat, seperti input_features. Dalam respons penjelasan, Anda akan mendapatkan daftar atribusi dimensi N, di mana N adalah jumlah fitur dalam model, dan elemen dalam daftar ditampilkan dengan urutan yang sama seperti set data pelatihan.

    2. Jika ingin, Anda dapat menambahkan satu atau beberapa baseline input. Jika tidak, Vertex Explainable AI akan memilih baseline input default dari nilai nol semua, yang merupakan gambar hitam untuk data gambar.

  4. Tetapkan Output name fitur Anda.

  5. Klik tombol Import setelah selesai mengonfigurasi setelan explainability.

gcloud

  1. Tulis ExplanationMetadata berikut ke file JSON di lingkungan lokal Anda. Nama file tidak menjadi masalah, tetapi untuk contoh ini, panggil file explanation-metadata.json:

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {}
  },
  "outputs": {
    "OUTPUT_NAME": {}
  }
}

    Ganti kode berikut:

    • FEATURE_NAME: Nama fitur, seperti yang dijelaskan di bagian "Menentukan nama fitur" pada dokumen ini.
    • OUTPUT_NAME: Nama output, seperti yang dijelaskan di bagian "Menentukan nama output" dalam dokumen ini.

    Jika ingin, Anda dapat menambahkan baseline input ke ExplanationMetadata. Jika tidak, Vertex AI akan memilih baseline input untuk Model.

    Jika Anda menentukan baseline input, pastikan baseline tersebut cocok dengan input model Anda, yang biasanya berupa daftar matriks 2-D. Jika tidak, nilai default untuk baseline input adalah matriks 2-D nilai 0 dari bentuk input.

  2. Jalankan perintah berikut untuk membuat resource Model yang mendukung Vertex Explainable AI. Flag yang paling relevan dengan Vertex Explainable AI akan disorot. 

    gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
  --explanation-method=sampled-shapley \
  --explanation-path-count=PATH_COUNT \
  --explanation-metadata-file=explanation-metadata.json

    Ganti kode berikut:

    • PATH_COUNT: Jumlah permutasi fitur yang akan digunakan untuk metode atribusi Sampled Shapley. Harus berupa bilangan bulat dalam rentang [1, 50].

      Nilai yang lebih tinggi dapat mengurangi error perkiraan, tetapi lebih intensif secara komputasi. Jika Anda tidak tahu nilai apa yang sebaiknya digunakan, coba 25.

    Untuk mempelajari nilai yang sesuai untuk placeholder lainnya, lihat upload dan Mengimpor model.

REST

Sebelum menggunakan data permintaan mana pun, lakukan penggantian berikut:

  • PATH_COUNT: Jumlah permutasi fitur yang akan digunakan untuk metode atribusi Sampled Shapley. Harus berupa bilangan bulat dalam rentang [1, 50].

    Nilai yang lebih tinggi dapat mengurangi error perkiraan, tetapi lebih intensif secara komputasi. Jika Anda tidak tahu nilai apa yang sebaiknya digunakan, coba 25.

  • FEATURE_NAME: Nama fitur, seperti yang dijelaskan di bagian "Menentukan nama fitur" pada dokumen ini.
  • OUTPUT_NAME: Nama output, seperti yang dijelaskan di bagian "Menentukan nama output" dalam dokumen ini.

Untuk mempelajari nilai yang sesuai untuk placeholder lainnya, lihat upload dan Mengimpor model.

Jika ingin, Anda dapat menambahkan baseline input ke ExplanationMetadata. Jika tidak, Vertex AI akan memilih baseline input untuk Model.

Metode HTTP dan URL: 

POST http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Isi JSON permintaan: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {}
       },
       "outputs": {
         "OUTPUT_NAME": {}
       }
    }
  }
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Langkah selanjutnya