Referensi AlphaEvolve API

Dokumen ini berfungsi sebagai referensi API tingkat produksi yang resmi dan spesifikasi sistem untuk AlphaEvolve Cloud API di bagian Google Cloud lapisan percakapan Discovery Engine. Spesifikasi ini menentukan hierarki resource bertingkat yang tepat, endpoint REST dan gRPC, batasan tingkat kolom, mesin status siklus proses, matriks diagnostik error, aturan sandbox keamanan, dan alur kerja integrasi yang diperlukan untuk merekayasa loop evaluasi dan pengontrol sisi klien yang sepenuhnya otomatis.

Mesin status siklus proses terpadu

Agen AlphaEvolve mengoordinasikan dua mesin status independen untuk memantau progres kampanye eksperimen dan mengelola penayangan serta eksekusi mutasi program individual.

Status siklus proses eksperimen

Eksperimen mewakili kampanye pengoptimalan secara keseluruhan. Resource ini diproses sebagai resource sisi server yang persisten dan bertransisi melalui status berikut:

  • CREATED: Status inisialisasi. Resource dideklarasikan dan dikonfigurasi, tetapi belum mengisi generasi awal atau mengirim panggilan API.

  • RUNNING: Status evaluasi aktif. Mesin ini secara bersamaan mengambil sampel kandidat induk, membuat mutasi kode melalui campuran LLM, dan melakukan streaming tugas ke evaluator.

  • PAUSED: Status penampungan sementara yang dipicu secara manual atau melalui idle_timeout pelindung otomatis. Pembuatan kode berhenti, dan pengiriman metrik pekerja yang ada dijeda.

  • COMPLETED: Status akhir yang menunjukkan bahwa penelusuran telah berhasil memenuhi alokasi target max_programs atau mencapai batas pembuatan strukturalnya.

  • FAILED: Status error terminal yang menunjukkan bahwa masalah lingkungan sistemik—seperti pengecualian kredensial API yang tidak tertangkap, kerusakan penyimpanan data, atau panik runner berturut-turut—menghentikan eksekusi pemrosesan.

Status program

Urutan validasi runtime diterapkan ke setiap varian kandidat.

Setiap mutasi kode yang dihasilkan berperilaku sebagai entity program terisolasi yang bertransisi melalui serangkaian status operasional terperinci dalam database populasi.

  1. INITIALIZED: Entri program dibuat di database, melacak silsilah leluhur dan keterkaitan program induknya.

  2. GENERATING: Tugas dikirim secara aktif ke backend campuran model bahasa untuk membuat draf atau mengubah blok kode fungsional tertentu.

  3. EVALUATING: Payload kode dikunci oleh proses pekerja evaluasi dan dieksekusi di dalam lingkungan test harness yang terisolasi.

  4. COMPLETED: Skor eksekusi dan insight struktural deskriptif disimpan dengan aman ke database evolusioner, dan program ditambahkan ke pool seleksi.

Mekanisme konkurensi dan penguncian

Program diperoleh oleh loop pekerja menggunakan mekanisme token kunci atomik untuk mencegah kondisi race atau overhead penilaian duplikat di seluruh topologi terdistribusi. Evaluator harus mengirimkan skema pemberian skor akhir bersama dengan token kunci pencocokan persis agar berhasil melakukan hasil kembali ke database.

Skema konfigurasi dan setelan

Ringkasan konfigurasi, parameter, dan default skema inti yang digunakan oleh runtime mesin AlphaEvolve.

AlphaEvolveExperimentConfig

Menentukan parameter struktural inti dan batasan terprogram dari jalannya eksperimen evolusioner.

Nama Kolom Jenis Default Batasan / Batas Nilai Deskripsi Teknis
title string Wajib Maks. 256 karakter Nama tampilan unik eksperimen.
problemDescription string Wajib Maksimal 5.000 karakter Spesifikasi formal masalah. Hal ini disisipkan langsung ke dalam konteks perintah untuk menetapkan aturan.
programLanguage string Wajib Nilai bentuk bebas Bahasa target codebase yang dikembangkan (misalnya, "python", "cpp", "verilog", "cuda", "julia", "java").
runSettings objek Wajib Memetakan ke skema RunSettings Parameter kecepatan dan waktu tunggu.
generationSettings objek Opsional Memetakan ke skema GenerationSettings Pemilihan model dan parameter konteks.
evolutionSettings objek Opsional Memetakan ke skema EvolutionSettings Parameter pemilihan induk dan keragaman.

RunSettings

Mengatur kecepatan throughput, batas paralelisme, dan waktu tunggu sistem otomatis.

