Sebagian atau seluruh informasi di halaman ini mungkin tidak berlaku untuk Cloud de Confiance dari S3NS. Lihat Perbedaan dengan Google Cloud untuk mengetahui detail selengkapnya.

Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Memecahkan masalah deployment agen

Dokumen ini menjelaskan cara mengatasi error yang mungkin Anda alami saat men-deploy agen ke Agent Runtime. Topik ini membahas berbagai masalah umum, termasuk kegagalan serialisasi, error izin, dan pelanggaran batas VPC-SC.

Catatan: Untuk menelusuri dan memfilter log error agen, gunakan Logs Explorer, pilih RESOURCE TYPE ke "Vertex AI Reasoning Engine", lalu pilih nilai RESOURCE CONTAINER (yaitu nomor project) dan nilai REASONING ENGINE ID yang sesuai.

Error Template yang Telah Dibuat Sebelumnya

Jika Anda mengalami masalah dengan template LangchainAgent selama deployment, hal itu mungkin disebabkan oleh salah satu masalah di bagian ini.

Error server internal

Masalah:

Anda akan menerima pesan error yang mirip dengan berikut ini:

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

Sayangnya, ini adalah error umum untuk setiap masalah pada container saat runtime, dan kemungkinan penyebabnya adalah salah satu dari banyak error yang mungkin terjadi.

Kemungkinan penyebab:

Status kotor pada LangchainAgent. Hal ini mungkin terjadi jika .set_up() dipanggil di LangchainAgent sebelum men-deploy agen.
Versi paket yang tidak konsisten. Hal ini dapat terjadi jika paket yang diinstal di lingkungan pengembangan berbeda dengan paket yang diinstal di lingkungan jarak jauh di Agent Runtime.

Solusi yang direkomendasikan:

Status kotor pada LangchainAgent. Buat instance baru dari LangchainAgent atau hapus agent.set_up() dari kode sebelum men-deploy agen.
Spesifikasi paket tidak konsisten. Lihat bagian tentang memecahkan masalah error serialisasi.

Error serialisasi

Secara umum, penting untuk memastikan bahwa lingkungan "lokal" dan "jarak jauh" disinkronkan saat men-deploy agen. Anda dapat memastikan hal ini dengan menentukan requirements= saat men-deploy agen.

Jika Anda mengalami masalah dengan serialisasi (error yang terkait dengan "pickle" atau "pickling" identik dengan error "serialisasi"), hal ini mungkin disebabkan oleh salah satu masalah yang dijelaskan di bagian ini.

Versi Pydantic

Masalah:

Anda akan menerima pesan error yang mirip dengan berikut ini:

PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator

Kemungkinan penyebab:

Hal ini mungkin terjadi jika paket pydantic Anda lebih lama dari versi 2.6.4. Untuk memeriksa versi yang Anda gunakan, jalankan perintah berikut di terminal:

pip show pydantic

Solusi yang direkomendasikan:

Update paket Anda dengan menjalankan perintah berikut di terminal:

pip install pydantic --upgrade

Jalankan perintah berikut di terminal untuk memverifikasi bahwa Anda menggunakan versi 2.6.4 atau yang lebih baru:

pip show pydantic

Jika Anda berada di instance notebook (misalnya, Jupyter, Colab, atau Workbench), Anda mungkin perlu memulai ulang runtime untuk menggunakan paket yang diupdate.

Versi Cloudpickle

Masalah:

Anda akan menerima pesan error yang mirip dengan berikut ini:

AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>

Kemungkinan penyebab:

Hal ini dapat terjadi jika versi paket cloudpickle Anda berbeda di lingkungan pengembangan dan lingkungan deployment. Untuk memeriksa versi yang Anda gunakan dalam pengembangan, jalankan perintah berikut di terminal:

pip show cloudpickle

Solusi yang direkomendasikan:

Deploy versi cloudpickle yang sama di kedua lingkungan, seperti lingkungan pengembangan lokal dan agen yang di-deploy dari jarak jauh dengan menentukan requirements= saat men-deploy agen.

Error server internal

Masalah:

Anda akan menerima pesan error yang mirip dengan berikut ini:

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

Kemungkinan penyebab:

Hal ini mungkin terjadi jika sys_version= berbeda dari lingkungan pengembangan saat men-deploy agen.

Solusi yang direkomendasikan:

Setelah men-deploy agen, pertimbangkan untuk menghapus sys_version= dari argumen input. Jika Anda masih mengalami masalah, ajukan laporan bug.

Error bucket Cloud Storage

Jika Anda mengalami masalah dengan bucket staging Cloud Storage yang digunakan pada waktu deployment untuk mengumpulkan dan mengupload agen, hal ini mungkin disebabkan oleh salah satu masalah berikut:

