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

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

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

警告：

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

模型規格

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

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

  # 模型資訊參數（可選）
  model_info:
    exposed: true                          # true：在 /models 清單中可見；false：僅限內部
    max_input_tokens: 128000               # 上下文視窗大小
    max_output_tokens: 4096                # 模型可生成的最大 token 數
    input_cost_per_token: 0.0000025        # 每個輸入 token 的費用（美元，用於用量計量）
    output_cost_per_token: 0.000010        # 每個輸出 token 的費用（美元）
    cache_read_input_token_cost: 0.00      # 快取命中輸入 token 的費用（提示快取）
    cache_creation_input_token_cost: 0.00  # 建立新快取條目的費用
    supports_prompt_caching: true          # 如果模型支援提示快取則為 true
    supports_function_calling: true        # 如果模型支援工具/函式呼叫則為 true
    supports_tool_choice: true             # 如果支援 tool_choice 參數則為 true
    supports_reasoning: false              # 如果模型支援 reasoning_effort 參數則為 true
    supports_vision: false                 # 如果模型接受聊天訊息中的圖片輸入則為 true
    mode: chat                             # chat | embedding | image_generation

  # 可選的有序 model_name 清單，當此模型無法使用時嘗試
  fallbacks:
    - fallback_model

  # 可選的自由格式請求參數，附加到傳送給
  # 供應商的每個請求，包括標準參數（例如 temperature、top_p、
  # max_tokens）和供應商特定的擴展（例如 top_k、
  # repetition_penalty、anthropic_beta）。
  chat_inference_params:
    temperature: 0.7
    top_p: 0.9

警告：

僅在接受圖片輸入的模型上將 supports_vision: true。如果在不支援圖片輸入的模型上將 supports_vision 設為 true，在聊天中傳送圖片會導致供應商錯誤。以下模型不支援圖片輸入，必須使用 supports_vision: false 或省略該旗標：Laguna S2.1 和 Nvidia Nemotron 3。

供應商

`openai_compatible`

連線到任何具有 OpenAI 相容 REST API 的外部託管模型（例如 Azure OpenAI、自訂端點）。

openai_compatible:
  model: gpt-4o                          # 供應商預期的模型 ID
  base_url: https://base_url             # 模型部署的基礎 URL
  api_key: env.API_KEY                   # 用於身分驗證的 API 金鑰。env.<VAR> 從容器環境讀取
  extra_headers:                         # 推論時要包含的額外標頭
    example_header: env.HEADER_VALUE
  insecure_skip_verify: true             # 停用 TLS 驗證（不建議用於生產環境）
  ca_cert_pem: env.CA_CERT               # 用於 TLS 驗證的 CA 憑證

`bedrock`

連線到透過 AWS Bedrock 提供服務的模型。

bedrock:
  model: claude                                  # 供應商預期的模型 ID
  region: us-east-1                              # Bedrock 端點所在的 AWS 區域
  access_key_id: env.AWS_ACCESS_KEY              # Bedrock 存取金鑰 ID
  secret_access_key: env.AWS_SECRET_ACCESS_KEY   # Bedrock 秘密存取金鑰

`vertex`

連線到透過 Google Vertex AI（Gemini）提供服務的模型。憑證必須以 base64 編碼的服務帳戶 JSON 字串形式提供。

vertex:
  model: gemini                              # 供應商預期的模型 ID
  project: my-gcp-project                    # GCP 專案 ID
  location: global                           # Vertex AI 區域 / 全域 API 的 "global"
  credentials: env.GEMINI_CREDENTIALS        # 服務帳戶 JSON，base64 編碼

YAML 錨點

憑證錨點

定義一次憑證，並在多個模型項目中使用 <<: *anchor-name 參照以避免重複。

# AWS Bedrock 憑證 — 由 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            # 合併上面定義的憑證錨點
    model_info:
      exposed: true
      mode: chat

模型錨點

跨多個項目合併完整的模型區塊，以避免重複供應商設定和 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

憑證和 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 和憑證需求

根 CA 套件組合包含雲端供應商的標準公開 CA 憑證。但是，當使用私有端點或內部模型伺服器（例如帶有自訂或自簽章企業憑證的 vLLM 或 OpenShift AI）時，你必須提供內部根/中間 CA 憑證以建立 TLS 信任。

注意：

此模型端點 TLS 設定與 Bob IDE 和 Bob Shell 連線到 Bob 後端所需的憑證是分開的。如需後端端點憑證和用戶端信任步驟，請參閱 TLS 憑證。

自訂 TLS 憑證遵循與 API 憑證相同的雙檔案分散式設定模式：

在 model-gateway.yaml 中：將 ca_cert_pem 設定為環境變數名稱（例如 env.CA_CERT）。

在 config.yaml 中：在 bob.modelGateway.secrets 下新增對應的變數名稱，並貼上完整的 PEM 編碼憑證字串。

模型閘道設定：

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

安裝設定（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 握手。

完整範例

以下是涵蓋所有供應商類型的完整範例。將模型閘道設定儲存到檔案（例如 /tmp/example/model-gateway.yaml）並在安裝時參照它。

模型閘道設定（/tmp/example/model-gateway.yaml）

# ── 憑證錨點（透過 YAML 合併鍵跨模型項目共享）──────
# 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

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

# ── 共享模型錨點（可選）─────────────────────────────
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:
  # OpenAI 相容模型（例如 Azure OpenAI），使用 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

  # AWS Bedrock 模型
  - model_name: my-bedrock-model
    bedrock:
      model: us.anthropic.claude-3-5-sonnet-20241022-v2:0
      <<: *aws-bedrock-auth
    fallbacks:                          # 可選：有序的備援模型名稱清單
      - 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_name: my-gemini-model
    <<: *my-base-model

  # 帶有自訂 CA 憑證的 OpenAI 相容模型
  - 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 相容模型
  - 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

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

安裝指令

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

部署設定

初始安裝期間

在安裝時使用 --model-config 旗標傳遞模型閘道設定檔的路徑：

bobctl install --model-config path/to/model-gateway-config.yaml --accept-license

警告：

如果執行 bobctl install 時未使用 --model-config，Bob 將以空的模型閘道設定安裝。Inference Service 會執行，但沒有與任何模型的連線可用於推論。安裝後使用 bobctl update-model-config 將模型設定推送到叢集。

憑證如何部署到叢集

模型閘道設定檔以環境變數的形式參照憑證（例如 env.AWS_ACCESS_KEY、env.BOB_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 身分驗證
      BOB_AZURE_API_KEY: "<your-azure-api-key>"

      # Google Cloud Vertex AI / Gemini 身分驗證
      BOB_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，以及切換核心推論模型時，這是必要的路徑。

該指令管理兩個獨立的叢集資源：

旗標	叢集資源	來源
`--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` 指令

設定模型閘道