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, las opciones de fallback 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, …)
  bedrock:            # — endpoint de invocación de AWS Bedrock
  vertex:             # — Google Vertex AI (Gemini)

  # Parámetros de información del modelo (opcionales)
  model_info:
    exposed: true                          # true: visible en la lista /models; false: solo interno
    max_input_tokens: 128000               # tamaño de la ventana de contexto
    max_output_tokens: 4096                # máximo de tokens que el modelo puede generar
    input_cost_per_token: 0.0000025        # coste en USD por token de entrada (para medición de uso)
    output_cost_per_token: 0.000010        # coste en USD por token de salida
    cache_read_input_token_cost: 0.00      # coste para tokens de entrada en cache hit (caché de prompts)
    cache_creation_input_token_cost: 0.00  # coste para escribir una nueva entrada en caché
    supports_prompt_caching: true          # true si el modelo soporta caché de prompts
    supports_function_calling: true        # true si el modelo soporta llamadas a herramientas/funciones
    supports_tool_choice: true             # true si el parámetro tool_choice es respetado
    supports_reasoning: false              # true si el modelo soporta el parámetro reasoning_effort
    supports_vision: false                 # true si el modelo acepta entradas de imagen en mensajes de chat
    mode: chat                             # chat | embedding | image_generation

  # Lista ordenada opcional de valores model_name a intentar cuando este modelo no está disponible
  fallbacks:
    - fallback_model

  # 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

Warning:

Establece supports_vision: true únicamente en los modelos que aceptan entradas de imagen. Si supports_vision se establece en true en un modelo que no admite entradas de imagen, enviar una imagen en el chat provocará un error del proveedor. Los siguientes modelos no admiten entradas de imagen y deben usar supports_vision: false u omitir el flag: Laguna S2.1 y Nvidia Nemotron 3.

Proveedores

`openai_compatible`

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

openai_compatible:
  model: gpt-4o                          # ID del modelo según lo esperado por el proveedor
  base_url: https://base_url             # URL base del despliegue del modelo
  api_key: env.API_KEY                   # Clave API para autenticación. env.<VAR> lee del entorno del contenedor
  extra_headers:                         # Cabeceras adicionales a incluir en la inferencia
    example_header: env.HEADER_VALUE
  insecure_skip_verify: true             # Deshabilita la verificación TLS (no recomendado en producción)
  ca_cert_pem: env.CA_CERT               # Certificado CA para verificación TLS

`bedrock`

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

bedrock:
  model: claude                                  # 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   # Clave de acceso secreta de Bedrock

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

vertex:
  model: gemini                              # ID del modelo según lo esperado por el proveedor
  project: my-gcp-project                    # 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

Anclajes YAML

Anclajes de credenciales

Define las credenciales una vez y referenciarlas con <<: *anchor-name en múltiples entradas de modelos para evitar repeticiones.

# Credenciales de AWS Bedrock — referenciadas por los modelos bedrock.
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            # fusiona el anclaje de credenciales definido arriba
    model_info:
      exposed: true
      mode: chat

Anclajes de modelos

Fusiona un bloque de modelo completo en varias entradas para evitar repetir la configuración del proveedor y 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

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

El bundle de CA raíz incluye certificados CA públicos estándar para proveedores cloud. Sin embargo, 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 establecer la 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.

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.

Configuración del gateway de modelos:

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

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 cubre todos los tipos de proveedores. Guarda la configuración del gateway de modelos 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 (/tmp/example/model-gateway.yaml)

# ── Anclajes de credenciales (compartidos entre entradas de modelos mediante claves de fusión YAML) ──
# Credenciales de AWS Bedrock
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

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

# ── Anclajes de modelos compartidos (opcionales) ───────────────────────────────────────────
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

# ── Modelos ────────────────────────────────────────────────────────────────────
models:
  # Modelo compatible con OpenAI (p. ej. Azure OpenAI) con clave API
  - 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

  # Modelo de AWS Bedrock
  - model_name: my-bedrock-model
    bedrock:
      model: us.anthropic.claude-3-5-sonnet-20241022-v2:0
      <<: *aws-bedrock-auth
    fallbacks:                          # opcional: lista ordenada de nombres de modelos de fallback
      - 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

  # Modelo Google Vertex AI (Gemini) usando anclaje de modelo compartido
  - model_name: my-gemini-model
    <<: *my-base-model

  # Modelo compatible con OpenAI con certificado CA personalizado
  - 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

  # Modelo compatible con OpenAI con cabeceras adicionales
  - 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

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

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

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

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

      # Autenticación de Google Cloud Vertex AI / Gemini
      BOB_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.

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