Error izin

Solusi yang direkomendasikan:

Jika Anda ingin menggunakan bucket yang sudah ada: pastikan akun utama yang diautentikasi untuk menggunakan Agent Platform (baik Anda sendiri atau akun layanan) memiliki akses Storage Admin ke bucket, dan berikan izin ke akun layanan.

Atau, Anda dapat menentukan bucket baru saat men-deploy agen dan SDK akan membuat bucket dengan izin yang diperlukan.

Jika Anda masih mengalami masalah, ajukan laporan bug.

Subdirektori bucket Cloud Storage tidak dibuat

Masalah:

Anda akan menerima pesan error yang mirip dengan berikut ini:

NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.

(Error 404 terjadi saat sistem mencoba menyalin ke folder yang tidak ada.)

Kemungkinan penyebab:

Hal ini mungkin disebabkan oleh masalah interpolasi string di versi google-cloud-aiplatform sebelum versi 1.49.0. Masalah ini diperbaiki di versi yang lebih baru. Untuk memeriksa versi google-cloud-aiplatform yang Anda gunakan, jalankan perintah berikut di terminal:

pip show google-cloud-aiplatform

Solusi yang direkomendasikan:

Update paket Anda dengan menjalankan perintah berikut di terminal:

pip install google-cloud-aiplatform --upgrade

Pastikan Anda menggunakan google-cloud-aiplatform versi 1.49.0 atau yang lebih baru dengan menjalankan perintah berikut di terminal:

pip show google-cloud-aiplatform

Jika Anda menggunakan instance notebook (misalnya, Jupyter atau Colab atau Workbench), Anda mungkin perlu memulai ulang runtime sebelum dapat menggunakan paket yang diupdate.

Error pelanggaran VPC-SC

Jika Anda mengalami masalah dengan VPC-SC, salah satu masalah berikut mungkin menjadi penyebabnya:

Error izin

Masalah:

Anda akan menerima pesan error yang mirip dengan berikut ini:

Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.

atau:

Request is prohibited by organization's policy.

Kemungkinan penyebab:

Hal ini kemungkinan disebabkan oleh tidak adanya aturan ingress yang diperlukan di perimeter VPC-SC.

Solusi yang direkomendasikan:

Jika Anda menggunakan Agent Platform di lingkungan VPC-SC, Anda harus membuat aturan ingress di perimeter Anda untuk mengizinkan ingress dari Agen Layanan Mesin Penalaran (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com) ke layanan storage.googleapis.com dan layanan artifactregistry.googleapis.com.

Error akun layanan kustom

Jika Anda mengalami masalah dengan akun layanan, salah satu masalah berikut mungkin menjadi penyebabnya:

Bertindak sebagai akun layanan

Masalah:

Anda akan menerima pesan error yang mirip dengan berikut ini:

You do not have permission to act as service_account.

Kemungkinan penyebab:

Anda mungkin tidak memiliki izin iam.serviceAccounts.actAs di akun layanan kustom yang digunakan untuk deployment. Perhatikan bahwa dalam sistem multi-agen yang memiliki beberapa akun layanan kustom, satu penulis atau deployer agen dapat bertindak sebagai beberapa akun layanan. Jika Anda menggunakan akun layanan yang salah, error ini adalah perilaku yang diharapkan

Selain itu, Anda mungkin mengalami error ini jika akun layanan kustom berada di project yang berbeda dengan project tempat Anda men-deploy agen, dan kebijakan organisasi iam.disableCrossProjectServiceAccountUsage diterapkan di project akun layanan.

Lihat Akun layanan kustom lintas project untuk mengetahui daftar lengkap konfigurasi yang diperlukan untuk skenario ini.

Solusi yang direkomendasikan:

Pastikan Anda menggunakan akun layanan yang diinginkan. Periksa apakah Anda memiliki peran Service Account User (roles/iam.serviceAccountUser) di akun layanan ini. Jika tidak, minta administrator untuk memberi Anda peran di akun layanan ini.

Jika Anda berada dalam skenario lintas project, periksa apakah project akun layanan Anda telah menerapkan kebijakan organisasi iam.disableCrossProjectServiceAccountUsage. Jika demikian, minta administrator Anda untuk menonaktifkan kebijakan tersebut.

Server metadata tidak tersedia

Masalah:

Anda akan menerima pesan error yang mirip dengan berikut ini:

ServiceUnavailable: 503 Getting metadata from plugin failed with error

atau

Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token

Kemungkinan penyebab:

Hal ini dapat terjadi jika akun layanan kustom dan agen Anda berada di project yang berbeda dan Agen Layanan Mesin Penalaran Platform AI tidak memiliki izin iam.serviceAccounts.getAccessToken di akun layanan kustom.