Nama Kolom Jenis Default Batasan / Batas Nilai Deskripsi Teknis
maxPrograms int32 100 Min: 2, Maks: 100000 Total anggaran eksekusi (program untuk membuat dan mengevaluasi). Harus lebih besar dari 1.
concurrency int32 1 Min: 1, Maks: 30 Jumlah mutasi program paralel yang aktif dalam antrean. Nilai >30 tidak diizinkan.
maxDuration string 24 jam (86400 detik) String dayTimeDuration ISO 8601
Min: >0, Maks: 7 Hari		 Total waktu nyata yang diizinkan sebelum eksperimen dihentikan.
idleTimeout string 5 jam (Amerika Serikat/Eropa)
2 jam (global)		 String dayTimeDuration ISO 8601
Min: >0
Maks: default lokasi		 Durasi tidak ada aktivitas sebelum transisi otomatis ke PAUSED. Nilai defaultnya adalah 2 jam di global dan 5 jam di lokasi regional (us, eu). Durasi dibatasi oleh nilai default lokasi, sehingga penentuan nilai di atas nilai default lokasi (misalnya, 12 jam di global) akan diabaikan dan nilainya adalah 2 jam (tanpa error).

Setelan pembuatan

Skema GenerationSettings mengontrol perakitan perintah, periode konteks, dan konfigurasi model untuk mutasi:

  • context (string): Dokumentasi referensi, API tambahan, atau aturan opsional yang disediakan pengguna. Sebaiknya tetap di bawah 200.000 token. Ukuran konteks yang melebihi 200.000 token akan mengurangi perhatian model dan menurunkan kualitas mutasi.

  • includeFullProgramInPrompt (bool): Default false.

    • true: Perintah mutasi mencakup EVOLVE-BLOCK yang dapat diubah dan boilerplate yang tidak dapat diubah di sekitarnya (sangat direkomendasikan untuk penalaran struktural yang kompleks).

    • false: Hanya blok yang dapat diubah yang terlihat, sehingga menghemat konteks token.

  • models (array objek): Opsional. Setiap entri memberi nama model dan memberikan weight opsional, yang merupakan pangsa panggilan pembuatan model tersebut relatif terhadap entri lainnya. Jika Anda tidak menyertakan models, AlphaEvolve akan memilih default saat membuat eksperimen: model Gemini yang direkomendasikan Google untuk pembuatan kode dengan AlphaEvolve. Rekomendasi tersebut berubah saat model yang lebih baru dirilis. Mulai 29 September 2026, setelan defaultnya adalah gemini-3.8-flash. Untuk menggunakan model lain, tentukan model yang Anda inginkan di models. Untuk menyematkan model yang sama di setiap proses, setel models sendiri.

    Karena AlphaEvolve menyelesaikan default saat membuat eksperimen, eksperimen yang dibuat sebelum model default berubah akan mempertahankan model yang dicatat dalam konfigurasinya. Untuk memindahkan eksperimen yang ada ke Gemini 3.8 Flash, tentukan di models atau buat eksperimen baru.

    Contoh berikut mengirimkan sekitar sembilan dari sepuluh panggilan pembuatan ke model pertama dan sisanya ke model kedua. Bobot adalah rasio, jadi tidak harus berjumlah 1.

    "models": [
  {
    "name": "gemini-3.8-flash",
    "weight": 0.9
  },
  {
    "name": "gemini-3.1-pro-preview",
    "weight": 0.1
  }
]

Model yang didukung

Tetapkan models[].name ke salah satu nilai berikut. Anda dapat menggabungkan paling banyak dua model dalam satu eksperimen.

Nama model Wilayah penayangan
gemini-3.8-flash (default) global, us, eu
gemini-3.7-flash global, us, eu
gemini-3.5-flash global, us, eu
gemini-3.1-pro-preview global

AlphaEvolve memvalidasi models saat membuat eksperimen dan menampilkan INVALID_ARGUMENT untuk nama model yang tidak ada dalam tabel ini atau yang tidak tersedia di wilayah yang Anda minta.

Setelan evolusi

Skema EvolutionSettings mengontrol pengisian ulang model pulau dan probabilitas pengambilan sampel induk:

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (float): Probabilitas (0,0 hingga 1,0) untuk mengambil sampel program induk secara langsung dari batas Pareto aktif, bukan menggunakan pemilihan berbasis kebugaran standar. Parameter ini harus disetel ke 0.0 (dinonaktifkan) jika metrik yang dioptimalkan hanya menampilkan satu metrik skalar.

Model data program kandidat

Bagian ini menguraikan skema dan representasi data yang digunakan untuk menentukan dan mengatur struktur kode kandidat dalam database populasi.

AlphaEvolveProgramContent

Menentukan file dan struktur program kandidat.

  • files (array AlphaEvolveSourceFile): Daftar semua file yang membentuk codebase kandidat. Payload harus berisi setidaknya satu file sumber. Google merekomendasikan agar jumlah total file tetap 50 file per program kandidat; hal ini memberikan perhatian model yang optimal dan efisiensi jendela konteks.

  • description (string): Ringkasan yang dibuat secara otomatis yang menguraikan perubahan terprogram yang disarankan oleh model pembuatan (Maks. 1.000 karakter).

AlphaEvolveSourceFile

