Saiba como criar e gerenciar um arquivo de configuração do Model Gateway, incluindo configurações do provedor, definições de modelos, gerenciamento de credenciais, configuração TLS e exemplos de implantação para provedores de modelos suportados.

O Model Gateway permite que o Bob on-premises se conecte e roteie solicitações para modelos de IA suportados de diferentes provedores, incluindo endpoints compatíveis com OpenAI, AWS Bedrock e Google Vertex AI. Uma configuração do Model Gateway define os endpoints de modelo, as configurações de autenticação, o comportamento de roteamento e as capacidades do modelo, enquanto as credenciais e os certificados sensíveis são gerenciados com segurança por meio do config.yaml.

A configuração do model gateway é um arquivo YAML que define a quais modelos o gateway se conecta e como autenticar com cada provedor.

Aviso:

Configure apenas um modelo de inferência principal no model gateway por vez. Configurar múltiplos modelos principais simultaneamente não é suportado e resulta em comportamento indefinido.

Especificação de modelo

Cada entrada na lista models deve ter um model_name único. A especificação completa do modelo é:

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

Para que os usuários enviem entradas de imagem na interface de chat, o modelo de inferência principal deve ter supports_vision: true definido no seu bloco model_info. Se esta flag estiver ausente ou for false, a entrada de imagem não estará disponível.

Aviso:

Se supports_vision for definido como true para um modelo que na verdade não suporta entradas de imagem, o uso de imagens falhará com um erro do provedor. Certifique-se de que esta flag seja habilitada apenas para modelos que suportam entradas de imagem. Note que os seguintes modelos não suportam entradas de imagem e devem ter supports_vision: false: Laguna S2.1 e Nvidia Nemotron 3.

Valores suportados de `provider` / `family` / `version`

Bob usa os campos provider, family e version em conjunto para selecionar ajuste fino de prompt e otimizações específicas do modelo. Use os valores mais próximos para modelos não listados.

`provider`	`family`	`version`	Exemplo de ID de modelo
`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`

Slots de nomes de modelos reservados

Os seguintes valores de model_name devem estar presentes na sua lista models:

`model_name`	Usado para
`premium-ide`	Modelo padrão para chat interativo
`security`	Verificações de guardrail / segurança
`background`	Tarefas de agente autônomo e em segundo plano

O template define security e background como aliases de merge YAML do modelo ativo, para que todos sigam a mesma configuração do provedor automaticamente. Para security e background, um modelo menor e mais eficiente é recomendado quando disponível (por exemplo, openai/gpt-oss-20b).

Provedores

`openai_compatible`

Conecta-se a qualquer modelo hospedado externamente com uma API REST compatível com OpenAI (por exemplo, Azure OpenAI, vLLM, endpoints personalizados).

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

Conecta-se a um modelo servido via 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`

Conecta-se a um modelo servido via Google Vertex AI (Gemini). As credenciais devem ser fornecidas como uma string JSON de conta de serviço codificada em 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

Roteadores

A seção routers configura a resolução de modelo entre o frontend e o backend. O default_model configurado será o LLM principal usado durante as interações de chat.

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

Campo	Descrição
`name`	Nome do roteador (use sempre `router`)
`strategy`	Estratégia de roteamento. Atualmente apenas `static` é suportado
`static.default_model`	O `model_name` a ser usado como LLM principal. Deve corresponder exatamente a uma entrada `model_name` na lista `models`

Nota:

premium-ide é um slot de nome de modelo obrigatório (veja Slots de nomes de modelos reservados), portanto a prática recomendada é manter default_model: premium-ide e alterar a qual provedor/modelo a entrada premium-ide aponta na sua lista models.

Âncoras YAML

A configuração do model gateway suporta âncoras YAML padrão (&name) e chaves de merge (<<: *name). O template usa isso para suportar reutilização e evitar repetição.

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

Gerenciamento de credenciais e segredos

Segredos

Para quaisquer segredos referenciados na configuração do modelo (chaves de API, senhas, certificados), configure-os no config.yaml de instalação em bob.modelGateway.secrets. Os segredos são montados no container do Inference Service em runtime.

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

Referencie um segredo na configuração do modelo usando a sintaxe env.<VAR_NAME>:

api_key: env.VAR_BAR_1

Requisitos de TLS e certificados

Ao usar endpoints privados ou servidores de modelo internos (por exemplo, vLLM ou OpenShift AI com certificados corporativos personalizados ou autoassinados), você deve fornecer seu certificado CA Raiz/Intermediário interno para que os containers de inferência possam estabelecer a confiança TLS.

Nota:

Esta configuração TLS de endpoint de modelo é separada do certificado necessário para que o Bob IDE e o Bob Shell se conectem ao backend do Bob. Para as etapas de certificado do endpoint de backend e confiança do cliente, consulte Certificados TLS.

Há duas formas de adicionar uma CA para inferência:

Opção 1 — Bundle de confiança de inferência (recomendado)

Adicione a CA ao bob-inferencing-bundle-tls rotulando um Secret do Kubernetes. O operador detecta o rótulo e reconstrói o bundle automaticamente — nenhuma alteração na configuração do model gateway é necessária e a CA fica disponível imediatamente para todos os containers de inferência.

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>

O Secret bob-inferencing-bundle-tls é montado nos containers de inferência como seu armazenamento de confiança. Ele sempre contém tudo que está em bob-bundle-tls mais quaisquer Secrets rotulados adicionalmente. Nenhuma reinicialização de pod é necessária — os Secrets são projetados no container em execução.

Para detalhes completos e etapas de verificação, consulte Certificados TLS.

Opção 2 — `ca_cert_pem` por modelo (configuração do model gateway)

Use isso quando precisar fornecer uma CA para um único endpoint de modelo específico sem afetar outros containers de inferência. Os certificados TLS personalizados seguem o mesmo padrão de configuração distribuída em dois arquivos das credenciais de API:

Em model-gateway.yaml: defina ca_cert_pem como um nome de variável de ambiente (por exemplo, env.CA_CERT).

Em config.yaml: adicione o nome de variável correspondente em bob.modelGateway.secrets e cole a string do certificado codificado em PEM completo.

1. Configuração do 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. Configuração de instalação (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 a implantação, o bobctl injeta CA_CERT no Secret do Kubernetes bob-inference-model-secrets. Ele é então montado no serviço inference gateway e usado para o handshake TLS com seu servidor de modelo privado.

Exemplo completo

A seguir, um exemplo completo espelhando a estrutura de config-model-gateway-template.yaml do Bob Bundle. Salve-o em um arquivo (por exemplo, /tmp/example/model-gateway.yaml) e referencie-o no momento da instalação.

Configuração do 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

Segredos (`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 de instalação

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

Para um ambiente conectado, especifique sua chave de direito para icr.io. --registry-creds só pode ser omitido se você tiver um registro privado que não requer autenticação para fazer pull.

Implantando a configuração

Durante a instalação inicial

Passe o caminho para o arquivo de configuração do model gateway usando o flag --model-config no momento da instalação:

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

Aviso:

Se bobctl install for executado sem --model-config, o Bob é instalado com uma configuração de model gateway vazia. O Inference Service é executado, mas não tem conexão com nenhum modelo para inferência. Use bobctl update-model-config após a instalação para enviar uma configuração de modelo para o cluster.

Como as credenciais são implantadas no cluster

O arquivo de configuração do model gateway referencia as credenciais como variáveis de ambiente (por exemplo, env.AWS_ACCESS_KEY, env.AZURE_API_KEY). Diferentes provedores de modelos requerem segredos diferentes — chaves IAM da AWS para Bedrock, chaves de API para Azure OpenAI, ou JSON de conta de serviço para Google Gemini.

Durante a instalação, essas credenciais são fornecidas no seu config.yaml em bob.modelGateway.secrets. O CLI bobctl processa automaticamente essa seção e cria um Secret do Kubernetes chamado bob-inference-model-secrets no cluster, montando as chaves como variáveis de ambiente diretamente dentro do container do serviço 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-----

Atualizando a configuração após a instalação (`bobctl update-model-config`)

Use bobctl update-model-config para enviar uma configuração de model gateway e/ou segredos para um cluster ativo sem reinstalar. Esse é o caminho obrigatório quando bobctl install foi executado sem --model-config, e o mesmo comando usado ao trocar o modelo de inferência principal.

Internamente, ele executa helm template contra os templates model-config.yaml e model-secrets.yaml no chart local ibm-bob e aplica os manifestos renderizados ao cluster. Uma vez aplicado, o ibm-bob-operator reconcilia o deployment bob-inference com a nova configuração do modelo.

O comando gerencia dois recursos separados do cluster:

Flag	Recurso do cluster	Origem
`--model-config <file>`	`ConfigMap` `bob-inference-model-config`	O arquivo que você passa
`--update-secrets`	`Secret` `bob-inference-model-secrets`	`bob.modelGateway.secrets` no `config.yaml`

Pelo menos um dos dois deve ser fornecido — não passar nenhum é um erro.

Pré-requisitos:

Você deve estar logado no cluster (oc login)

config.yaml deve existir ao lado do bobctl (copie de config-template.yaml)

helm ≥ 3.14.0 deve estar no seu PATH

Uso comum:

# 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

Todos os flags:

Flag	Padrão	Descrição
`--model-config <file>`		Caminho para o arquivo de configuração do modelo a ser enviado para o ConfigMap
`--update-secrets`		Envia `bob.modelGateway.secrets` do `config.yaml` para o Secret
`--output-config <file>`	`model-gateway-config.yaml`	Local para gravar o manifesto do ConfigMap renderizado
`--output-secret <file>`	`model-gateway-secret.yaml`	Local para gravar o manifesto do Secret renderizado
`--cleanup`	false	Exclui os arquivos de manifesto renderizados após aplicá-los
`--dry-run`	false	Imprime o que seria executado sem executar nenhum comando `oc`

Configurando o Model Gateway

Especificação de modelo

Valores suportados de `provider` / `family` / `version`

Slots de nomes de modelos reservados

Provedores

`openai_compatible`

`bedrock`

`vertex`

Roteadores

Âncoras YAML

Gerenciamento de credenciais e segredos

Segredos

Requisitos de TLS e certificados

Opção 1 — Bundle de confiança de inferência (recomendado)

Opção 2 — `ca_cert_pem` por modelo (configuração do model gateway)

Exemplo completo

Configuração do Model Gateway

Segredos (`config.yaml`)

Comando de instalação

Implantando a configuração

Durante a instalação inicial

Como as credenciais são implantadas no cluster

Atualizando a configuração após a instalação (`bobctl update-model-config`)

Nesta página