Pelajari cara membuat dan mengelola file konfigurasi Model Gateway, termasuk pengaturan penyedia, definisi model, manajemen kredensial, konfigurasi TLS, dan contoh deployment untuk penyedia model yang didukung.

Model Gateway memungkinkan Bob self-hosted terhubung dan merutekan permintaan ke model AI yang didukung di berbagai penyedia, termasuk endpoint yang kompatibel dengan OpenAI, AWS Bedrock, dan Google Vertex AI. Konfigurasi Model Gateway mendefinisikan endpoint model, pengaturan autentikasi, perilaku routing, dan kapabilitas model, sementara kredensial dan sertifikat sensitif dikelola secara aman melalui config.yaml.

Konfigurasi model gateway adalah file YAML yang menentukan model mana yang dihubungkan oleh gateway dan cara mengautentikasi dengan setiap penyedia.

Peringatan:

Konfigurasikan hanya satu model inferensi inti dalam model gateway pada satu waktu. Mengonfigurasi beberapa model inti secara bersamaan tidak didukung dan menghasilkan perilaku yang tidak terdefinisi.

Spesifikasi model

Setiap entri dalam daftar models harus memiliki model_name yang unik. Spesifikasi model lengkap adalah:

- model_name: example_model
  # Tipe penyedia (pilih satu per model):
  openai_compatible:  # — endpoint REST yang kompatibel dengan OpenAI (Azure, vLLM, …)
  bedrock:            # — endpoint invoke AWS Bedrock
  vertex:             # — Google Vertex AI (Gemini)

  # Metadata model
  model_info:
    exposed: true                         # true: terlihat di daftar /v1/model/info; false: internal-only
    provider: openai                      # penyedia model (misalnya openai, anthropic, google, nvidia, mistral)
    family: gpt                           # famili model dalam penyedia (misalnya gpt, sonnet, gemini)
    version: "5.6-sol"                    # string versi model (lihat tabel di bawah)
    max_input_tokens: 270000              # ukuran context window
    max_output_tokens: 20000              # token maksimum yang dapat dihasilkan model
    supports_prompt_caching: true         # true jika model mendukung prompt caching
    supports_vision: true                 # true jika model mendukung input gambar
    mode: chat                            # chat | embedding | image_generation

  # Parameter permintaan bebas opsional yang ditambahkan ke setiap permintaan yang dikirim ke
  # penyedia, termasuk parameter standar (misalnya temperature, top_p,
  # max_tokens) dan ekstensi spesifik penyedia (misalnya top_k,
  # repetition_penalty, anthropic_beta).
  chat_inference_params:
    temperature: 0.7
    top_p: 0.9

Catatan:

Agar pengguna dapat mengirimkan input gambar di antarmuka chat, model inferensi inti harus memiliki supports_vision: true yang diatur di blok model_info miliknya. Jika flag ini tidak ada atau false, input gambar tidak akan tersedia.

Peringatan:

Jika supports_vision diatur ke true untuk model yang sebenarnya tidak mendukung input gambar, penggunaan gambar akan gagal dengan error dari penyedia. Pastikan flag ini hanya diaktifkan untuk model yang mendukung input gambar. Perhatikan bahwa model berikut tidak mendukung input gambar dan harus memiliki supports_vision: false: Laguna S2.1 dan Nvidia Nemotron 3.

Nilai `provider` / `family` / `version` yang didukung

Bob menggunakan field provider, family, dan version secara bersama-sama untuk memilih prompt tuning dan optimasi khusus model. Gunakan nilai yang paling cocok untuk model yang tidak terdaftar.

`provider`	`family`	`version`	Contoh ID model
`openai`	`gpt`	`5.6-sol`	`gpt-5.6-sol`
`openai`	`gpt-oss`	`20b`	`openai/gpt-oss-20b`
`anthropic`	`sonnet`	`5`	`us.anthropic.claude-sonnet-5`
`google`	`gemini`	`3.6-flash`	`gemini-3.6-flash`
`google`	`gemini`	`3.1-pro`	`gemini-3.1-pro`
`nvidia`	`nemotron`	`3-ultra`	`nvidia/nemotron-3-ultra-550b`
`mistral`	`medium`	`3.5`	`mistralai/mistral-medium-3-5-0`
`poolside`	`laguna`	`s2.1`	`poolside/laguna-s-2.1`

Slot nama model yang dicadangkan

Nilai model_name berikut harus ada dalam daftar models kamu:

`model_name`	Digunakan untuk
`premium-ide`	Model default untuk chat interaktif
`security`	Pemeriksaan guardrail / keamanan
`background`	Tugas agent di latar belakang dan otonom