Lihat Akun layanan kustom lintas project untuk mengetahui daftar lengkap konfigurasi yang diperlukan untuk skenario ini.

Solusi yang direkomendasikan:

Minta administrator Anda untuk memberikan peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator) pada akun layanan kustom kepada Agen Layanan Mesin Penalaran Platform AI dari project agen.

Agen Layanan Mesin Penalaran Platform AI harus berada di project yang sama dengan yang Anda gunakan untuk men-deploy agen. Binding IAM dari pemberian peran harus berada dalam project tempat akun layanan kustom berada.

Resource habis atau error pembatasan kapasitas (Error 429)

Masalah:

Deployment gagal dengan status Error 429 atau RESOURCE_EXHAUSTED.

Kemungkinan penyebab:

Project telah melampaui batas kapasitas API atau kuota permintaan serentak.

Solusi yang direkomendasikan:

Menerapkan strategi backoff eksponensial dan percobaan ulang dalam skrip deployment.
Verifikasi penggunaan saat ini terhadap batas di halaman Cloud de Confiance Kuota untuk "Agent Platform API".
Mengurangi frekuensi deployment serentak.

Region mencapai batas kapasitas untuk sementara

Masalah:

Deployment gagal dengan status 429, RESOURCE_EXHAUSTED dan pesan yang menyatakan bahwa region tersebut sementara mencapai kapasitas untuk jumlah total memori atau CPU yang diizinkan.

Kemungkinan penyebab:

Deployment agen di suatu region memanfaatkan kumpulan kapasitas inferensi yang dikelola Agent Runtime untuk Anda dan digunakan bersama oleh semua pelanggan di region tersebut. Jika pool habis, deployment baru di region tersebut akan gagal hingga kapasitas tersedia.

Batas ini bukan salah satu kuota project Anda. Kuota ini tidak muncul di halamanCloud de Confiance Kuota, dan tidak dapat dinaikkan dengan meminta penambahan kuota.

Solusi yang direkomendasikan:

Deploy ke wilayah yang didukung lain. Ini adalah cara tercepat untuk membatalkan pemblokiran deployment.
Coba lagi nanti. Region yang mencapai kapasitas adalah masalah sementara yang biasanya akan teratasi dengan sendirinya.
Minta jumlah memori atau CPU yang lebih kecil untuk agen Anda. Deployment yang lebih kecil mungkin sesuai dengan kapasitas yang tersisa.
Hubungi dukungan jika deployment di suatu region terus gagal dengan cara ini. Meskipun kami tidak dapat menaikkan batas, laporan Anda membantu kami mengarahkan kapasitas ke tempat yang diperlukan.

Solusi yang tidak berlaku:

Menghapus agen yang ada tidak akan mengosongkan kapasitas untuk batas ini, karena kapasitas tidak hanya digunakan oleh project Anda.
Meminta penambahan kuota tidak akan berpengaruh, karena batas tersebut bukan kuota project.

Instance maksimum melebihi batas regional

Masalah:

Deployment gagal dengan status 429, RESOURCE_EXHAUSTED dan pesan yang menyatakan bahwa spec.deployment_spec.max_instances melebihi jumlah maksimum instance yang didukung untuk CPU atau memori yang diminta di resource_limits region.

Kemungkinan penyebab:

Saat Anda men-deploy agen, Agent Runtime mengalikan spec.deployment_spec.max_instances dengan cpu dan memory per instance di spec.deployment_spec.resource_limits dan memeriksa apakah alokasi puncak agen tunggal ini sesuai dengan batas regional project inferensi yang mendasarinya. Jika Anda tidak menentukan max_instances, Agent Runtime akan menerapkan nilai default (seperti 200), yang di region dengan batas lebih rendah dapat melebihi instance maksimum yang didukung saat dikalikan dengan cpu atau memory per instance yang dikonfigurasi.

Solusi yang direkomendasikan:

Tetapkan spec.deployment_spec.max_instances ke nilai maksimum yang ditampilkan dalam pesan error (atau lebih sedikit).
Kurangi nilai cpu atau memory per instance di spec.deployment_spec.resource_limits.
Deploy agen ke wilayah yang didukung lain dengan batas yang lebih tinggi.

Solusi yang tidak berlaku:

Meminta penambahan kuota di halaman Kuota Cloud de Confiance project Anda tidak akan berpengaruh, karena batas ini diterapkan pada project penyaluran yang dikelola Google, bukan project Anda.
Menghapus agen lain dalam project Anda atau mencoba lagi tanpa mengubah max_instances atau resource_limits tidak akan menyelesaikan error ini, karena pemeriksaan mengevaluasi alokasi puncak deployment tunggal terhadap batas statis.

Error akses Secret Manager

Masalah:

Deployment gagal dengan status 400, INVALID_ARGUMENT (REASONING_ENGINE_SECRET_ACCESS_DENIED) dan pesan yang mirip dengan berikut:

The Reasoning Engine could not access `projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/VERSION_ID` referenced by `spec.deployment_spec.secret_env` (reason: FAILURE_REASON).

Kemungkinan penyebab:

NOT_FOUND: ID secret atau ID versi yang ditentukan di secret_env tidak ada di Secret Manager dalam project yang sama dengan agen yang di-deploy, atau berisi kesalahan ketik.
DESTROYED atau DISABLED: Versi secret yang direferensikan di Secret Manager dalam status dihancurkan atau dinonaktifkan.
PERMISSION_DENIED: Akun layanan yang digunakan oleh agen tidak memiliki peran Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) pada secret yang direferensikan.

Solusi yang direkomendasikan:

Untuk NOT_FOUND, DESTROYED, atau DISABLED:
1. Di halaman Secret Manager pada project tempat Anda men-deploy agen, pastikan setiap SECRET_ID dan VERSION_ID yang direferensikan di secret_env ada dan dalam status Enabled.
2. Jika versi yang direferensikan dinonaktifkan atau dihancurkan, aktifkan versi yang valid atau update secret_env untuk mereferensikan versi yang diaktifkan.
Untuk PERMISSION_DENIED: Berikan peran Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) pada secret (atau project yang berisi secret) ke akun layanan yang mengambil secret:
- Akun layanan default: Berikan peran ke Agen Layanan Mesin Penalaran Platform AI (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com).
- Akun layanan kustom: Berikan peran ke akun layanan kustom yang dikonfigurasi di agen.

Waktu tunggu build image container habis

Masalah:

Deployment gagal dengan status 504, DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT) dan pesan yang menyatakan bahwa image container agen tidak selesai dibuat tepat waktu.

Kemungkinan penyebab:

Saat Anda men-deploy dari file sumber, Agent Runtime akan membangun image container yang menginstal kode Anda dan dependensinya. Deployment akan gagal jika build masih berjalan saat waktu yang diizinkan habis. Build biasanya memerlukan waktu terlalu lama karena dependensi yang diinstal, misalnya:

Daftar panjang paket di requirements, termasuk paket yang tidak digunakan agen.
Paket tanpa wheel bawaan untuk lingkungan build, yang dikompilasi dari sumber selama build.
Versi yang tidak disematkan atau disematkan secara longgar, yang memperlambat resolusi dependensi.

Solusi yang direkomendasikan:

Periksa log build yang ditautkan di kolom logs_url metadata error untuk melihat langkah mana yang sedang berjalan saat build berhenti.
Hapus dependensi yang tidak diperlukan dan sematkan versi semua paket yang diperlukan.
Prioritaskan paket dan versi yang memublikasikan wheel bawaan, sehingga tidak ada yang dikompilasi selama build.
Coba lagi deployment. Build terkadang dapat berjalan lebih lama dari biasanya karena alasan yang tidak terkait dengan kode Anda.

Container tidak dimulai tepat waktu

Masalah:

Deployment gagal dengan status 504, DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT) dan pesan yang menyatakan bahwa container agen tidak mulai menyajikan tepat waktu.

Kemungkinan penyebab:

Setelah image dibuat, Agent Runtime akan memulai container agen dan menunggu hingga container siap menyalurkan permintaan. Deployment akan gagal jika container masih dimulai saat waktu yang diizinkan habis. Penyebab umumnya dapat mencakup hal berikut:

Pekerjaan yang lambat pada waktu impor, seperti memuat model atau file besar saat modul agen diimpor.
Pekerjaan yang lambat atau memblokir dalam metode set_up() agen, seperti panggilan jaringan yang menunggu layanan yang tidak dapat dijangkau.

Solusi yang direkomendasikan:

Periksa log container yang ditautkan di kolom logs_url metadata error untuk melihat tempat startup terhenti.
Pindahkan inisialisasi yang mahal dari waktu impor modul, dan minimalkan jumlah langkah di set_up() dengan cepat. Tunda pekerjaan yang tidak diperlukan untuk menyajikan permintaan pertama.
Pastikan layanan apa pun yang dipanggil agen selama startup dapat dijangkau dari agen, dan tetapkan waktu tunggu pada panggilan tersebut sehingga tidak dapat memblokir startup tanpa batas waktu.
Jika log container menunjukkan bahwa agen dimulai secara normal, coba deploy ulang. Startup terkadang dapat memerlukan waktu lebih lama dari biasanya karena alasan yang tidak terkait dengan kode Anda.

Referensi dukungan

Jika masalah Anda masih belum terselesaikan, lihat panduan dukungan kami untuk mendapatkan bantuan.