Mewakili setiap file kode sumber dalam codebase.

  • path (string): Tujuan jalur relatif ruang kerja (Wajib, Maks. 256 karakter). Setiap entri file sumber harus menentukan jalur yang tidak kosong. Jika mengonfigurasi ruang kerja Python, titik entri file yang dapat dieksekusi utama harus diberi nama "initial_program.py".

  • content (string): String kode sumber mentah yang terdiri dari blok penerapan fungsional. Google merekomendasikan agar ukuran codebase kumulatif di semua file tetap di bawah 4.000 hingga 5.000 baris kode (LOC); hal ini optimal untuk performa pembuatan mutasi dan perhatian model.

  • programLanguage (string): Tag pemetaan parser bahasa. String ini harus cocok secara eksplisit dengan bahasa yang ditetapkan dalam konfigurasi eksperimen induk.

  • description (string): Ringkasan opsional yang menguraikan arsitektur atau tujuan masing-masing file, yang diekspos ke LLM selama proses mutasi (Maks. 500 karakter).

AlphaEvolveProgramEvaluation

Payload terstruktur yang dikirimkan oleh instance peluncur klien kembali ke database evolusioner setelah eksekusi runtime.

  • scores (AlphaEvolveScores): Nilai metrik numerik objektif yang distandardisasi. Praktik terbaik mengharuskan pembatasan ini menjadi 3 hingga 5 metrik float yang berbeda; dimensi target yang berlebihan menurunkan performa pembanding Pareto multi-tujuan.

  • insights (array AlphaEvolveEvaluationInsight): Label semantik diagnostik dan rekaman aktivitas eksekusi bahasa alami yang dikirim kembali untuk membantu upaya pembuatan mutasi berikutnya oleh LLM (Maksimum 10 item yang direkomendasikan).

Format perumusan dan penyerapan skor

Aturan memaksimalkan

AlphaEvolve pada dasarnya beroperasi sebagai algoritma pendakian bukit monoton dan secara ketat memaksimalkan semua metrik numerik. Jika pipeline evaluasi Anda melacak target minimisasi (seperti meminimalkan latensi aplikasi dalam milidetik atau mengurangi penggunaan memori), Anda harus meniadakan nilai sebelum mengirimkannya kembali ke database: submitted_score = -latency_ms.

Idealnya, skor harus berkelanjutan. Metrik Boolean atau sangat diskrit tidak memberikan sinyal gradien yang memadai untuk eksplorasi pendakian bukit yang efektif.

Skema penyerapan satu tujuan

Gunakan JSON berikut saat harness evaluasi Anda mengoptimalkan fungsi objektif skalar tunggal.

{
  "scores": {
    "scores": [
      {
        "metric": "accuracy",
        "score": 0.95
      }
    ]
  },
  "insights": {
    "insights": [
      {
        "label": "validation",
        "text": "Passed syntax and basic compilation."
      }
    ]
  }
}

Skema penyerapan multi-tujuan

Gunakan JSON berikut saat meneruskan parameter pelacakan multi-objektif independen untuk mengaktifkan rutin pengoptimalan batas Pareto sisi server.

{
  "scores": {
    "scores": [
      {
        "metric": "accuracy",
        "score": 0.95
      },
      {
        "metric": "latency",
        "score": -42.5
      }
    ]
  },
  "insights": {
    "insights": [
      {
        "label": "verification",
        "text": "Passed 5 out of 5 unit tests."
      },
      {
        "label": "latency_warning",
        "text": "Latency regression of 3% observed on large dataset."
      }
    ]
  }
}

Mengambil dan membuat kueri data program

Sistem AlphaEvolve mencatat telemetri, metrik eksekusi, dan kode sumber lengkap setiap mutasi yang dihasilkan, sehingga developer dapat membuat kueri datastore historis ini menggunakan API atau CLI untuk melacak progres pengoptimalan dan mengekstrak kandidat kode berperforma terbaik.

Pengambilan program menggunakan REST API

Resource program yang dievaluasi dapat dikueri dari database menggunakan endpoint ListAlphaEvolvePrograms standar dengan parameter kueri pemfilteran dan pengurutan:

  • Pemfilteran status: Kueri program yang cocok dengan status siklus proses tertentu:

    GET /v1alpha/{parent}/alphaEvolvePrograms?state_filter=COMPLETED

  • Pengurutan berbasis metrik: Ambil kandidat yang diurutkan berdasarkan metrik yang dioptimalkan:

    GET /v1alpha/{parent}/alphaEvolvePrograms?order_by=accuracy desc,latency&page_size=5

Pengambilan program menggunakan CLI

Untuk menarik kandidat yang menyelesaikan paling banyak tugas langsung dari terminal, jalankan perintah berikut:

ae results best <experiment-nickname> --top 5

Contoh penggunaan CLI lengkap

CLI AlphaEvolve memberi developer kontrol administratif dan pemantauan cepat atas kampanye langsung dari shell:

  • Mencantumkan semua eksperimen dalam sesi percakapan:

    ae experiment list

  • Mencantumkan semua program kandidat yang dimutasi untuk eksperimen tertentu:

    ae program list EXPERIMENT_NICKNAME \
  --state=COMPLETED \
  --order_by="accuracy desc"

    Ganti EXPERIMENT_NICKNAME dengan nama eksperimen Anda.

  • Mengambil kandidat kode yang telah selesai dan berperforma terbaik:

    ae results best EXPERIMENT_NICKNAME --top 5

    Ganti EXPERIMENT_NICKNAME dengan nama eksperimen Anda.

  • Melanjutkan kampanye yang dijeda:

    ae experiment resume EXPERIMENT_NICKNAME

    Ganti EXPERIMENT_NICKNAME dengan nama eksperimen Anda.

