Persyaratan container kustom

Untuk menggunakan container kustom guna menampilkan prediksi, Anda harus menyediakan AI Platform Prediction dengan image container Docker yang menjalankan server HTTP. Dokumen ini menjelaskan persyaratan yang harus dipenuhi image container agar kompatibel dengan AI Platform Prediction. Dokumen ini juga menjelaskan cara AI Platform Prediction berinteraksi dengan penampung kustom Anda setelah mulai berjalan. Dengan kata lain, dokumen ini menjelaskan hal-hal yang perlu Anda pertimbangkan saat mendesain image container untuk digunakan dengan AI Platform Prediction.

Untuk mempelajari penggunaan image container kustom dalam menampilkan prediksi, baca Menggunakan container kustom.

Persyaratan image container

Saat image container Docker Anda berjalan sebagai container, container tersebut harus menjalankan server HTTP. Secara khusus, container harus memproses dan merespons pemeriksaan keaktifan, health check, dan permintaan prediksi. Subbagian berikut menjelaskan persyaratan ini secara mendetail.

Anda dapat mengimplementasikan server HTTP dengan cara apa pun, menggunakan bahasa pemrograman apa pun, selama memenuhi persyaratan di bagian ini. Misalnya, Anda dapat menulis server HTTP kustom menggunakan framework web seperti Flask atau menggunakan software inferensi machine learning (ML) yang menjalankan server HTTP, seperti TensorFlow Serving, TorchServe, atau Server KFServing.

Menjalankan server HTTP

Anda dapat menjalankan server HTTP menggunakan petunjuk ENTRYPOINT, petunjuk CMD, atau keduanya di Dockerfile yang Anda gunakan untuk membangun image container. Baca interaksi antara CMD dan ENTRYPOINT.

Atau, Anda dapat menentukan kolom containerSpec.command dan containerSpec.args saat membuat versi model untuk mengganti ENTRYPOINT dan CMD image penampung. Menentukan salah satu kolom ini memungkinkan Anda menggunakan image container yang tidak akan memenuhi persyaratan karena ENTRYPOINT atau CMD yang tidak kompatibel (atau tidak ada).

Meskipun Anda menentukan perintah mana yang dijalankan container saat dimulai, pastikan perintah titik entri ini berjalan tanpa batas. Contohnya, jangan menjalankan perintah yang memulai server HTTP di latar belakang lalu keluar; jika dilakukan, container akan segera keluar setelah mulai berjalan.

Server HTTP Anda harus memproses permintaan pada 0.0.0.0, pada port yang Anda pilih. Saat Anda membuat versi model, tentukan port ini di kolom containerSpec.ports. Untuk mempelajari cara container dapat mengakses nilai ini, baca bagian dalam dokumen ini tentang variabel lingkungan AIP_HTTP_PORT.

Pemeriksaan keaktifan

AI Platform Prediction melakukan pemeriksaan keaktifan saat penampung mulai memastikan bahwa server Anda berjalan. Selama proses pembuatan versi, AI Platform Prediction menggunakan pemeriksaan keaktifan TCP untuk mencoba membuat koneksi TCP ke penampung Anda di port yang dikonfigurasi. Pemeriksaan ini melakukan hingga 4 kali percobaan untuk membuat koneksi, dan menunggu 10 detik setelah setiap kegagalan terjadi. Jika pemeriksaan masih belum membuat koneksi pada tahap ini, AI Platform Prediction akan memulai ulang penampung Anda.

Server HTTP Anda tidak perlu melakukan perilaku khusus untuk menangani pemeriksaan ini. Selama memproses permintaan pada port yang dikonfigurasi, pemeriksaan keaktifan dapat membuat koneksi.

Health check

AI Platform Prediction secara berkala melakukan health check di server HTTP Anda saat sedang berjalan untuk memastikannya siap menangani permintaan prediksi. Layanan ini menggunakan pemeriksaan kondisi untuk mengirim permintaan GET HTTP ke jalur health check yang dapat dikonfigurasi di server Anda. Tentukan jalur ini di kolom routes.health saat Anda membuat versi model. Untuk mempelajari cara container dapat mengakses nilai ini, baca bagian dalam dokumen ini tentang variabel lingkungan AIP_HEALTH_ROUTE.

