Menyesuaikan persyaratan container untuk prediksi

Catatan: Ini adalah versi 1.0.0 dari dokumen ini. Dokumen diperbarui sesuai dengan pembuatan versi semantik.

Agar dapat menggunakan container kustom untuk menampilkan prediksi dari model yang dilatih khusus, Anda harus menyediakan Vertex AI dengan image container Docker yang menjalankan server HTTP. Dokumen ini menjelaskan persyaratan yang harus dipenuhi image container agar kompatibel dengan Vertex AI. Dokumen ini juga menjelaskan cara Vertex AI berinteraksi dengan container kustom Anda setelah mulai berjalan. Dengan kata lain, dokumen ini menjelaskan hal-hal yang perlu Anda pertimbangkan saat mendesain image container untuk digunakan dengan Vertex AI.

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 KServe Python 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 resource Model untuk mengganti ENTRYPOINT dan CMD image container. 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 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

Vertex AI melakukan pemeriksaan keaktifan saat container mulai memastikan bahwa server Anda berjalan. Saat Anda men-deploy model yang dilatih khusus ke resource Endpoint, Vertex AI 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, Vertex AI 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

Anda juga dapat menentukan startup_probe atau health_probe.

Pemeriksaan startup memeriksa apakah aplikasi container telah dimulai. Jika pemeriksaan startup tidak disediakan, tidak akan ada pemeriksaan startup dan health check akan segera dimulai. Jika pemeriksaan startup diberikan, health check tidak akan dilakukan sampai pemeriksaan startup berhasil.

Aplikasi lama yang mungkin memerlukan waktu startup tambahan pada inisialisasi pertamanya harus mengonfigurasi pemeriksaan startup. Misalnya, jika aplikasi perlu menyalin artefak model dari sumber eksternal, pemeriksaan startup harus dikonfigurasi untuk menampilkan keberhasilan saat inisialisasi tersebut selesai.

Health check memeriksa apakah container siap menerima traffic. Jika pemeriksaan kesehatan tidak disediakan, Vertex AI akan menggunakan health check default seperti yang dijelaskan dalam Health check default.

Aplikasi lama yang tidak menampilkan 200 OK untuk menunjukkan bahwa model dimuat dan siap menerima traffic harus mengonfigurasi pemeriksaan kesehatan. Misalnya, aplikasi mungkin menampilkan 200 OK untuk menunjukkan keberhasilan meskipun status pemuatan model sebenarnya yang ada di isi respons menunjukkan bahwa model mungkin belum dimuat sehingga mungkin belum siap untuk menerima traffic. Dalam hal ini, pemeriksaan kesehatan harus dikonfigurasi untuk menampilkan keberhasilan hanya saat model dimuat dan siap menyalurkan traffic.

Untuk menjalankan pemeriksaan, Vertex AI menjalankan perintah exec yang telah ditentukan dalam container target. Jika berhasil, perintah akan menampilkan 0, dan container dianggap aktif dan sehat.

Health check default

Secara default, Vertex AI sesekali melakukan health check di server HTTP Anda saat sedang berjalan untuk memastikan bahwa Vertex AI 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 containerSpec.healthRoute saat Anda membuat Model. Untuk mempelajari cara container 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 dalam waktu 10 detik dengan kode status 200 OK. Konten dari isi respons tidak menjadi masalah; Vertex AI mengabaikannya.

  Respons ini menandakan bahwa server responsif.

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

  Respons ini (atau tidak adanya respons) menandakan bahwa server tidak responsif.

Jika pemeriksaan kondisi menerima respons tidak responsif dari server Anda (termasuk tidak ada respons dalam 10 detik), pemeriksaan akan mengirimkan hingga 3 health check tambahan pada interval 10 detik. Selama periode ini, Vertex AI 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, Vertex AI akan berhenti mengarahkan traffic prediksi ke container. (Jika resource DeployedModel diskalakan untuk menggunakan beberapa node prediksi, Vertex AI akan merutekan permintaan prediksi ke container lain yang responsif.)

