了解當你的環境尚未提供模型服務解決方案時，如何部署和設定模型端點。

在將 IBM Bob 連線至大型語言模型（LLM）之前，你必須能夠存取已部署的模型端點。Bob 不負責佈建、託管或管理模型服務基礎架構。如果你的組織已透過 OpenShift AI、GPU 推論伺服器、雲端 AI 服務或其他推論平台提供模型端點，請直接前往設定模型閘道。

部署選項

選擇最符合你的環境和作業需求的選項。

選項	使用時機
OpenShift AI（叢集內，OCI/ModelCar）	氣隙或自我託管模型；RHOAI 已在叢集上可用
公用雲端	透過 AWS Bedrock、Azure OpenAI 或 Google Vertex AI 存取前沿模型
私有基礎架構	在獨立 GPU 伺服器或專用推論叢集上提供服務的模型

OpenShift AI（叢集內，OCI/ModelCar）

Red Hat OpenShift AI（RHOAI）是在叢集上提供模型服務的推薦平台，包括氣隙部署。載入模型權重的首選方法是 OCI/ModelCar 模式：模型檔案被烘焙到 /models/ 下的 OCI 映像檔中，並推送到私有 registry。部署 InferenceService 時，KServe 會注入一個 modelcar-init 初始容器，該容器提取映像檔並將權重複製到 /mnt/models/ 的共享磁碟區，然後由服務執行環境（例如 vLLM）從中載入。模型映像檔在首次提取後快取在節點上——同一節點上的後續重啟將完全跳過下載。

先決條件：

叢集上已安裝 Red Hat OpenShift AI operator

KServe 已啟用並設定

已設定具有 NVIDIA GPU Operator（或同等工具）的 GPU 工作節點

oc CLI 已對目標叢集進行身分驗證，並具有在目標命名空間中建立資源的權限

叢集可存取的私有容器 registry，以及推送映像檔所需的憑證

設定 Red Hat OpenShift AI

依照以下方式設定 DataScienceClusterInitialization 和 DataScienceCluster 資源：

停用 serviceMesh。

透過設定 managementState: Managed 啟用 KServe。

設定 KServe 使用 RawDeployment 模式。

移除所有未使用的 Red Hat OpenShift AI 元件。

KServe 設定範例：

kserve:
  defaultDeploymentMode: RawDeployment
  nim:
    managementState: Managed
  rawDeploymentServiceConfig: Headed
  serving:
    ingressGateway:
      certificate:
        type: OpenshiftDefaultIngress
    managementState: Removed
    name: knative-serving
  managementState: Managed

啟用 ModelCar 支援

ModelCar 支援由 redhat-ods-applications 命名空間中的 inferenceservice-config ConfigMap 控制。storageInitializer 鍵必須包含 "enableModelcar": true。

驗證目前設定：

oc get configmap inferenceservice-config \
  -n redhat-ods-applications \
  -o jsonpath='{.data.storageInitializer}'

輸出必須包含：

{
  "enableModelcar": true,
  "cpuModelcar": "10m",
  "memoryModelcar": "15Mi"
}

如果 enableModelcar 缺失或為 false，請更新 ConfigMap：

# 擷取目前值，合併旗標，然後修補
CURRENT=$(oc get configmap inferenceservice-config \
  -n redhat-ods-applications \
  -o jsonpath='{.data.storageInitializer}')
