Referensi AlphaEvolve API

Dokumen ini berfungsi sebagai referensi API dan spesifikasi sistem tingkat produksi yang otoritatif untuk AlphaEvolve Cloud API di lapisan percakapan Discovery Engine Google Cloud. API 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 pengontrol sisi klien dan loop evaluasi yang sepenuhnya otomatis.

Mesin status siklus proses terpadu

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

Status siklus proses eksperimen

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

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

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

  • PAUSED: Status penangguhan sementara yang dipicu secara manual atau melalui idle_timeout perlindungan otomatis. Pembuatan kode berhenti, dan worker yang ada menjeda pengiriman metrik.

  • COMPLETED: Status terminal 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 kepanikan 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 urutan status operasional terperinci dalam database populasi.

  1. INITIALIZED: Entri program dibuat dalam database, yang 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 worker evaluasi dan dieksekusi di dalam lingkungan harness pengujian yang terisolasi.

  4. COMPLETED: Skor eksekusi dan insight struktural deskriptif di-commit dengan aman ke database evolusioner, dan program ditambahkan ke kumpulan pilihan.

Mekanisme konkurensi dan penguncian

Program diperoleh oleh loop worker menggunakan mekanisme token kunci atomik untuk mencegah kondisi race atau overhead penilaian duplikat di seluruh topologi terdistribusi. Evaluator harus mengirimkan skema penilaian yang telah diselesaikan bersama dengan token kunci pencocokan persis agar berhasil meng-commit 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 eksekusi eksperimen evolusioner.

Nama Kolom Jenis Default Batasan / Batas Nilai Deskripsi Teknis
title string Wajib Maksimal 256 karakter Nama tampilan unik eksperimen.
problemDescription string Wajib Maksimal 5.000 karakter Spesifikasi formal masalah. Prompt ini dimasukkan 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 Dipetakan ke skema RunSettings Parameter kecepatan dan waktu tunggu.
generationSettings objek Opsional Dipetakan ke skema GenerationSettings Pemilihan model dan parameter konteks.
evolutionSettings objek Opsional Dipetakan ke skema EvolutionSettings Parameter pemilihan induk dan keragaman.

RunSettings

Mengatur kecepatan throughput, batas paralelisasi, 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 yang akan dibuat dan dievaluasi). 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 (86.400 dtk) String dayTimeDuration ISO 8601
Min: >0, Maks: 7 Hari		 Total waktu nyata yang diizinkan sebelum eksperimen dihentikan.
idleTimeout string 5 jam (AS/EU)
2 jam (global)		 String dayTimeDuration ISO 8601
Min: >0
Maks: default lokasi		 Durasi tidak aktif sebelum transisi otomatis ke PAUSED. Defaultnya adalah 2 jam di global dan 5 jam di lokasi regional (us, eu). Durasi dibatasi oleh default lokasi, sehingga menentukan nilai di atas default lokasi (misalnya, 12 jam di global) akan diabaikan dan nilainya adalah 2 jam (tanpa error).

Setelan pembuatan

Skema GenerationSettings mengontrol perakitan perintah, jendela 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 memberinya weight opsional, yang merupakan bagian panggilan pembuatan model tersebut dibandingkan dengan entri lainnya. Jika Anda menghilangkan models, AlphaEvolve akan menetapkannya ke model default saat membuat eksperimen. Default akan berubah seiring dirilisnya model Gemini yang lebih baru; Model default mencantumkan model yang berlaku pada tanggal tertentu. Untuk memilih model sendiri, atau untuk mempertahankan model yang sama pada setiap operasi, tetapkan models.

    Contoh berikut mengirimkan sekitar sembilan dari sepuluh panggilan pembuatan ke model pertama dan sisanya ke model kedua. Bobot adalah rasio, sehingga 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 maksimal dua model dalam satu eksperimen.

Nama model Region penyajian
gemini-4-argon global, us, eu
gemini-3.8-flash 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 region yang Anda minta.