Vertex AI tidak memulai ulang container; sebagai gantinya, pemeriksaan kesehatan terus mengirimkan permintaan health check yang tidak responsif 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.locations.endpoints.predict ke Vertex AI API, Vertex AI akan meneruskan permintaan ini sebagai permintaan POST HTTP ke jalur prediksi yang dapat dikonfigurasi di server Anda. Tentukan jalur ini di kolom containerSpec.predictRoute saat Anda membuat Model. Untuk mempelajari cara container dapat mengakses nilai ini, baca bagian dalam dokumen ini tentang variabel lingkungan AIP_PREDICT_ROUTE.

Persyaratan permintaan

Jika model di-deploy ke endpoint publik, setiap permintaan prediksi harus berukuran 1,5 MB atau lebih kecil. Server HTTP harus menerima permintaan prediksi yang memiliki header HTTP Content-Type: application/json dan isi JSON dengan format berikut:

{
  "instances": INSTANCES,
  "parameters": PARAMETERS
}

Dalam permintaan ini:

• INSTANCES adalah array dari satu atau beberapa nilai JSON dari jenis apa pun. Setiap nilai mewakili instance yang Anda berikan prediksi.

• PARAMETERS adalah objek JSON yang berisi parameter apa pun yang diperlukan container Anda untuk membantu menampilkan prediksi pada instance. Vertex AI menganggap kolom parameters opsional, sehingga Anda dapat mendesain container agar memerlukannya, hanya menggunakannya jika disediakan, atau mengabaikannya.

Pelajari lebih lanjut persyaratan isi permintaan.

Persyaratan respons

Jika model di-deploy ke endpoint publik, setiap respons prediksi harus berukuran 1,5 MB atau lebih kecil. Server HTTP harus mengirimkan respons dengan isi JSON yang memenuhi format berikut:

{
  "predictions": PREDICTIONS
}

Dalam respons ini, ganti PREDICTIONS dengan array nilai JSON yang mewakili prediksi yang telah dihasilkan container Anda untuk setiap INSTANCES dalam permintaan yang sesuai.

Setelah server HTTP Anda mengirimkan respons ini, Vertex AI akan menambahkan kolom deployedModelId ke respons sebelum menampilkannya ke klien. Kolom ini menentukan DeployedModel mana pada Endpoint yang mengirimkan respons. Pelajari lebih lanjut format isi respons.

Catatan: Jika penampung Anda tidak memenuhi persyaratan ini untuk menerima permintaan dan mengirim respons, Anda masih dapat menggunakan penampung untuk prediksi mentah.

Persyaratan publikasi image container

Anda harus mengirim image container ke Artifact Registry agar dapat menggunakannya dengan Vertex AI. 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

Saat Anda menggunakan Artifact Registry, repositori harus menggunakan region yang cocok dengan endpoint regional tempat Anda berencana membuat Model. Misalnya, jika Anda berencana membuat Model pada endpoint us-central1-aiplatform.googleapis.com, nama lengkap image container harus diawali dengan us-central1-docker.pkg.dev/. Jangan gunakan repositori multi-regional untuk image container Anda.

Izin

Vertex AI harus memiliki izin untuk mengambil image container saat Anda membuat Model. Secara khusus, Agen Layanan Vertex AI untuk project Anda harus memiliki izin peran Pembaca Artifact Registry (roles/artifactregistry.reader) untuk repositori image container.

Vertex AI Service Agent untuk project Anda adalah akun layanan yang dikelola Google yang digunakan Vertex AI untuk berinteraksi dengan layanan Google Cloud lainnya. Akun layanan ini memiliki alamat email [e-mail], di mana PROJECT_NUMBER diganti dengan nomor project dari project Vertex AI Anda.

