Memecahkan masalah deployment agen

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

Error Template bawaan

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

Error server internal

Masalah:

Anda menerima pesan error yang mirip dengan pesan berikut:

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

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

Kemungkinan penyebab:

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

Solusi yang direkomendasikan:

  • Status kotor di LangchainAgent. Buat instance baru LangchainAgent atau hapus agent.set_up() dari kode sebelum men-deploy agen.
  • Spesifikasi paket yang 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 terkait "pickle" atau "pickling" identik dengan error "serialisasi"), hal ini mungkin disebabkan oleh salah satu masalah yang dijelaskan di bagian ini.

Versi Pydantic

Masalah:

Anda menerima pesan error yang mirip dengan pesan berikut:

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:

Perbarui 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 diperbarui.

Versi Cloudpickle

Masalah:

Anda menerima pesan error yang mirip dengan pesan berikut:

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 mungkin 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 menerima pesan error yang mirip dengan pesan berikut:

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 saat 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 Platform Agen (baik Anda sendiri maupun 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 menerima pesan error yang mirip dengan pesan berikut:

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 kemungkinan disebabkan oleh masalah dengan interpolasi string dalam versi google-cloud-aiplatform yang lebih lama dari versi 1.49.0. Masalah ini telah diperbaiki dalam 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:

Perbarui 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 diperbarui.

Error pelanggaran VPC-SC

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

Error izin

Masalah:

Anda menerima pesan error yang mirip dengan pesan berikut:

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 aturan ingress yang diperlukan tidak ada di perimeter VPC-SC.

Solusi yang direkomendasikan:

Jika Anda menggunakan Agent Platform di lingkungan VPC-SC, Anda harus membuat aturan ingress di perimeter untuk mengizinkan ingress dari Agen Layanan Reasoning Engine (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.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 menerima pesan error yang mirip dengan pesan berikut:

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 dimaksud. Periksa apakah Anda memiliki peran Pengguna Akun Layanan (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 menerapkan kebijakan organisasi iam.disableCrossProjectServiceAccountUsage. Jika ya, minta administrator untuk menonaktifkan kebijakan tersebut.

Server metadata tidak tersedia

Masalah:

Anda menerima pesan error yang mirip dengan pesan berikut:

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 Reasoning Engine AI Platform tidak memiliki iam.serviceAccounts.getAccessToken izin 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 untuk memberikan peran Pembuat Token Akun Layanan (roles/iam.serviceAccountTokenCreator) kepada Agen Layanan Reasoning Engine AI Platform dari project agen di akun layanan kustom.

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

Error resource habis atau batas 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:

  • Terapkan strategi backoff eksponensial dan coba lagi dalam skrip deployment.
  • Verifikasi penggunaan saat ini terhadap batas di halaman Google Cloud Kuota untuk "Agent Platform API".
  • Kurangi frekuensi deployment serentak.

Referensi dukungan

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