Model default

Tabel berikut mencantumkan model yang digunakan AlphaEvolve jika Anda menghilangkan models, berdasarkan tanggal pembuatan eksperimen.

Eksperimen dibuat Model default
Pada atau setelah 24 Oktober 2026 gemini-4-argon
29 September 2026 hingga 23 Oktober 2026 gemini-3.8-flash
30 Juni 2026 hingga 28 September 2026 gemini-3.5-flash
Sebelum 30 Juni 2026 gemini-2.5-flash

Untuk mengidentifikasi model yang ditetapkan ke eksperimen, periksa generationSettings.models dalam konfigurasi eksperimen atau respons pembuatan. Karena perubahan diterapkan selama hari transisi, eksperimen yang dibuat pada tanggal tersebut mungkin menerima model default lama atau baru. Eksperimen yang dibuat tanpa models sebelum 30 Juni 2026 tidak berisi nilai untuk kolom ini.

Karena model disimpan di setiap eksperimen, perubahan pada default tidak akan memengaruhi eksperimen yang sudah ada. Untuk menggunakan model default yang lebih baru, buat eksperimen baru.

Setelan evolusi

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

  • parentSamplingConfig → paretoSamplingConfig → paretoSamplingProbability (float): Probabilitas (0,0 hingga 1,0) pengambilan sampel program induk langsung dari Pareto frontier aktif, bukan menggunakan pemilihan berbasis kesesuaian standar. Parameter ini harus ditetapkan 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 susunan struktural program kandidat.

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

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

AlphaEvolveSourceFile

Mewakili setiap file kode sumber dalam codebase.

  • path (string): Tujuan jalur relatif ruang kerja (Wajib, Maksimal 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 persis "initial_program.py".

  • content (string): String kode sumber mentah yang terdiri dari blok implementasi fungsional. Google merekomendasikan untuk menjaga ukuran codebase kumulatif di semua file 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 secara eksplisit cocok 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 penerusan mutasi (Maksimal 500 karakter).

AlphaEvolveProgramEvaluation

Payload terstruktur yang dikirim oleh instance runner klien kembali ke database evolusioner setelah eksekusi runtime.

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

  • insights (array AlphaEvolveEvaluationInsight): Label semantik diagnostik dan trace eksekusi natural language yang diteruskan kembali untuk membantu upaya pembuatan mutasi berikutnya dari LLM (Maksimum yang direkomendasikan adalah 10 item).

Formulasi skor dan format penyerapan

Aturan pemaksimalan

AlphaEvolve beroperasi secara mendasar sebagai algoritma monotonic hill-climbing dan secara ketat memaksimalkan semua metrik numerik. Jika pipeline evaluasi Anda melacak target minimalisasi (seperti meminimalkan latensi aplikasi dalam milidetik atau mengurangi penggunaan memori), Anda harus menegasikan nilai tersebut 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 hill-climbing yang efektif.

Skema penyerapan tujuan tunggal

Gunakan JSON berikut saat harness evaluasi Anda mengoptimalkan fungsi tujuan 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-tujuan independen untuk mengaktifkan rutinitas 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 log sistem telemetri, metrik eksekusi, dan kode sumber lengkap dari setiap mutasi yang dihasilkan, sehingga developer dapat mengkueri datastore historis ini menggunakan API atau CLI untuk melacak progres pengoptimalan dan mengekstrak kandidat kode berperforma tertinggi.

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: Buat 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 teratas yang telah selesai langsung dari terminal Anda, jalankan perintah berikut:

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

Contoh penggunaan CLI lengkap

AlphaEvolve CLI 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.

  • Ambil kandidat kode lengkap dengan performa 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 API inti

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 dalam bahasa global, us, dan eu. Membuat eksperimen di lokasi lain akan menampilkan FAILED_PRECONDITION.
  • Project Assured Workloads tidak didukung.
  • Project dibatasi hingga 30 eksperimen AlphaEvolve (STARTED atau RUNNING) yang aktif secara bersamaan per lokasi. Memulai atau melanjutkan eksperimen yang melebihi batas ini akan menampilkan RESOURCE_EXHAUSTED.

Membuat eksperimen (POST)

  • Path:

    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
        }
      }
    }
  }
}

