Scopri come creare e gestire un file di configurazione del Model Gateway, incluse le impostazioni del provider, le definizioni dei modelli, la gestione delle credenziali, la configurazione TLS e gli esempi di deployment per i provider di modelli supportati.

Il Model Gateway consente a Bob on-premises di connettersi e instradare le richieste verso modelli AI supportati di diversi provider, inclusi endpoint compatibili con OpenAI, AWS Bedrock e Google Vertex AI. Una configurazione del Model Gateway definisce gli endpoint dei modelli, le impostazioni di autenticazione, il comportamento di routing e le capacità dei modelli, mentre credenziali e certificati sensibili sono gestiti in modo sicuro tramite config.yaml.

La configurazione del model gateway è un file YAML che definisce a quali modelli il gateway si connette e come autenticarsi con ogni provider.

Attenzione:

Configura un solo modello di inference core nel model gateway alla volta. La configurazione simultanea di più modelli core non è supportata e produce comportamenti indefiniti.

Specifica del modello

Ogni voce nell'elenco models deve avere un model_name univoco. La specifica completa del modello è:

- model_name: example_model
  # Provider types (pick one per model):
  openai_compatible:  # — any OpenAI-compatible REST endpoint (Azure, vLLM, …)
  bedrock:            # — AWS Bedrock invoke endpoint
  vertex:             # — Google Vertex AI (Gemini)

  # Model metadata
  model_info:
    exposed: true                         # true: visible in /v1/model/info list; false: internal-only
    provider: openai                      # model provider (e.g. openai, anthropic, google, nvidia, mistral)
    family: gpt                           # model family within the provider (e.g. gpt, sonnet, gemini)
    version: "5.6-sol"                    # model version string (see table below)
    max_input_tokens: 270000              # context window size
    max_output_tokens: 20000              # maximum tokens the model may generate
    supports_prompt_caching: true         # true if the model supports prompt caching
    supports_vision: true                 # true if the model supports image inputs
    mode: chat                            # chat | embedding | image_generation

  # Optional free-form request parameters appended to every request sent to
  # the provider, including standard parameters (e.g. temperature, top_p,
  # max_tokens) and provider-specific extensions (e.g. top_k,
  # repetition_penalty, anthropic_beta).
  chat_inference_params:
    temperature: 0.7
    top_p: 0.9

Nota:

Affinché gli utenti possano inviare input di immagini nell'interfaccia di chat, il modello di inference core deve avere supports_vision: true impostato nel suo blocco model_info. Se questo flag è assente o false, l'input di immagini non sarà disponibile.

Attenzione:

Se supports_vision viene impostato su true per un modello che in realtà non supporta input di immagini, l'uso delle immagini fallirà con un errore del provider. Assicurati che questo flag sia abilitato solo per i modelli che supportano input di immagini. Nota che i seguenti modelli non supportano input di immagini e devono avere supports_vision: false: Laguna S2.1 e Nvidia Nemotron 3.

Valori `provider` / `family` / `version` supportati

Bob usa i campi provider, family e version insieme per selezionare la ottimizzazione del prompt e le ottimizzazioni specifiche del modello. Usa i valori più corrispondenti per i modelli non elencati.

`provider`	`family`	`version`	Esempio di ID modello
`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 di nome modello riservati

I seguenti valori model_name devono essere presenti nell'elenco models:

`model_name`	Usato per
`premium-ide`	Modello predefinito per la chat interattiva
`security`	Controlli guardrail / sicurezza
`background`	Task in background e agent autonomi

Il template definisce security e background come alias YAML merge del modello attivo, in modo che seguano automaticamente la stessa configurazione del provider. Per security e background, si raccomanda un modello più piccolo ed efficiente dove disponibile (ad esempio, openai/gpt-oss-20b).

Provider

`openai_compatible`

Si connette a qualsiasi modello ospitato esternamente con un'API REST compatibile con OpenAI (ad esempio, Azure OpenAI, vLLM, endpoint personalizzati).

- model_name: premium-ide
  openai_compatible:
    model: gpt-5.6-sol                     # Model ID as expected by the provider
    base_url: https://<resource>.cognitiveservices.azure.com/openai
    api_key: env.AZURE_API_KEY             # env.<VAR> reads from the model gateway secrets
    extra_headers:                         # Extra headers to include when inferencing
      example_header: env.HEADER_VALUE
    ca_cert_pem: env.CA_CERT               # CA certificate for TLS verification
  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`

Si connette a un modello servito tramite AWS Bedrock.

- model_name: premium-ide
  bedrock:
    model: us.anthropic.claude-sonnet-5    # Model ID as expected by the provider
    region: us-east-1                      # AWS region where your Bedrock endpoint lives
    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`

Si connette a un modello servito tramite Google Vertex AI (Gemini). Le credenziali devono essere fornite come stringa JSON dell'account di servizio con codifica base64.

- model_name: premium-ide
  vertex:
    model: gemini-3.6-flash                # Model ID as expected by the provider
    project: <gcp-project-id>              # GCP project ID
    location: global                       # Vertex AI region / "global" for Global API
    credentials: env.GEMINI_CREDENTIALS    # Service-account JSON, base64-encoded
  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

La sezione routers configura la risoluzione dei modelli tra il frontend e il backend. Il default_model configurato sarà il principale LLM usato durante le interazioni di chat.

routers:
  - name: router
    strategy: static
    static:
      default_model: premium-ide   # must match a model_name in the models list

Campo	Descrizione
`name`	Nome del router (usa sempre `router`)
`strategy`	Strategia di routing. Attualmente è supportato solo `static`
`static.default_model`	Il `model_name` da usare come LLM principale. Deve corrispondere esattamente a una voce `model_name` nell'elenco `models`

Nota:

premium-ide è uno slot di nome modello obbligatorio (vedi Slot di nome modello riservati), quindi la pratica consigliata è mantenere default_model: premium-ide e modificare quale provider/modello la voce premium-ide indica nell'elenco models.

Anchor YAML

La configurazione del model gateway supporta anchor YAML standard (&name) e merge key (<<: *name). Il template usa questo per supportare il riutilizzo ed evitare ripetizioni.

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               # overrides premium-ide from the merged anchor

  - <<: *chat_llm
    model_name: background

Gestione di credenziali e secret

Secret

Per qualsiasi secret referenziato nella configurazione del modello (chiavi API, password, certificati), configurali nel file di installazione config.yaml sotto bob.modelGateway.secrets. I secret vengono montati nel container dell'Inference Service in fase di runtime.

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

Fai riferimento a un secret nella configurazione del modello usando la sintassi env.<VAR_NAME>:

api_key: env.VAR_BAR_1

Requisiti TLS e certificati

Quando si usano endpoint privati o server di modelli interni (ad esempio, vLLM o OpenShift AI con certificati enterprise personalizzati o self-signed), è necessario fornire il certificato CA Root/Intermediate interno in modo che i container di inferencing possano stabilire la trust TLS.

Nota:

Questa configurazione TLS dell'endpoint del modello è separata dal certificato necessario per la connessione di Bob IDE e Bob Shell al backend Bob. Per i passaggi relativi al certificato dell'endpoint backend e alla trust del client, vedere Certificati TLS.

Esistono due modi per aggiungere una CA per l'inferencing:

Opzione 1 — Bundle di trust per l'inferencing (consigliato)

Aggiungi la CA a bob-inferencing-bundle-tls etichettando un Kubernetes Secret. L'operator rileva l'etichetta e ricostruisce il bundle automaticamente — non sono necessarie modifiche alla configurazione del model gateway e la CA è disponibile immediatamente per tutti i container di 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>

Il Secret bob-inferencing-bundle-tls viene montato nei container di inferencing come trust store. Contiene sempre tutto ciò che è in bob-bundle-tls più qualsiasi Secret aggiuntivo etichettato. Non è necessario riavviare il pod — i Secret vengono proiettati nel container in esecuzione.

Per dettagli completi e passaggi di verifica, vedere Certificati TLS.

Opzione 2 — `ca_cert_pem` per modello (configurazione del model gateway)

Usa questa opzione quando hai bisogno di fornire una CA per un singolo endpoint di modello specifico senza influenzare gli altri container di inferencing. I certificati TLS personalizzati seguono lo stesso pattern di configurazione distribuita a due file delle credenziali API:

In model-gateway.yaml: Imposta ca_cert_pem su un nome di variabile d'ambiente (ad esempio, env.CA_CERT).

In config.yaml: Aggiungi il nome della variabile corrispondente sotto bob.modelGateway.secrets e incolla la stringa del certificato completa con codifica PEM.

1. Configurazione del 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           # Points to the variable name defined in config.yaml
    model_info:
      exposed: true
      mode: chat

2. Configurazione di installazione (config.yaml):

bob:
  modelGateway:
    secrets:
      MODEL_API_KEY: "<your-api-key>"
      # The actual PEM certificate content matching env.CA_CERT above:
      CA_CERT: |
        -----BEGIN CERTIFICATE-----
        MIIFazCCA1OgAwIBAgIRAIIQjJaDSmJT3g4qg05...
        ... [full PEM-encoded CA certificate data] ...
        -----END CERTIFICATE-----

Durante il deployment, bobctl inietta CA_CERT nel Kubernetes Secret bob-inference-model-secrets. Questo viene poi montato nel servizio inference gateway e usato per l'handshake TLS contro il server del modello privato.

Esempio completo

Di seguito è riportato un esempio completo che rispecchia la struttura di config-model-gateway-template.yaml del Bob Bundle. Salvalo in un file (ad esempio, /tmp/example/model-gateway.yaml) e fai riferimento ad esso durante l'installazione.

Configurazione del Model Gateway

# ── Provider definitions ───────────────────────────────────────────────────────
# The x-providers key is ignored by the model gateway — it is a YAML scratchpad
# for provider examples. Only the active provider's anchor is referenced below.
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

  # Custom inference service (RHOAI, vLLM, etc.)
  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

# ── Models ────────────────────────────────────────────────────────────────────
models:

  # ── ACTIVE MODEL ─────────────────────────────────────────────────────────────
  # Change <<: *bedrock to e.g. *azure, *gemini, or *isvc to switch providers.
  - &chat_llm
    <<: *bedrock                       # ← change provider here
    model_name: premium-ide
    model_info:
      exposed: true

  # ── Aliases ───────────────────────────────────────────────────────────────────
  - <<: *chat_llm
    model_name: security               # overrides premium-ide from the merged anchor

  - <<: *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>

Comando di installazione

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

Per un ambiente connesso, specifica la tua entitlement key per icr.io. --registry-creds può essere omesso solo se hai un registry privato che non richiede autenticazione per il pull.

Deployment della configurazione

Durante l'installazione iniziale

Passa il percorso del file di configurazione del model gateway usando il flag --model-config al momento dell'installazione:

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

Attenzione:

Se bobctl install viene eseguito senza --model-config, Bob viene installato con una configurazione del model gateway vuota. L'Inference Service viene avviato ma non ha connessione ad alcun modello per l'inferencing. Usa bobctl update-model-config post-installazione per inviare una configurazione del modello al cluster.

Come le credenziali vengono deployate nel cluster

Il file di configurazione del model gateway fa riferimento alle credenziali come variabili d'ambiente (ad esempio, env.AWS_ACCESS_KEY, env.AZURE_API_KEY). Provider di modelli diversi richiedono secret diversi — chiavi IAM AWS per Bedrock, chiavi API per Azure OpenAI, o JSON dell'account di servizio per Google Gemini.

Durante l'installazione, queste credenziali vengono fornite nel tuo config.yaml sotto bob.modelGateway.secrets. La CLI bobctl elabora automaticamente questa sezione e crea un Kubernetes Secret denominato bob-inference-model-secrets nel cluster, montando le chiavi come variabili d'ambiente direttamente all'interno del container del servizio inference gateway.

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

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

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

      # Custom endpoint API keys / tokens or internal proxy auth
      # RITS_APIKEY: "<your-api-key>"

      # Custom CA certificate in PEM format for self-signed internal endpoints
      # CA_CERT: |
      #   -----BEGIN CERTIFICATE-----
      #   ...
      #   -----END CERTIFICATE-----

Aggiornamento della configurazione post-installazione (`bobctl update-model-config`)

Usa bobctl update-model-config per inviare una configurazione del model gateway e/o dei secret a un cluster attivo senza reinstallare. Questo è il percorso richiesto quando bobctl install è stato eseguito senza --model-config, ed è lo stesso comando usato per cambiare il modello di inference core.

Internamente esegue helm template sui template model-config.yaml e model-secrets.yaml nel chart ibm-bob locale, poi applica i manifest renderizzati al cluster. Una volta applicati, ibm-bob-operator riconcilia il deployment bob-inference con la nuova configurazione del modello.

Il comando gestisce due risorse cluster separate:

Flag	Risorsa cluster	Sorgente
`--model-config <file>`	`ConfigMap` `bob-inference-model-config`	Il file che passi
`--update-secrets`	`Secret` `bob-inference-model-secrets`	`bob.modelGateway.secrets` in `config.yaml`

Almeno uno dei due deve essere fornito — non passarne nessuno è un errore.

Prerequisiti:

Devi essere autenticato al cluster (oc login)

config.yaml deve esistere nella stessa directory di bobctl (copialo da config-template.yaml)

helm ≥ 3.14.0 deve essere nel PATH

Utilizzo comune:

# Update only the model config file
bobctl update-model-config --model-config ./my-model-config.yaml

# Update only the secrets (keys come from config.yaml)
bobctl update-model-config --update-secrets

# Update both at once
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets

# Preview what would be applied without touching the cluster
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets --dry-run

Tutti i flag:

Flag	Predefinito	Descrizione
`--model-config <file>`		Percorso del file di configurazione del modello da caricare nella ConfigMap
`--update-secrets`		Carica `bob.modelGateway.secrets` da `config.yaml` nel Secret
`--output-config <file>`	`model-gateway-config.yaml`	Dove scrivere il manifest ConfigMap renderizzato
`--output-secret <file>`	`model-gateway-secret.yaml`	Dove scrivere il manifest Secret renderizzato
`--cleanup`	false	Elimina i file manifest renderizzati dopo averli applicati
`--dry-run`	false	Stampa cosa verrebbe eseguito senza eseguire alcun comando `oc`

Configurazione del Model Gateway

In questa pagina