Template mendefinisikan security dan background sebagai alias merge YAML dari model aktif, sehingga semuanya secara otomatis mengikuti konfigurasi penyedia yang sama. Untuk security dan background, model yang lebih kecil dan lebih efisien direkomendasikan jika tersedia (misalnya, openai/gpt-oss-20b).

Penyedia

`openai_compatible`

Menghubungkan ke model yang di-host secara eksternal dengan REST API yang kompatibel dengan OpenAI (misalnya, Azure OpenAI, vLLM, endpoint kustom).

- model_name: premium-ide
  openai_compatible:
    model: gpt-5.6-sol                     # ID model seperti yang diharapkan oleh penyedia
    base_url: https://<resource>.cognitiveservices.azure.com/openai
    api_key: env.AZURE_API_KEY             # env.<VAR> membaca dari secret model gateway
    extra_headers:                         # Header tambahan untuk disertakan saat inferencing
      example_header: env.HEADER_VALUE
    ca_cert_pem: env.CA_CERT               # Sertifikat CA untuk verifikasi TLS
  model_info:
    exposed: true
    provider: openai
    family: gpt
    version: "5.6-sol"
    max_input_tokens: 270000
    max_output_tokens: 20000
    supports_prompt_caching: true
    supports_vision: true
    mode: chat

`bedrock`

Menghubungkan ke model yang dilayani melalui AWS Bedrock.

- model_name: premium-ide
  bedrock:
    model: us.anthropic.claude-sonnet-5    # ID model seperti yang diharapkan oleh penyedia
    region: us-east-1                      # AWS region tempat endpoint Bedrock kamu berada
    access_key_id: env.AWS_ACCESS_KEY      # Bedrock Access Key ID
    secret_access_key: env.AWS_SECRET_ACCESS_KEY
  model_info:
    exposed: true
    provider: anthropic
    family: sonnet
    version: "5"
    max_input_tokens: 270000
    max_output_tokens: 20000
    supports_prompt_caching: true
    supports_vision: true
    mode: chat

`vertex`

Menghubungkan ke model yang dilayani melalui Google Vertex AI (Gemini). Kredensial harus disediakan sebagai string JSON service-account yang di-encode base64.

- model_name: premium-ide
  vertex:
    model: gemini-3.6-flash                # ID model seperti yang diharapkan oleh penyedia
    project: <gcp-project-id>              # ID project GCP
    location: global                       # Region Vertex AI / "global" untuk Global API
    credentials: env.GEMINI_CREDENTIALS    # JSON Service-account, di-encode base64
  model_info:
    exposed: true
    provider: google
    family: gemini
    version: "3.6-flash"
    max_input_tokens: 270000
    max_output_tokens: 20000
    supports_prompt_caching: true
    supports_vision: true
    mode: chat

Router

Bagian routers mengonfigurasi resolusi model antara frontend dan backend. default_model yang dikonfigurasi akan menjadi LLM utama yang digunakan selama interaksi chat.

routers:
  - name: router
    strategy: static
    static:
      default_model: premium-ide   # harus cocok dengan model_name dalam daftar models

Field	Deskripsi
`name`	Nama router (selalu gunakan `router`)
`strategy`	Strategi routing. Saat ini hanya `static` yang didukung
`static.default_model`	`model_name` yang akan digunakan sebagai LLM utama. Harus sama persis dengan entri `model_name` dalam daftar `models`

Catatan:

premium-ide adalah slot nama model yang diperlukan (lihat Slot nama model yang dicadangkan), jadi praktik yang direkomendasikan adalah mempertahankan default_model: premium-ide dan mengubah penyedia/model mana yang dituju oleh entri premium-ide dalam daftar models kamu.

YAML anchor

Konfigurasi model gateway mendukung YAML anchor standar (&name) dan merge key (<<: *name). Template menggunakan ini untuk mendukung penggunaan kembali dan menghindari pengulangan.

x-providers:
  gemini: &gemini
    vertex:
      model: gemini-3.6-flash
      project: <gcp-project-id>
      location: global
      credentials: env.GEMINI_CREDENTIALS
    model_info:
      exposed: true
      provider: google
      family: gemini
      version: "3.6-flash"
      max_input_tokens: 270000
      max_output_tokens: 20000
      supports_prompt_caching: true
      supports_vision: true
      mode: chat

models:
  - &chat_llm
    <<: *gemini
    model_name: premium-ide

  - <<: *chat_llm
    model_name: security               # menimpa premium-ide dari anchor yang digabungkan

  - <<: *chat_llm
    model_name: background

Manajemen kredensial dan secret

Secret

Untuk semua secret yang dirujuk dalam konfigurasi model (API key, kata sandi, sertifikat), konfigurasikan di config.yaml instalasi di bawah bob.modelGateway.secrets. Secret dipasang ke dalam container Inference Service saat runtime.

bob:
  modelGateway:
    secrets:
      VAR_BAR_1: FOO_1
      VAR_BAR_2: FOO_2
      VAR_BAR_N: FOO_N

Rujuk secret dalam konfigurasi model menggunakan sintaks env.<VAR_NAME>:

api_key: env.VAR_BAR_1

Persyaratan TLS dan sertifikat

Saat menggunakan private endpoint atau server model internal (misalnya, vLLM atau OpenShift AI dengan sertifikat enterprise kustom atau self-signed), kamu harus menyediakan sertifikat Root/Intermediate CA internalmu sehingga container inferencing dapat membangun kepercayaan TLS.

Catatan:

Konfigurasi TLS model-endpoint ini terpisah dari sertifikat yang diperlukan untuk Bob IDE dan Bob Shell untuk terhubung ke backend Bob. Untuk sertifikat endpoint backend dan langkah kepercayaan klien, lihat Sertifikat TLS.

Ada dua cara untuk menambahkan CA untuk inferencing:

Opsi 1 — Trust bundle inferencing (direkomendasikan)

Tambahkan CA ke bob-inferencing-bundle-tls dengan memberi label pada Kubernetes Secret. Operator mendeteksi label dan membangun ulang bundle secara otomatis — tidak diperlukan perubahan konfigurasi model gateway dan CA langsung tersedia untuk semua container inferencing.

oc create secret generic my-model-endpoint-ca \
  --from-file=tls.crt=model-ca.crt \
  -n <instance-namespace>

oc label secret my-model-endpoint-ca \
  bob.ibm.com/inferencing-bundle-ca=true \
  -n <instance-namespace>

Secret bob-inferencing-bundle-tls dipasang ke dalam container inferencing sebagai trust store mereka. Ini selalu berisi semua yang ada di bob-bundle-tls ditambah Secret berlabel tambahan. Tidak diperlukan restart pod — Secret diproyeksikan ke dalam container yang sedang berjalan.

Untuk detail lengkap dan langkah verifikasi, lihat Sertifikat TLS.

Opsi 2 — `ca_cert_pem` per-model (konfigurasi model gateway)

Gunakan ini saat kamu perlu menyediakan CA untuk satu endpoint model tertentu tanpa memengaruhi container inferencing lainnya. Sertifikat TLS kustom mengikuti pola konfigurasi terdistribusi dua file yang sama seperti kredensial API:

Di model-gateway.yaml: Tetapkan ca_cert_pem ke nama environment variable (misalnya, env.CA_CERT).

Di config.yaml: Tambahkan nama variabel yang cocok di bawah bob.modelGateway.secrets dan tempel string sertifikat berformat PEM lengkap.

1. Konfigurasi model gateway (model-gateway.yaml):

models:
  - model_name: example-model
    openai_compatible:
      model: mistral-3.5
      base_url: https://vllm.internal.corp:8000/v1
      api_key: env.MODEL_API_KEY
      ca_cert_pem: env.CA_CERT           # Merujuk ke nama variabel yang didefinisikan di config.yaml
    model_info:
      exposed: true
      mode: chat

2. Konfigurasi instalasi (config.yaml):

bob:
  modelGateway:
    secrets:
      MODEL_API_KEY: "<your-api-key>"
      # Konten sertifikat PEM sebenarnya yang cocok dengan env.CA_CERT di atas:
      CA_CERT: |
        -----BEGIN CERTIFICATE-----
        MIIFazCCA1OgAwIBAgIRAIIQjJaDSmJT3g4qg05...
        ... [data sertifikat CA lengkap berformat PEM] ...
        -----END CERTIFICATE-----

Selama deployment, bobctl menyuntikkan CA_CERT ke dalam Kubernetes Secret bob-inference-model-secrets. Ini kemudian dipasang ke dalam layanan inference gateway dan digunakan untuk TLS handshake terhadap server model privatmu.

Contoh lengkap

Berikut adalah contoh lengkap yang mencerminkan struktur config-model-gateway-template.yaml dari Bob Bundle. Simpan ke sebuah file (misalnya, /tmp/example/model-gateway.yaml) dan rujuk pada saat instalasi.

Konfigurasi Model Gateway

# ── Definisi penyedia ─────────────────────────────────────────────────────────
# Kunci x-providers diabaikan oleh model gateway — ini adalah scratchpad YAML
# untuk contoh penyedia. Hanya anchor penyedia yang aktif yang dirujuk di bawah.
x-providers:

  # AWS Bedrock
  bedrock: &bedrock
    bedrock:
      model: us.anthropic.claude-sonnet-5
      region: us-east-1
      access_key_id: env.AWS_ACCESS_KEY
      secret_access_key: env.AWS_SECRET_ACCESS_KEY
    model_info:
      exposed: true
      provider: anthropic
      family: sonnet
      version: "5"
      max_input_tokens: 270000
      max_output_tokens: 20000
      supports_prompt_caching: true
      supports_vision: true
      mode: chat

  # Google Vertex AI (Gemini)
  gemini: &gemini
    vertex:
      model: gemini-3.6-flash
      project: <gcp-project-id>
      location: global
      credentials: env.GEMINI_CREDENTIALS
    model_info:
      exposed: true
      provider: google
      family: gemini
      version: "3.6-flash"
      max_input_tokens: 270000
      max_output_tokens: 20000
      supports_prompt_caching: true
      supports_vision: true
      mode: chat

  # Azure OpenAI
  azure: &azure
    openai_compatible:
      model: gpt-5.6-sol
      base_url: https://<resource>.cognitiveservices.azure.com/openai
      api_key: env.AZURE_API_KEY
    model_info:
      exposed: true
      provider: openai
      family: gpt
      version: "5.6-sol"
      max_input_tokens: 270000
      max_output_tokens: 20000
      supports_prompt_caching: true
      supports_vision: true
      mode: chat

  # Layanan inferensi kustom (RHOAI, vLLM, dll.)
  inference_service: &isvc
    openai_compatible:
      model: nvidia/nemotron-3-ultra-550b
      base_url: https://<llm-inference-server>
      api_key: env.INFERENCE_API_KEY
    model_info:
      exposed: true
      provider: nvidia
      family: nemotron
      version: "3-ultra"
      max_input_tokens: 262144
      supports_vision: false
      mode: chat

# ── Model ────────────────────────────────────────────────────────────────────
models:

  # ── MODEL AKTIF ─────────────────────────────────────────────────────────────
  # Ubah <<: *bedrock menjadi misalnya *azure, *gemini, atau *isvc untuk beralih penyedia.
  - &chat_llm
    <<: *bedrock                       # ← ubah penyedia di sini
    model_name: premium-ide
    model_info:
      exposed: true

  # ── Alias ───────────────────────────────────────────────────────────────────
  - <<: *chat_llm
    model_name: security               # menimpa premium-ide dari anchor yang digabungkan

  - <<: *chat_llm
    model_name: background

# ── Router ────────────────────────────────────────────────────────────────────
routers:
  - name: router
    strategy: static
    static:
      default_model: premium-ide

Secret (`config.yaml`)

bob:
  modelGateway:
    secrets:
      AWS_ACCESS_KEY: "<your-aws-access-key-id>"
      AWS_SECRET_ACCESS_KEY: "<your-aws-secret-access-key>"
      GEMINI_CREDENTIALS: "<base64-encoded service-account JSON>"
      AZURE_API_KEY: "<your-azure-api-key>"
      INFERENCE_API_KEY: "<your-inference-api-key>"
      CA_CERT: <PEM encoded CA cert>

Perintah instalasi

bobctl install --model-config /tmp/example/model-gateway.yaml --accept-license --registry-creds <username:password>

Untuk lingkungan yang terhubung, tentukan entitlement key kamu untuk icr.io. --registry-creds hanya dapat diabaikan jika kamu memiliki private registry yang tidak memerlukan autentikasi untuk pull.

Men-deploy konfigurasi

Selama instalasi awal

Berikan jalur ke file konfigurasi model gateway menggunakan flag --model-config saat instalasi:

bobctl install --model-config path/to/model-gateway-config.yaml --accept-license --registry-creds <username:password>

Peringatan:

Jika bobctl install dijalankan tanpa --model-config, Bob diinstal dengan konfigurasi model gateway kosong. Layanan Inference berjalan tetapi tidak memiliki koneksi ke model apa pun untuk inferencing. Gunakan bobctl update-model-config pasca-instalasi untuk menerapkan konfigurasi model ke cluster.

Bagaimana kredensial di-deploy ke cluster

File konfigurasi model gateway merujuk kredensial sebagai environment variable (misalnya, env.AWS_ACCESS_KEY, env.AZURE_API_KEY). Penyedia model yang berbeda memerlukan secret yang berbeda — AWS IAM key untuk Bedrock, API key untuk Azure OpenAI, atau service account JSON untuk Google Gemini.

Selama instalasi, kredensial ini disediakan dalam config.yaml kamu di bawah bob.modelGateway.secrets. CLI bobctl secara otomatis memproses bagian ini dan membuat Kubernetes Secret bernama bob-inference-model-secrets di dalam cluster, memasang kunci sebagai environment variable langsung di dalam container layanan inference gateway.

bob:
  modelGateway:
    secrets:
      # Autentikasi AWS Bedrock
      AWS_ACCESS_KEY: "<your-aws-access-key-id>"
      AWS_SECRET_ACCESS_KEY: "<your-aws-secret-access-key>"

      # Autentikasi Azure OpenAI
      AZURE_API_KEY: "<your-azure-api-key>"

      # Autentikasi Google Cloud Vertex AI / Gemini
      GEMINI_CREDENTIALS: "<your-gemini-credentials-json>"

      # API key / token endpoint kustom atau autentikasi proxy internal
      # RITS_APIKEY: "<your-api-key>"

      # Sertifikat CA kustom dalam format PEM untuk endpoint internal self-signed
      # CA_CERT: |
      #   -----BEGIN CERTIFICATE-----
      #   ...
      #   -----END CERTIFICATE-----

Memperbarui konfigurasi pasca-instalasi (`bobctl update-model-config`)

Gunakan bobctl update-model-config untuk menerapkan konfigurasi model gateway dan/atau secret ke cluster yang sedang berjalan tanpa perlu menginstal ulang. Ini adalah jalur yang diperlukan jika bobctl install dijalankan tanpa --model-config, dan perintah yang sama digunakan saat mengganti model inferensi inti.

Di balik layar, perintah ini menjalankan helm template terhadap template model-config.yaml dan model-secrets.yaml di chart lokal ibm-bob, lalu menerapkan manifes yang di-render ke cluster. Setelah diterapkan, ibm-bob-operator merekonsiliasi deployment bob-inference dengan konfigurasi model yang baru.

Perintah ini mengelola dua resource cluster yang terpisah:

Flag	Resource cluster	Sumber
`--model-config <file>`	`ConfigMap` `bob-inference-model-config`	File yang kamu masukkan
`--update-secrets`	`Secret` `bob-inference-model-secrets`	`bob.modelGateway.secrets` di `config.yaml`

Setidaknya salah satu dari keduanya harus diberikan — tidak memberikan keduanya akan menghasilkan error.

Prasyarat:

Kamu harus sudah login ke cluster (oc login)

config.yaml harus ada di sebelah bobctl (salin dari config-template.yaml)

helm ≥ 3.14.0 harus ada di PATH-mu

Penggunaan umum:

# Perbarui hanya file konfigurasi model
bobctl update-model-config --model-config ./my-model-config.yaml

# Perbarui hanya secret (kunci diambil dari config.yaml)
bobctl update-model-config --update-secrets

# Perbarui keduanya sekaligus
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets

# Pratinjau apa yang akan diterapkan tanpa menyentuh cluster
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets --dry-run

Semua flag:

Flag	Default	Deskripsi
`--model-config <file>`		Jalur ke file konfigurasi model untuk dimasukkan ke dalam ConfigMap
`--update-secrets`		Menerapkan `bob.modelGateway.secrets` dari `config.yaml` ke dalam Secret
`--output-config <file>`	`model-gateway-config.yaml`	Tempat menulis manifes ConfigMap yang di-render
`--output-secret <file>`	`model-gateway-secret.yaml`	Tempat menulis manifes Secret yang di-render
`--cleanup`	false	Hapus file manifes yang di-render setelah menerapkannya
`--dry-run`	false	Cetak apa yang akan dijalankan tanpa mengeksekusi perintah `oc` apa pun

Mengonfigurasi Model Gateway

Spesifikasi model

Nilai `provider` / `family` / `version` yang didukung

Slot nama model yang dicadangkan

Penyedia

`openai_compatible`

`bedrock`

`vertex`

Router

YAML anchor

Manajemen kredensial dan secret

Secret

Persyaratan TLS dan sertifikat

Opsi 1 — Trust bundle inferencing (direkomendasikan)

Opsi 2 — `ca_cert_pem` per-model (konfigurasi model gateway)

Contoh lengkap

Konfigurasi Model Gateway

Secret (`config.yaml`)

Perintah instalasi

Men-deploy konfigurasi

Selama instalasi awal

Bagaimana kredensial di-deploy ke cluster

Memperbarui konfigurasi pasca-instalasi (`bobctl update-model-config`)

Di halaman ini