Jika telah mengirim image container ke project Google Cloud yang sama dengan tempat Anda menggunakan Vertex AI, Anda tidak perlu mengonfigurasi izin apa pun. Izin default yang diberikan ke Vertex AI Service Agent sudah cukup.

Di sisi lain, jika Anda telah mengirim image container ke project Google Cloud yang berbeda dari tempat Anda menggunakan Vertex AI, Anda harus memberikan peran Artifact Registry Reader untuk repositori Artifact Registry ke Agen Layanan Vertex AI.

Catatan: Meskipun Anda berencana untuk menggunakan akun layanan kustom di container kustom, Anda tidak perlu memberikan izin Artifact Registry akun layanan kustom; hanya akun layanan yang dikelola Google yang memerlukan izin ini. Vertex AI tidak menggunakan akun layanan kustom Anda untuk mengambil image container. Alat ini hanya menggunakan akun layanan kustom untuk menjalankan kode inferensi model Anda.

Mengakses artefak model

Saat Anda membuat Model yang dilatih khusus tanpa container kustom, Anda harus menentukan URI direktori Cloud Storage dengan artefak model sebagai kolom artifactUri. Saat Anda membuat 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 artifactUri, container harus memuat artefak tersebut saat mulai berjalan. Saat Vertex AI memulai container Anda, Vertex AI 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 identik dengan URI Cloud Storage yang Anda tentukan di kolom artifactUri saat membuat Model. Sebaliknya, AIP_STORAGE_URI mengarah ke salinan direktori artefak model Anda di bucket Cloud Storage lain, yang dikelola Vertex AI. Vertex AI mengisi direktori ini saat Anda membuat Model. Anda tidak dapat memperbarui konten direktori. Jika ingin menggunakan artefak model baru, Anda harus membuat Model baru.

Akun layanan yang digunakan container Anda secara default memiliki izin untuk membaca dari URI ini.

Di sisi lain, jika Anda menentukan akun layanan kustom saat men-deploy Model ke Endpoint, Vertex AI 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.

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 Vertex AI. Bagian ini menjelaskan setiap cara yang dapat dilakukan untuk menetapkan variabel lingkungan, dan memberikan detail tentang variabel yang ditetapkan secara otomatis oleh Vertex AI.

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 Model Anda.

Variabel yang ditetapkan oleh Vertex AI

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

Perintah titik entri container dapat mengakses variabel ini. Untuk mempelajari kolom Vertex AI API mana yang juga dapat mereferensikan variabel ini, baca referensi API untuk ModelContainerSpec.

Catatan: Petunjuk Docker yang digunakan untuk membangun image container, seperti RUN, tidak dapat mengakses variabel ini, karena Anda harus membangun image container sebelum Anda memberikannya ke Vertex AI.

Catatan: Vertex AI menetapkan nilai beberapa variabel berikut saat Anda men-deploy Model sebagai DeployedModel ke Endpoint. Anda dapat mereferensikan kolom API lain saat membuat Model, dan nilainya akan diperluas setiap kali Anda men-deploy Model.

