了解在你的环境中尚未提供模型服务解决方案时，如何部署和配置模型端点。

在将 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 模式：将模型文件打包到 OCI 镜像的 /models/ 目录下，并推送到私有镜像仓库。部署 InferenceService 时，KServe 会注入一个 modelcar-init init 容器，该容器拉取镜像并将权重复制到 /mnt/models/ 的共享卷中，推理运行时（例如 vLLM）随后从该位置加载模型。模型镜像在首次拉取后会被缓存到节点上——同一节点上的后续重启会跳过下载过程。

先决条件：

集群上已安装 Red Hat OpenShift AI Operator

KServe 已启用并配置

已配置启用 GPU 的工作节点以及 NVIDIA GPU Operator（或同等组件）

oc CLI 已通过身份验证连接到目标集群，并有权在目标命名空间中创建资源

集群可访问的私有容器镜像仓库，并拥有推送镜像的凭证

配置 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：

# Retrieve current value, merge the flag, and patch
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 模型分片，并排除 .bin、.pt 和 original/* 等旧版 checkpoint 文件。

Dockerfile 示例：

FROM busybox:latest

# Model weights — safetensors shards and index
COPY <model-name>/model-*.safetensors         /models/
COPY <model-name>/model.safetensors.index.json /models/

# Model configuration
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.jinja），请添加它。或者，通过一条指令复制整个目录——更简洁，但会包含 vLLM 不需要的文件：

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

将镜像推送到私有镜像仓库

将 OCI 镜像推送到集群可访问的私有容器镜像仓库：

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

你可以使用任何受支持的镜像管理工具，包括：

Podman
Skopeo
CI/CD 流水线
镜像仓库专用工具

创建目标命名空间和镜像拉取 Secret

创建项目命名空间，并配置拉取模型镜像的凭证：

oc new-project <namespace>

创建镜像仓库拉取 Secret：

# Pull secret so KServe can pull the model image from your private registry
oc create secret docker-registry model-registry-secret \
  --docker-server=<registry> \
  --docker-username=<username> \
  --docker-password=<password-or-token> \
  -n <namespace>

创建服务账号：

# Service account used by the KServe predictor
oc create sa model-puller-sa -n <namespace>

将拉取 Secret 与服务账号关联：

# Attach the pull secret — both commands are required:
# oc secrets link covers general secret use;
# imagePullSecrets is needed by KServe's ModelCar init container specifically
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

创建一个使用 oci:// 存储 URI 引用 OCI 模型镜像的 InferenceService。

关键配置要求：

引用之前创建的 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>"          # e.g. "8"
        limits:
          cpu: "<cpu-limit>"            # e.g. "16"
          memory: <memory-limit>        # e.g. 96Gi — size to model VRAM requirements
          nvidia.com/gpu: "<gpu-count>" # e.g. "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"        # truncate vLLM log lines to avoid log flooding
        - 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>" # must match nvidia.com/gpu limit above
        - name: CUDA_VISIBLE_DEVICES
          value: "<gpu-indices>" # e.g. "0" for a single GPU; "0,1" for two
        - 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 启动和运行时日志：

# Watch the InferenceService reach Ready state
oc get inferenceservice <model-name> -n <namespace> -w

# Watch the predictor pod start up
oc get pods -n <namespace> -w

# Tail predictor logs (model load can take several minutes once 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`	镜像仓库凭证缺失或无效	确认 `model-registry-secret` 存在、凭证有效，并使用 `oc secrets link` 和 `imagePullSecrets` patch 两种方式链接到 `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` 进度；拉取时间随镜像大小和镜像仓库带宽而变化。
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 配置（如需要）。

网络策略和防火墙允许访问。

端点身份验证运行正常。

连接和身份验证验证通过后，请前往配置模型网关。

模型服务基础设施

本页内容