Saiba como implantar e configurar endpoints de modelo quando seu ambiente ainda não possui uma solução de serviço de modelo.

Antes de conectar o IBM Bob a um modelo de linguagem grande (LLM), você deve ter acesso a um endpoint de modelo implantado. O Bob não provisiona, hospeda nem gerencia infraestrutura de serviço de modelo. Se sua organização já fornece endpoints de modelo por meio do OpenShift AI, servidores de inferência baseados em GPU, serviços de IA em nuvem ou outras plataformas de inferência, prossiga diretamente para Configurando o Model Gateway.

Opções de implantação

Escolha a opção que melhor se adapta ao seu ambiente e requisitos operacionais.

Opção	Quando usar
OpenShift AI (on-cluster, OCI/ModelCar)	Modelos air-gapped ou self-hosted; RHOAI já disponível no cluster
Nuvem pública	Modelos frontier via AWS Bedrock, Azure OpenAI ou Google Vertex AI
Infraestrutura privada	Modelo servido em servidores GPU separados ou um cluster de inferência dedicado

OpenShift AI (on-cluster, OCI/ModelCar)

O Red Hat OpenShift AI (RHOAI) é a plataforma recomendada para servir modelos on-cluster, incluindo implantações air-gapped. A abordagem preferida para carregar pesos de modelo é o padrão OCI/ModelCar: os arquivos de modelo são incorporados em uma imagem OCI em /models/ e enviados para um registro privado. Quando o InferenceService é implantado, o KServe injeta um init container modelcar-init que baixa a imagem e copia os pesos para um volume compartilhado em /mnt/models/, a partir do qual o runtime de serviço (por exemplo, vLLM) carrega. A imagem do modelo é armazenada em cache no nó após o primeiro download — reinicializações subsequentes no mesmo nó ignoram o download completamente.

Pré-requisitos:

Operador Red Hat OpenShift AI instalado no cluster

KServe habilitado e configurado

Nós worker habilitados para GPU com o NVIDIA GPU Operator (ou equivalente) configurado

CLI oc autenticado no cluster de destino com permissão para criar recursos no namespace de destino

Um registro de contêiner privado acessível a partir do cluster, com credenciais para enviar imagens

Configurar o Red Hat OpenShift AI

Configure os recursos DataScienceClusterInitialization e DataScienceCluster da seguinte forma:

Desabilite serviceMesh.

Habilite o KServe definindo managementState: Managed.

Configure o KServe para usar o modo RawDeployment.

Remova todos os componentes não utilizados do Red Hat OpenShift AI.

Exemplo de configuração do KServe:

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

Habilitar suporte ao ModelCar

O suporte ao ModelCar é controlado pelo ConfigMap inferenceservice-config no namespace redhat-ods-applications. A chave storageInitializer deve conter "enableModelcar": true.

Verifique a configuração atual:

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

A saída deve conter:

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

Se enableModelcar estiver ausente ou for false, atualize o 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()))')}}"

Reinicie o controller do KServe para aplicar a mudança:

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

Empacotar arquivos de modelo em uma imagem OCI

