Mengonfigurasi perutean model

Halaman ini menjelaskan cara mengonfigurasi, men-deploy, dan menguji perutean model di Gateway API menggunakan spesifikasi OpenAPI 3.x.

Sebelum memulai

Sebelum mengonfigurasi perutean model, periksa apakah lingkungan Anda memenuhi prasyarat berikut:

1. Periksa izin IAM: Periksa apakah Anda memiliki akses ke Gateway API Management Plane dan Vertex AI Model Garden. Anda harus memiliki peran Admin API Gateway (roles/apigateway.admin) untuk membuat konfigurasi dan gateway API. Selain itu, akun layanan yang digunakan oleh gateway API Anda—baik akun layanan Compute Engine default maupun akun layanan yang dikelola pengguna yang ditentukan saat membuat konfigurasi API—harus diberi peran Vertex AI User (roles/aiplatform.user) untuk mengakses model target.
2. Periksa ketersediaan model dan akses endpoint: Pastikan model yang dapat dirutekan telah di-deploy sebelumnya sebagai model terbuka untuk Model sebagai Layanan (MaaS) di Vertex AI Model Garden. Semua model yang dirujuk oleh satu router harus memiliki nama host yang sama persis. Pilih endpoint global (aiplatform.googleapis.com) atau satu endpoint regional (misalnya, us-central1-aiplatform.googleapis.com) untuk setiap model yang dirujuk dalam router tersebut.
3. Periksa kelayakan deployment gateway: Anda tidak dapat memperbarui gateway yang ada yang di-deploy tanpa perutean model untuk mengaktifkan perutean model, dan Anda juga tidak dapat memperbarui gateway yang di-deploy dengan perutean model untuk menonaktifkan atau menghapus perutean model. Untuk mengganti mode perutean, Anda harus membuat dan men-deploy konfigurasi API dan instance gateway baru.
4. Periksa kompatibilitas endpoint dan Kontrol Layanan VPC: Gateway perutean model tidak mendukung konfigurasi endpoint Private Service Connect (PSC) atau Kontrol Layanan VPC. Pastikan project target dan instance Gateway API Anda tidak dibatasi oleh perimeter Kontrol Layanan VPC, dan model Anda menggunakan endpoint regional atau global publik.

Validasi konfigurasi

Saat Anda men-deploy konfigurasi API, bidang pengelolaan Gateway API akan memvalidasi spesifikasi OpenAPI Anda. Management plane menolak konfigurasi yang tidak valid selama deployment dengan error validasi informasi. Proses validasi menerapkan aturan berikut:

Pemeriksaan struktural dan lokasi

• Ekstensi x-google-api-management dan blok terkaitnya (backends, ai.models.routing.routers, router individual, dan rules) harus memiliki format yang benar. Kunci harus cocok dengan jenis data yang diharapkan (peta, daftar, atau string). Bidang pengelolaan menolak ketidakcocokan jenis dengan error expected map/list/string.
• Ekstensi x-google-api-management harus berisi blok backends yang valid saat perutean model diaktifkan.
• Ekstensi x-google-model-router hanya didukung dalam spesifikasi OpenAPI 3.x (tidak didukung di OpenAPI 2.0 / Swagger).
• Ekstensi x-google-model-router hanya dapat ditentukan di tingkat operasi. Bidang pengelolaan secara eksplisit menolak definisi x-google-model-router yang ditempatkan di tingkat jalur atau tingkat root (atas).
• Blok ai.models.routing.routers harus ditentukan di dalam x-google-api-management setiap kali ada operasi yang mereferensikan x-google-model-router.
• Anda tidak dapat menentukan x-google-model-router dan x-google-backend sekaligus pada operasi API yang sama.
• Spesifikasi OpenAPI tidak boleh berisi campuran operasi perutean model dan non-model. Anda tidak dapat menentukan ekstensi perutean standar (seperti x-google-backend) pada beberapa operasi saat menggunakan x-google-model-router pada operasi lain dalam spesifikasi API yang sama.

