Aprende a crear y gestionar un archivo de configuración del gateway de modelos, incluyendo los ajustes del proveedor, las definiciones de modelos, la gestión de credenciales, la configuración TLS y ejemplos de despliegue para los proveedores de modelos compatibles.

El gateway de modelos permite a Bob on-premises conectarse y enrutar solicitudes a los modelos de IA compatibles de distintos proveedores, como endpoints compatibles con OpenAI, AWS Bedrock y Google Vertex AI. Una configuración del gateway de modelos define los endpoints de modelos, los ajustes de autenticación, el comportamiento de enrutamiento y las capacidades del modelo, mientras que las credenciales y los certificados confidenciales se gestionan de forma segura a través de config.yaml.

La configuración del gateway de modelos es un archivo YAML que define a qué modelos se conecta el gateway y cómo autenticarse con cada proveedor.

Advertencia:

Configura solo un modelo de inferencia principal en el gateway de modelos a la vez. Configurar varios modelos principales simultáneamente no está soportado y produce comportamiento indefinido.

Especificación de modelos

Cada entrada en la lista models debe tener un model_name único. La especificación completa del modelo es:

- model_name: example_model
  # Tipos de proveedor (elige uno por modelo):
  openai_compatible:  # — cualquier endpoint REST compatible con OpenAI (Azure, vLLM, …)
  bedrock:            # — endpoint de invocación de AWS Bedrock
  vertex:             # — Google Vertex AI (Gemini)

  # Metadatos del modelo
  model_info:
    exposed: true                         # true: visible en la lista /v1/model/info; false: solo interno
    provider: openai                      # proveedor del modelo (p. ej. openai, anthropic, google, nvidia, mistral)
    family: gpt                           # familia del modelo dentro del proveedor (p. ej. gpt, sonnet, gemini)
    version: "5.6-sol"                    # cadena de versión del modelo (ver tabla abajo)
    max_input_tokens: 270000              # tamaño de la ventana de contexto
    max_output_tokens: 20000              # máximo de tokens que el modelo puede generar
    supports_prompt_caching: true         # true si el modelo soporta caché de prompts
    supports_vision: true                 # true si el modelo soporta entradas de imagen
    mode: chat                            # chat | embedding | image_generation

  # Parámetros de solicitud opcionales de forma libre que se añaden a cada solicitud enviada al
  # proveedor, incluyendo parámetros estándar (p. ej. temperature, top_p,
  # max_tokens) y extensiones específicas del proveedor (p. ej. top_k,
  # repetition_penalty, anthropic_beta).
  chat_inference_params:
    temperature: 0.7
    top_p: 0.9

Nota:

Para que los usuarios puedan enviar entradas de imagen en la interfaz de chat, el modelo de inferencia principal debe tener supports_vision: true establecido en su bloque model_info. Si este flag está ausente o es false, la entrada de imagen no estará disponible.

Advertencia:

Si supports_vision se establece en true para un modelo que en realidad no admite entradas de imagen, el uso de imágenes fallará con un error del proveedor. Asegúrate de que este flag solo esté habilitado para modelos que admitan entradas de imagen. Ten en cuenta que los siguientes modelos no admiten entradas de imagen y deben tener supports_vision: false: Laguna S2.1 y Nvidia Nemotron 3.

Valores compatibles de `provider` / `family` / `version`

Bob usa los campos provider, family y version juntos para seleccionar ajustes de prompt y optimizaciones específicos del modelo. Usa los valores más cercanos para modelos no listados.

`provider`	`family`	`version`	Ejemplo 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 nombre de modelo reservados

Los siguientes valores de model_name deben estar presentes en tu lista models:

`model_name`	Usado para
`premium-ide`	Modelo predeterminado para el chat interactivo
`security`	Comprobaciones de guardia / seguridad
`background`	Tareas de agente autónomo y en segundo plano

La plantilla define security y background como alias de fusión YAML del modelo activo, para que todos sigan la misma configuración de proveedor automáticamente. Para security y background, se recomienda un modelo más pequeño y eficiente cuando esté disponible (por ejemplo, openai/gpt-oss-20b).

Proveedores

`openai_compatible`