Direktori endpoint Core REST API

Semua endpoint diberi versi di bagian v1alpha dari Google Cloud Discovery Engine API.

Pola jalur resource induk

URI resource induk bertingkat yang sebenarnya disusun sebagai: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}

  • AlphaEvolve tersedia di global, us, dan eu. Membuat eksperimen di lokasi lain akan menampilkan FAILED_PRECONDITION.
  • Project Assured Workloads tidak didukung.
  • Project dibatasi hingga 30 eksperimen AlphaEvolve yang aktif secara serentak (STARTED atau RUNNING) per lokasi. Memulai atau melanjutkan eksperimen yang melebihi batas ini akan menampilkan RESOURCE_EXHAUSTED.

Buat eksperimen (POST)

  • Jalur:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*}/alphaEvolveExperiments

  • Isi permintaan: AlphaEvolveExperimentConfig (Lihat Pasal 2.1)

  • Respons: Resource AlphaEvolveExperiment yang berisi kampanye yang diinisialisasi.

  • Status HTTP: 200 OK

Contoh payload API

  1. Contoh isi permintaan (POST /alphaEvolveExperiments)

    {
  "config": {
    "title": "Sorting Optimization Campaign",
    "problemDescription": "Optimize the custom_heuristic function.",
    "programLanguage": "python",
    "runSettings": {
      "maxPrograms": 250,
      "concurrency": 8,
      "maxDuration": "86400s",
      "idleTimeout": "1800s"
    },
    "generationSettings": {
      "context": "Ensure custom_heuristic is in-place.",
      "includeFullProgramInPrompt": true,
      "models": [
        {
          "name": "gemini-3.8-flash",
          "weight": 1.0
        }
      ]
    },
    "evolutionSettings": {
      "parentSamplingConfig": {
        "paretoSamplingConfig": {
          "paretoSamplingProbability": 0.0
        }
      }
    }
  }
}

  2. Contoh isi respons (200 OK)

    {
  "name": "projects/.../sort-opt-01",
  "state": "CREATED",
  "createTime": "2026-06-23T13:30:00Z",
  "config": {
    "title": "Sorting Optimization Campaign",
    "problemDescription": "Optimize the custom_heuristic function.",
    "programLanguage": "python",
    "runSettings": {
      "maxPrograms": 250,
      "concurrency": 8,
      "maxDuration": "86400s",
      "idleTimeout": "1800s"
    },
    "generationSettings": {
      "context": "Ensure custom_heuristic is in-place.",
      "includeFullProgramInPrompt": true,
      "models": [
        {
          "name": "gemini-3.8-flash",
          "weight": 1.0
        }
      ]
    },
    "evolutionSettings": {
      "parentSamplingConfig": {
        "paretoSamplingConfig": {
          "paretoSamplingProbability": 0.0
        }
      }
    }
  }
}

Mulai eksperimen (POST)

  • Jalur:

    POST v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:start

  • Isi permintaan: StartExperimentRequest

  • Peringatan penghentian penggunaan: Kolom body initialProgram tidak digunakan lagi dan diabaikan.

  • Respons: GoogleLongrunningOperation (LRO).

  • Status HTTP: 200 OK (Mengubah status dari CREATED menjadi RUNNING)

Contoh payload API

  1. Contoh isi permintaan

    {
  "desiredProgramsCount": 1
}

  2. Contoh isi respons (200 OK - operasi yang berjalan lama)

    {
  "name": "projects/.../operations/start-op-7788",
  "metadata": {
    "@type": "type.googleapis.com/.../AlphaEvolveStartExperimentMetadata",
    "createTime": "2026-06-23T13:31:00Z"
  },
  "done": false
}

Program akuisisi (POST)

  • Jalur:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:acquirePrograms

  • Isi permintaan: AcquireProgramsRequest

    • desiredProgramsCount (int32): Jumlah batch opsional program yang diubah untuk diambil (defaultnya 1 jika tidak disetel).

  • Status respons:

    • 200 OK: Menampilkan respons yang berisi resource AlphaEvolveProgram yang dikunci.

    • 204 No Content: Antrean kosong atau kampanye dijeda. Pelari harus tidur (misalnya, 15 detik) dan mencoba lagi.

Contoh payload API

  1. Contoh isi permintaan

    {
  "desiredProgramsCount": 1
}

  2. Contoh isi respons (200 OK)

    {
  "programs": [
    {
      "name": "projects/.../alphaEvolvePrograms/prog-102",
      "lockToken": "token_uuid_8877_x99",
      "state": "EVALUATING",
      "createTime": "2026-06-23T13:32:00Z",
      "content": {
        "description": "Mutated candidate program.",
        "files": [
          {
            "path": "initial_program.py",
            "programLanguage": "python",
            "description": "Primary sorting executable.",
            "content": "def custom_heuristic(arr, _):\n    ..."
          }
        ]
      }
    }
  ]
}

  3. Contoh isi respons (204 No Content)