Konfigurasi server HTTP untuk merespons setiap permintaan health check sebagai berikut:

  • Jika server siap menangani permintaan prediksi, tanggapi permintaan health check dengan kode status 200 OK. Isi isi respons tidak penting; AI Platform Prediction mengabaikannya.

    Respons ini menandakan bahwa server responsif.

  • Jika server belum siap menangani permintaan prediksi, jangan merespons permintaan health check, atau merespons dengan kode status apa pun kecuali untuk 200 OK. Misalnya, respons dengan kode status 503 Service Unavailable.

    Respons ini menandakan bahwa server tidak responsif.

Jika pemeriksaan kondisi menerima respons tidak responsif dari server Anda, pemeriksaan akan mengirimkan hingga 3 health check tambahan pada interval 10 detik. Selama periode ini, AI Platform Prediction masih menganggap server Anda responsif. Jika pemeriksaan menerima respons yang responsif terhadap salah satu pemeriksaan ini, pemeriksaan akan segera kembali ke jadwal health check yang berselang-seling. Namun, jika pemeriksaan menerima 4 respons tidak responsif secara berturut-turut, AI Platform Prediction akan berhenti mengarahkan traffic prediksi ke container. (Jika versi model diskalakan untuk menggunakan beberapa node prediksi, AI Platform Prediction akan merutekan permintaan prediksi ke penampung lain yang responsif.)

AI Platform Prediction tidak memulai ulang container; sebagai gantinya, pemeriksaan kondisi terus mengirim permintaan health check yang berselang-seling ke server yang tidak responsif. Jika menerima respons yang baik, pemeriksaan ini akan menandai container tersebut sebagai responsif dan mulai mengarahkan traffic prediksi ke container itu lagi.

Panduan praktis

Dalam beberapa kasus, cukup bagi server HTTP di container Anda untuk selalu merespons dengan kode status 200 OK untuk health check. Jika container Anda memuat resource sebelum memulai server, container tersebut tidak responsif selama periode memulai dan selama periode ketika server HTTP gagal. Pada waktu yang lain, respons menjadi responsif.

Untuk konfigurasi yang lebih canggih, Anda mungkin ingin mendesain server HTTP secara sengaja untuk merespons health check dengan status yang tidak responsif pada waktu tertentu. Misalnya, Anda mungkin ingin memblokir traffic prediksi ke sebuah node selama jangka waktu tertentu sehingga container dapat melakukan pemeliharaan.

Permintaan prediksi

Saat klien mengirim permintaan projects.predict ke AI Platform Training and Prediction API, AI Platform Prediction akan meneruskan permintaan ini sebagai permintaan POST HTTP ke jalur prediksi yang dapat dikonfigurasi di server Anda. Tentukan jalur ini di kolom routes.predict saat Anda membuat versi model. Untuk mempelajari cara container dapat mengakses nilai ini, baca bagian dalam dokumen ini tentang variabel lingkungan AIP_PREDICT_ROUTE.

AI Platform Prediction tidak memvalidasi permintaan dan respons prediksi; layanan ini meneruskan setiap permintaan prediksi tanpa perubahan ke server HTTP di penampung Anda, dan meneruskan respons server kembali ke klien.

Setiap permintaan dan respons prediksi harus berukuran 1,5 MB atau lebih kecil. Namun, Anda tidak diwajibkan untuk mengikuti persyaratan untuk isi permintaan dan persyaratan untuk isi respons lainnya; persyaratan ini hanya berlaku untuk versi model yang tidak menggunakan penampung kustom. Saat Anda menggunakan penampung kustom, isi permintaan dan respons dapat berupa apa pun.

Namun, sebaiknya Anda tetap mendesain server HTTP agar sesuai dengan persyaratan permintaan dan respons yang dijelaskan di link sebelumnya. Jika tidak, tidak ada jaminan bahwa fitur AI Platform Prediction lainnya—seperti logging, pemantauan, dan Penjelasan AI—akan berfungsi dengan benar.

Persyaratan publikasi image container

Anda harus mengirim image container ke Artifact Registry agar dapat menggunakannya dengan AI Platform Prediction. Pelajari cara mengirim image container ke Artifact Registry.

Secara khusus, Anda harus mengirim image container ke repositori yang memenuhi persyaratan lokasi dan izin berikut.

Lokasi

Repositori harus menggunakan region yang cocok dengan endpoint regional tempat Anda berencana membuat versi model. Misalnya, jika Anda berencana membuat versi model di endpoint us-central1-ml.googleapis.com, nama lengkap image penampung harus diawali dengan us-central1-docker.pkg.dev/.

Jangan gunakan repositori multi-regional untuk image container Anda.

Izin