Se conecta a cualquier modelo alojado externamente con una API REST compatible con OpenAI (por ejemplo, Azure OpenAI, vLLM, endpoints personalizados).

- model_name: premium-ide
  openai_compatible:
    model: gpt-5.6-sol                     # ID del modelo según lo esperado por el proveedor
    base_url: https://<resource>.cognitiveservices.azure.com/openai
    api_key: env.AZURE_API_KEY             # env.<VAR> lee de los secretos del gateway de modelos
    extra_headers:                         # Cabeceras adicionales a incluir en la inferencia
      example_header: env.HEADER_VALUE
    ca_cert_pem: env.CA_CERT               # Certificado CA para verificación 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`

Se conecta a un modelo servido a través de AWS Bedrock.

- model_name: premium-ide
  bedrock:
    model: us.anthropic.claude-sonnet-5    # ID del modelo según lo esperado por el proveedor
    region: us-east-1                      # Región de AWS donde está tu endpoint de Bedrock
    access_key_id: env.AWS_ACCESS_KEY      # ID de clave de acceso de Bedrock
    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`

Se conecta a un modelo servido a través de Google Vertex AI (Gemini). Las credenciales deben proporcionarse como una cadena JSON de cuenta de servicio codificada en base64.

- model_name: premium-ide
  vertex:
    model: gemini-3.6-flash                # ID del modelo según lo esperado por el proveedor
    project: <gcp-project-id>              # ID del proyecto GCP
    location: global                       # Región de Vertex AI / "global" para la API global
    credentials: env.GEMINI_CREDENTIALS    # JSON de cuenta de servicio, codificado en 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

Enrutadores

La sección routers configura la resolución de modelos entre el frontend y el backend. El default_model configurado será el LLM principal utilizado durante las interacciones de chat.

routers:
  - name: router
    strategy: static
    static:
      default_model: premium-ide   # debe coincidir con un model_name de la lista models

Campo	Descripción
`name`	Nombre del enrutador (usa siempre `router`)
`strategy`	Estrategia de enrutamiento. Actualmente solo se admite `static`
`static.default_model`	El `model_name` a usar como LLM principal. Debe coincidir exactamente con una entrada `model_name` de la lista `models`

Nota:

premium-ide es un slot de nombre de modelo reservado (ver Slots de nombre de modelo reservados), por lo que la práctica recomendada es mantener default_model: premium-ide y cambiar a qué proveedor/modelo apunta la entrada premium-ide en tu lista models.

Anclajes YAML

La configuración del gateway de modelos admite anclajes YAML estándar (&name) y claves de fusión (<<: *name). La plantilla usa esto para permitir la reutilización y evitar repeticiones.

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               # sobreescribe premium-ide del anclaje fusionado

  - <<: *chat_llm
    model_name: background

Gestión de credenciales y secretos

Secretos

Para cualquier secreto referenciado en la configuración del modelo (claves API, contraseñas, certificados), configúralos en config.yaml de instalación bajo bob.modelGateway.secrets. Los secretos se montan en el contenedor del servicio de inferencia en tiempo de ejecución.

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

Referencia un secreto en la configuración del modelo usando la sintaxis env.<VAR_NAME>:

api_key: env.VAR_BAR_1

Requisitos de TLS y certificados

Al usar endpoints privados o servidores de modelos internos (por ejemplo, vLLM u OpenShift AI con certificados empresariales personalizados o autofirmados), debes proporcionar tu certificado CA raíz/intermedio interno para que los contenedores de inferencia puedan establecer confianza TLS.

Nota:

Esta configuración TLS de endpoint de modelo es independiente del certificado requerido para que Bob IDE y Bob Shell se conecten al backend de Bob. Para los pasos del certificado de endpoint de backend y la confianza del cliente, consulta Certificados TLS.

Hay dos formas de añadir una CA para la inferencia:

Opción 1 — Bundle de confianza de inferencia (recomendado)

Añade la CA a bob-inferencing-bundle-tls etiquetando un Secret de Kubernetes. El operador detecta la etiqueta y reconstruye el bundle automáticamente — no se requieren cambios en la configuración del gateway de modelos y la CA está disponible para todos los contenedores de inferencia inmediatamente.

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>

El Secret bob-inferencing-bundle-tls se monta en los contenedores de inferencia como su almacén de confianza. Siempre contiene todo lo que hay en bob-bundle-tls más los Secrets etiquetados adicionales. No se necesita reiniciar el pod — los Secrets se proyectan en el contenedor en ejecución.

Para más detalles y pasos de verificación, consulta Certificados TLS.

Opción 2 — `ca_cert_pem` por modelo (configuración del gateway de modelos)

Usa esto cuando necesitas proporcionar una CA para un endpoint de modelo específico sin afectar a otros contenedores de inferencia. Los certificados TLS personalizados siguen el mismo patrón de configuración distribuida de dos archivos que las credenciales API:

En model-gateway.yaml: Establece ca_cert_pem en un nombre de variable de entorno (por ejemplo, env.CA_CERT).

En config.yaml: Añade el nombre de variable correspondiente bajo bob.modelGateway.secrets y pega la cadena del certificado codificada en PEM.

1. Configuración del gateway de modelos (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           # Apunta al nombre de variable definido en config.yaml
    model_info:
      exposed: true
      mode: chat

2. Configuración de instalación (config.yaml):

bob:
  modelGateway:
    secrets:
      MODEL_API_KEY: "<your-api-key>"
      # El contenido real del certificado PEM que corresponde a env.CA_CERT arriba:
      CA_CERT: |
        -----BEGIN CERTIFICATE-----
        MIIFazCCA1OgAwIBAgIRAIIQjJaDSmJT3g4qg05...
        ... [full PEM-encoded CA certificate data] ...
        -----END CERTIFICATE-----

Durante el despliegue, bobctl inyecta CA_CERT en el secreto de Kubernetes bob-inference-model-secrets. Este secreto se monta en el contenedor del servicio del gateway de inferencia y se usa en el handshake TLS contra tu servidor de modelos privado.

Ejemplo completo

A continuación se muestra un ejemplo completo que refleja la estructura de config-model-gateway-template.yaml del Bob Bundle. Guárdalo en un archivo (por ejemplo, /tmp/example/model-gateway.yaml) y referencíalo en el momento de la instalación.

Configuración del gateway de modelos

# ── Definiciones de proveedores ────────────────────────────────────────────────────────
# La clave x-providers es ignorada por el gateway de modelos — es un espacio de trabajo YAML
# para ejemplos de proveedores. Solo se referencia el anclaje del proveedor activo abajo.
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

  # Servicio de inferencia personalizado (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

# ── Modelos ────────────────────────────────────────────────────────────────────
models:

  # ── MODELO ACTIVO ─────────────────────────────────────────────────────────────
  # Cambia <<: *bedrock por p. ej. *azure, *gemini o *isvc para cambiar de proveedor.
  - &chat_llm
    <<: *bedrock                       # ← cambia el proveedor aquí
    model_name: premium-ide
    model_info:
      exposed: true

  # ── Alias ───────────────────────────────────────────────────────────────────
  - <<: *chat_llm
    model_name: security               # sobreescribe premium-ide del anclaje fusionado

  - <<: *chat_llm
    model_name: background

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

Secretos (`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 instalación

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

