了解如何创建和管理模型网关配置文件，包括提供商设置、模型定义、凭证管理、TLS 配置以及受支持模型提供商的部署示例。

模型网关使 Bob 本地版能够连接到不同提供商的受支持 AI 模型并路由请求，支持的提供商包括兼容 OpenAI 的端点、AWS Bedrock 和 Google Vertex AI。模型网关配置定义了模型端点、身份验证设置、路由行为和模型功能，而敏感凭证和证书则通过 config.yaml 安全管理。

模型网关配置是一个 YAML 文件，定义了网关连接的模型以及如何对每个提供商进行身份验证。

警告：

每次只能在模型网关中配置一个核心推理模型。同时配置多个核心模型不受支持，且会导致未定义行为。

模型规格

models 列表中的每个条目必须有唯一的 model_name。完整的模型规格如下：

- 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

注意：

为了让用户在聊天界面中发送图像输入，核心推理模型必须在其 model_info 块中设置 supports_vision: true。如果缺少此标志或设置为 false，则图像输入将不可用。

警告：

如果在实际上不支持图像输入的模型上将 supports_vision 设置为 true，使用图像将失败并收到来自提供商的错误。请确保仅对支持图像输入的模型启用此标志。注意，以下模型不支持图像输入，应设置 supports_vision: false：Laguna S2.1 和 Nvidia Nemotron 3。

支持的 `provider` / `family` / `version` 值

Bob 结合使用 provider、family 和 version 字段来选择针对特定模型的提示词微调和优化。对于未列出的模型，请使用最接近的匹配值。

`provider`	`family`	`version`	示例模型 ID
`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`

保留的模型名称槽位

以下 model_name 值必须出现在你的 models 列表中：

`model_name`	用途
`premium-ide`	交互式聊天的默认模型
`security`	护栏 / 安全检查
`background`	后台和自主代理任务

模板将 security 和 background 定义为活动模型的 YAML 合并别名，因此它们都会自动遵循相同的提供商配置。对于 security 和 background，如果可用，建议使用更小且更高效的模型（例如 openai/gpt-oss-20b）。

提供商

`openai_compatible`

连接到任何具有兼容 OpenAI 的 REST API 的外部托管模型（例如 Azure OpenAI、vLLM、自定义端点）。

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