Baixe os pesos do modelo do Hugging Face e empacote-os em uma imagem OCI. A imagem deve ter todos os arquivos de modelo no diretório /models. Para mais informações, consulte a documentação do KServe. Para implantações vLLM, inclua os shards do modelo safetensors e exclua arquivos de checkpoint legados como .bin, .pt e original/*.

Exemplo de 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/

Se o modelo incluir um template de chat (por exemplo, chat_template.jinja), adicione-o. Alternativamente, copie o diretório inteiro em uma instrução — mais simples, mas inclui arquivos não necessários pelo vLLM:

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

Enviar a imagem para um registro privado

Envie a imagem OCI para um registro de contêiner privado acessível a partir do cluster:

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

Você pode usar qualquer ferramenta de gerenciamento de imagens suportada, incluindo:

Podman
Skopeo
Pipelines de CI/CD
Ferramentas específicas do registro

Criar o namespace de destino e o secret de pull de imagem

Crie o namespace do projeto e configure as credenciais para fazer pull da imagem do modelo:

oc new-project <namespace>

Crie o secret de pull do registro:

# 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>

Crie uma conta de serviço:

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

Associe o secret de pull à conta de serviço:

# 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"}]}'

Nota:

Ambos os comandos são necessários. A entrada imagePullSecrets é usada pelo container de inicialização do ModelCar durante a recuperação da imagem do modelo.

Criar um ServingRuntime

Implante um ServingRuntime baseado em vLLM no namespace de destino:

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

Aplique a configuração do runtime:

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

Implantar o InferenceService

Crie um InferenceService que referencia a imagem OCI do modelo usando um URI de armazenamento oci://.

Requisitos principais de configuração:

Referencie o ServingRuntime criado anteriormente.
Especifique a localização da imagem OCI em storageUri.
Configure os limites de recursos de CPU, memória e GPU que correspondam aos requisitos do modelo.
Monte memória compartilhada (/dev/shm) para o vLLM.
Configure os argumentos de runtime e as variáveis de ambiente do vLLM.

Exemplo:

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

Aplique o manifesto do InferenceService:

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

Verificar a implantação

Monitore o status da implantação, a inicialização dos pods e os logs do runtime:

# 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>

Quando o InferenceService reportar READY: True, valide o endpoint.

Verifique o registro do modelo e envie uma solicitação de inferência de teste:

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

Solução de problemas

Problema	Causa possível	Resolução
`ErrImagePull`	Credenciais de registro ausentes ou inválidas	Confirme que `model-registry-secret` existe, tem credenciais válidas e está vinculado a `model-puller-sa` usando tanto `oc secrets link` quanto o patch de `imagePullSecrets`.
`ImagePullBackOff`	Secret de pull de imagem não configurado para ModelCar	Verifique se a conta de serviço inclui a configuração de `imagePullSecrets`. Execute `oc patch serviceaccount model-puller-sa -n <namespace> -p '{"imagePullSecrets": [{"name": "model-registry-secret"}]}'`
O predictor permanece em `Init:0/1`	Download da imagem do modelo em andamento	Verifique os eventos `oc describe pod` para progresso de `Pulling`/`Pulled`; o tempo de download escala com o tamanho da imagem e a largura de banda do registro.
O predictor permanece em `Init:0/1` indefinidamente	Arquivos de modelo não encontrados	Verifique se os arquivos de modelo estão armazenados em `/models` na imagem OCI.
`Engine core initialization failed`	Timeout de compilação CUDA inicial	A primeira inicialização pode demorar mais enquanto os caches são gerados. Reinicie e tente novamente.
Falha no carregamento do modelo	Formato de arquivo de modelo não suportado	Use arquivos safetensors do Hugging Face e exclua checkpoints legados.
Erros de self-test FIPS do OpenSSL	A imagem do container não é compatível com FIPS	Use uma imagem vLLM compatível com FIPS.
`OutOfMemory` / `OOMKilled`	Memória GPU insuficiente	Aumente os recursos de GPU, reduza o comprimento de contexto ou use um modelo quantizado.
O InferenceService permanece `Pending`	Recursos do cluster indisponíveis	Verifique a disponibilidade de GPU e libere recursos de cargas de trabalho não utilizadas.

Para mais informações, consulte:

Red Hat OpenShift AI — Serving models

KServe documentation

KServe ModelCar — OCI model packaging

Endpoints de modelo em nuvem pública

Use esta opção quando os modelos são hospedados por um provedor de nuvem, como IBM watsonx, AWS Bedrock, Azure OpenAI ou Google Vertex AI.

Pré-requisitos:

Conectividade HTTPS de saída (porta 443) do cluster OpenShift para o endpoint de serviço de nuvem.

Chaves de API válidas, credenciais IAM ou credenciais de autenticação equivalentes.

Antes de configurar o IBM Bob

Certifique-se de que:

A implantação do modelo está provisionada e ativa.

As credenciais de autenticação foram geradas e armazenadas com segurança.

Quaisquer requisitos de rede ou acesso específicos do provedor foram atendidos.

Após o endpoint estar disponível, prossiga para Configurando o Model Gateway.

Endpoints de modelo em infraestrutura privada

Use esta opção quando os modelos são hospedados em infraestrutura gerenciada pelo cliente fora do cluster IBM Bob, como:

Servidores GPU dedicados

Clusters OpenShift separados

Servidores de inferência bare-metal

Plataformas de IA empresariais

Pré-requisitos:

O endpoint do modelo expõe uma API compatível com OpenAI.

Existe conectividade HTTPS entre o cluster IBM Bob e o endpoint.

As credenciais de autenticação estão disponíveis como secrets do Kubernetes.

Antes de configurar o IBM Bob

Valide o seguinte:

Conectividade de rede do cluster para o endpoint.

Configuração TLS ou TLS mútuo, se necessário.

As políticas de rede e firewalls permitem o acesso.

A autenticação do endpoint está funcionando corretamente.

Após a conectividade e a autenticação serem verificadas, prossiga para Configurando o Model Gateway.

Infraestrutura de serviço de modelo

Opções de implantação

OpenShift AI (on-cluster, OCI/ModelCar)

Configurar o Red Hat OpenShift AI

Habilitar suporte ao ModelCar

Empacotar arquivos de modelo em uma imagem OCI

Enviar a imagem para um registro privado

Criar o namespace de destino e o secret de pull de imagem

Criar um ServingRuntime

Implantar o InferenceService

Verificar a implantação

Solução de problemas

Endpoints de modelo em nuvem pública

Endpoints de modelo em infraestrutura privada

Nesta página