Para un entorno conectado, especifica tu clave de titularidad para icr.io. --registry-creds solo puede omitirse si tienes un registro privado que no requiere autenticación para extraer imágenes.

Desplegar la configuración

Durante la instalación inicial

Pasa la ruta a tu archivo de configuración del gateway de modelos usando el flag --model-config en el momento de la instalación:

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

Advertencia:

Si bobctl install se ejecuta sin --model-config, Bob se instala con una configuración del gateway de modelos vacía. El servicio de inferencia se ejecuta pero no tiene conexión a ningún modelo para la inferencia. Usa bobctl update-model-config después de la instalación para enviar una configuración de modelos al clúster.

Cómo se despliegan las credenciales en el clúster

El archivo de configuración del gateway de modelos referencia las credenciales como variables de entorno (por ejemplo, env.AWS_ACCESS_KEY, env.AZURE_API_KEY). Los distintos proveedores de modelos requieren secretos diferentes: claves IAM de AWS para Bedrock, claves API para Azure OpenAI o JSON de cuenta de servicio para Google Gemini.

Durante la instalación, estas credenciales se proporcionan en tu config.yaml bajo bob.modelGateway.secrets. La CLI bobctl procesa automáticamente esta sección y crea un secreto de Kubernetes llamado bob-inference-model-secrets en el clúster, montando las claves como variables de entorno directamente dentro del contenedor del servicio del gateway de inferencia.

