Persyaratan container kustom

Untuk menggunakan container kustom guna menyajikan prediksi, Anda harus menyediakan image container Docker yang menjalankan server HTTP untuk AI Platform Prediction. Dokumen ini menjelaskan persyaratan yang harus dipenuhi oleh 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 yang akan 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 penyajian machine learning (ML) yang menjalankan server HTTP, seperti TensorFlow Serve, TorchServe, atau KFServe Server.

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 gambar penampung. Dengan menentukan salah satu kolom ini, Anda dapat 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 penampung dapat mengakses nilai ini, baca bagian dokumen ini tentang variabel lingkungan AIP_HTTP_PORT.

Pemeriksaan keaktifan

AI Platform Prediction melakukan pemeriksaan keaktifan saat penampung Anda mulai memastikan bahwa server Anda berjalan. Selama proses pembuatan versi, Prediksi AI Platform menggunakan pemeriksaan keaktifan TCP untuk mencoba membuat koneksi TCP ke container Anda pada 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 container 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 sesekali melakukan health check di server HTTP Anda saat server tersebut berjalan untuk memastikan bahwa server 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 penampung dapat mengakses nilai ini, baca bagian 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 tersebut, atau merespons dengan kode status apa pun kecuali 200 OK. Misalnya, respons dengan kode status 503 Service Unavailable.

    Respons ini menandakan bahwa server tidak responsif.

Jika health check menerima respons tidak responsif dari server Anda, pemeriksaan akan mengirim 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 berturut-turut, Prediksi AI Platform akan berhenti merutekan traffic prediksi ke container. (Jika versi model diskalakan untuk menggunakan beberapa node prediksi, AI Platform Prediction akan mengarahkan permintaan prediksi ke container lain yang responsif.)

Prediksi AI Platform tidak memulai ulang penampung; sebagai gantinya, pemeriksaan kondisi terus mengirimkan permintaan health check yang terputus-putus 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 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 penampung dapat mengakses nilai ini, baca bagian dalam dokumen ini tentang variabel lingkungan AIP_PREDICT_ROUTE.

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

Setiap permintaan prediksi dan respons harus berukuran 1,5 MB atau lebih kecil. Namun, Anda tidak harus mematuhi 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 berbentuk apa pun.

Namun, sebaiknya desain server HTTP Anda agar sesuai dengan persyaratan permintaan dan respons yang dijelaskan dalam link sebelumnya. Jika tidak, tidak ada jaminan bahwa fitur Prediksi AI Platform lainnya—seperti logging, monitoring, dan AI Penjelasan—akan berfungsi dengan baik.

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.

Location

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 multiregional untuk image container Anda.

Izin

Prediksi AI Platform harus memiliki izin untuk mengambil image container saat Anda membuat versi model. Secara khusus, akun layanan yang dikelola Google 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 akun layanan yang dikelola Google sudah memadai.

Di sisi lain, jika Anda telah mengirim image container ke project Google Cloud yang berbeda dari project tempat Anda menggunakan AI Platform Prediction, Anda harus memberikan peran Artifact Registry Reader untuk repositori Artifact Registry ke akun layanan yang dikelola Google di 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 container 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 memulai container Anda, Prediction AI Platform akan menetapkan variabel lingkungan AIP_STORAGE_URI ke URI Cloud Storage 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 URI Cloud Storage 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 berbeda, yang dikelola Prediksi AI Platform. 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 secara otomatis memberikan peran Storage Object Viewer (roles/storage.objectViewer) ke akun layanan yang Anda tentukan 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 container mendukung ADC untuk akun layanan yang dikelola Google AI Platform—atau akun layanan kustom, jika Anda telah menentukannya, container tersebut juga dapat mengakses layanan Google Cloud lainnya yang izinnya dimiliki oleh akun layanan tersebut.

Variabel lingkungan yang tersedia di container

Saat dijalankan, 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 Anda lakukan untuk menetapkan variabel lingkungan, dan menyediakan detail tentang variabel yang disetel 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 entrypoint 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 Prediksi AI Platform mulai menjalankan container, Prediction ini 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 API Pelatihan dan Prediksi AI Platform 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 pada container yang menjadi tujuan pengiriman health check oleh Prediction AI Platform.
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 pada 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 tersebut sedang berjalan di AI Platform Prediction untuk menyajikan prediksi online. Anda dapat menggunakan variabel lingkungan ini untuk menambahkan logika kustom ke container, 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 diharapkan oleh AI Platform Prediction untuk dipenuhi. Dokumen ini diperbarui sesuai dengan pembuatan versi semantik.
AIP_MODEL_NAME Tidak ada default, harus dikonfigurasi Saat Anda membuat model (induk dari versi model yang menggunakan penampung), tentukan kolom name. Nilai ini tidak mencakup awalan projects/PROJECT_ID/models/ yang dihasilkan oleh AI Platform Training and Prediction API.
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 tempat Prediksi AI Platform meneruskan permintaan prediksi.
AIP_PROJECT_NUMBER Nomor project dari project Google Cloud tempat Anda menggunakan AI Platform Prediction 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: URI Cloud Storage (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 mencakup awalan projects/PROJECT_ID/models/MODEL/versions/ yang dihasilkan oleh AI Platform Training and Prediction API dalam output.

Variabel yang ditetapkan dalam 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 API Pelatihan dan Prediksi AI Platform yang juga dapat mereferensikan variabel ini, baca referensi API untuk ContainerSpec.

Langkah selanjutnya