在安裝前驗證模型連線能力、憑證、憑證和設定，以識別並解決模型閘道問題，避免在部署 Bob 本地版時發生問題。

在安裝 Bob 本地版之前，請驗證你的模型端點、身分驗證憑證、TLS 憑證和模型閘道設定是否已正確設定，並可從目標 OpenShift 叢集存取。執行這些驗證檢查有助於在部署前識別連線問題、無效憑證、憑證信任問題和設定錯誤，從而減少安裝失敗和疑難排解的工作量。

在執行 bobctl install 之前，請逐一完成此檢查清單，以便及早發現缺少的設定。

測試模型端點的連線能力

在部署任何 Bob 元件之前，確認 OpenShift 叢集可以連線到每個模型端點。在目標命名空間中啟動一個臨時除錯 Pod，並直接測試 HTTPS 可存取性：

# openai_compatible
oc run curl-test --image=curlimages/curl --restart=Never --rm -it -- \
  curl -v https://<model-endpoint>/v1/models

# bedrock
oc run curl-test --image=curlimages/curl --restart=Never --rm -it -- \
  curl -k https://bedrock.<AWS_REGION>.amazonaws.com/foundation-models \
  --aws-sigv4 "aws:amz:${REGION}:bedrock" \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY"

對於 openai_compatible 端點，請針對你的模型閘道設定中的 base_url 值進行測試。對於氣隙或私有基礎架構，這是驗證連線能力的唯一方式，因為設計上沒有外部可達性。

身分驗證驗證

在將憑證編碼為 config.yaml 中的 Secret 之前，請先驗證憑證。錯誤的憑證會導致 Inference Service 啟動失敗，通常伴隨著難以理解的日誌訊息。

openai_compatible — 直接從除錯 Pod 測試 API 金鑰：

curl -s https://<base_url>/v1/models \
  -H "Authorization: Bearer <api_key>" | jq '.data[].id'

bedrock — 在將 AWS_ACCESS_KEY 和 AWS_SECRET_ACCESS_KEY 值新增至 config.yaml 之前，使用 AWS CLI 驗證它們：
```
aws bedrock list-foundation-models --region us-east-1
```
vertex — 解碼 GEMINI_CREDENTIALS base64 值，並在提供之前確認它是有效的服務帳戶 JSON：
```
base64 -d <<< "$GEMINI_CREDENTIALS" | jq '.type'
# 預期輸出："service_account"
```

TLS 憑證驗證

如果對 openai_compatible 端點使用 ca_cert_pem，請在將其作為 Secret 提供之前驗證憑證。

驗證憑證為 PEM 編碼且未過期：

echo "<cert content>" | openssl x509 -noout -dates

確認憑證符合端點的 CA 鏈：

openssl s_client -connect <host>:<port> -CAfile ca.pem

警告：

insecure_skip_verify: true 只能在初始連線能力除錯期間暫時使用。在正式上線前請移除它。如果 ca_cert_pem 參照的環境變數不存在於 bob.modelGateway.secrets 中，Inference Service 會成功啟動，但 TLS 會在推論時失敗。

模型探索驗證

確認供應商區塊中的 model ID 與供應商公開的 ID 完全相符。不符合的情況會在推論時（而非啟動時）導致 404 或模型未找到錯誤。

對於 openai_compatible 端點，在安裝前檢查可用的模型 ID：

curl -s https://<base_url>/v1/models \
  -H "Authorization: Bearer <api_key>" | jq '.data[].id'

常見設定錯誤檢查

設定錯誤	症狀	檢查
模型設定中的 Secret 名稱與 `config.yaml` `secrets` 區塊中的金鑰不符	身分驗證在請求時失敗，而非啟動時	對照 `bob.modelGateway.secrets` 金鑰比對模型設定中的每個 `env.*` 參照
`GEMINI_CREDENTIALS` 未進行 base64 編碼	Vertex 供應商在啟動時無法解析憑證	執行 `base64 -d <<< "$VALUE"` 並確認它是帶有 `"type": "service_account"` 的有效 JSON
`base_url` 包含結尾 `/` 或路徑後綴	供應商回傳 404	移除結尾斜線——閘道本身會附加 `/v1/chat/completions` 等路徑
`models` 清單中有重複的 `model_name` 值	路由行為未定義	確保設定中所有 `model_name` 值都是唯一的
`bobctl install` 執行時未使用 `--model-config`	空閘道，無法推論	確認已傳遞 `--model-config` 且指定路徑的檔案可讀取
模型設定中定義了 `ca_cert_pem` 環境變數，但 `secrets` 中缺少該變數	推論時 TLS 失敗	對照 `secrets` 區塊交叉比對模型設定中的每個 `env.*` 參照

安裝前驗證

測試模型端點的連線能力

身分驗證驗證

TLS 憑證驗證

模型探索驗證

常見設定錯誤檢查

本頁內容