Persyaratan penampung kustom untuk prediksi

Untuk menggunakan penampung kustom guna menyajikan prediksi dari model yang dilatih khusus, Anda harus memberikan gambar container Docker AI yang menjalankan server HTTP kepada Vertex AI. Dokumen ini menjelaskan persyaratan yang harus dipenuhi gambar container agar kompatibel dengan Vertex AI. Dokumen tersebut juga menjelaskan cara Vertex AI berinteraksi dengan penampung kustom setelah mulai dijalankan. Dengan kata lain, dokumen ini menjelaskan hal yang perlu Anda pertimbangkan saat mendesain gambar container untuk digunakan dengan Vertex AI.

Untuk panduan penggunaan gambar penampung kustom guna menayangkan prediksi, baca Menggunakan penampung kustom.

Persyaratan gambar container

Saat gambar container Docker Anda berjalan sebagai container, container harus menjalankan server HTTP. Secara khusus, penampung harus mendengarkan dan menanggapi pemeriksaan aktivitas, health check, dan permintaan prediksi. Subbagian berikut menjelaskan persyaratan ini secara mendetail.

Anda dapat menerapkan server HTTP dengan cara apa pun, menggunakan bahasa pemrograman apa pun, selama memenuhi persyaratan di bagian ini. Misalnya, Anda dapat menulis server HTTP khusus menggunakan kerangka kerja web seperti Flask atau menggunakan perangkat lunak yang menyajikan machine learning (ML) yang menjalankan server HTTP, seperti TensorFlow Serve, oborSize, atau KFServing Server.

Menjalankan server HTTP

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

Atau, Anda dapat menentukan kolom containerSpec.command dan containerSpec.args saat membuat resource Model untuk mengganti ENTRYPOINT gambar container Anda dan CMD masing-masing. Menentukan salah satu kolom ini memungkinkan Anda menggunakan gambar container yang tidak akan memenuhi persyaratan karena ENTRYPOINT atau CMD tidak kompatibel (atau tidak ada).

Bagaimana pun cara Anda menentukan perintah yang dijalankan oleh container saat dijalankan, pastikan bahwa perintah entri ini berjalan tanpa batas. Misalnya, jangan jalankan perintah yang memulai server HTTP di latar belakang lalu keluar; jika Anda melakukannya, penampung akan segera keluar setelah mulai berjalan.

Server HTTP Anda harus mendengarkan permintaan pada 0.0.0.0, pada port pilihan Anda. Saat Anda membuat Model, tentukan port ini di kolom containerSpec.ports. Untuk mempelajari cara penampung dapat mengakses nilai ini, baca bagian dokumen ini tentang AIP_HTTP_PORT variabel lingkungan.

Pemeriksaan kehidupan

Vertex AI melakukan pemeriksaan l Hidup ketika penampung Anda mulai untuk memastikan bahwa server Anda berjalan. Saat Anda menerapkan model yang dilatih secara khusus ke Endpoint resource, Vertex AI menggunakan penyelidikan TCP l Hidup untuk mencoba membuat sambungan TCP ke container Anda pada port. Probe melakukan hingga 4 upaya untuk membuat sambungan, menunggu 10 detik setelah setiap kegagalan. Jika pada saat ini masih belum ada sambungan yang dibuat, Vertex AI akan memulai ulang penampung Anda.

Server HTTP Anda tidak perlu melakukan perilaku khusus untuk menangani pemeriksaan ini. Selama aplikasi mendeteksi permintaan pada port yang dikonfigurasi, ProAvity dapat membuat sambungan.

Health check

Vertex AI secara berkala melakukan health check di server HTTP Anda saat sedang berjalan untuk memastikan bahwa siap menangani permintaan prediksi. Layanan menggunakan health check untuk mengirim permintaan HTTP GET ke lokasi health check yang dapat dikonfigurasi di server Anda. Tentukan jalur ini di kolom containerSpec.healthRoute saat Anda membuat Model. Untuk mempelajari cara penampung dapat mengakses nilai ini, baca bagian dokumen ini tentang AIP_HEALTH_ROUTE variabel lingkungan.

Konfigurasikan server HTTP untuk menanggapi 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. Isi isi respons tidak penting; Vertex AI mengabaikannya.

    Tanggapan ini menandakan bahwa server responsif.

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

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

Jika pemeriksaan respons pernah menerima respons tidak responsif dari server Anda (termasuk tidak ada respons dalam waktu 10 detik), maka akan mengirim hingga 3 health check tambahan pada interval 10 detik. Selama periode ini, Vertex AI tetap menganggap server Anda responsif. Jika penyelidikan menerima respons yang responsif terhadap salah satu pemeriksaan ini, maka penyelidikan akan segera kembali ke jadwal pemeriksaan kesehatan yang berselang-seling. Namun, jika penyelidikan menerima 4 respons tidak responsif berturut-turut, Vertex AI akan menghentikan perutean traffic prediksi ke penampung. (Jika resource DeployedModel diskalakan untuk menggunakan beberapa node prediksi, Vertex AI mengarahkan permintaan prediksi ke container sehat lainnya.)