Status HTTP 204 ditampilkan dengan konteks payload kosong.

Mengirimkan evaluasi program (POST)

  • Jalur:

    POST v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:submitProgramsEvaluations

  • Isi permintaan: SubmitProgramsEvaluationsRequest

    • evaluationSubmissions (array): Berisi lockToken yang cocok, jalur resource program yang memenuhi syarat, dan payload evaluasi (skor dan insight). API menerima tepat satu pengiriman evaluasi per panggilan. Pengelompokan beberapa evaluasi menjadi satu permintaan ditolak dengan INVALID_ARGUMENT. Saat mengevaluasi beberapa kandidat, kirimkan setiap program satu per satu.

  • Respons: SubmitProgramsEvaluationsResponse (kosong).

  • Status HTTP: 200 OK (Menyimpan skor, melepaskan kunci aktif, dan mendaftarkan insight)

Contoh payload API

  1. Contoh isi permintaan

    {
  "evaluationSubmissions": [
    {
      "lockToken": "token_uuid_8877_x99",
      "program": "projects/.../alphaEvolvePrograms/prog-102",
      "evaluation": {
        "scores": {
          "scores": [
            {
              "metric": "latency_performance",
              "score": evaluation_payload["score"]
            }
          ]
        },
        "insights": {
          "insights": [
            {
              "label": "benchmark",
              "text": "Completed test case in 12.45ms."
            }
          ]
        }
      }
    }
  ]
}

  2. Contoh isi respons (200 OK)

    {}

Lanjutkan eksperimen (POST)

  • Jalur:

    POST v1alpha/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}:resume

  • Isi permintaan: ResumeExperimentRequest

  • Respons: GoogleLongrunningOperation (LRO).

  • Status HTTP: 200 OK (Mengubah status dari PAUSED kembali ke RUNNING)

Contoh payload API

  1. Contoh isi permintaan

    {}

  2. Contoh isi respons (200 OK - operasi yang berjalan lama)

    {
  "name": "projects/.../operations/resume-op-9900",
  "metadata": {
    "@type": "type.googleapis.com/.../AlphaEvolveResumeExperimentMetadata",
    "createTime": "2026-06-23T13:45:00Z"
  },
  "done": false
}