PATCHED=$(echo "$CURRENT" | python3 -c "
import json, sys
d = json.load(sys.stdin)
d['enableModelcar'] = True
print(json.dumps(d))
")
oc patch configmap inferenceservice-config \
  -n redhat-ods-applications \
  --type merge \
  -p "{\"data\":{\"storageInitializer\":$(echo $PATCHED | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}}"

重啟 KServe controller 以套用變更：

oc rollout restart deployment kserve-controller-manager -n redhat-ods-applications
oc rollout status deployment kserve-controller-manager -n redhat-ods-applications

將模型檔案打包到 OCI 映像檔中

從 Hugging Face 下載模型權重，並將其打包到 OCI 映像檔中。映像檔必須將所有模型檔案放在 /models 目錄下。如需詳細資訊，請參閱 KServe 文件。對於 vLLM 部署，請包含 safetensors 模型分片，並排除舊版 checkpoint 檔案，例如 .bin、.pt 和 original/*。

Dockerfile 範例：

FROM busybox:latest

# 模型權重 — safetensors 分片和索引
COPY <model-name>/model-*.safetensors         /models/
COPY <model-name>/model.safetensors.index.json /models/

# 模型設定
COPY <model-name>/config.json             /models/
COPY <model-name>/generation_config.json  /models/

# Tokenizer
COPY <model-name>/tokenizer.json           /models/
COPY <model-name>/tokenizer_config.json    /models/
COPY <model-name>/special_tokens_map.json  /models/

如果模型包含 chat template（例如 chat_template.jinja），請將其加入。或者，用一條指令複製整個目錄——較為簡便，但包含 vLLM 不需要的檔案：

FROM busybox:latest
COPY <model-name>/ /models/

將映像檔推送到私有 registry

將 OCI 映像檔推送到叢集可存取的私有容器 registry：

<registry>/<project>/<model-name>:latest

你可以使用任何受支援的映像檔管理工具，包括：

Podman
Skopeo
CI/CD pipeline
Registry 專用工具

建立目標命名空間和映像檔提取 Secret

建立專案命名空間並設定提取模型映像檔所需的憑證：

oc new-project <namespace>

建立 registry 提取 Secret：

# 提取 Secret，讓 KServe 可以從你的私有 registry 提取模型映像檔
oc create secret docker-registry model-registry-secret \
  --docker-server=<registry> \
  --docker-username=<username> \
  --docker-password=<password-or-token> \
  -n <namespace>

建立服務帳戶：

# KServe predictor 使用的服務帳戶
oc create sa model-puller-sa -n <namespace>

將提取 Secret 與服務帳戶關聯：

# 附加提取 Secret — 兩個指令都是必需的：
# oc secrets link 涵蓋一般 Secret 使用；
# imagePullSecrets 特別由 KServe 的 ModelCar init 容器需要
oc secrets link model-puller-sa model-registry-secret --for=pull -n <namespace>
oc patch serviceaccount model-puller-sa -n <namespace> \
  -p '{"imagePullSecrets": [{"name": "model-registry-secret"}]}'

注意：

兩個指令都是必需的。imagePullSecrets 條目由 ModelCar 初始化容器在模型映像檔提取期間使用。

建立 ServingRuntime

在目標命名空間中部署基於 vLLM 的 ServingRuntime：

apiVersion: serving.kserve.io/v1alpha1
kind: ServingRuntime
metadata:
  name: vllm-runtime
  namespace: <namespace>
spec:
  multiModel: false
  supportedModelFormats:
    - name: pytorch
      autoSelect: true
  containers:
    - name: kserve-container
      image: vllm/vllm-openai:<version>
      ports:
        - containerPort: 3000
          protocol: TCP
      livenessProbe:
        httpGet:
          path: /health
          port: 3000
        periodSeconds: 30
        timeoutSeconds: 5
        failureThreshold: 3
      readinessProbe:
        httpGet:
          path: /health
          port: 3000
        periodSeconds: 10
        timeoutSeconds: 5
        failureThreshold: 3
      startupProbe:
        httpGet:
          path: /health
          port: 3000
        periodSeconds: 10
        timeoutSeconds: 5
        failureThreshold: 60

套用執行時設定：

oc apply -n <namespace> -f serving-runtime-vllm.yaml

部署 InferenceService

建立一個 InferenceService，使用 oci:// 儲存 URI 參照 OCI 模型映像檔。

主要設定需求：

參照先前建立的 ServingRuntime。
在 storageUri 中指定 OCI 映像檔位置。
設定符合模型需求的 CPU、記憶體和 GPU 資源限制。
為 vLLM 掛載共享記憶體（/dev/shm）。
設定 vLLM 執行時引數和環境變數。

範例：

apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  name: <model-name>
  annotations:
    serving.kserve.io/autoscalerClass: external
    serving.kserve.io/deploymentMode: RawDeployment
spec:
  predictor:
    affinity:
      nodeAffinity:
        requiredDuringSchedulingIgnoredDuringExecution:
          nodeSelectorTerms:
            - matchExpressions:
                - key: kubernetes.io/arch
                  operator: In
                  values:
                    - amd64
    tolerations:
      - key: nvidia.com/gpu
        operator: Exists
        effect: NoSchedule
    volumes:
      - name: shm
        emptyDir:
          medium: Memory
          sizeLimit: 64Gi
    model:
      modelFormat:
        name: pytorch
      runtime: vllm-runtime
      storageUri: "oci://<registry>/<namespace-or-project>/<model-name>:latest"
      resources:
        requests:
          cpu: "<cpu-request>"          # 例如 "8"
        limits:
          cpu: "<cpu-limit>"            # 例如 "16"
          memory: <memory-limit>        # 例如 96Gi — 根據模型 VRAM 需求調整
          nvidia.com/gpu: "<gpu-count>" # 例如 "1"
      volumeMounts:
        - name: shm
          mountPath: /dev/shm
      args:
        - /mnt/models/
        - --served-model-name=<model-name>
        - --port=3000
        - --enable-auto-tool-choice
        - --tool-call-parser=openai
      env:
        - name: HOME
          value: /tmp
        - name: MAX_LOG_LEN
          value: "100"        # 截斷 vLLM 日誌行以避免日誌泛濫
        - name: HF_HUB_CACHE
          value: /tmp
        - name: TRITON_CACHE_DIR
          value: /tmp
        - name: XDG_CACHE_HOME
          value: /tmp
        - name: HF_HOME
          value: /tmp/hf_home
        - name: NUM_GPUS
          value: "<gpu-count>" # 必須與上方 nvidia.com/gpu 限制相符
        - name: CUDA_VISIBLE_DEVICES
          value: "<gpu-indices>" # 例如 "0" 代表單 GPU；"0,1" 代表兩個
        - name: VLLM_WORKER_MULTIPROC_METHOD
          value: spawn
        - name: LOGNAME
          value: vllm
        - name: USER
          value: vllm

套用 InferenceService 資訊清單：

oc apply -n <namespace> -f isvc-<model-name>.yaml

驗證部署

監控部署狀態、Pod 啟動和執行時日誌：

# 監看 InferenceService 達到 Ready 狀態
oc get inferenceservice <model-name> -n <namespace> -w

# 監看 predictor Pod 啟動
oc get pods -n <namespace> -w

# 追蹤 predictor 日誌（模型載入在 Running 後可能需要幾分鐘）
oc logs -f deployment/<model-name>-predictor -n <namespace>

當 InferenceService 報告 READY: True 時，驗證端點。

驗證模型註冊並傳送測試推論請求：

POD=$(oc get pods -n <namespace> \
  -l app=isvc.<model-name>-predictor \
  -o jsonpath='{.items[0].metadata.name}')

oc exec -n <namespace> "$POD" -c kserve-container -- \
  curl -fsS http://127.0.0.1:3000/v1/models

oc exec -n <namespace> "$POD" -c kserve-container -- \
  curl -fsS http://127.0.0.1:3000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<model-name>",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 50
  }'

疑難排解

問題	可能原因	解決方案
`ErrImagePull`	缺少或無效的 registry 憑證	確認 `model-registry-secret` 存在、具有有效憑證，並使用 `oc secrets link` 和 `imagePullSecrets` 修補兩者都連結到 `model-puller-sa`。
`ImagePullBackOff`	ModelCar 的映像檔提取 Secret 未設定	確保服務帳戶包含 `imagePullSecrets` 設定。執行 `oc patch serviceaccount model-puller-sa -n <namespace> -p '{"imagePullSecrets": [{"name": "model-registry-secret"}]}'`
Predictor 持續處於 `Init:0/1`	模型映像檔下載進行中	檢查 `oc describe pod` 事件以了解 `Pulling`/`Pulled` 進度；提取時間隨映像檔大小和 registry 頻寬而異。
Predictor 無限期處於 `Init:0/1`	找不到模型檔案	確認模型檔案儲存在 OCI 映像檔的 `/models` 下。
`Engine core initialization failed`	初始 CUDA 編譯逾時	第一次啟動在生成快取時可能需要較長時間。重啟並重試。
模型載入失敗	不支援的模型檔案格式	使用 Hugging Face safetensors 檔案，並排除舊版 checkpoint。
OpenSSL FIPS 自我測試錯誤	容器映像檔不符合 FIPS 規範	使用符合 FIPS 規範的 vLLM 映像檔。
`OutOfMemory` / `OOMKilled`	GPU 記憶體不足	增加 GPU 資源、減少上下文長度，或使用量化模型。
InferenceService 持續 `Pending`	叢集資源不可用	驗證 GPU 可用性，並釋放未使用工作負載的資源。

如需詳細資訊，請參閱：

Red Hat OpenShift AI — 提供模型服務

KServe 文件

KServe ModelCar — OCI 模型打包

公用雲端模型端點

當模型由雲端供應商託管時使用此選項，例如 IBM watsonx、AWS Bedrock、Azure OpenAI 或 Google Vertex AI。

先決條件：

從 OpenShift 叢集到雲端服務端點的出站 HTTPS（連接埠 443）連線能力。

有效的 API 金鑰、IAM 憑證或同等的身分驗證憑證。

設定 IBM Bob 之前

確認：

模型部署已佈建且處於活動狀態。

身分驗證憑證已生成並安全儲存。

所有供應商特定的網路或存取需求已完成。

端點可用後，請繼續設定模型閘道。

私有基礎架構模型端點

當模型託管在 IBM Bob 叢集之外的客戶管理基礎架構上時使用此選項，例如：

專用 GPU 伺服器

獨立 OpenShift 叢集

裸機推論伺服器

企業 AI 平台

先決條件：

模型端點公開 OpenAI 相容的 API。

IBM Bob 叢集與端點之間存在 HTTPS 連線。

身分驗證憑證可作為 Kubernetes Secret 取得。

設定 IBM Bob 之前

驗證以下項目：

從叢集到端點的網路連線。

如需要，TLS 或相互 TLS 設定。

網路原則和防火牆允許存取。

端點身分驗證運作正常。

連線和身分驗證驗證完成後，請繼續設定模型閘道。

模型服務基礎架構

本頁內容