Pemeriksaan metode HTTP

• Ekstensi x-google-model-router hanya dapat diterapkan pada operasi yang menggunakan metode HTTP POST. Bidang pengelolaan menolak perutean model pada metode HTTP lainnya (seperti GET, PUT, atau DELETE).

Validitas backend

• Setiap backend yang ditentukan dalam x-google-api-management.backends harus menyertakan kolom address yang tidak boleh kosong.
• Backend address harus berupa URL yang valid menggunakan skema http atau https. Untuk melindungi payload perintah dan kredensial autentikasi dalam pengiriman di seluruh endpoint publik atau jarak jauh, selalu tentukan skema https saat menentukan kolom address.
• Setiap backend yang ditentukan dalam x-google-api-management.backends dan dirujuk oleh perute model harus menggunakan pathTranslation: CONSTANT_ADDRESS. Bidang pengelolaan menolak konfigurasi yang menggunakan pathTranslation: APPEND_PATH_TO_ADDRESS untuk backend perutean model karena terjemahan jalur diabaikan di jalur runtime perute model.
• Backend perutean model tidak mendukung konfigurasi endpoint Private Service Connect (PSC) atau Kontrol Layanan VPC. Semua kolom address backend harus mengarah ke endpoint model terbuka MaaS regional atau global publik.

Penyelesaian referensi router

• Nama router yang dirujuk oleh x-google-model-router operasi harus cocok dengan kunci router valid yang ditentukan di ai.models.routing.routers.
• backend yang dirujuk oleh defaultModel router harus cocok dengan backend valid yang ditentukan di x-google-api-management.backends.
• backend yang dirujuk oleh setiap aturan di router harus cocok dengan backend valid yang ditentukan di x-google-api-management.backends.

Isi router

• Setiap router harus menentukan defaultModel.
• defaultModel harus menyertakan kolom backend yang valid.
• defaultModel harus menyertakan kolom targetModel yang tidak kosong.
• Setiap entri di bagian rules harus menyertakan kolom model yang tidak boleh kosong. Nilai string default dicadangkan dan tidak dapat digunakan sebagai nilai model aturan.
• Setiap entri di bagian rules harus menyertakan kolom targetModel yang tidak boleh kosong.
• Nilai model yang ditentukan di semua aturan dalam satu perouter harus unik. Bidang pengelolaan menolak nilai model duplikat dalam router yang sama.

Konsistensi host dan skema backend

• Semua backend yang dirujuk oleh satu router (termasuk defaultModel.backend dan backend setiap aturan) harus memiliki nama host dan skema URL yang identik. Bidang pengelolaan menolak konfigurasi dengan nama host yang berbeda atau skema yang tidak konsisten (http versus https) dalam router yang sama, sehingga memastikan router mengirimkan semua permintaan ke endpoint layanan upstream yang konsisten.

Validasi model target

• Bagian <provider> dari string targetModel (google, openai, atau anthropic) dan format ID <provider>/<model> divalidasi pada waktu config-create (deploy). Management plane menolak targetModel yang tidak diformat sebagai <provider>/<model> atau yang penyedianya bukan google, openai, atau anthropic dengan error InvalidArgument: unsupported publisher selama deployment.

Langkah 1: Identifikasi model target

Identifikasi model dasar target dan URL endpoint Vertex AI yang sesuai. Semua model yang dapat dirutekan dalam router harus berbagi satu nama host (untuk model terbuka MaaS, nama host ini adalah aiplatform.googleapis.com).

Jalur URL endpoint bervariasi berdasarkan penyedia model:

• Google Gemini: Menggunakan metode :generateContent.
• Anthropic Claude: Menggunakan metode :rawPredict.
• OpenAI: Menggunakan jalur endpoint /endpoints/openapi/chat/completions.

Tabel berikut mencantumkan endpoint MaaS yang digunakan dalam contoh spesifikasi OpenAPI di bagian ini:

Ganti YOUR_PROJECT_ID dengan project ID Google Cloud Anda.

Langkah 2: Konfigurasi spesifikasi OpenAPI 3.x

Buat atau perbarui spesifikasi OpenAPI 3.x untuk menentukan konfigurasi perutean model dan endpoint backend Anda.

Contoh berikut menunjukkan spesifikasi OpenAPI 3.0.3 yang menentukan dua perute model yang berbeda. Untuk mencegah scrolling horizontal, URL alamat backend yang panjang menggunakan kelanjutan string multi-baris dengan tanda kutip ganda YAML (``):

openapi: 3.0.3

info:
  title: OpenAPI 3.x spec using Model Routing
  description: Using Model Routing in an OAS 3.x spec
  version: 1.0.0

x-google-api-management:
  backends:
    gemini-35-flashlite:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/publishers/google/\
        models/gemini-3.5-flash-lite:generateContent"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

    anthropic-claude-opus-47:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/publishers/anthropic/\
        models/claude-opus-4-7:rawPredict"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

    openai-gpt-oss-120b:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/endpoints/openapi/\
        chat/completions"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

  ai:
    models:
      routing:
        routers:
          # Router 1: route between Gemini (default) and Claude.
          gemini-claude-router:
            defaultModel:
              backend: gemini-35-flashlite
              targetModel: google/gemini-3.5-flash-lite
            rules:
              - model: "claude-opus-4-7"
                backend: anthropic-claude-opus-47
                targetModel: anthropic/claude-opus-4-7

          # Router 2: route between OpenAI GPT (default) and Gemini.
          openai-gemini-router:
            defaultModel:
              backend: openai-gpt-oss-120b
              targetModel: openai/gpt-oss-120b-maas
            rules:
              - model: "gemini-3.5-flash-lite"
                backend: gemini-35-flashlite
                targetModel: google/gemini-3.5-flash-lite

servers:
  - url: "https://my-gateway-url.com"

paths:
  /v1/chat/gemini-claude:
    post:
      summary: "Endpoint:defaults to Gemini & Claude as an option."
      operationId: "chatGeminiClaude"
      x-google-model-router: gemini-claude-router
      responses:
        '200':
          description: "OK"

  /v1/chat/openai-gemini:
    post:
      summary: "Endpoint:defaults to OpenAI & Gemini as an option."
      operationId: "chatOpenAIGemini"
      x-google-model-router: openai-gemini-router
      responses:
        '200':
          description: "OK"

Properti konfigurasi

1. backends: Objek backends di bawah x-google-api-management menentukan semua endpoint model yang dapat dirutekan. Setiap nama backend merepresentasikan nama model simbolis (misalnya, gemini-35-flashlite) yang berisi address tujuan. Kolom backends adalah ekstensi Google OpenAPI yang sudah ada.
2. ai.models.routing: Konfigurasi perutean model berada di x-google-api-management sebagai ai.models.routing, yang berisi peta router bernama. Setiap entri peta menentukan satu perute model, dengan kunci yang merepresentasikan nama perute (misalnya, gemini-claude-router) dan nilai yang berisi:
   • defaultModel: Tujuan model penggantian yang diperlukan digunakan saat payload permintaan masuk tidak cocok dengan aturan eksplisit apa pun. Entri ini memiliki struktur yang sama persis dengan entri aturan, tetapi tidak menyertakan kolom pencocokan model. Untuk rute yang kompatibel dengan OpenAI, saat permintaan kembali ke defaultModel, nilai targetModel akan diteruskan sebagai atribut model keluar dalam isi permintaan yang dikirim ke Vertex AI.
   • rules: Array opsional yang setiap elemennya memetakan string model payload klien ke backend tujuan dan model target.
