了解如何建立和管理模型閘道設定檔，包括供應商設定、模型定義、憑證管理、TLS 設定，以及支援模型供應商的部署範例。

模型閘道讓 Bob 本地部署能夠連線至跨不同供應商的受支援 AI 模型並路由請求，包括 OpenAI 相容端點、AWS Bedrock 和 Google Vertex AI。模型閘道設定定義了模型端點、身分驗證設定、路由行為和模型功能，而敏感憑證和憑證則透過 config.yaml 安全管理。

模型閘道設定是一個 YAML 檔案，定義閘道連線到哪些模型以及如何對每個供應商進行身分驗證。

警告：

一次只能在模型閘道中設定一個核心推論模型。同時設定多個核心模型不受支援，且會導致未定義的行為。

模型規格

models 清單中的每個項目都必須有唯一的 model_name。完整的模型規格如下：

- model_name: example_model
  # 供應商類型（每個模型選擇一種）：
  openai_compatible:  # — 任何 OpenAI 相容的 REST 端點（Azure、vLLM 等）
  bedrock:            # — AWS Bedrock invoke 端點
  vertex:             # — Google Vertex AI（Gemini）

  # 模型中繼資料
  model_info:
    exposed: true                         # true：在 /v1/model/info 清單中可見；false：僅限內部
    provider: openai                      # 模型供應商（例如 openai、anthropic、google、nvidia、mistral）
    family: gpt                           # 供應商內的模型系列（例如 gpt、sonnet、gemini）
    version: "5.6-sol"                    # 模型版本字串（見下表）
    max_input_tokens: 270000              # 上下文視窗大小
    max_output_tokens: 20000              # 模型可生成的最大 token 數
    supports_prompt_caching: true         # 如果模型支援提示快取則為 true
    supports_vision: true                 # 如果模型支援圖片輸入則為 true
    mode: chat                            # chat | embedding | image_generation

  # 可選的自由格式請求參數，附加到傳送給
  # 供應商的每個請求，包括標準參數（例如 temperature、top_p、
  # max_tokens）和供應商特定的擴展（例如 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                     # 供應商預期的模型 ID
    base_url: https://<resource>.cognitiveservices.azure.com/openai
    api_key: env.AZURE_API_KEY             # env.<VAR> 從模型閘道 Secret 讀取
    extra_headers:                         # 推論時要包含的額外標頭
      example_header: env.HEADER_VALUE
    ca_cert_pem: env.CA_CERT               # 用於 TLS 驗證的 CA 憑證
  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    # 供應商預期的模型 ID
    region: us-east-1                      # Bedrock 端點所在的 AWS 區域
    access_key_id: env.AWS_ACCESS_KEY      # Bedrock 存取金鑰 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                # 供應商預期的模型 ID
    project: <gcp-project-id>              # GCP 專案 ID
    location: global                       # Vertex AI 區域 / 全域 API 的 "global"
    credentials: env.GEMINI_CREDENTIALS    # 服務帳戶 JSON，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

路由器

routers 區段設定前端和後端之間的模型解析。設定的 default_model 將是聊天互動期間使用的主要 LLM。

routers:
  - name: router
    strategy: static
    static:
      default_model: premium-ide   # 必須與 models 清單中的 model_name 相符

欄位	描述
`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               # 覆寫合併錨點中的 premium-ide

  - <<: *chat_llm
    model_name: background

憑證和 Secret 管理

Secret

對於模型設定中參照的任何 Secret（API 金鑰、密碼、憑證），請在安裝 config.yaml 的 bob.modelGateway.secrets 下進行設定。Secret 在執行時掛載到 Inference Service 容器中。

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           # 指向 config.yaml 中定義的變數名稱
    model_info:
      exposed: true
      mode: chat

2. 安裝設定（config.yaml）：

bob:
  modelGateway:
    secrets:
      MODEL_API_KEY: "<your-api-key>"
      # 對應上方 env.CA_CERT 的實際 PEM 憑證內容：
      CA_CERT: |
        -----BEGIN CERTIFICATE-----
        MIIFazCCA1OgAwIBAgIRAIIQjJaDSmJT3g4qg05...
        ... [full PEM-encoded CA certificate data] ...
        -----END CERTIFICATE-----

部署期間，bobctl 將 CA_CERT 注入到 bob-inference-model-secrets Kubernetes Secret 中。接著將其掛載到推論閘道服務中，用於對你的私有模型伺服器進行 TLS 握手。

完整範例

以下是鏡像 Bob Bundle 中 config-model-gateway-template.yaml 結構的完整範例。將其儲存到檔案（例如 /tmp/example/model-gateway.yaml）並在安裝時參照它。

模型閘道設定

# ── 供應商定義 ───────────────────────────────────────────────────────────────
# x-providers 鍵被模型閘道忽略——它是供應商範例的 YAML 草稿區。
# 下面只參照作用中供應商的錨點。
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

  # 自訂推論服務（RHOAI、vLLM 等）
  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:

  # ── 作用中模型 ───────────────────────────────────────────────────────────────
  # 將 <<: *bedrock 更改為 *azure、*gemini 或 *isvc 以切換供應商。
  - &chat_llm
    <<: *bedrock                       # ← 在此更改供應商
    model_name: premium-ide
    model_info:
      exposed: true

  # ── 別名 ─────────────────────────────────────────────────────────────────────
  - <<: *chat_llm
    model_name: security               # 覆寫合併錨點中的 premium-ide

  - <<: *chat_llm
    model_name: background

# ── 路由器 ────────────────────────────────────────────────────────────────────
routers:
  - name: router
    strategy: static
    static:
      default_model: premium-ide

Secret（`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 將以空的模型閘道設定安裝。Inference Service 會執行，但沒有與任何模型的連線可用於推論。安裝後使用 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 身分驗證
      AWS_ACCESS_KEY: "<your-aws-access-key-id>"
      AWS_SECRET_ACCESS_KEY: "<your-aws-secret-access-key>"

      # Azure OpenAI 身分驗證
      AZURE_API_KEY: "<your-azure-api-key>"

      # Google Cloud Vertex AI / Gemini 身分驗證
      GEMINI_CREDENTIALS: "<your-gemini-credentials-json>"

      # 自訂端點 API 金鑰/權杖或內部 proxy 驗證
      # RITS_APIKEY: "<your-api-key>"

      # 自簽章內部端點的 PEM 格式自訂 CA 憑證
      # CA_CERT: |
      #   -----BEGIN CERTIFICATE-----
      #   ...
      #   -----END CERTIFICATE-----

安裝後更新設定（`bobctl update-model-config`）

使用 bobctl update-model-config 將模型閘道設定和/或 Secret 推送到執行中的叢集，無需重新安裝。當執行 bobctl install 時未使用 --model-config，以及切換核心推論模型時，這是必要的路徑。

在底層，它針對本機 ibm-bob 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 中

常見用法：

# 僅更新模型設定檔
bobctl update-model-config --model-config ./my-model-config.yaml

# 僅更新 Secret（金鑰來自 config.yaml）
bobctl update-model-config --update-secrets

# 同時更新兩者
bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets

# 預覽將套用的內容而不影響叢集
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` 指令

設定模型閘道