Mencantumkan program (GET)

  • Jalur:

    GET v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*/alphaEvolveExperiments/*}/alphaEvolvePrograms

  • Parameter kueri:

    • stateFilter (string): Opsional. Filter daftar standar, misalnya, stateFilter = 'COMPLETED'.

    • orderBy (string): Opsional. Pengurutan berbasis metrik, misalnya, accuracy desc.

  • Respons: ListAlphaEvolveProgramsResponse.

  • Status HTTP: 200 OK

Contoh payload API

  1. Contoh URL kueri permintaan

    GET v1alpha/projects/.../alphaEvolveExperiments/sort-opt-01/
  alphaEvolvePrograms?stateFilter=COMPLETED&orderBy=latency_performance%20desc
  &pageSize=1

  2. Contoh isi respons (200 OK)

    {
  "alphaEvolvePrograms": [
    {
      "name": "projects/.../alphaEvolvePrograms/prog-102",
      "state": "COMPLETED",
      "createTime": "2026-06-23T13:32:00Z",
      "evaluation": {
        "scores": {
          "scores": [
            {
              "metric": "latency_performance",
              "score": -12.45
            }
          ]
        },
        "insights": {
          "insights": [
            {
              "label": "benchmark",
              "text": "Completed test case in 12.45ms."
            }
          ]
        }
      }
    }
  ],
  "nextPageToken": "token_page_1_next"
}

Kode diagnostik dan referensi pemecahan masalah

Matriks kode diagnostik API

Status HTTP Jenis error Penyebab sistem Solusi atau tindakan mitigasi
400 INVALID_ARGUMENT
  • Penanda EVOLVE-BLOCK-START / EVOLVE-BLOCK-END yang salah format (misalnya, konten yang berbagi baris penanda, blok bertingkat, atau penanda akhir yang tidak ada).
  • Blok evolusi kosong yang hanya berisi komentar atau spasi kosong tanpa kode yang dapat diedit.
  • maxPrograms ditetapkan ke kurang dari 2.
  • Kolom konfigurasi tidak dikenal.
  • Konfigurasi model tidak valid (lebih dari dua model, entri duplikat, bobot non-positif, atau suhu di luar [0.0, 2.0]).
  • Mengirimkan beberapa evaluasi dalam satu panggilan submitProgramsEvaluations.
  • Project adalah project Assured Workloads.
 Pastikan penanda berada sendiri di barisnya dan menyertakan setidaknya satu baris kode non-komentar. Tetapkan maxPrograms ke 2 atau lebih. Menghapus kolom yang bukan bagian dari API, seperti notes yang ada di versi pratinjau API. Kirimkan evaluasi satu per satu.
403 PERMISSION_DENIED
  • Pemanggil tidak memiliki peran Editor (roles/discoveryengine.editor) atau Admin (roles/discoveryengine.admin) Discovery Engine. Catatan: roles/discoveryengine.user tidak memberikan izin AlphaEvolve, dan roles/discoveryengine.viewer tidak dapat memperoleh eksperimen.
  • Pemanggil tidak memiliki izin pada resource sesi induk.
  • Tidak ada lisensi Gemini Enterprise aktif yang ditetapkan.
 Berikan roles/discoveryengine.editor atau roles/discoveryengine.admin di tingkat project dan verifikasi akses ke sesi induk. Verifikasi lisensi Gemini Enterprise yang aktif. Konfigurasi kredensial default aplikasi:

gcloud auth application-default login --project=PROJECT_ID

Catatan: Model Armor tidak didukung dalam konfigurasi AlphaEvolve.
400 FAILED_PRECONDITION
  • Token kunci sudah tidak berlaku atau habis masa berlakunya, atau ketidakcocokan status program (misalnya, kandidat diperoleh kembali atau diselesaikan setelah masa sewa berakhir).
  • Eksperimen dibuat di lokasi yang tidak didukung (di luar global, us, atau eu).
  • Vertex AI API (aiplatform.googleapis.com) tidak diaktifkan di project.
 Mengulangi lockToken persis yang ditampilkan oleh :acquirePrograms. Terapkan waktu tunggu sisi klien (direkomendasikan 30 menit) dan kirimkan skor penalti kegagalan saat waktu tunggu habis. Buat ulang eksperimen di lokasi yang didukung. Aktifkan Vertex AI API: gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID.
429 RESOURCE_EXHAUSTED
  • Project telah mencapai batas 30 eksperimen yang aktif secara bersamaan (STARTED / RUNNING) per lokasi.
  • Kuota token pembuatan model backend habis.
 Untuk batas eksperimen aktif: Selesaikan atau hentikan eksperimen yang sedang berjalan sebelum memulai eksperimen baru (menurunkan concurrency di runSettings tidak memengaruhi batas ini). Untuk kuota token model: Turunkan concurrency di runSettings dan terapkan backoff eksponensial.
503 SERVICE_UNAVAILABLE Pengklasifikasi keamanan input tidak tersedia atau layanan backend kelebihan beban untuk sementara. Terapkan loop percobaan ulang dengan backoff eksponensial acak di sisi klien.

Pesan error dan resolusi umum

Referensi berikut mencantumkan pesan error umum yang ditampilkan oleh API, penyebab yang mendasarinya, dan langkah-langkah penyelesaian.

Error penguraian program awal dan EVOLVE-BLOCK

Pesan error Penyebab sistem Solusi atau tindakan mitigasi
Parsing error: Unexpected evolve block delimiters in line <line_number>. Cannot be in the same line. Penanda EVOLVE-BLOCK-START dan EVOLVE-BLOCK-END muncul di baris yang sama. Tempatkan penanda awal dan akhir di baris terpisah.
Parsing error: Unexpected content on the same line as <marker> in line <line_number>. Kode, teks, atau karakter akhir berbagi baris dengan penanda EVOLVE-BLOCK-START atau EVOLVE-BLOCK-END. Pastikan penanda berada sendiri di barisnya (hanya diawali dengan awalan komentar, seperti # EVOLVE-BLOCK-START).
Parsing error: Unexpected evolve block start delimiter in line <line_number>. Cannot nest evolve blocks. Penanda EVOLVE-BLOCK-START muncul di dalam blok evolusi yang sudah dibuka. Hapus penanda mulai bertingkat; blok evolusi bertingkat tidak didukung.
Parsing error: Unexpected evolve block end delimiter in line <line_number>. No block started. Penanda EVOLVE-BLOCK-END muncul tanpa EVOLVE-BLOCK-START sebelumnya. Pastikan setiap penanda akhir didahului oleh penanda awal yang cocok.
Parsing error: Evolve block started but not ended. Penanda EVOLVE-BLOCK-START ditemukan tanpa penanda penutup EVOLVE-BLOCK-END yang cocok. Tambahkan penanda penutup EVOLVE-BLOCK-END.

Kesalahan konten dan struktur program

Pesan error Penyebab sistem Solusi atau tindakan mitigasi
Program content must contain at least one source file. program_content.source_files kosong. Berikan minimal satu file sumber.
source_files entries must have a non-empty path. Entri file sumber memiliki string path kosong. Tentukan jalur relatif yang valid untuk setiap file sumber.
source_files entry has empty content; path: <path> Entri file sumber berisi konten string kosong. Isi konten file.
Program content must contain at least one EVOLVE-BLOCK-START / EVOLVE-BLOCK-END region with editable code between the markers (whitespace and comment-only regions don't count -- AlphaEvolve has nothing to mutate). Blok yang berkembang hanya berisi komentar, docstring, atau spasi kosong, tanpa kode yang dapat diedit. Sertakan setidaknya satu baris kode yang dapat diedit (seperti definisi fungsi atau logika algoritma) di dalam blok.

Error validasi konfigurasi dan model

Pesan error Penyebab sistem Solusi atau tindakan mitigasi
unsupported model: <model_name> Model yang diminta tidak didukung atau tidak diaktifkan untuk project Anda. Gunakan model yang didukung. Lihat Setelan pembuatan.
model '<model_name>' is not served from domain shard '<location>'. Model tidak tersedia di lokasi regional yang ditentukan. Lihat Setelan pembuatan untuk model dan lokasi yang didukung.
generation_settings.models must contain at most 2 distinct models; got <count>. Lebih dari dua konfigurasi model ditentukan dalam generation_settings.models. Tentukan paling banyak dua model dalam campuran.
generation_settings.models contains duplicate entry: <model_name> Nama model yang sama muncul lebih dari sekali di generation_settings.models. Hapus entri model duplikat.
generation_settings.models weight for <model_name> must be finite and strictly positive; got <weight>. Remove the entry instead of setting weight to zero. Bobot pengambilan sampel model negatif, nol, atau tidak berhingga. Tetapkan berat positif atau hapus entri.
generation_settings.models temperature for <model_name> must be in [0.0, 2.0]; got <temperature>. Suhu model berada di luar rentang yang valid [0.0, 2.0]. Sesuaikan suhu ke nilai antara 0.0 dan 2.0.
RunSettings.max_programs is required and must be greater than 1. max_programs dihapus atau ditetapkan ke 1 atau kurang. Tetapkan max_programs ke 2 atau lebih besar (minimum 2 diperlukan untuk menerima kandidat yang telah berkembang).
RunSettings.concurrency is required and must be positive. concurrency dihapus atau disetel ke 0 atau kurang. Tetapkan concurrency ke bilangan bulat positif (biasanya 1–30).
EvolutionSettings.pareto_sampling_probability must be in [0, 1]; got <probability>. pareto_sampling_probability berada di luar [0.0, 1.0]. Tetapkan probabilitas antara 0.0 dan 1.0.

Prasyarat proyek dan kesalahan siklus proses eksperimen

Pesan error Penyebab sistem Solusi atau tindakan mitigasi
AlphaEvolve requires the Vertex AI API to be enabled in this project. Enable it with: gcloud services enable aiplatform.googleapis.com --project=<project_id> Vertex AI API (aiplatform.googleapis.com) tidak diaktifkan di project Google Cloud . Jalankan gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID.
Project has reached the limit of 30 concurrently active AlphaEvolve experiments in location <location>. Stop or wait for a running experiment to finish before starting or resuming another. Project telah mencapai kuota 30 eksperimen yang aktif secara serentak (STARTED atau RUNNING) di lokasi tersebut. Hentikan atau selesaikan eksperimen yang ada sebelum memulai atau melanjutkan eksperimen baru.
Cannot <action> experiment from state <current_state> Mencoba transisi status yang tidak valid (misalnya, memulai eksperimen yang sudah berjalan, atau melanjutkan eksperimen yang baru dibuat). Pastikan eksperimen mengikuti transisi siklus proses standar: CREATED → START, PAUSED/COMPLETED → RESUME, STARTED/RUNNING → STOP.
Cannot resume experiment: a start or watchdog message is already pending. Stop the experiment first to drain it, or wait for the pending delivery to complete. Operasi mulai atau lanjutkan sebelumnya masih dalam proses. Tunggu hingga pengiriman tertunda selesai, atau panggil STOP untuk menguras pesan tertunda.
AlphaEvolve is not available for this project. Project diblokir atau merupakan profil kepatuhan yang tidak didukung. Lihat Profil kepatuhan dan keamanan.

Error akuisisi dan evaluasi program

Pesan error Penyebab sistem Solusi atau tindakan mitigasi
Exactly one evaluation submission is required. Beberapa pengiriman evaluasi dikelompokkan dalam satu permintaan submitProgramsEvaluations. Kirimkan evaluasi satu per satu, satu per panggilan API.
Program is required for each evaluation submission./submission.program is required. Jalur resource program tidak diberikan dalam pengiriman evaluasi. Teruskan jalur resource program lengkap.
Lock token is required for each evaluation submission./submission.lock_token is required. lock_token yang dikembalikan selama acquirePrograms tidak disertakan. Teruskan string lock_token persis yang ditampilkan saat program diperoleh.
Program <program_name> has unexpected lock token. Expected token: '<expected>', actual token: '<actual>' Token kunci yang dikirim dalam pengiriman tidak cocok dengan sewa server aktif (misalnya, sewa telah berakhir dan pekerja lain mendapatkannya, atau token yang salah diberikan). Mengulangi lockToken yang sama persis dari acquirePrograms dan mengirimkan hasil sebelum waktu tunggu klien habis.
Program <program_name> is not in expected state. Expected state: EVALUATION_IN_PROGRESS, actual state: <actual_state> Program telah dievaluasi, dibatalkan, atau tidak lagi menggunakan EVALUATION_IN_PROGRESS. Buang evaluasi yang sudah tidak berlaku atau dapatkan kembali kandidat jika tersedia.
The request was rejected by a safety policy. Deskripsi masalah input, kode awal, atau metrik evaluasi memicu kebijakan klasifikasi keamanan. Bersihkan teks perintah dan deskripsi masalah untuk menghapus kata kunci atau jejak sensitif.
The input safety classifier is currently unavailable. Layanan klasifikasi keamanan tidak dapat dijangkau atau kelebihan beban untuk sementara (gagal tertutup). Terapkan logika percobaan ulang backoff eksponensial.

Memperbaiki "drop senyap"

Penyadapan filter keamanan (penghapusan senyap) terjadi saat model bahasa sisi server menandai dan menghapus perintah kandidat yang diubah karena frasa sensitif atau pemicu aturan keamanan. Server membungkam output, sehingga antrean menampilkan respons kosong, dan peluncur klien mungkin menunggu tanpa batas waktu.

Perbaikan solusi:

  • Membersihkan konteks: Menghapus frasa yang memicu emosi atau sensitif terhadap keamanan dari problemDescription.

  • Insight filter: Mengurai dan memangkas rekaman aktivitas pengecualian mentah atau log stderr terminal dalam payload insights untuk mencegah pengulangan konten sistem yang tidak aman yang memicu filter hilir.

  • Melokalkan set data: Jangan menempatkan rekaman pelatihan atau korpus teks besar dalam perintah; muat secara lokal di lingkungan klien selama eksekusi loop evaluasi.

Praktik terbaik evaluasi sisi klien

Hambatan "spaghetti code"

Pemformatan sumber yang tidak optimal menurunkan kualitas pengoptimalan: "Kode spaghetti == Ruang penelusuran yang berisik". Sebelum menempatkan penanda EVOLVE-BLOCK:

  • Refaktorkan blok kode sehingga variabel dan tanda tangan fungsi diberi nama dengan jelas.

  • Tambahkan docstring deskriptif dan ringkas yang menjelaskan fungsi atau variabel dan alasannya. Pastikan docstring berada bersama kode fungsional yang sebenarnya; menempatkan hanya docstring atau komentar di dalam EVOLVE-BLOCK ditolak sebagai blok kosong.

  • Pastikan penanda komentar EVOLVE-BLOCK-START dan EVOLVE-BLOCK-END ditempatkan sendiri di barisnya masing-masing, kecuali untuk spasi kosong di awal dan awalan komentar (seperti # atau //).

  • Pastikan semua dependensi eksternal yang tidak dapat diubah (seperti mengimpor modul helper atau memuat data statis) berada di luar EVOLVE-BLOCK.

Alokasi jendela konteks

Untuk memaksimalkan kreativitas mutasi, batasi payload kode yang dikirim ke API. Total konteks program harus tetap di bawah 150.000 hingga 200.000 token. Blok besar boilerplate statis yang tidak dapat diubah menggunakan perhatian model dan menurunkan performa. Pindahkan skrip utilitas, pipeline penyerapan data, dan library validasi berat sepenuhnya ke evaluator sisi klien.

Siapkan program awal terlebih dahulu

Sebelum menjalankan AlphaEvolve, gunakan agen coding standar untuk men-debug codebase awal dan evaluator Anda:

  • Menyiapkan bibit: Memperbaiki bug sintaksis yang jelas, masalah kompilasi, dan kasus ekstrem.

  • Verifikasi skor awal: Verifikasi bahwa skor dasar sudah wajar dan evaluator sepenuhnya deterministik (kode yang sama + input yang sama = skor yang sama).

  • Uji dengan input yang tidak valid: Jalankan evaluator dengan fungsi yang sengaja rusak untuk mengonfirmasi bahwa evaluator menangkap masalah compiler, menangani loop tak terbatas dengan baik, dan menampilkan skor penalti negatif yang tinggi.

Hindari dasar pengukuran yang terlalu dioptimalkan

Jangan meneruskan program dasar yang sudah sangat dioptimalkan sebagai seed. Jika program awal Anda sudah hampir optimal, AlphaEvolve akan kesulitan melakukan pendakian karena hanya ada sedikit ruang untuk peningkatan. Mulai dengan dasar yang wajar, tetapi tidak dioptimalkan secara maksimal. Hal ini memberi ruang bagi AlphaEvolve untuk mengeksplorasi dan menaikkan bukit.

Pengamanan peluncur sisi klien

Evaluator sisi klien harus menerapkan perlindungan ketat untuk mencegah kandidat berbahaya, yang menggunakan banyak resource, atau tidak responsif menghentikan pekerja paralel:

  • Waktu tunggu yang ketat: Menerapkan batas waktu eksekusi yang ketat selama 30 menit (atau kurang, bergantung pada struktur ruang penelusuran).

  • Pengiriman penalti waktu tunggu: Jika varian program kandidat melampaui batas waktu tunggu, segera hentikan thread eksekusinya. Jangan biarkan proses kandidat gagal. Sebagai gantinya, segera kompilasi dan kirimkan skor penalti kegagalan berat (misalnya, -100000.0) bersama dengan insight debug deskriptif kembali ke server untuk melepaskan kunci antrean program.

  • Filter keamanan AST: Selalu jalankan pemeriksaan Abstract Syntax Tree (AST) pada payload kode sumber yang masuk sebelum kompilasi. Segera batalkan eksekusi dan terapkan penalti kegagalan berat jika primitif eksekusi atau refleksi yang dibatasi (seperti eval, exec, getattr, atau setattr) terdeteksi.

Aset lainnya

Untuk informasi selengkapnya, lihat referensi berikut: