Deploy dan konfigurasikan endpoint model untuk IBM Bob on-premises ketika lingkunganmu belum menyediakan solusi serving model.

Sebelum menghubungkan IBM Bob ke large language model (LLM), kamu harus memiliki akses ke endpoint model yang sudah di-deploy. Bob IDE tidak menyediakan, menghosting, atau mengelola infrastruktur serving model. Jika organisasimu sudah menyediakan endpoint model melalui Red Hat OpenShift Container Platform (OCP) AI, server inferensi berbasis GPU, layanan AI cloud, atau platform inferensi lainnya, lanjutkan langsung ke Mengonfigurasi model inference gateway.

Pilih opsi yang paling sesuai dengan lingkungan dan persyaratan operasionalmu.

Opsi	Kapan digunakan
OpenShift AI (on-cluster, OCI/ModelCar)	Model air-gapped atau self-hosted; Red Hat OpenShift AI sudah tersedia di cluster
Endpoint model cloud publik	Model frontier melalui AWS Bedrock, Azure OpenAI, atau Google Vertex AI
Endpoint model infrastruktur privat	Model yang disajikan di server GPU terpisah atau cluster inferensi khusus

Mendeploy model dengan OpenShift AI (on-cluster, OCI/ModelCar)

Red Hat OpenShift AI (RHOAI) adalah platform yang direkomendasikan untuk menyajikan model on-cluster, termasuk deployment air-gapped. Pendekatan yang disukai untuk memuat bobot model adalah pola OCI/ModelCar: file model di-bake ke dalam OCI image di bawah /models/ dan di-push ke private registry. Ketika InferenceService di-deploy, KServe menginjeksikan init container modelcar-init yang menarik image dan menyalin bobot ke volume bersama di /mnt/models/, yang kemudian dimuat oleh serving runtime (misalnya, vLLM). Image model di-cache di node setelah penarikan pertama; restart berikutnya di node yang sama akan melewati pengunduhan sepenuhnya.

Prasyarat:

Operator Red Hat OpenShift AI terinstal di cluster

KServe diaktifkan dan dikonfigurasi

Node worker yang mengaktifkan GPU dengan NVIDIA GPU Operator (atau yang setara) dikonfigurasi

CLI oc terotentikasi ke cluster target dengan izin untuk membuat sumber daya di namespace target

Private container registry yang dapat diakses dari cluster, dengan kredensial untuk push image ke dalamnya

Mengonfigurasi Red Hat OpenShift AI

Konfigurasikan resource DataScienceClusterInitialization dan DataScienceCluster sebagai berikut:

Nonaktifkan serviceMesh.

Aktifkan KServe dengan menetapkan managementState: Managed.

Konfigurasikan KServe untuk menggunakan mode RawDeployment.

Hapus semua komponen Red Hat OpenShift AI yang tidak digunakan.

Contoh konfigurasi KServe:

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

Mengaktifkan dukungan ModelCar

Dukungan ModelCar dikendalikan oleh ConfigMap inferenceservice-config di namespace redhat-ods-applications. Kunci storageInitializer harus berisi "enableModelcar": true.

Verifikasi konfigurasi saat ini:

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

Output harus berisi:

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

Jika enableModelcar tidak ada atau false, perbarui ConfigMap:

# Ambil nilai saat ini, gabungkan flag, dan 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()))')}}"

Restart controller KServe untuk menerapkan perubahan:

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

Kemas file model ke dalam OCI image

Unduh bobot model dari Hugging Face dan kemas ke dalam OCI image. Image harus memiliki semua file model di bawah direktori /models. Untuk informasi lebih lanjut, lihat dokumentasi KServe tentang menyiapkan OCI image dengan data model. Untuk deployment vLLM, sertakan shard model safetensors dan kecualikan file checkpoint lama seperti .bin, .pt, dan original/*.

Contoh Dockerfile:

FROM busybox:latest

# Bobot model -- shard safetensors dan index
COPY <model-name>/model-*.safetensors        /models/
COPY <model-name>/model.safetensors.index.json /models/

# Konfigurasi model
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/

Jika model menyertakan chat template (misalnya, chat_template.jinja), tambahkan. Alternatifnya, salin seluruh direktori dalam satu instruksi, yang lebih sederhana tetapi menyertakan file yang tidak diperlukan vLLM:

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

Push image ke private registry

Push OCI image ke private container registry yang dapat dijangkau dari cluster:

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

Gunakan tooling mana pun yang sesuai dengan lingkunganmu (podman push, skopeo copy, CI pipeline, dan sebagainya).

Buat namespace target dan image pull secret

Buat namespace proyek dan konfigurasikan kredensial untuk menarik image model.

Buat namespace:

oc new-project <namespace>

Buat registry pull secret:

# Pull secret agar KServe dapat menarik image model dari private registry-mu
oc create secret docker-registry model-registry-secret \
  --docker-server=<registry> \
  --docker-username=<username> \
  --docker-password=<password-or-token> \
  -n <namespace>

Buat service account:

# Service account yang digunakan oleh prediktor KServe
oc create sa model-puller-sa -n <namespace>

Asosiasikan pull secret dengan service account:

# Lampirkan pull secret -- kedua perintah diperlukan:
# oc secrets link mencakup penggunaan secret umum;
# imagePullSecrets diperlukan oleh init container ModelCar KServe secara khusus
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"}]}'

Catatan:

Kedua perintah diperlukan. Entri imagePullSecrets digunakan oleh init container ModelCar selama pengambilan image model.

Buat ServingRuntime

Deploy ServingRuntime berbasis vLLM di namespace target.

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

Terapkan konfigurasi runtime:

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

Deploy InferenceService

Buat InferenceService yang mereferensikan OCI model image menggunakan URI storage oci://.

Persyaratan konfigurasi utama:

Referensikan ServingRuntime yang telah dibuat sebelumnya.
Tentukan lokasi OCI image di storageUri.
Konfigurasikan batas sumber daya CPU, memori, dan GPU yang sesuai dengan persyaratan model.
Mount shared memory (/dev/shm) untuk vLLM.
Konfigurasikan argumen runtime vLLM dan variabel lingkungan.

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>"          # contoh: "8"
        limits:
          cpu: "<cpu-limit>"            # contoh: "16"
          memory: <memory-limit>        # contoh: 96Gi -- sesuaikan dengan kebutuhan VRAM model
          nvidia.com/gpu: "<gpu-count>" # contoh: "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"        # potong baris log vLLM untuk menghindari 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>" # harus sesuai dengan batas nvidia.com/gpu di atas
        - name: CUDA_VISIBLE_DEVICES
          value: "<gpu-indices>" # contoh: "0" untuk satu GPU; "0,1" untuk dua GPU
        - name: VLLM_WORKER_MULTIPROC_METHOD
          value: spawn
        - name: LOGNAME
          value: vllm
        - name: USER
          value: vllm

Terapkan manifest InferenceService:

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

Verifikasi deployment

Pantau status deployment, startup pod, dan log runtime:

# Pantau InferenceService mencapai status Ready
oc get inferenceservice <model-name> -n <namespace> -w

# Pantau startup pod prediktor
oc get pods -n <namespace> -w

# Ikuti log prediktor (pemuatan model dapat memakan beberapa menit setelah Running)
oc logs -f deployment/<model-name>-predictor -n <namespace>

Ketika InferenceService melaporkan READY: True, validasi endpoint.

Verifikasi registrasi model dan kirim permintaan inferensi uji:

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
  }'

Pemecahan masalah

Masalah	Kemungkinan penyebab	Resolusi
`ErrImagePull`	Kredensial registry hilang atau tidak valid	Konfirmasikan bahwa `model-registry-secret` ada, memiliki kredensial yang valid, dan ditautkan ke `model-puller-sa` menggunakan `oc secrets link` dan patch `imagePullSecrets`.
`ImagePullBackOff`	Image pull secret tidak dikonfigurasi untuk ModelCar	Pastikan service account menyertakan entri `imagePullSecrets`. Lihat perintah `oc patch serviceaccount` di langkah 3.
Prediktor tetap di `Init:0/1`	Pengunduhan image model sedang berlangsung	Periksa event `oc describe pod` untuk progres `Pulling`/`Pulled`; waktu penarikan bergantung pada ukuran image dan bandwidth registry.
Prediktor tetap di `Init:0/1` tanpa batas waktu	File model tidak ditemukan	Verifikasi bahwa file model disimpan di bawah `/models` dalam OCI image.
`Engine core initialization failed`	Timeout kompilasi CUDA awal	Startup pertama bisa lebih lama saat cache dihasilkan. Restart dan coba lagi.
Pemuatan model gagal	Format file model tidak didukung	Gunakan file safetensors Hugging Face dan kecualikan checkpoint lama.
Error OpenSSL FIPS self-test	Container image tidak kompatibel dengan FIPS	Gunakan image vLLM yang kompatibel dengan FIPS.
`OutOfMemory` / `OOMKilled`	Memori GPU tidak mencukupi	Tingkatkan sumber daya GPU, kurangi panjang konteks, atau gunakan model yang dikuantisasi.
InferenceService tetap `Pending`	Sumber daya cluster tidak tersedia	Verifikasi ketersediaan GPU dan bebaskan sumber daya dari workload yang tidak digunakan.

Sumber daya tambahan

Red Hat OpenShift AI - Serving models

Dokumentasi KServe

KServe ModelCar - OCI model packaging

Menggunakan endpoint model cloud publik

Gunakan opsi ini ketika model dihosting oleh penyedia cloud, seperti IBM watsonx, AWS Bedrock, Azure OpenAI, atau Google Vertex AI.

Prasyarat:

Konektivitas HTTPS keluar (port 443) dari cluster Red Hat OpenShift Container Platform (OCP) ke endpoint layanan cloud.

API key, kredensial IAM, atau kredensial autentikasi yang setara yang valid.

Sebelum memulai:

Pastikan bahwa:

Deployment model sudah disediakan dan aktif.

Kredensial autentikasi telah dibuat dan disimpan dengan aman.

Persyaratan jaringan atau akses khusus penyedia sudah diselesaikan.

Setelah endpoint tersedia, lanjutkan ke Mengonfigurasi model inference gateway.

Menggunakan endpoint model infrastruktur privat

Gunakan opsi ini ketika model dihosting di infrastruktur yang dikelola pelanggan di luar cluster IBM Bob, seperti:

Server GPU khusus

Cluster OpenShift terpisah

Server inferensi bare-metal

Platform AI enterprise

Prasyarat:

Endpoint model mengekspos API yang kompatibel dengan OpenAI.

Konektivitas HTTPS ada antara cluster IBM Bob dan endpoint.

Kredensial autentikasi tersedia sebagai Kubernetes secret.

Sebelum memulai:

Validasi hal-hal berikut:

Konektivitas jaringan dari cluster ke endpoint.

Konfigurasi TLS atau mutual TLS, jika diperlukan.

Kebijakan jaringan dan firewall mengizinkan akses.

Autentikasi endpoint berfungsi dengan benar.

Setelah konektivitas dan autentikasi diverifikasi, lanjutkan ke Mengonfigurasi model inference gateway.

Infrastruktur serving model

Mendeploy model dengan OpenShift AI (on-cluster, OCI/ModelCar)

Mengonfigurasi Red Hat OpenShift AI

Mengaktifkan dukungan ModelCar

Pemecahan masalah

Sumber daya tambahan

Menggunakan endpoint model cloud publik

Menggunakan endpoint model infrastruktur privat

On this page