Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Penjelasan online dengan Clarify SageMaker Panduan ini menunjukkan cara mengonfigurasi penjelasan online dengan SageMaker Clarify. Dengan titik akhir [inferensi real-time SageMaker ](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints.html) AI, Anda dapat menganalisis penjelasan secara real time, terus menerus. Fungsi penjelasan online cocok dengan bagian **Deploy to production** dari alur kerja [Amazon AI Machine SageMaker Learning](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-mlconcepts.html). ## Bagaimana Klarifikasi Penjelasan Online Bekerja Grafik berikut menggambarkan arsitektur SageMaker AI untuk menghosting titik akhir yang melayani permintaan penjelasan. Ini menggambarkan interaksi antara titik akhir, wadah model, dan SageMaker penjelasan Clarify. ![\[SageMaker Arsitektur AI menunjukkan hosting titik akhir yang melayani permintaan penjelasan sesuai permintaan.\]](http://docs.aws.amazon.com/id_id/sagemaker/latest/dg/images/clarify/DeveloperGuideArchitecture.png) Inilah cara kerja Clarify online explainability. Aplikasi mengirimkan `InvokeEndpoint` permintaan gaya REST ke SageMaker AI Runtime Service. Layanan merutekan permintaan ini ke titik akhir SageMaker AI untuk mendapatkan prediksi dan penjelasan. Kemudian, layanan menerima respons dari titik akhir. Terakhir, layanan mengirimkan respons kembali ke aplikasi. Untuk meningkatkan ketersediaan titik akhir, SageMaker AI secara otomatis mencoba mendistribusikan instance titik akhir di beberapa Availability Zone, sesuai dengan jumlah instans dalam konfigurasi titik akhir. Pada instance titik akhir, atas permintaan penjelasan baru, penjelasan SageMaker Clarify memanggil wadah model untuk prediksi. Kemudian menghitung dan mengembalikan atribusi fitur. Berikut adalah empat langkah untuk membuat endpoint yang menggunakan SageMaker Clarify online explainability: 1. [Periksa apakah model SageMaker AI pra-terlatih Anda kompatibel dengan penjelasan online dengan mengikuti langkah-langkah pra-pemeriksaan.](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-online-explainability-precheck.html) 1. [Buat konfigurasi endpoint dengan konfigurasi](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpointConfig.html) SageMaker Clarify explainer menggunakan API. `CreateEndpointConfig` 1. [Buat titik akhir](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html) dan berikan konfigurasi titik akhir ke SageMaker AI menggunakan API. `CreateEndpoint` Layanan meluncurkan instance komputasi ML dan menerapkan model seperti yang ditentukan dalam konfigurasi. 1. [Panggil titik akhir: Setelah titik](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) akhir dalam layanan, panggil SageMaker AI Runtime API `InvokeEndpoint` untuk mengirim permintaan ke titik akhir. Titik akhir kemudian mengembalikan penjelasan dan prediksi. # Pra-periksa wadah model Bagian ini menunjukkan cara memeriksa terlebih dahulu input dan output wadah model untuk kompatibilitas sebelum mengonfigurasi titik akhir. SageMaker Penjelasan Clarify adalah **model agnostik**, tetapi memiliki persyaratan untuk input dan output wadah model. **catatan** Anda dapat meningkatkan efisiensi dengan mengonfigurasi penampung Anda untuk mendukung permintaan batch, yang mendukung dua atau lebih catatan dalam satu permintaan. Misalnya, catatan tunggal adalah satu baris data CSV, atau satu baris data JSON Lines. SageMaker Clarify akan mencoba mengirim kumpulan catatan mini ke wadah model terlebih dahulu sebelum kembali ke permintaan rekaman tunggal. ## Masukan wadah model ------ #### [ CSV ] Wadah model mendukung input dalam CSV dengan tipe MIME:. `text/csv` Tabel berikut menunjukkan contoh input yang mendukung SageMaker Clarify. | Masukan wadah model (representasi string) | Komentar | | --- | --- | | '1,2,3,4' | Rekaman tunggal yang menggunakan empat fitur numerik. | | '1,2,3,4\$1n5,6,7,8' | Dua catatan, dipisahkan oleh jeda baris '\$1n'. | | “Ini adalah produk yang bagus”, 5' | Rekaman tunggal yang berisi fitur teks dan fitur numerik. | | '"Ini adalah produk yang bagus” ,5\$1n“Pengalaman belanja yang buruk”, 1 ' | Dua catatan. | ------ #### [ JSON Lines ] SageMaker AI juga mendukung input dalam [format padat JSON Lines](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html#cm-jsonlines) dengan tipe MIME:`application/jsonlines`, seperti yang ditunjukkan pada tabel berikut. | Masukan wadah model | Komentar | | --- | --- | | '\$1"data”: \$1"features”: [1,2,3,4]\$1\$1' | Rekaman tunggal; daftar fitur dapat diekstraksi dengan JMESPath ekspresi`data.features`. | | '\$1"data”: \$1"features”: [1,2,3,4]\$1\$1\$1n\$1"data”: \$1"features”: [5,6,7,8]\$1\$1' | Dua catatan. | | '\$1"features”: ["Ini adalah produk yang bagus” ,5]\$1' | Rekaman tunggal; daftar fitur dapat diekstraksi dengan JMESPath ekspresi`features`. | | '\$1"features”: ["Ini adalah produk yang bagus” ,5]\$1\$1n\$1"features”: ["Pengalaman belanja yang buruk” ,1]\$1' | Dua catatan. | ------ ## Output wadah model Output wadah model Anda juga harus dalam format padat CSV, atau JSON Lines. Selain itu wadah model harus menyertakan probabilitas catatan input, yang digunakan SageMaker Clarify untuk menghitung atribusi fitur. Contoh data berikut adalah untuk output wadah model dalam **format CSV**. ------ #### [ Probability only ] Untuk masalah regresi dan klasifikasi biner, wadah model mengeluarkan nilai probabilitas tunggal (skor) dari label yang diprediksi. Probabilitas ini dapat diekstraksi menggunakan indeks kolom 0. Untuk masalah multi-kelas, wadah model mengeluarkan daftar probabilitas (skor). Untuk masalah multi-kelas, jika tidak ada indeks yang disediakan, semua nilai diekstraksi. | Masukan wadah model | Output wadah model (representasi string) | | --- | --- | | Rekaman tunggal | '0,6' | | Dua catatan (hasil dalam satu baris) | '0,6,0,3' | | Dua catatan (menghasilkan dua baris) | '0,6\$1n0,3' | | Rekaman tunggal model multi-kelas (tiga kelas) | '0.1,0.6,0.3' | | Dua catatan model multi-kelas (tiga kelas) | '0.1,0.6,0.3\$1n0.2,0.5,0.3' | ------ #### [ Predicted label and probabilities ] Wadah model mengeluarkan label yang diprediksi diikuti oleh probabilitasnya dalam **format CSV**. Probabilitas dapat diekstraksi menggunakan indeks. `1` | Masukan wadah model | Output wadah model | | --- | --- | | Rekaman tunggal | '1,0.6' | | Dua catatan | '1,0.6\$1n0,0.3' | ------ #### [ Predicted labels header and probabilities ] **Wadah model multi-kelas yang dilatih oleh Autopilot dapat dikonfigurasi untuk menampilkan **representasi string** dari daftar label dan probabilitas yang diprediksi dalam format CSV.** Dalam contoh berikut, probabilitas dapat diekstraksi dengan indeks. `1` Header label dapat diekstraksi dengan indeks`1`, dan header label dapat diekstraksi menggunakan indeks. `0` | Masukan wadah model | Output wadah model | | --- | --- | | Rekaman tunggal | '"[\$1 'cat\$1',\$1 'dog\$1 ',\$1 'ikan\$1']”, "[0.1,0.6,0.3]" ' | | Dua catatan | '"[\$1 'cat\$1',\$1 'dog\$1 ',\$1 'ikan\$1']”, "[0.1,0.6,0.3]”\$1n“[\$1 'cat\$1 ',\$1 'dog\$1',\$1 'ikan\$1 ']”, "[0.2,0.5,0.3]"' | ------ Contoh data berikut adalah untuk output wadah model dalam format **JSON Lines**. ------ #### [ Probability only ] Dalam contoh ini, wadah model mengeluarkan probabilitas yang dapat diekstraksi dengan [https://jmespath.org/](https://jmespath.org/)ekspresi `score` dalam format **JSON** Lines. | Masukan wadah model | Output wadah model | | --- | --- | | Rekaman tunggal | '\$1"skor” :0.6\$1' | | Dua catatan | '\$1"score” :0.6\$1\$1n\$1"skor” :0.3\$1' | ------ #### [ Predicted label and probabilities ] **Dalam contoh ini, wadah model multi-kelas mengeluarkan daftar header label bersama dengan daftar probabilitas dalam format JSON Lines.** Probabilitas dapat diekstraksi dengan `JMESPath` ekspresi`probability`, dan header label dapat diekstraksi dengan ekspresi. `JMESPath` `predicted labels` | Masukan wadah model | Output wadah model | | --- | --- | | Rekaman tunggal | '\$1"predicted\$1labels”: ["cat”, "dog”, "fish "], "probabilities”: [0.1,0.6,0.3]\$1' | | Dua catatan | '\$1"predicted\$1labels”: ["cat”, "dog”, "fish "], "probabilities”: [0.1,0.6,0.3]\$1\$1n\$1"predicted\$1labels”: ["cat”, "dog”, "fish "], "probabilities”: [0.2,0.5,0.3]\$1' | ------ #### [ Predicted labels header and probabilities ] **Dalam contoh ini, wadah model multi-kelas mengeluarkan daftar header label dan probabilitas dalam format JSON Lines.** Probabilitas dapat diekstraksi dengan `JMESPath` ekspresi`probability`, dan header label dapat diekstraksi dengan ekspresi. `JMESPath` `predicted labels` | Masukan wadah model | Output wadah model | | --- | --- | | Rekaman tunggal | '\$1"predicted\$1labels”: ["cat”, "dog”, "fish "], "probabilities”: [0.1,0.6,0.3]\$1' | | Dua catatan | '\$1"predicted\$1labels”: ["cat”, "dog”, "fish "], "probabilities”: [0.1,0.6,0.3]\$1\$1n\$1"predicted\$1labels”: ["cat”, "dog”, "fish "], "probabilities”: [0.2,0.5,0.3]\$1' | ------ ## Validasi wadah model Kami menyarankan Anda menerapkan model Anda ke titik akhir inferensi real-time SageMaker AI, dan mengirim permintaan ke titik akhir. Periksa permintaan (input kontainer model) dan respons (keluaran wadah model) secara manual untuk memastikan bahwa keduanya sesuai dengan persyaratan di bagian Input **Penampung Model dan bagian Output** **Penampung Model**. Jika wadah model Anda mendukung permintaan batch, Anda dapat memulai dengan satu permintaan rekaman, lalu mencoba dua atau lebih catatan. Perintah berikut menunjukkan cara meminta respons menggunakan AWS CLI. AWS CLI Ini sudah diinstal sebelumnya di SageMaker Studio Classic, dan instance SageMaker Notebook. Jika Anda perlu menginstal AWS CLI, ikuti [panduan instalasi](https://aws.amazon.com/cli/) ini. ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name $ENDPOINT_NAME \ --content-type $CONTENT_TYPE \ --accept $ACCEPT_TYPE \ --body $REQUEST_DATA \ $CLI_BINARY_FORMAT \ /dev/stderr 1>/dev/null ``` Parameter didefinisikan, sebagai berikut: + `$ENDPOINT NAME`: Nama titik akhir. + `$CONTENT_TYPE`: Jenis permintaan MIME (input wadah model). + `$ACCEPT_TYPE`: Jenis respons MIME (keluaran wadah model). + `$REQUEST_DATA`: String payload yang diminta. + `$CLI_BINARY_FORMAT`: Format parameter antarmuka baris perintah (CLI). Untuk AWS CLI v1, parameter ini harus tetap kosong. Untuk v2, parameter ini harus diatur ke`--cli-binary-format raw-in-base64-out`. **catatan** AWS CLI [v2 melewati parameter biner sebagai string yang dikodekan base64 default.](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html#cliv2-migration-binaryparam) Contoh berikut menggunakan AWS CLI v1: ------ #### [ Request and response in CSV format ] + Permintaan terdiri dari satu catatan dan responsnya adalah nilai probabilitasnya. ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-sagemaker-xgboost-model \ --content-type text/csv \ --accept text/csv \ --body '1,2,3,4' \ /dev/stderr 1>/dev/null ``` Output: `0.6` + Permintaan terdiri dari dua catatan, dan responsnya mencakup probabilitasnya, dan model memisahkan probabilitas dengan koma. `$'content'`Ekspresi dalam `--body` memberitahu perintah untuk menafsirkan `\n` dalam konten sebagai jeda baris. ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-sagemaker-xgboost-model \ --content-type text/csv \ --accept text/csv \ --body $'1,2,3,4\n5,6,7,8' \ /dev/stderr 1>/dev/null ``` Output: `0.6,0.3` + Permintaan terdiri dari dua catatan, respons mencakup probabilitasnya, dan model memisahkan probabilitas dengan jeda baris. ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-csv-1 \ --content-type text/csv \ --accept text/csv \ --body $'1,2,3,4\n5,6,7,8' \ /dev/stderr 1>/dev/null ``` Output: `0.6` `0.3` + Permintaan terdiri dari satu catatan, dan responsnya adalah nilai probabilitas (model multi-kelas, tiga kelas). ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-csv-1 \ --content-type text/csv \ --accept text/csv \ --body '1,2,3,4' \ /dev/stderr 1>/dev/null ``` Output: `0.1,0.6,0.3` + Permintaan terdiri dari dua catatan, dan responsnya mencakup nilai probabilitasnya (model multi-kelas, tiga kelas). ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-csv-1 \ --content-type text/csv \ --accept text/csv \ --body $'1,2,3,4\n5,6,7,8' \ /dev/stderr 1>/dev/null ``` Output: `0.1,0.6,0.3` `0.2,0.5,0.3` + Permintaan terdiri dari dua catatan, dan responsnya mencakup label dan probabilitas yang diprediksi. ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-csv-2 \ --content-type text/csv \ --accept text/csv \ --body $'1,2,3,4\n5,6,7,8' \ /dev/stderr 1>/dev/null ``` Output: `1,0.6` `0,0.3` + Permintaan terdiri dari dua catatan dan responsnya mencakup header label dan probabilitas. ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-csv-3 \ --content-type text/csv \ --accept text/csv \ --body $'1,2,3,4\n5,6,7,8' \ /dev/stderr 1>/dev/null ``` Output: `"['cat','dog','fish']","[0.1,0.6,0.3]"` `"['cat','dog','fish']","[0.2,0.5,0.3]"` ------ #### [ Request and response in JSON Lines format ] + Permintaan terdiri dari satu catatan dan responsnya adalah nilai probabilitasnya. ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-jsonlines \ --content-type application/jsonlines \ --accept application/jsonlines \ --body '{"features":["This is a good product",5]}' \ /dev/stderr 1>/dev/null ``` Output: `{"score":0.6}` + Permintaan berisi dua catatan, dan responsnya mencakup label dan probabilitas yang diprediksi. ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-jsonlines-2 \ --content-type application/jsonlines \ --accept application/jsonlines \ --body $'{"features":[1,2,3,4]}\n{"features":[5,6,7,8]}' \ /dev/stderr 1>/dev/null ``` Output: `{"predicted_label":1,"probability":0.6}` `{"predicted_label":0,"probability":0.3}` + Permintaan berisi dua catatan dan responsnya mencakup header label dan probabilitas. ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-jsonlines-3 \ --content-type application/jsonlines \ --accept application/jsonlines \ --body $'{"data":{"features":[1,2,3,4]}}\n{"data":{"features":[5,6,7,8]}}' \ /dev/stderr 1>/dev/null ``` Output: `{"predicted_labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]}` `{"predicted_labels":["cat","dog","fish"],"probabilities":[0.2,0.5,0.3]}` ------ #### [ Request and response in different formats ] + Permintaan dalam format CSV dan responsnya dalam format JSON Lines: ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-csv-in-jsonlines-out \ --content-type text/csv \ --accept application/jsonlines \ --body $'1,2,3,4\n5,6,7,8' \ /dev/stderr 1>/dev/null ``` Output: `{"probability":0.6}` `{"probability":0.3}` + Permintaan dalam format JSON Lines dan responsnya dalam format CSV: ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name test-endpoint-jsonlines-in-csv-out \ --content-type application/jsonlines \ --accept text/csv \ --body $'{"features":[1,2,3,4]}\n{"features":[5,6,7,8]}' \ /dev/stderr 1>/dev/null ``` Output: `0.6` `0.3` ------ Setelah validasi selesai, [hapus titik akhir](https://docs.aws.amazon.com/sagemaker/latest/dg/realtime-endpoints-delete-resources.html) pengujian. # Konfigurasikan dan buat titik akhir Buat konfigurasi titik akhir baru agar sesuai dengan model Anda, dan gunakan konfigurasi ini untuk membuat titik akhir. Anda dapat menggunakan wadah model yang divalidasi pada [langkah pra-pemeriksaan](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-online-explainability-precheck.html) untuk membuat titik akhir dan mengaktifkan fitur SageMaker Clarify online explainability. Gunakan `sagemaker_client` objek untuk membuat titik akhir menggunakan [CreateEndpointConfig](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_CreateEndpointConfig.html)API. Atur anggota `ClarifyExplainerConfig` di dalam `ExplainerConfig` parameter sebagai berikut: ``` sagemaker_client.create_endpoint_config( EndpointConfigName='name-of-your-endpoint-config', ExplainerConfig={ 'ClarifyExplainerConfig': { 'EnableExplanations': '`true`', 'InferenceConfig': { ... }, 'ShapConfig': { ... } }, }, ProductionVariants=[{ 'VariantName': 'AllTraffic', 'ModelName': 'name-of-your-model', 'InitialInstanceCount': 1, 'InstanceType': 'ml.m5.xlarge', }] ... ) sagemaker_client.create_endpoint( EndpointName='name-of-your-endpoint', EndpointConfigName='name-of-your-endpoint-config' ) ``` Panggilan pertama ke `sagemaker_client` objek membuat konfigurasi titik akhir baru dengan fitur penjelasan diaktifkan. Panggilan kedua menggunakan konfigurasi titik akhir untuk meluncurkan titik akhir. **catatan** Anda juga dapat meng-host beberapa model dalam satu wadah di belakang [titik akhir multi-model inferensi real-time SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg/multi-model-endpoints.html) dan mengonfigurasi penjelasan online dengan Clarify. SageMaker # `EnableExplanations`Ekspresi `EnableExplanations`Parameternya adalah string ekspresi [https://jmespath.org/](https://jmespath.org/)Boolean. Ini dievaluasi untuk **setiap catatan** dalam permintaan penjelasan. Jika parameter ini dievaluasi menjadi **benar**, maka catatan akan dijelaskan. Jika parameter ini dievaluasi **salah**, maka penjelasan tidak akan dihasilkan. SageMaker Klarifikasi deserialisasi output wadah model untuk setiap catatan ke dalam struktur data yang kompatibel dengan JSON, dan kemudian menggunakan `EnableExplanations` parameter untuk mengevaluasi data. **Catatan** Ada dua opsi untuk catatan tergantung pada format output wadah model. Jika keluaran wadah model dalam format CSV, maka catatan dimuat sebagai array JSON. Jika keluaran wadah model dalam format JSON Lines, maka catatan dimuat sebagai objek JSON. `EnableExplanations`Parameter adalah JMESPath ekspresi yang dapat diteruskan baik selama `InvokeEndpoint` atau `CreateEndpointConfig` operasi. Jika JMESPath ekspresi yang Anda berikan tidak valid, pembuatan endpoint akan gagal. Jika ekspresi valid, tetapi hasil evaluasi ekspresi tidak terduga, maka titik akhir akan berhasil dibuat, tetapi kesalahan akan dihasilkan ketika titik akhir dipanggil. Uji `EnableExplanations` ekspresi Anda dengan menggunakan `InvokeEndpoint` API, lalu terapkan ke konfigurasi titik akhir. Berikut ini adalah beberapa contoh `EnableExplanations` ekspresi yang valid. Dalam contoh, JMESPath ekspresi melampirkan literal menggunakan karakter backtick. Misalnya, ``true`` berarti benar. | Ekspresi (representasi string) | Output wadah model (representasi string) | Hasil evaluasi (Boolean) | Arti | | --- | --- | --- | --- | | '`benar`' | (N/A) | True | Aktifkan penjelasan online tanpa syarat. | | '`salah`' | (N/A) | False | Nonaktifkan penjelasan online tanpa syarat. | | '[1] >`0.5`' | '1,0.6' | True | Untuk setiap catatan, wadah model mengeluarkan label dan probabilitas yang diprediksi. Menjelaskan catatan jika probabilitasnya (pada indeks 1) lebih besar dari 0,5. | | 'probabilitas>`0,5 `' | '\$1"predicted\$1label” :1, "probabilitas” :0.6\$1' | True | Untuk setiap catatan, wadah model mengeluarkan data JSON. Jelaskan catatan jika probabilitasnya lebih besar dari 0,5. | | '\$1 berisi (probabilitas [:-1], maks (probabilitas)) ' | '\$1"probabilities”: [0.4, 0.1, 0.4], “labels”: ["cat”, "dog”, "fish "]\$1' | False | Untuk model multi-kelas: Menjelaskan catatan jika label yang diprediksi (kelas yang memiliki nilai probabilitas maks) adalah kelas terakhir. Secara harfiah, ekspresi berarti bahwa nilai probabilitas maks tidak ada dalam daftar probabilitas tidak termasuk yang terakhir. | # Dataset sintetis SageMaker Clarify menggunakan algoritma Kernel SHAP. Diberikan catatan (juga disebut sampel atau instance) dan konfigurasi SHAP, penjelasan pertama-tama menghasilkan kumpulan data sintetis. SageMaker Klarifikasi kemudian kueri wadah model untuk prediksi kumpulan data, lalu hitung dan kembalikan atribusi fitur. Ukuran kumpulan data sintetis memengaruhi runtime untuk penjelasan Clarify. Kumpulan data sintetis yang lebih besar membutuhkan lebih banyak waktu untuk mendapatkan prediksi model daripada yang lebih kecil. Ukuran dataset sintetis ditentukan oleh rumus berikut: ``` Synthetic dataset size = SHAP baseline size * n_samples ``` Ukuran dasar SHAP adalah jumlah catatan dalam data dasar SHAP. Informasi ini diambil dari`ShapBaselineConfig`. Ukuran `n_samples` diatur oleh parameter `NumberOfSamples` dalam konfigurasi explainer dan jumlah fitur. Jika jumlah fitur adalah`n_features`, maka `n_samples` adalah sebagai berikut: ``` n_samples = MIN(NumberOfSamples, 2^n_features - 2) ``` Berikut ini menunjukkan `n_samples` jika `NumberOfSamples` tidak disediakan. ``` n_samples = MIN(2*n_features + 2^11, 2^n_features - 2) ``` Misalnya, catatan tabular dengan 10 fitur memiliki ukuran dasar SHAP 1. Jika tidak `NumberOfSamples` disediakan, dataset sintetis berisi 1022 catatan. Jika catatan memiliki 20 fitur, dataset sintetis berisi 2088 catatan. Untuk masalah NLP, `n_features` sama dengan jumlah fitur non-teks ditambah jumlah unit teks. **catatan** `InvokeEndpoint`API memiliki batas waktu tunggu permintaan. Jika kumpulan data sintetis terlalu besar, penjelasan mungkin tidak dapat menyelesaikan perhitungan dalam batas ini. Jika perlu, gunakan informasi sebelumnya untuk memahami dan mengurangi ukuran dasar SHAP dan. `NumberOfSamples` Jika wadah model Anda diatur untuk menangani permintaan batch, maka Anda juga dapat menyesuaikan nilai`MaxRecordCount`. # Memanggil titik akhir Setelah titik akhir berjalan, gunakan SageMaker AI Runtime [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html)API di layanan SageMaker AI Runtime untuk mengirim permintaan ke, atau memanggil titik akhir. Sebagai tanggapan, permintaan ditangani sebagai permintaan penjelasan oleh Clarify explainer. SageMaker **catatan** Untuk memanggil titik akhir, pilih salah satu opsi berikut: Untuk petunjuk menggunakan Boto3 atau AWS CLI untuk memanggil titik akhir, lihat. [Memanggil model untuk inferensi waktu nyata](realtime-endpoints-test-endpoints.md) [Untuk menggunakan SageMaker SDK for Python untuk menjalankan endpoint, lihat Predictor API.](https://sagemaker.readthedocs.io/en/stable/api/inference/predictors.html) ## Permintaan `InvokeEndpoint`API memiliki parameter opsional`EnableExplanations`, yang dipetakan ke header `X-Amzn-SageMaker-Enable-Explanations` HTTP. Jika parameter ini disediakan, itu mengesampingkan `EnableExplanations` parameter. `ClarifyExplainerConfig` **catatan** `Accept`Parameter `ContentType` dan `InvokeEndpoint` API diperlukan. Format yang didukung termasuk tipe MIME `text/csv` dan`application/jsonlines`. Gunakan `sagemaker_runtime_client` untuk mengirim permintaan ke titik akhir, sebagai berikut: ``` response = sagemaker_runtime_client.invoke_endpoint( EndpointName='name-of-your-endpoint', EnableExplanations='`true`', ContentType='text/csv', Accept='text/csv', Body='1,2,3,4', # single record (of four numerical features) ) ``` Untuk titik akhir multi-model, berikan `TargetModel` parameter tambahan dalam permintaan contoh sebelumnya untuk menentukan model mana yang akan ditargetkan pada titik akhir. Titik akhir multi-model secara dinamis memuat model target sesuai kebutuhan. Untuk informasi selengkapnya tentang titik akhir multi-model, lihat. [Titik akhir multi-model](multi-model-endpoints.md) Lihat [SageMaker Clarify Online Explainability on Multi-Model Endpoint Sample Notebook](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/tabular_multi_model_endpoint/multi_model_xgboost_with_online_explainability.ipynb) untuk contoh cara menyiapkan dan memanggil beberapa model target dari satu titik akhir. ## Respons Jika titik akhir dibuat dengan`ExplainerConfig`, maka skema respons baru digunakan, Skema baru ini berbeda dari, dan tidak kompatibel dengan, titik akhir yang tidak memiliki parameter yang disediakan. `ExplainerConfig` Jenis respons MIME adalah`application/json`, dan payload respons dapat diterjemahkan dari UTF-8 byte ke objek JSON. Berikut ini menunjukkan anggota objek JSON ini adalah sebagai berikut: + `version`: Versi skema respons dalam format string. Misalnya, `1.0`. + `predictions`: Prediksi yang dibuat permintaan memiliki yang berikut: + `content_type`: Jenis prediksi MIME, mengacu pada respons `ContentType` wadah model. + `data`: String data prediksi dikirimkan sebagai muatan respons wadah model untuk permintaan tersebut. + `label_headers`: Header label dari `LabelHeaders` parameter. Ini disediakan baik dalam konfigurasi explainer atau output wadah model. + `explanations`: Penjelasan yang diberikan dalam payload permintaan. Jika tidak ada catatan yang dijelaskan, maka anggota ini mengembalikan objek kosong`{}`. + + `kernel_shap`: Kunci yang mengacu pada array penjelasan Kernel SHAP untuk setiap catatan dalam permintaan. Jika catatan tidak dijelaskan, penjelasan yang sesuai adalah`null`. `kernel_shap`Elemen memiliki anggota berikut: + `feature_header`: Nama header dari fitur yang disediakan oleh `FeatureHeaders` parameter dalam konfigurasi `ExplainerConfig` explainer. + `feature_type`: Jenis fitur yang disimpulkan oleh penjelasan atau disediakan dalam `FeatureTypes` parameter di. `ExplainerConfig` Elemen ini hanya tersedia untuk masalah penjelasan NLP. + `attributions`: Sebuah array objek atribusi. Fitur teks dapat memiliki beberapa objek atribusi, masing-masing untuk satu unit. Objek atribusi memiliki anggota berikut: + `attribution`: Daftar nilai probabilitas, diberikan untuk setiap kelas. + `description`: Deskripsi unit teks, hanya tersedia untuk masalah penjelasan NLP. + `partial_text`: Bagian teks yang dijelaskan oleh penjelas. + `start_idx`: Indeks berbasis nol untuk mengidentifikasi lokasi array dari awal fragmen teks sebagian. # Contoh kode: SDK untuk Python Bagian ini menyediakan contoh kode untuk membuat dan memanggil titik akhir yang menggunakan SageMaker Clarify online explainability. Contoh kode ini menggunakan [AWS SDK untuk Python](https://aws.amazon.com/sdk-for-python/). ## Data tabular Contoh berikut menggunakan data tabular dan model SageMaker AI yang disebut`model_name`. Dalam contoh ini, wadah model menerima data dalam format CSV, dan setiap catatan memiliki empat fitur numerik. Dalam konfigurasi minimal ini, **hanya untuk tujuan demonstrasi**, data dasar SHAP diatur ke nol. Lihat [Garis Dasar SHAP untuk Penjelasan](clarify-feature-attribute-shap-baselines.md) untuk mempelajari cara memilih nilai yang lebih sesuai untuk`ShapBaseline`. Konfigurasikan titik akhir, sebagai berikut: ``` endpoint_config_name = 'tabular_explainer_endpoint_config' response = sagemaker_client.create_endpoint_config( EndpointConfigName=endpoint_config_name, ProductionVariants=[{ 'VariantName': 'AllTraffic', 'ModelName': model_name, 'InitialInstanceCount': 1, 'InstanceType': 'ml.m5.xlarge', }], ExplainerConfig={ 'ClarifyExplainerConfig': { 'ShapConfig': { 'ShapBaselineConfig': { 'ShapBaseline': '0,0,0,0', }, }, }, }, ) ``` Gunakan konfigurasi endpoint untuk membuat endpoint, sebagai berikut: ``` endpoint_name = 'tabular_explainer_endpoint' response = sagemaker_client.create_endpoint( EndpointName=endpoint_name, EndpointConfigName=endpoint_config_name, ) ``` Gunakan `DescribeEndpoint` API untuk memeriksa kemajuan pembuatan titik akhir, sebagai berikut: ``` response = sagemaker_client.describe_endpoint( EndpointName=endpoint_name, ) response['EndpointStatus'] ``` Setelah status endpoint adalah "InService“, panggil titik akhir dengan catatan pengujian, sebagai berikut: ``` response = sagemaker_runtime_client.invoke_endpoint( EndpointName=endpoint_name, ContentType='text/csv', Accept='text/csv', Body='1,2,3,4', ) ``` **catatan** Dalam contoh kode sebelumnya, untuk titik akhir multi-model, berikan `TargetModel` parameter tambahan dalam permintaan untuk menentukan model mana yang akan ditargetkan pada titik akhir. Asumsikan bahwa respons memiliki kode status 200 (tidak ada kesalahan), dan muat badan respons, sebagai berikut: ``` import codecs import json json.load(codecs.getreader('utf-8')(response['Body'])) ``` Tindakan default untuk titik akhir adalah menjelaskan catatan. Berikut ini menunjukkan contoh output dalam objek JSON dikembalikan. ``` { "version": "1.0", "predictions": { "content_type": "text/csv; charset=utf-8", "data": "0.0006380207487381" }, "explanations": { "kernel_shap": [ [ { "attributions": [ { "attribution": [-0.00433456] } ] }, { "attributions": [ { "attribution": [-0.005369821] } ] }, { "attributions": [ { "attribution": [0.007917749] } ] }, { "attributions": [ { "attribution": [-0.00261214] } ] } ] ] } } ``` Gunakan `EnableExplanations` parameter untuk mengaktifkan penjelasan sesuai permintaan, sebagai berikut: ``` response = sagemaker_runtime_client.invoke_endpoint( EndpointName=endpoint_name, ContentType='text/csv', Accept='text/csv', Body='1,2,3,4', EnableExplanations='[0]>`0.8`', ) ``` **catatan** Dalam contoh kode sebelumnya, untuk titik akhir multi-model, berikan `TargetModel` parameter tambahan dalam permintaan untuk menentukan model mana yang akan ditargetkan pada titik akhir. Dalam contoh ini, nilai prediksi kurang dari nilai ambang batas`0.8`, sehingga catatan tidak dijelaskan: ``` { "version": "1.0", "predictions": { "content_type": "text/csv; charset=utf-8", "data": "0.6380207487381995" }, "explanations": {} } ``` Gunakan alat visualisasi untuk membantu menafsirkan penjelasan yang dikembalikan. Gambar berikut menunjukkan bagaimana plot SHAP dapat digunakan untuk memahami bagaimana setiap fitur berkontribusi pada prediksi. Nilai dasar pada diagram, juga disebut nilai yang diharapkan, adalah prediksi rata-rata dari kumpulan data pelatihan. Fitur yang mendorong nilai yang diharapkan lebih tinggi berwarna merah, dan fitur yang mendorong nilai yang diharapkan lebih rendah berwarna biru. Lihat [tata letak gaya aditif SHAP](https://shap.readthedocs.io/en/latest/generated/shap.plots.force.html) untuk informasi tambahan. ![\[Contoh plot SHAP, yang dapat digunakan untuk memahami bagaimana setiap fitur berkontribusi pada prediksi.\]](http://docs.aws.amazon.com/id_id/sagemaker/latest/dg/images/clarify/force-plot.png) Lihat [contoh buku catatan lengkap untuk data tabular](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/tabular/tabular_online_explainability_with_sagemaker_clarify.ipynb). ## Data teks Bagian ini memberikan contoh kode untuk membuat dan memanggil titik akhir penjelasan online untuk data teks. Contoh kode menggunakan SDK untuk Python. Contoh berikut menggunakan data teks dan model SageMaker AI yang disebut`model_name`. Dalam contoh ini, wadah model menerima data dalam format CSV, dan setiap catatan adalah string tunggal. ``` endpoint_config_name = 'text_explainer_endpoint_config' response = sagemaker_client.create_endpoint_config( EndpointConfigName=endpoint_config_name, ProductionVariants=[{ 'VariantName': 'AllTraffic', 'ModelName': model_name, 'InitialInstanceCount': 1, 'InstanceType': 'ml.m5.xlarge', }], ExplainerConfig={ 'ClarifyExplainerConfig': { 'InferenceConfig': { 'FeatureTypes': ['text'], 'MaxRecordCount': 100, }, 'ShapConfig': { 'ShapBaselineConfig': { 'ShapBaseline': '""', }, 'TextConfig': { 'Granularity': 'token', 'Language': 'en', }, 'NumberOfSamples': 100, }, }, }, ) ``` + `ShapBaseline`: Token khusus yang disediakan untuk pemrosesan bahasa alami (NLP). + `FeatureTypes`: Mengidentifikasi fitur sebagai teks. Jika parameter ini tidak disediakan, penjelasan akan mencoba menyimpulkan jenis fitur. + `TextConfig`: Menentukan unit granularitas dan bahasa untuk analisis fitur teks. Dalam contoh ini, bahasanya adalah bahasa Inggris, dan granularitas `token` berarti kata dalam teks bahasa Inggris. + `NumberOfSamples`: Batas untuk mengatur batas atas ukuran dataset sintetis. + `MaxRecordCount`: Jumlah maksimum catatan dalam permintaan yang dapat ditangani oleh wadah model. Parameter ini diatur untuk menstabilkan kinerja. Gunakan konfigurasi endpoint untuk membuat endpoint, sebagai berikut: ``` endpoint_name = 'text_explainer_endpoint' response = sagemaker_client.create_endpoint( EndpointName=endpoint_name, EndpointConfigName=endpoint_config_name, ) ``` Setelah status titik akhir menjadi`InService`, panggil titik akhir. Contoh kode berikut menggunakan catatan uji sebagai berikut: ``` response = sagemaker_runtime_client.invoke_endpoint( EndpointName=endpoint_name, ContentType='text/csv', Accept='text/csv', Body='"This is a good product"', ) ``` Jika permintaan berhasil diselesaikan, badan respons akan mengembalikan objek JSON yang valid yang mirip dengan yang berikut ini: ``` { "version": "1.0", "predictions": { "content_type": "text/csv", "data": "0.9766594\n" }, "explanations": { "kernel_shap": [ [ { "attributions": [ { "attribution": [ -0.007270948666666712 ], "description": { "partial_text": "This", "start_idx": 0 } }, { "attribution": [ -0.018199033666666628 ], "description": { "partial_text": "is", "start_idx": 5 } }, { "attribution": [ 0.01970993241666666 ], "description": { "partial_text": "a", "start_idx": 8 } }, { "attribution": [ 0.1253469515833334 ], "description": { "partial_text": "good", "start_idx": 10 } }, { "attribution": [ 0.03291143366666657 ], "description": { "partial_text": "product", "start_idx": 15 } } ], "feature_type": "text" } ] ] } } ``` Gunakan alat visualisasi untuk membantu menafsirkan atribusi teks yang dikembalikan. Gambar berikut menunjukkan bagaimana utilitas visualisasi captum dapat digunakan untuk memahami bagaimana setiap kata berkontribusi pada prediksi. Semakin tinggi saturasi warna, semakin tinggi pentingnya kata tersebut. Dalam contoh ini, warna merah cerah yang sangat jenuh menunjukkan kontribusi negatif yang kuat. Warna hijau yang sangat jenuh menunjukkan kontribusi positif yang kuat. Warna putih menunjukkan bahwa kata tersebut memiliki kontribusi netral. Lihat perpustakaan [captum](https://github.com/pytorch/captum) untuk informasi tambahan tentang penguraian dan rendering atribusi. ![\[Utilitas visualisasi Captum digunakan untuk memahami bagaimana setiap kata berkontribusi pada prediksi.\]](http://docs.aws.amazon.com/id_id/sagemaker/latest/dg/images/clarify/word-importance.png) Lihat [contoh buku catatan lengkap untuk data teks](https://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/online_explainability/natural_language_processing/nlp_online_explainability_with_sagemaker_clarify.ipynb). # Panduan pemecahan masalah Jika Anda menemukan kesalahan menggunakan SageMaker Clarify online explainability, lihat topik di bagian ini. **`InvokeEndpoint`API gagal dengan kesalahan “: Baca ReadTimeoutError batas waktu di titik akhir...”** Kesalahan ini berarti bahwa permintaan tidak dapat diselesaikan dalam batas waktu 60 detik yang ditetapkan oleh batas [waktu permintaan](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html). Untuk mengurangi latensi permintaan, coba yang berikut ini: + Sesuaikan kinerja model selama inferensi. Misalnya, SageMaker AI [Neo](https://aws.amazon.com/sagemaker/neo/) dapat mengoptimalkan model untuk inferensi. + Izinkan wadah model untuk menangani permintaan batch. + Gunakan yang lebih besar `MaxRecordCount` untuk mengurangi jumlah panggilan dari penjelasan ke wadah model. Ini akan mengurangi latensi jaringan dan overhead. + Gunakan jenis instance yang memiliki lebih banyak sumber daya yang dialokasikan untuk itu. Sebagai alternatif, tetapkan lebih banyak instance ke titik akhir untuk membantu menyeimbangkan beban. + Kurangi jumlah catatan dalam satu `InvokeEndpoint` permintaan. + Kurangi jumlah catatan dalam data dasar. + Gunakan `NumberOfSamples` nilai yang lebih kecil untuk mengurangi ukuran kumpulan data sintetis. Untuk informasi selengkapnya tentang bagaimana jumlah sampel memengaruhi kumpulan data sintetis Anda, lihat[Dataset sintetis](clarify-online-explainability-create-endpoint-synthetic.md).