Vertex AI tidak memulai ulang penampung; sebagai gantinya, health check terus mengirim permintaan health check yang berselang ke server yang tidak responsif. Jika menerima respons yang responsif, penampung akan ditandai sebagai respons yang sehat dan mulai mengarahkan lalu lintas prediksi ke sana.

Panduan praktis

Dalam beberapa kasus, server HTTP di container Anda sudah cukup untuk selalu merespons dengan kode status 200 OK untuk health check. Jika penampung Anda memuat sumber daya sebelum memulai server, penampung tidak responsif selama periode mulai dan selama periode ketika server HTTP gagal. Selain itu, responsnya pun dianggap responsif.

Untuk konfigurasi yang lebih canggih, Anda dapat merancang server HTTP dengan sengaja untuk merespons health check dengan status tidak responsif pada waktu tertentu. Misalnya, Anda mungkin ingin memblokir lalu lintas prediksi ke node untuk jangka waktu sehingga penampung dapat melakukan pemeliharaan.

Permintaan prediksi

Saat klien mengirim projects.locations.endpoints.predict permintaan ke Vertex AI API, Vertex AI 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 penampung dapat mengakses nilai ini, baca bagian dokumen ini tentang AIP_PREDICT_ROUTE variabel lingkungan.

Persyaratan permintaan

Setiap permintaan prediksi harus berukuran 1,5 MB atau lebih kecil. Server HTTP harus menerima permintaan prediksi yang memiliki Content-Type: application/json header HTTP dan isi JSON dengan format berikut:

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

Dalam permintaan ini:

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

  • PARAMETERS adalah objek JSON yang berisi parameter apa pun yang diperlukan penampung Anda untuk membantu menyajikan prediksi pada instance. Vertex AI menganggap kolom parameters bersifat opsional, sehingga Anda dapat mendesain container untuk mewajibkannya, hanya menggunakannya saat disediakan, atau mengabaikannya.

Pelajari lebih lanjut tentang persyaratan isi permintaan.

Persyaratan respons

Setiap respons prediksi harus berukuran 1,5 MB atau lebih kecil. Server HTTP harus mengirim respons dengan isi JSON yang memenuhi format berikut:

{
  "predictions": PREDICTIONS
}

Dalam respons ini, ganti PREDICTIONS dengan larik nilai JSON yang mewakili prediksi yang telah dibuat oleh penampung Anda untuk setiap INSTANCES dalam permintaan yang sesuai.

Setelah server HTTP mengirim respons ini, Vertex AI menambahkan deployedModelId kolom ke respons sebelum mengembalikannya ke klien. Kolom ini menentukan DeployedModel yang berada di Endpoint yang mengirimkan respons. Pelajari lebih lanjut tentang format isi respons.

Persyaratan publikasi gambar container

Anda harus memasukkan gambar container ke Artefact Registry atau ke Container Registry agar dapat menggunakannya dengan Vertex AI. Pelajari cara mendorong gambar container ke Artifact Registry atau cara mendorong gambar container ke Container Registry.

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

Lokasi

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

Jika Anda menggunakan Container Registry, repositori Anda dapat menggunakan salah satu hostname Container Registry.

Izin

Vertex AI harus memiliki izin untuk menarik gambar container saat Anda membuat Model. Secara khusus:

Agen Layanan Vertex AI 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 service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, dengan PROJECT_NUMBER diganti dengan nomor project project Vertex AI Anda.

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

Di sisi lain, jika Anda telah mengirimkan gambar container ke project Google Cloud yang berbeda dari project tempat Anda menggunakan Vertex AI, Anda harus memberikan peran Artefact Registry Reader untuk repositori Registry Artefak ke Agen Layanan Vertex AI atau berikan peran Penampil Objek Penyimpanan untuk bucket Cloud Storage yang digunakan Container Registry ke Agen Layanan Vertex AI.

Mengakses artefak model

Saat membuat Model khusus yang dilatih tanpa penampung kustom, Anda harus menentukan URI direktori Cloud Storage dengan artefak model sebagai kolom artifactUri. Saat Anda membuat Model dengan penampung kustom, menyediakan artefak model di Cloud Storage bersifat opsional.