bob:
  modelGateway:
    secrets:
      # Autenticación de AWS Bedrock
      AWS_ACCESS_KEY: "<your-aws-access-key-id>"
      AWS_SECRET_ACCESS_KEY: "<your-aws-secret-access-key>"

      # Autenticación de Azure OpenAI
      AZURE_API_KEY: "<your-azure-api-key>"

      # Autenticación de Google Cloud Vertex AI / Gemini
      GEMINI_CREDENTIALS: "<your-gemini-credentials-json>"

      # Claves API / tokens de endpoints personalizados o autenticación de proxy interno
      # RITS_APIKEY: "<your-api-key>"

      # Certificado CA personalizado en formato PEM para endpoints internos autofirmados
      # CA_CERT: |
      #   -----BEGIN CERTIFICATE-----
      #   ...
      #   -----END CERTIFICATE-----

Actualizar la configuración después de la instalación (`bobctl update-model-config`)

Usa bobctl update-model-config para enviar una configuración del gateway de modelos y/o secretos a un clúster activo sin reinstalar. Este es el camino requerido cuando bobctl install se ejecutó sin --model-config, y el mismo comando que se usa al cambiar el modelo de inferencia principal.

Internamente ejecuta helm template contra las plantillas model-config.yaml y model-secrets.yaml del chart ibm-bob local, luego aplica los manifiestos renderizados al clúster. Una vez aplicados, el ibm-bob-operator reconcilia el despliegue bob-inference con la nueva configuración del modelo.

El comando gestiona dos recursos de clúster separados:

Flag	Recurso del clúster	Fuente
`--model-config <file>`	`ConfigMap` `bob-inference-model-config`	El archivo que pasas
`--update-secrets`	`Secret` `bob-inference-model-secrets`	`bob.modelGateway.secrets` en `config.yaml`

Al menos uno de los dos debe proporcionarse; no pasar ninguno es un error.

Prerequisitos:

Debes estar conectado al clúster (oc login)

config.yaml debe existir junto a bobctl (copia desde config-template.yaml)

helm ≥ 3.14.0 debe estar en tu PATH

Uso común:

# Actualizar solo el archivo de configuración del modelo
bobctl update-model-config --model-config ./my-model-config.yaml

# Actualizar solo los secretos (las claves vienen de config.yaml)
bobctl update-model-config --update-secrets

# Actualizar ambos a la vez
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets

# Previsualizar lo que se aplicaría sin tocar el clúster
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets --dry-run

Todos los flags:

Flag	Predeterminado	Descripción
`--model-config <file>`		Ruta al archivo de configuración del modelo para enviar al ConfigMap
`--update-secrets`		Envía `bob.modelGateway.secrets` de `config.yaml` al secreto
`--output-config <file>`	`model-gateway-config.yaml`	Dónde escribir el manifiesto del ConfigMap renderizado
`--output-secret <file>`	`model-gateway-secret.yaml`	Dónde escribir el manifiesto del secreto renderizado
`--cleanup`	false	Elimina los archivos de manifiesto renderizados después de aplicarlos
`--dry-run`	false	Imprime lo que se ejecutaría sin ejecutar ningún comando `oc`

Configurar el gateway de modelos

Especificación de modelos

Valores compatibles de `provider` / `family` / `version`

Slots de nombre de modelo reservados

Proveedores

`openai_compatible`

`bedrock`

`vertex`

Enrutadores

Anclajes YAML

Gestión de credenciales y secretos

Secretos

Requisitos de TLS y certificados

Opción 1 — Bundle de confianza de inferencia (recomendado)

Opción 2 — `ca_cert_pem` por modelo (configuración del gateway de modelos)

Ejemplo completo

Configuración del gateway de modelos

Secretos (`config.yaml`)

Comando de instalación

Desplegar la configuración

Durante la instalación inicial

Cómo se despliegan las credenciales en el clúster

Actualizar la configuración después de la instalación (`bobctl update-model-config`)

En esta página