Memulai eksperimen (POST)

  • Path:

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

  • Isi permintaan: StartExperimentRequest

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

  • Respons: GoogleLongrunningOperation (LRO).

  • Status HTTP: 200 OK (Mentransisikan status dari CREATED ke 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
}

Mendapatkan program (POST)

  • Path:

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

  • Isi permintaan: AcquireProgramsRequest

    • desiredProgramsCount (int32): Jumlah batch opsional dari program yang dimutasi untuk diambil (defaultnya adalah 1 jika tidak ditetapkan).

  • Status respons:

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

    • 204 No Content: Antrean kosong atau kampanye dijeda. Runner 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.

Mengirim evaluasi program (POST)

  • Path:

    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 ke dalam satu permintaan akan 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)

    {}

Melanjutkan eksperimen (POST)

  • Path:

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

  • Isi permintaan: ResumeExperimentRequest

  • Respons: GoogleLongrunningOperation (LRO).

  • Status HTTP: 200 OK (Mentransisikan 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
}

Membuat daftar program (GET)

  • Path:

    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"
}

Referensi kode diagnostik dan 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 salah format (misalnya, konten yang berbagi baris penanda, blok bertingkat, atau penanda akhir tidak ada).
  • Blok evolve kosong yang hanya berisi komentar atau spasi kosong tanpa kode yang dapat diedit.
  • maxPrograms ditetapkan ke kurang dari 2.
  • Kolom konfigurasi tidak dikenali.
  • 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 merupakan project Assured Workloads.
 Pastikan penanda berada di barisnya sendiri dan mencakup setidaknya satu baris kode non-komentar. Tetapkan maxPrograms ke 2 atau lebih. Hapus kolom yang bukan bagian dari API, seperti notes yang ada dalam versi pratinjau API. Kirim evaluasi satu per satu.
403 PERMISSION_DENIED
  • Pemanggil tidak memiliki peran Discovery Engine Editor (roles/discoveryengine.editor) atau peran Admin (roles/discoveryengine.admin). Catatan: roles/discoveryengine.user tidak memberikan izin AlphaEvolve, dan roles/discoveryengine.viewer tidak dapat mendapatkan 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 level project dan verifikasi akses ke sesi induk. Verifikasi lisensi Gemini Enterprise yang aktif. Konfigurasikan kredensial default aplikasi:

gcloud auth application-default login --project=PROJECT_ID

Catatan: Model Armor tidak didukung dalam konfigurasi AlphaEvolve.
400 FAILED_PRECONDITION
  • Token kunci yang sudah tidak berlaku atau sudah tidak berlaku, 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.
 Tampilkan lockToken persis yang ditampilkan oleh :acquirePrograms. Terapkan waktu tunggu sisi klien (disarankan 30 menit) dan kirimkan skor penalti kegagalan setelah 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 (STARTED / RUNNING) yang aktif secara bersamaan 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 umum dan penyelesaian masalah

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

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 di barisnya sendiri (hanya didahului oleh 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 awal bertingkat; blok evolve 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 EVOLVE-BLOCK-END penutup.

Error 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 Evolve 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 mengetahui model dan lokasi yang didukung.
generation_settings.models must contain at most 2 distinct models; got <count>. Lebih dari dua konfigurasi model ditentukan di generation_settings.models. Tentukan maksimal 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 bernilai negatif, nol, atau tidak terbatas. Tetapkan bobot 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 dihilangkan atau ditetapkan ke 1 atau kurang. Tetapkan max_programs ke 2 atau lebih besar (minimum 2 diperlukan untuk menerima kandidat yang berevolusi).
RunSettings.concurrency is required and must be positive. concurrency dihilangkan atau ditetapkan 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 project dan error 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 (STARTED atau RUNNING) yang aktif secara bersamaan 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 memulai atau melanjutkan sebelumnya masih dalam proses. Tunggu hingga pengiriman yang tertunda selesai, atau panggil STOP untuk mengosongkan pesan yang 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. Kirim 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 ditampilkan selama acquirePrograms dihilangkan. 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 diberikan salah). Ulangi lockToken yang sama persis dari acquirePrograms dan kirimkan hasilnya 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 dialihkan dari EVALUATION_IN_PROGRESS. Hapus 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 untuk sementara atau kelebihan beban (gagal ditutup). Terapkan logika percobaan ulang backoff eksponensial.

