Halaman ini diterjemahkan oleh Cloud Translation API.

Menyesuaikan persyaratan container untuk inferensi

Agar dapat menggunakan container kustom untuk menampilkan inferensi 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 inferensi, 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 inferensi. 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 petunjuk ENTRYPOINT ini berjalan tanpa batas. Misalnya, 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 dapat secara opsional menentukan startup_probe atau health_probe.

Pemeriksaan startup memeriksa apakah aplikasi container telah dimulai. Jika pemeriksaan startup tidak disediakan, tidak ada pemeriksaan startup dan pemeriksaan kondisi langsung dimulai. Jika pemeriksaan startup disediakan, health check tidak dilakukan hingga pemeriksaan startup berhasil.

Aplikasi lama yang mungkin memerlukan waktu startup tambahan pada inisialisasi pertama 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.

Pemeriksaan kesehatan memeriksa apakah container siap menerima traffic. Jika pemeriksaan kondisi 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 telah dimuat dan siap menerima traffic harus mengonfigurasi pemeriksaan kondisi. Misalnya, aplikasi dapat menampilkan 200 OK untuk menunjukkan keberhasilan meskipun status pemuatan model sebenarnya yang ada di isi respons menunjukkan bahwa model mungkin tidak dimuat dan oleh karena itu mungkin belum siap menerima traffic. Dalam hal ini, pemeriksaan kondisi harus dikonfigurasi agar hanya menampilkan keberhasilan saat model dimuat dan siap untuk menayangkan traffic.

Untuk melakukan pemeriksaan, Vertex AI menjalankan perintah exec yang ditentukan di container target. Jika berhasil, perintah akan menampilkan 0, dan container dianggap aktif dan berfungsi dengan baik.

Health check default

Secara default, Vertex AI secara bergantian melakukan health check di server HTTP Anda saat sedang berjalan untuk memastikannya siap menangani permintaan inferensi. 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 inferensi, tanggapi permintaan health check dalam waktu 10 detik dengan kode status 200 OK. Isi dari isi respons tidaklah penting; Vertex AI mengabaikannya.

Respons ini menandakan bahwa server responsif.
Jika server belum siap menangani permintaan inferensi, jangan merespons permintaan health check dalam waktu 10 detik, atau merespons dengan kode status apa pun kecuali untuk 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 inferensi ke container. (Jika resource DeployedModel diskalakan untuk menggunakan beberapa node inferensi, Vertex AI akan merutekan permintaan inferensi ke container lain yang responsif.)

Vertex AI 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 inferensi 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 inferensi ke sebuah node selama jangka waktu tertentu sehingga container dapat melakukan pemeliharaan.

Permintaan inferensi

Saat klien mengirim permintaan projects.locations.endpoints.predict ke Vertex AI API, Vertex AI akan meneruskan permintaan ini sebagai permintaan POST HTTP ke jalur inferensi 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 inferensi harus berukuran 1,5 MB atau lebih kecil. Server HTTP harus menerima permintaan inferensi 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 inferensi.
PARAMETERS adalah objek JSON yang berisi parameter apa pun yang diperlukan container Anda untuk membantu menyajikan inferensi 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 inferensi harus berukuran 1,5 MB atau lebih kecil. Server HTTP harus mengirimkan respons dengan isi JSON yang memenuhi format berikut:

{
  "predictions": INFERENCES
}

Dalam respons ini, ganti INFERENCES dengan array nilai JSON yang mewakili inferensi 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.

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.

Lokasi

Saat Anda menggunakan Artifact Registry, repositori harus menggunakan region yang cocok dengan endpoint lokasi 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, Vertex AI Service Agent untuk project Anda harus memiliki izin peran Artifact Registry Reader (roles/artifactregistry.reader) untuk repositori image container.

Vertex AI menggunakan Vertex AI Service Agent untuk project Anda guna berinteraksi dengan layanan Google Cloud lainnya. Akun layanan ini memiliki alamat email service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, di mana PROJECT_NUMBER diganti dengan nomor project dari project Vertex AI Anda.

Jika Anda telah mengirim image container ke project Google Cloud yang sama 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 projectGoogle Cloud yang berbeda dengan project tempat Anda menggunakan Vertex AI, Anda harus memberikan peran Artifact Registry Reader untuk repositori Artifact Registry kepada Vertex AI Service Agent.

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 menyajikan inferensi, 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://. Instruksi ENTRYPOINT 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 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, instruksi 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 tetapkan variabel lingkungan yang dimulai dengan awalan AIP_.

Petunjuk ENTRYPOINT 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 tetapkan secara manual variabel lingkungan apa pun yang menggunakan awalan ini.

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

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 inferensi 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 menyajikan inferensi 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 inferensi.
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.