Jika gambar container menyertakan artefak model yang Anda butuhkan untuk menyajikan prediksi, maka tidak perlu memuat file dari Cloud Storage. Namun, jika Anda menyediakan artefak model dengan menentukan kolom artifactUri, penampung harus memuat artefak ini saat mulai berjalan. Saat Vertex AI memulai penampung Anda, variabel lingkungan AIP_STORAGE_URI disetel ke URI Cloud Storage yang dimulai dengan gs://. Perintah titik masuk penampung Anda dapat mengunduh direktori yang ditentukan oleh URI ini untuk mengakses artefak model.

Perhatikan bahwa nilai variabel lingkungan AIP_STORAGE_URI tidak sama 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 yang berbeda, yang dikelola oleh Vertex AI. Vertex AI mengisi direktori ini saat Anda membuat Model. Anda tidak dapat memperbarui konten direktori. Jika Anda ingin menggunakan artefak model baru, Anda harus membuat 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 khusus saat menerapkan Model ke Endpoint, Vertex AI otomatis memberikan akun layanan yang Anda tentukan sebagai 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 mengonfigurasi autentikasi secara eksplisit.

Variabel lingkungan yang tersedia di penampung

Saat berjalan, perintah titik masuk penampung dapat mereferensikan variabel lingkungan yang telah Anda konfigurasikan secara manual, serta variabel lingkungan yang disetel secara otomatis oleh Vertex AI. Bagian ini menjelaskan setiap cara untuk menetapkan variabel lingkungan, dan memberikan detail tentang variabel yang ditetapkan secara otomatis oleh Vertex AI.

Variabel yang ditetapkan dalam gambar container

Untuk menyetel variabel lingkungan di gambar container saat Anda membuatnya, gunakan ENV petunjuk Docker. Jangan tetapkan variabel lingkungan apa pun yang diawali dengan awalan AIP_.

Perintah titik masuk penampung dapat menggunakan variabel lingkungan ini, tetapi Anda tidak dapat mereferensikannya di salah satu kolom API Model.

Variabel yang ditetapkan oleh Vertex AI

Saat Vertex AI mulai menjalankan container, variabel lingkungan berikut akan disetel di lingkungan container. Setiap variabel diawali dengan awalan AIP_. Jangan tetapkan secara manual variabel lingkungan apa pun yang menggunakan awalan ini.

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

Nama variabel Nilai default Cara mengonfigurasi nilai Detail
AIP_ACCELERATOR_TYPE Tidak disetel Saat Anda menerapkan Model sebagai DeployedModel ke resource Endpoint, setel kolom dedicatedResources.machineSpec.acceleratorType. Jika berlaku, variabel ini menentukan jenis akselerator yang digunakan oleh instance mesin virtual (VM) yang menjalankan container.
AIP_DEPLOYED_MODEL_ID String digit yang mengidentifikasi DeployedModel tempat Model penampung ini telah diterapkan. Tidak dapat dikonfigurasi Nilai ini adalah kolom id DeployedModel.
AIP_ENDPOINT_ID String digit yang mengidentifikasi Endpoint tempat Model penampung telah diterapkan. 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, setel kolom containerSpec.healthRoute. Variabel ini menentukan jalur HTTP pada penampung yang dikirimi health check untuk Vertex AI.
AIP_HTTP_PORT 8080 Saat membuat Model, tetapkan kolom containerSpec.ports. Entri pertama di kolom ini menjadi nilai AIP_HTTP_PORT. Vertex AI mengirimkan pemeriksaan aktivitas, health check, dan permintaan prediksi ke port ini pada container. Server HTTP penampung Anda harus mendengarkan permintaan pada port ini.
AIP_MOLDINE_TYPE Tidak ada default, harus dikonfigurasi Saat Anda menerapkan Model sebagai DeployedModel ke resource Endpoint, setel kolom dedicatedResources.machineSpec.machineType. Variabel ini menentukan jenis VM yang menjalankan container.
AIP_MODE PREDICTION Tidak dapat dikonfigurasi Variabel ini menandakan bahwa penampung berjalan di Vertex AI untuk menayangkan 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 Vertex AI.
AIP_MODE_VERSION 1.0.0 Tidak dapat dikonfigurasi Variabel ini menandakan versi persyaratan penampung kustom (dokumen ini) yang diharapkan oleh Vertex AI untuk ditampung 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 membuat Model, tetapkan kolom containerSpec.predictRoute. Variabel ini menentukan jalur HTTP pada penampung yang meneruskan permintaan prediksi Vertex.
AIP_PROJECT_NUMBER Nomor project project Google Cloud tempat Anda menggunakan Vertex AI Tidak dapat dikonfigurasi
AIP_STORAGE_URI
  • Jika Anda tidak menyetel kolom artifactUri saat membuat Model: string kosong
  • Jika Anda menyetel kolom artifactUri saat membuat Model: URI Cloud Storage (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 di resource Model

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

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

Langkah berikutnya