AI Platform Prediction harus memiliki izin untuk mengambil image container saat Anda membuat versi model. Secara khusus, agen layanan AI Platform harus memiliki izin peran Artifact Registry Reader (roles/artifactregistry.reader) untuk repositori image container.

Jika Anda telah mengirim image container ke project Google Cloud yang sama tempat Anda menggunakan AI Platform Prediction, Anda tidak perlu mengonfigurasi izin apa pun. Izin default yang diberikan ke agen layanan sudah cukup.

Di sisi lain, jika Anda telah mengirim image container ke project Google Cloud yang berbeda dengan project tempat Anda menggunakan AI Platform Prediction, Anda harus memberikan peran Artifact Registry Reader untuk repositori Artifact Registry kepada agen layanan AI Platform.

Mengakses artefak model

Saat membuat versi model tanpa penampung kustom, Anda harus menentukan URI direktori Cloud Storage dengan artefak model sebagai kolom deploymentUri. Saat Anda membuat versi model dengan penampung kustom, memberikan artefak model di Cloud Storage bersifat opsional.

Jika image container menyertakan artefak model yang Anda perlukan untuk menampilkan prediksi, Anda tidak perlu memuat file dari Cloud Storage. Namun, jika Anda menyediakan artefak model dengan menentukan kolom deploymentUri, container harus memuat artefak tersebut saat mulai berjalan. Saat AI Platform Prediction memulai container Anda, AI Platform Prediction akan menetapkan variabel lingkungan AIP_STORAGE_URI ke Cloud Storage URI yang dimulai dengan gs://. Perintah titik entri container Anda dapat mendownload direktori yang ditentukan oleh URI ini agar dapat mengakses artefak model.

Perhatikan bahwa nilai variabel lingkungan AIP_STORAGE_URI tidak sama dengan Cloud Storage URI yang Anda tentukan di kolom deploymentUri saat membuat versi model. Sebaliknya, AIP_STORAGE_URI mengarah ke salinan direktori artefak model Anda di bucket Cloud Storage lain, yang dikelola AI Platform Prediction. AI Platform Prediction mengisi direktori ini saat Anda membuat versi model. Anda tidak dapat memperbarui konten direktori. Jika ingin menggunakan artefak model baru, Anda harus membuat versi model baru.

Akun layanan yang digunakan penampung Anda secara default memiliki izin untuk membaca dari URI ini. Di sisi lain, jika Anda menentukan akun layanan kustom saat membuat versi model, AI Platform Prediction akan otomatis memberi akun layanan yang Anda tentukan peran Storage Object Viewer (roles/storage.objectViewer) untuk bucket Cloud Storage URI.

Gunakan library apa pun yang mendukung Kredensial Default Aplikasi (ADC) untuk memuat artefak model; Anda tidak perlu secara eksplisit mengkonfigurasi autentikasi.

Karena penampung mendukung ADC untuk agen layanan AI Platform—atau akun layanan kustom, jika Anda telah menentukannya—penampung juga dapat mengakses layanan Google Cloud lainnya yang izinnya dimiliki oleh akun layanannya.

Variabel lingkungan yang tersedia di container

Saat berjalan, perintah entrypoint container dapat mereferensikan variabel lingkungan yang telah Anda konfigurasi secara manual, serta variabel lingkungan yang ditetapkan secara otomatis oleh AI Platform Prediction. Bagian ini menjelaskan setiap cara yang dapat dilakukan untuk menetapkan variabel lingkungan, dan memberikan detail tentang variabel yang ditetapkan secara otomatis oleh AI Platform Prediction.

Variabel yang ditetapkan dalam image container

Untuk menetapkan variabel lingkungan dalam image container saat Anda membuatnya, gunakan petunjuk ENV Docker. Jangan menetapkan variabel lingkungan yang dimulai dengan awalan AIP_.

Perintah titik entri container dapat menggunakan variabel lingkungan ini, tetapi Anda tidak dapat mereferensikannya di salah satu kolom API versi model Anda.

Variabel yang ditetapkan oleh AI Platform Prediction

Saat AI Platform Prediction mulai menjalankan container, AI Platform Prediction akan menetapkan variabel lingkungan berikut di lingkungan container. Setiap variabel dimulai dengan awalan AIP_. Jangan tetapkan secara manual variabel lingkungan apa pun yang menggunakan awalan ini.

Perintah titik entri container dapat mengakses variabel ini. Untuk mempelajari kolom AI Platform Training dan Prediction API mana yang juga dapat mereferensikan variabel ini, baca referensi API untuk ContainerSpec.