3. Properti aturan: Setiap entri dalam rules (dan defaultModel) menentukan properti berikut:
   • model (khusus aturan): Nilai string yang cocok dengan atribut model dalam payload perintah JSON yang masuk dari klien. Router membandingkan nilai model payload yang masuk dengan string ini. Jika tidak ada aturan yang cocok, router akan memilih defaultModel. Untuk rute yang kompatibel dengan OpenAI (dengan backend tujuan adalah /openapi/chat/completions), string ini diteruskan langsung sebagai atribut model keluar dalam isi permintaan yang dikirim ke Vertex AI. Oleh karena itu, untuk rute yang kompatibel dengan OpenAI, pemilih model itu sendiri harus berupa ID model penayang yang valid (misalnya, openai/gpt-oss-120b-maas); menggunakan alias seperti gpt-oss akan menghasilkan error 400 Malformed publisher model dari Vertex AI.
   • backend: Nama backend simbolis yang ditentukan di x-google-api-management.backends tempat gateway mengirimkan perintah.
   • targetModel: ID model target yang diformat sebagai <provider>/<model-id>. Router model menggunakan string ini untuk menerjemahkan permintaan dan respons untuk model tujuan. Awalan <provider> harus persis google, openai, atau anthropic. <model-id> harus berupa ID model penayang Vertex AI Model Garden yang valid. Gateway mengulangi string ini dalam kolom model dari respons yang ditampilkan kepada klien. Contoh nilai mencakup:
     • google/gemini-3.5-flash-lite
     • google/gemini-2.5-pro
     • openai/gpt-oss-120b-maas
     • anthropic/claude-opus-4-7
4. x-google-model-router: Untuk melampirkan perute model ke jalur operasi API, tentukan nama perute menggunakan atribut x-google-model-router. Dalam contoh sebelumnya, permintaan POST yang dikirim ke /v1/chat/gemini-claude memanggil gemini-claude-router, yang merutekan perintah berdasarkan nama model yang ditentukan dalam payload JSON.

Langkah 3: Buat dan deploy konfigurasi API

Buat konfigurasi API menggunakan spesifikasi OpenAPI 3.x yang Anda buat dan deploy konfigurasi ke instance API Gateway seperti yang dijelaskan dalam Men-deploy API ke gateway.

Bidang pengelolaan API Gateway memproses konfigurasi perutean model Anda dan mengaktifkan lapisan perutean. Setelah deployment gateway Anda selesai, gateway siap menerima permintaan perintah yang diformat sebagai payload JSON yang kompatibel dengan OpenAI.

Langkah 4: Uji perilaku perutean

Sebelum menguji gateway, tunggu hingga gateway mencapai status ACTIVE, lalu ambil URL-nya:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GATEWAY_LOCATION \
  --project=PROJECT_ID \
  --format='value(defaultHostname)'

Selama Pratinjau Publik, gateway pemilihan rute model menampilkan nama host *.run.app. Ambil nama host hanya setelah gateway ACTIVE; nilai yang dilaporkan saat gateway masih dibuat bukanlah URL akhir.

Uji perilaku perutean gateway Anda menggunakan curl untuk mengirim permintaan perintah yang kompatibel dengan OpenAI ke URL gateway Anda (https://GATEWAY_URL). Dalam contoh berikut, $TOKEN mewakili token autentikasi valid yang diperoleh menggunakan salah satu metode yang dijelaskan dalam Memilih Metode Autentikasi.

Menguji perutean aturan eksplisit

Kirim perintah yang meminta model Claude anthropic/claude-opus-4-7:

curl https://GATEWAY_URL/v1/chat/gemini-claude \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Explain the concept of recursion in one sentence."
      }
    ]
  }'

Mengirim permintaan ke /v1/chat/gemini-claude akan memanggil gemini-claude-router. Atribut "model": "claude-opus-4-7" dalam payload JSON cocok dengan aturan eksplisit di gemini-claude-router, yang mengarahkan gateway untuk merutekan permintaan ke backend anthropic-claude-opus-47.

Menguji penggantian model default