连接到通过 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`

连接到通过 Google Vertex AI（Gemini）提供服务的模型。凭证必须以 base64 编码的服务账号 JSON 字符串形式提供。

- 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

路由器

routers 部分配置前端与后端之间的模型解析。配置的 default_model 将作为聊天交互期间使用的主 LLM。

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

字段	描述
`name`	路由器名称（始终使用 `router`）
`strategy`	路由策略。目前仅支持 `static`
`static.default_model`	用作主 LLM 的 `model_name`。必须与 `models` 列表中的某个 `model_name` 条目完全匹配

注意：

premium-ide 是必需的模型名称槽位（请参阅保留的模型名称槽位），因此推荐的做法是保留 default_model: premium-ide，并在你的 models 列表中更改 premium-ide 条目所指向的提供商/模型。

YAML 锚点

模型网关配置支持标准 YAML 锚点（&name）和合并键（<<: *name）。模板利用此特性来支持复用并避免重复。

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

凭证与 Secret 管理

Secrets

对于模型配置中引用的任何 Secret（API 密钥、密码、证书），请在安装 config.yaml 的 bob.modelGateway.secrets 下配置它们。Secret 在运行时被挂载到推理服务容器中。

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

使用 env.<VAR_NAME> 语法在模型配置中引用 Secret：

api_key: env.VAR_BAR_1

TLS 和证书要求

当使用私有端点或内部模型服务器时（例如，带有自定义或自签名企业证书的 vLLM 或 OpenShift AI），你必须提供内部根/中间 CA 证书，以便推理容器建立 TLS 信任。

注意：

此模型端点 TLS 配置与 Bob IDE 和 Bob Shell 连接到 Bob 后端所需的证书不同。有关后端端点证书和客户端信任步骤，请参阅 TLS 证书。

有两种为推理添加 CA 的方法：

选项 1 — 推理信任捆绑包（推荐）

通过为 Kubernetes Secret 添加标签，将 CA 添加到 bob-inferencing-bundle-tls。Operator 会检测到该标签并自动重新构建捆绑包——无需更改模型网关配置，并且 CA 会立即可供所有推理容器使用。

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>

bob-inferencing-bundle-tls Secret 被挂载到推理容器中作为其信任存储库。它始终包含 bob-bundle-tls 中的所有内容以及任何额外标记的 Secret。无需重启 Pod——Secret 会直接投射到正在运行的容器中。

有关完整的详细信息和验证步骤，请参阅 TLS 证书。

选项 2 — 按模型配置 `ca_cert_pem`（模型网关配置）

当你需要为单个特定模型端点提供 CA 而不影响其他推理容器时，请使用此方法。自定义 TLS 证书遵循与 API 凭证相同的双文件分布式配置模式：

在 model-gateway.yaml 中：将 ca_cert_pem 设置为环境变量名（例如 env.CA_CERT）。

在 config.yaml 中：在 bob.modelGateway.secrets 下添加匹配的变量名，并粘贴完整的 PEM 编码证书字符串。

1. 模型网关配置 (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. 安装配置 (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-----

部署时，bobctl 将 CA_CERT 注入 bob-inference-model-secrets Kubernetes Secret 中。该 Secret 随后被挂载到推理网关服务中，用于对私有模型服务器进行 TLS 握手。

完整示例

以下是与 Bob Bundle 中的 config-model-gateway-template.yaml 结构镜像的完整示例。将其保存到文件（例如 /tmp/example/model-gateway.yaml），并在安装时引用它。

模型网关配置

# ── 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

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

安装命令

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

对于已联网环境，请指定 icr.io 的授权密钥。仅当你的私有镜像仓库不需要身份验证即可拉取时，才可以省略 --registry-creds。

部署配置

初始安装时

在安装时使用 --model-config 标志传递模型网关配置文件的路径：

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

警告：

如果运行 bobctl install 时未指定 --model-config，Bob 将以空的模型网关配置安装。推理服务会运行，但无法连接到任何模型进行推理。请在安装后使用 bobctl update-model-config 将模型配置推送到集群。

凭证如何部署到集群

模型网关配置文件以环境变量形式引用凭证（例如 env.AWS_ACCESS_KEY、env.AZURE_API_KEY）。不同的模型提供商需要不同的 Secret——Bedrock 使用 AWS IAM 密钥，Azure OpenAI 使用 API 密钥，Google Gemini 使用服务账号 JSON。

安装时，这些凭证通过 config.yaml 中的 bob.modelGateway.secrets 提供。bobctl CLI 自动处理此部分，并在集群中创建名为 bob-inference-model-secrets 的 Kubernetes Secret，将密钥作为环境变量直接挂载到推理网关服务容器内。

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

安装后更新配置 (`bobctl update-model-config`)

使用 bobctl update-model-config 将模型网关配置和/或 Secret 推送到运行中的集群，无需重新安装。当 bobctl install 未使用 --model-config 运行时，以及切换核心推理模型时，均需使用此命令。

在底层，它会对本地 ibm-bob Helm chart 中的 model-config.yaml 和 model-secrets.yaml 模板运行 helm template，然后将渲染后的清单应用到集群。应用后，ibm-bob-operator 会使用新的模型配置协调 bob-inference 部署。

该命令管理两个独立的集群资源：

标志	集群资源	来源
`--model-config <file>`	`ConfigMap` `bob-inference-model-config`	你传入的文件
`--update-secrets`	`Secret` `bob-inference-model-secrets`	`config.yaml` 中的 `bob.modelGateway.secrets`

两者至少需要提供一个——都不提供会报错。

先决条件：

你必须已登录集群（oc login）

config.yaml 必须与 bobctl 在同一目录下（从 config-template.yaml 复制）

helm ≥ 3.14.0 必须在你的 PATH 中

常见用法：

# 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

所有标志：

标志	默认值	描述
`--model-config <file>`		要推送到 ConfigMap 的模型配置文件路径
`--update-secrets`		将 `config.yaml` 中的 `bob.modelGateway.secrets` 推送到 Secret
`--output-config <file>`	`model-gateway-config.yaml`	渲染的 ConfigMap 清单的写入位置
`--output-secret <file>`	`model-gateway-secret.yaml`	渲染的 Secret 清单的写入位置
`--cleanup`	false	应用后删除渲染的清单文件
`--dry-run`	false	打印将运行的内容，但不执行任何 `oc` 命令

配置模型网关