Nama variabel Nilai default Cara mengonfigurasi nilai Detail
AIP_ACCELERATOR_TYPE Tidak disetel Saat Anda membuat versi model, tetapkan kolom acceleratorConfig.type. Jika berlaku, variabel ini menentukan jenis akselerator yang digunakan oleh instance virtual machine (VM) tempat container berjalan.
AIP_FRAMEWORK CUSTOM_CONTAINER Tidak dapat dikonfigurasi
AIP_HEALTH_ROUTE /v1/models/MODEL/versions/VERSION

Dalam string ini, ganti MODEL dengan nilai variabel AIP_MODEL_NAME dan ganti VERSION dengan nilai variabel AIP_VERSION_NAME.		 Saat Anda membuat versi model, tetapkan kolom routes.health. Variabel ini menentukan jalur HTTP di container yang menjadi tujuan AI Platform Prediction mengirimkan health check.
AIP_HTTP_PORT 8080 Saat Anda membuat versi model, tetapkan kolom containerSpec.ports. Entri pertama di kolom ini menjadi nilai AIP_HTTP_PORT. AI Platform Prediction mengirimkan pemeriksaan keaktifan, health check, dan permintaan prediksi ke port ini di container. Server HTTP container Anda harus memproses permintaan pada port ini.
AIP_MACHINE_TYPE Tidak ada default, harus dikonfigurasi Saat Anda membuat versi model, tetapkan kolom machineType. Variabel ini menentukan jenis VM yang dijalankan oleh container.
AIP_MODE PREDICTION Tidak dapat dikonfigurasi Variabel ini menandakan bahwa container sedang berjalan di AI Platform Prediction untuk menampilkan prediksi online. Anda dapat menggunakan variabel lingkungan ini untuk menambahkan logika kustom ke penampung, sehingga dapat berjalan di beberapa lingkungan komputasi, tetapi hanya menggunakan jalur kode tertentu saat dijalankan di AI Platform Prediction.
AIP_MODE_VERSION 1.0.0 Tidak dapat dikonfigurasi Variabel ini menandakan versi persyaratan container kustom (dokumen ini) yang diperkirakan AI Platform Prediction akan dipenuhi oleh container. Dokumen ini diperbarui sesuai dengan pembuatan versi semantik.
AIP_MODEL_NAME Tidak ada default, harus dikonfigurasi Saat Anda membuat model (induk versi model yang menggunakan penampung), tentukan kolom name. Nilai ini tidak menyertakan awalan projects/PROJECT_ID/models/ yang dihasilkan oleh Training API dan Prediction API AI Platform dalam output.
AIP_PREDICT_ROUTE /v1/models/MODEL/versions/VERSION:predict

Dalam string ini, ganti MODEL dengan nilai variabel AIP_MODEL_NAME dan ganti VERSION dengan nilai variabel AIP_VERSION_NAME.		 Saat Anda membuat versi model, tetapkan kolom routes.predict. Variabel ini menentukan jalur HTTP di container yang menjadi tujuan AI Platform Prediction meneruskan permintaan prediksi.
AIP_PROJECT_NUMBER Nomor project dari project Google Cloud tempat Anda menggunakan Prediksi AI Platform Tidak dapat dikonfigurasi
AIP_STORAGE_URI
  • Jika Anda tidak menetapkan kolom deploymentUri saat membuat versi model: string kosong
  • Jika Anda menetapkan kolom deploymentUri saat membuat versi model: Cloud Storage URI (dimulai dengan gs://) yang menentukan direktori dalam bucket yang dikelola oleh AI Platform Prediction
 Tidak dapat dikonfigurasi Variabel ini menentukan direktori yang berisi salinan artefak model Anda, jika berlaku.
AIP_VERSION_NAME Tidak ada default, harus dikonfigurasi Saat Anda membuat versi model, tetapkan kolom name. Nilai ini tidak menyertakan awalan projects/PROJECT_ID/models/MODEL/versions/ yang dihasilkan AI Platform Training and Prediction API dalam output.

Variabel yang ditetapkan di resource Versi

Saat membuat versi model, Anda dapat menetapkan variabel lingkungan tambahan di kolom container.env.

Perintah titik entri container dapat mengakses variabel ini. Untuk mempelajari kolom AI Platform Training dan Prediction API mana yang juga dapat mereferensikan variabel ini, baca referensi API untuk ContainerSpec.

Langkah selanjutnya