Kirim perintah yang menentukan nama model yang tidak cocok untuk menguji perutean penggantian:

curl https://GATEWAY_URL/v1/chat/gemini-claude \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "unrecognized-model",
    "messages": [
      {
        "role": "user",
        "content": "Write a short poem about the ocean."
      }
    ],
    "stream": true
  }'

Mengirim permintaan ke /v1/chat/gemini-claude akan memanggil gemini-claude-router. Karena atribut "model": "unrecognized-model" tidak cocok dengan aturan eksplisit apa pun, gateway mengirimkan permintaan ke defaultModel yang dikonfigurasi router—backend gemini-35-flashlite.

Menguji jalur router alternatif

Kirim perintah yang meminta Gemini melalui endpoint router sekunder:

curl https://GATEWAY_URL/v1/chat/openai-gemini \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "gemini-3.5-flash-lite",
    "messages": [
      {
        "role": "user",
        "content": "List the three largest cities in the world."
      }
    ]
  }'

Mengirim permintaan ke /v1/chat/openai-gemini akan memanggil openai-gemini-router. Atribut "model": "gemini-3.5-flash-lite" cocok dengan aturan eksplisit di router tersebut, yang mengarahkan gateway untuk merutekan permintaan ke backend gemini-35-flashlite. Satu backend dapat dirujuk oleh beberapa router; dalam konfigurasi ini, gemini-35-flashlite berfungsi sebagai target aturan eksplisit di openai-gemini-router dan sebagai defaultModel penggantian di gemini-claude-router.

Kemampuan observasi

Router model diinstrumentasikan sehingga Anda dapat memverifikasi bahwa gateway Anda melayani traffic, memeriksa metadata per permintaan menggunakan Cloud Logging, dan mendiagnosis kegagalan menggunakan Cloud Monitoring.

Cloud Logging

Setiap permintaan yang dirutekan melalui gateway akan membuat entri dalam log permintaan Gateway API standar yang ada di project Google Cloud Anda di:

projects/YOUR_PROJECT_ID/logs/apigateway.googleapis.com%2Frequests

Setiap entri log mencakup kolom berikut:

• httpRequest.requestUrl, httpRequest.status, httpRequest.latency
• api, apiConfig, apiMethod
• backendRequest.hostname: Nama host backend Vertex AI yang menjadi tujuan proxy permintaan.
• responseDetails: Diisi dengan kategori error bermerek pada kegagalan perute model (lihat Memecahkan masalah kegagalan perute model tepat di bawah).

Untuk menemukan permintaan terbaru yang dikirim ke gateway tertentu, gunakan filter kueri Cloud Logging berikut:

(resource.type="apigateway.googleapis.com/Gateway" OR resource.type="api")
logName="projects/YOUR_PROJECT_ID/logs/apigateway.googleapis.com%2Frequests"

Cloud Monitoring

Metrik Gateway API standar apigateway.googleapis.com/proxy/request_count (BETA) melaporkan volume traffic gateway yang dikelompokkan menurut:

• response_code_class: Salah satu dari 2xx, 3xx, 4xx, atau 5xx.
• api_config: Nama konfigurasi API yang digunakan gateway.

Metrik ini memungkinkan Anda memverifikasi volume traffic dan rasio error secara keseluruhan. Metrik khusus model router (seperti perincian per-router atau per-target-model) akan ditambahkan dalam rilis mendatang.

Untuk melacak latensi permintaan gabungan, Anda dapat membuat metrik berbasis log dari kolom httpRequest.latency di log permintaan.

Memecahkan masalah kegagalan router model

Jika permintaan yang dirutekan melalui perute model gagal, kolom responseDetails pada entri log permintaan yang sesuai menunjukkan apakah kegagalan terjadi dalam lapisan perute model. Router model menampilkan empat kategori bermerek:

Langkah berikutnya

• Tinjau arsitektur dan konsep perutean model
• Menjelajahi ekstensi OpenAPI 3.x