Nama variabel	Nilai default	Cara mengonfigurasi nilai	Detail
AIP_ACCELERATOR_TYPE	Tidak ditetapkan	Saat Anda men-deploy Model sebagai DeployedModel ke resource Endpoint, tetapkan kolom dedicatedResources.machineSpec.acceleratorType.	Jika berlaku, variabel ini menentukan jenis akselerator yang digunakan oleh instance virtual machine (VM) tempat container berjalan.
AIP_DEPLOYED_MODEL_ID	String digit yang mengidentifikasi DeployedModel tempat Model container ini di-deploy.	Tidak dapat dikonfigurasi	Nilai ini adalah kolom id DeployedModel.
AIP_ENDPOINT_ID	String digit yang mengidentifikasi Endpoint tempat Model container di-deploy.	Tidak dapat dikonfigurasi	Nilai ini adalah segmen terakhir dari kolom name Endpoint (setelah endpoints/).
AIP_FRAMEWORK	CUSTOM_CONTAINER	Tidak dapat dikonfigurasi
AIP_HEALTH_ROUTE	/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL Dalam string ini, ganti ENDPOINT dengan nilai variabel AIP_ENDPOINT_ID dan ganti DEPLOYED_MODEL dengan nilai variabel AIP_DEPLOYED_MODEL_ID.	Saat Anda membuat Model, tetapkan kolom containerSpec.healthRoute.	Variabel ini menentukan jalur HTTP di container yang menjadi tujuan Vertex AI mengirimkan health check.
AIP_HTTP_PORT	8080	Saat Anda membuat Model, tetapkan kolom containerSpec.ports. Entri pertama di kolom ini menjadi nilai AIP_HTTP_PORT.	Vertex AI 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 men-deploy Model sebagai DeployedModel ke resource Endpoint, tetapkan kolom dedicatedResources.machineSpec.machineType.	Variabel ini menentukan jenis VM yang dijalankan oleh container.
AIP_MODE	PREDICTION	Tidak dapat dikonfigurasi	Variabel ini menandakan bahwa container sedang berjalan di Vertex AI untuk menampilkan 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 Vertex AI.
AIP_MODE_VERSION	1.0.0	Tidak dapat dikonfigurasi	Variabel ini menandakan versi persyaratan container kustom (dokumen ini) yang diperkirakan Vertex AI akan dipenuhi oleh container. Dokumen ini diperbarui sesuai dengan pembuatan versi semantik.
AIP_MODEL_NAME	Nilai variabel AIP_ENDPOINT_ID	Tidak dapat dikonfigurasi	Lihat baris AIP_ENDPOINT_ID. Variabel ini ada karena alasan kompatibilitas.
AIP_PREDICT_ROUTE	/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict Dalam string ini, ganti ENDPOINT dengan nilai variabel AIP_ENDPOINT_ID dan ganti DEPLOYED_MODEL dengan nilai variabel AIP_DEPLOYED_MODEL_ID.	Saat Anda membuat Model, tetapkan kolom containerSpec.predictRoute.	Variabel ini menentukan jalur HTTP di container yang menjadi tujuan Vertex AI meneruskan permintaan prediksi.
AIP_PROJECT_NUMBER	Nomor project dari project Google Cloud tempat Anda menggunakan Vertex AI	Tidak dapat dikonfigurasi
AIP_STORAGE_URI	Jika Anda tidak menetapkan kolom artifactUri saat membuat Model: string kosong Jika Anda menetapkan kolom artifactUri saat membuat Model: Cloud Storage URI (dimulai dengan gs://) yang menentukan direktori dalam bucket yang dikelola oleh Vertex AI	Tidak dapat dikonfigurasi	Variabel ini menentukan direktori yang berisi salinan artefak model Anda, jika berlaku.
AIP_VERSION_NAME	Nilai variabel AIP_DEPLOYED_MODEL_ID	Tidak dapat dikonfigurasi	Lihat baris AIP_DEPLOYED_MODEL_ID. Variabel ini ada karena alasan kompatibilitas.

Variabel yang ditetapkan dalam resource Model

Saat membuat Model, Anda dapat menetapkan variabel lingkungan tambahan di kolom containerSpec.env.

Perintah titik entri container dapat mengakses variabel ini. Untuk mempelajari kolom Vertex AI API mana yang juga dapat mereferensikan variabel ini, baca referensi API untuk ModelContainerSpec.

Catatan: Petunjuk Docker yang digunakan untuk membangun image container, seperti RUN, tidak dapat mengakses variabel ini, karena Anda harus membangun image container sebelum Anda memberikannya ke Vertex AI.

Langkah selanjutnya

• Pelajari lebih lanjut cara menampilkan prediksi menggunakan container kustom, termasuk cara menentukan kolom API terkait container saat Anda mengimpor model.