Memperbaiki "penurunan senyap"

Intersepsi filter keamanan (silent drop) terjadi saat model bahasa sisi server menandai dan menghapus perintah kandidat yang dimutasi karena frasa sensitif atau pemicu aturan keamanan. Server akan menghentikan output, sehingga antrean menampilkan respons kosong, dan runner klien mungkin menunggu tanpa batas waktu.

Perbaikan sementara:

  • Sanitasi konteks: Hapus frasa yang bermuatan emosional atau sensitif terhadap keamanan dari problemDescription.

  • Memfilter insight: Mengurai dan memotong pelacakan pengecualian mentah atau log stderr terminal dalam payload insights untuk mencegah pengulangan konten sistem yang tidak aman yang memicu filter downstream.

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

Praktik terbaik evaluasi sisi klien

Bottleneck "kode spaghetti"

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

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

  • Tambahkan docstring yang deskriptif dan ringkas yang menjelaskan fungsi dan alasan setiap fungsi atau variabel. Pastikan docstring berada di samping kode fungsional yang sebenarnya; menempatkan hanya docstring atau komentar di dalam EVOLVE-BLOCK akan 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 bantuan 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 akan mengonsumsi perhatian model dan menurunkan performa. Pindahkan skrip utilitas, pipeline penyerapan data, dan library validasi yang berat sepenuhnya ke evaluator sisi klien.

Siapkan program awal terlebih dahulu

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

  • Siapkan seed: Perbaiki bug sintaksis, masalah kompilasi, dan edge-case yang jelas.

  • Verifikasi skor awal: Pastikan skor dasar pengukuran 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 tanpa akhir dengan baik, dan menampilkan skor penalti negatif yang tinggi.

Menghindari dasar pengukuran yang dioptimalkan secara berlebihan

Jangan teruskan program dasar pengukuran yang sudah sangat dioptimalkan sebagai seed. Jika program awal Anda sudah hampir optimal, AlphaEvolve akan kesulitan melakukan hill-climbing karena ruang untuk peningkatan sangat sedikit. Mulailah dengan dasar pengukuran yang wajar, tetapi tidak dioptimalkan secara maksimal. Hal ini memberi AlphaEvolve ruang untuk mengeksplorasi dan melakukan hill-climbing.

Perlindungan runner sisi klien

Evaluator sisi klien harus menerapkan pengamanan ketat untuk mencegah kandidat yang berbahaya, memerlukan banyak resource, atau tidak responsif menghentikan worker paralel:

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

  • Pengiriman penalti waktu tunggu: Jika varian program kandidat melebihi batas waktu tunggu, segera hentikan thread eksekusinya. Jangan biarkan proses kandidat gagal. Sebagai gantinya, segera kompilasi dan kirimkan skor penalti kegagalan parah (misalnya, -100000.0) beserta 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 yang berat jika primitif refleksi atau eksekusi yang dibatasi (seperti eval, exec, getattr, atau setattr) terdeteksi.

Aset lainnya

Untuk informasi selengkapnya, lihat referensi berikut: