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, as opções de fallback 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, …)
  bedrock:            # — AWS Bedrock invoke endpoint
  vertex:             # — Google Vertex AI (Gemini)

  # Model info parameters (optional)
  model_info:
    exposed: true                          # true: visible in /models list; false: internal-only
    max_input_tokens: 128000               # context window size
    max_output_tokens: 4096                # maximum tokens the model may generate
    input_cost_per_token: 0.0000025        # cost in USD per input token (used for usage metering)
    output_cost_per_token: 0.000010        # cost in USD per output token
    cache_read_input_token_cost: 0.00      # cost for cache-hit input tokens (prompt caching)
    cache_creation_input_token_cost: 0.00  # cost to write a new cache entry
    supports_prompt_caching: true          # true if the model supports prompt caching
    supports_function_calling: true        # true if the model supports tool/function calls
    supports_tool_choice: true             # true if tool_choice param is honoured
    supports_reasoning: false              # true if the model supports a reasoning_effort param
    supports_vision: false                 # true if the model accepts image inputs in chat messages
    mode: chat                             # chat | embedding | image_generation

  # Optional ordered list of model_name values to try when this model is unavailable
  fallbacks:
    - fallback_model

  # 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

Aviso:

Defina supports_vision: true somente em modelos que aceitam entradas de imagem. Se supports_vision for definido como true em um modelo que não suporta entradas de imagem, o envio de uma imagem no chat resultará em erro do provedor. Os seguintes modelos não suportam entradas de imagem e devem usar supports_vision: false ou omitir a flag: Laguna S2.1 e Nvidia Nemotron 3.

Provedores

`openai_compatible`

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

openai_compatible:
  model: gpt-4o                          # Model ID as expected by the provider
  base_url: https://base_url             # Base URL of model deployment
  api_key: env.API_KEY                   # API key to authenticate. env.<VAR> reads from the container environment
  extra_headers:                         # Extra headers to include when inferencing
    example_header: env.HEADER_VALUE
  insecure_skip_verify: true             # Disable TLS verification (not recommended for production)
  ca_cert_pem: env.CA_CERT               # CA certificate for TLS verification

`bedrock`

Conecta-se a um modelo servido via AWS Bedrock.

bedrock:
  model: claude                                  # 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   # Bedrock Secret Access Key

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

vertex:
  model: gemini                              # Model ID as expected by the provider
  project: my-gcp-project                    # GCP project ID
  location: global                           # Vertex AI region / "global" for Global API
  credentials: env.GEMINI_CREDENTIALS        # Service-account JSON, base64-encoded

Âncoras YAML

Âncoras de credenciais

Defina as credenciais uma vez e referencie-as com <<: *anchor-name em múltiplas entradas de modelo para evitar repetição.

# AWS Bedrock credentials — referenced by bedrock models.
x-aws-bedrock-auth: &aws-bedrock-auth
  region: us-east-1
  access_key_id: env.AWS_ACCESS_KEY
  secret_access_key: env.AWS_SECRET_ACCESS_KEY

models:
  - model_name: my-bedrock-model
    bedrock:
      model: claude
      <<: *aws-bedrock-auth            # merge credentials anchor defined above
    model_info:
      exposed: true
      mode: chat

Âncoras de modelo

Mescle um bloco de modelo completo em várias entradas para evitar repetir a configuração do provedor e o model_info.

x-my-base-model: &my-base-model
  vertex:
    model: gemini-2.5-pro
    project: my-gcp-project
    location: global
    credentials: env.GEMINI_CREDENTIALS
  model_info:
    exposed: false
    supports_reasoning: true
    mode: chat

models:
  - model_name: my-gemini-model
    <<: *my-base-model

  - model_name: my-second-gemini-model
    <<: *my-base-model

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

O bundle de CA raiz inclui certificados CA públicos padrão para provedores de nuvem. No entanto, 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 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.

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.

Configuração do model gateway:

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

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 container do serviço inference gateway e usado para o handshake TLS com seu servidor de modelo privado.

Exemplo completo

A seguir, um exemplo completo cobrindo todos os tipos de provedor. Salve a configuração do model gateway em um arquivo (por exemplo, /tmp/example/model-gateway.yaml) e referencie-o no momento da instalação.

Configuração do model gateway (/tmp/example/model-gateway.yaml)

# ── Credential anchors (shared across model entries via YAML merge keys) ──────
# AWS Bedrock credentials
x-aws-bedrock-auth: &aws-bedrock-auth
  region: us-east-1
  access_key_id: env.AWS_ACCESS_KEY
  secret_access_key: env.AWS_SECRET_ACCESS_KEY

# Google Vertex AI credentials
x-vertex-auth: &vertex-auth
  project: my-gcp-project
  location: global
  credentials: env.GEMINI_CREDENTIALS

# ── Shared model anchors (optional) ───────────────────────────────────────────
x-my-base-model: &my-base-model
  vertex:
    model: gemini-2.5-pro
    <<: *vertex-auth
  model_info:
    exposed: true
    max_input_tokens: 200000
    max_output_tokens: 12000
    input_cost_per_token: 0.00000125
    output_cost_per_token: 0.00001
    cache_read_input_token_cost: 0.000000125
    supports_reasoning: true
    mode: chat

# ── Models ────────────────────────────────────────────────────────────────────
models:
  # OpenAI-compatible model (e.g. Azure OpenAI) with API key
  - model_name: my-gpt-model
    openai_compatible:
      model: gpt-4o
      base_url: https://<resource>.cognitiveservices.azure.com/openai
      api_key: env.BOB_AZURE_API_KEY
    model_info:
      exposed: true
      max_input_tokens: 128000
      max_output_tokens: 4096
      input_cost_per_token: 0.0000025
      output_cost_per_token: 0.000010
      supports_function_calling: true
      supports_tool_choice: true
      mode: chat
    chat_inference_params:
      temperature: 0.7
      top_p: 0.9

  # AWS Bedrock model
  - model_name: my-bedrock-model
    bedrock:
      model: us.anthropic.claude-3-5-sonnet-20241022-v2:0
      <<: *aws-bedrock-auth
    fallbacks:                          # optional: ordered list of fallback model names
      - my-fallback-model
    model_info:
      exposed: false
      max_input_tokens: 200000
      max_output_tokens: 8192
      input_cost_per_token: 0.000003
      output_cost_per_token: 0.000015
      cache_creation_input_token_cost: 0.00000375
      cache_read_input_token_cost: 0.0000003
      supports_prompt_caching: true
      supports_function_calling: true
      supports_tool_choice: true
      mode: chat
    chat_inference_params:
      temperature: 0.7
      top_k: 50

  # Google Vertex AI (Gemini) model using shared model anchor
  - model_name: my-gemini-model
    <<: *my-base-model

  # OpenAI-compatible model with custom CA certificate
  - model_name: example-model-mini
    openai_compatible:
      model: gpt-4o-mini
      base_url: https://llm-mock-server.ca-tor.containers.appdomain.cloud
      ca_cert_pem: env.CA_CERT
    model_info:
      exposed: true
      max_input_tokens: 131072
      input_cost_per_token: 0.00000015
      output_cost_per_token: 0.0000006
      supports_function_calling: true
      supports_tool_choice: true
      mode: chat

  # OpenAI-compatible model with extra headers
  - model_name: another-example-model-mini
    openai_compatible:
      model: gpt-4o-mini
      base_url: https://llm-mock-server.ca-tor.containers.appdomain.cloud
      extra_headers:
        model_key: env.MODEL_KEY
    model_info:
      exposed: true
      max_input_tokens: 131072
      input_cost_per_token: 0.00000015
      output_cost_per_token: 0.0000006
      supports_function_calling: true
      supports_tool_choice: true
      mode: chat

Segredos (config.yaml)

bob:
  modelGateway:
    secrets:
      BOB_AZURE_API_KEY: someapikeyvalue
      AWS_ACCESS_KEY: someapikeyvalue
      AWS_SECRET_ACCESS_KEY: someapikeyvalue
      GEMINI_CREDENTIALS: <base64_vertex_credentials>
      CA_CERT: <PEM encoded CA cert>
      MODEL_KEY: apikeyvalue

Comando de instalação

bobctl install --model-config /tmp/example/model-gateway.yaml

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

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.BOB_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
      BOB_AZURE_API_KEY: "<your-azure-api-key>"

      # Google Cloud Vertex AI / Gemini authentication
      BOB_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.

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

Provedores

`openai_compatible`

`bedrock`

`vertex`

Âncoras YAML

Âncoras de credenciais

Âncoras de modelo

Gerenciamento de credenciais e segredos

Segredos

Requisitos de TLS e certificados

Exemplo completo

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