Prerequisiti Installazione e configurazione Configura la memorizzazione nella cache KV e il routing intelligente per migliorare le prestazioni Implementa il tuo modello da Amazon S3, Amazon FSx o Hugging Face Hub Verifica dello stato dell’implementazione Gestione dell’implementazione

Distribuisci modelli da Amazon S3, Amazon FSx o Hugging Face Hub usando kubectl

I passaggi seguenti mostrano come distribuire modelli archiviati su Amazon S3, Amazon FSx o Hugging Face Hub su un cluster Amazon utilizzando kubectl. SageMaker HyperPod

Le istruzioni seguenti contengono celle di codice e comandi progettati per essere eseguiti in un terminale. Assicurati di aver configurato il tuo ambiente con le credenziali prima di eseguire questi comandi. AWS

Prerequisiti

Prima di iniziare, verifica di aver:

Configura funzionalità di inferenza sui tuoi SageMaker HyperPod cluster Amazon. Per ulteriori informazioni, consulta Configurazione dei HyperPod cluster per l'implementazione dei modelli.
Installato l’utilità kubectl e configurato jq nel terminale.

Installazione e configurazione

Sostituisci tutti i valori segnaposto con gli tuoi identificatori delle risorse effettivi.

Seleziona la tua Regione nell’ambiente.
```
export REGION=<region>
```
Inizializza il nome del cluster. Questo identifica il HyperPod cluster in cui verrà distribuito il tuo modello.

Nota
Rivolgiti all’amministratore del cluster per assicurarti di ottenere le autorizzazioni per questo ruolo o utente. Puoi eseguire !aws sts get-caller-identity --query "Arn" per verificare quale ruolo o utente stai utilizzando nel terminale.
```
# Specify your hyperpod cluster name here
HYPERPOD_CLUSTER_NAME="<Hyperpod_cluster_name>"

# NOTE: For sample deployment, we use g5.8xlarge for deepseek-r1 1.5b model which has sufficient memory and GPU
instance_type="ml.g5.8xlarge"
```
Inizializza il namespace del cluster. L’amministratore del cluster dovrebbe aver già creato un account di servizio hyperpod-inference nel tuo namespace.
```
cluster_namespace="<namespace>"
```

Crea una CRD utilizzando una delle seguenti opzioni:

Using Amazon FSx as the model source

Imposta un nome per l' SageMaker endpoint.


export SAGEMAKER_ENDPOINT_NAME="deepseek15b-fsx"

Configura l’ID del file system Amazon FSx da utilizzare.
```
export FSX_FILE_SYSTEM_ID="fs-1234abcd"
```

Di seguito è riportato un file yaml di esempio per la creazione di un endpoint con Amazon FSx e un modello. DeepSeek

Nota

Per i cluster con il partizionamento GPU abilitato, sostituiscilo con il nome della risorsa MIG appropriato, ad nvidia.com/gpu esempio. nvidia.com/mig-1g.10gb Per ulteriori informazioni, consulta Invio di attività con MIG.

cat <<EOF> deploy_fsx_cluster_inference.yaml
---
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: lmcache-test
  namespace: inf-update
spec:
  modelName: Llama-3.1-8B-Instruct
  instanceType: ml.g5.24xlarge
  invocationEndpoint: v1/chat/completions
  replicas: 2
  modelSourceConfig:
    fsxStorage:
      fileSystemId: $FSX_FILE_SYSTEM_ID
    modelLocation: deepseek-1-5b
    modelSourceType: fsx
  worker:
    environmentVariables:
    - name: HF_MODEL_ID
      value: /opt/ml/model
    - name: SAGEMAKER_PROGRAM
      value: inference.py
    - name: SAGEMAKER_SUBMIT_DIRECTORY
      value: /opt/ml/model/code
    - name: MODEL_CACHE_ROOT
      value: /opt/ml/model
    - name: SAGEMAKER_ENV
      value: '1'
    image: 763104351884.dkr.ecr.us-east-2.amazonaws.com/huggingface-pytorch-tgi-inference:2.4.0-tgi2.3.1-gpu-py311-cu124-ubuntu22.04-v2.0
    modelInvocationPort:
      containerPort: 8080
      name: http
    modelVolumeMount:
      mountPath: /opt/ml/model
      name: model-weights
    resources:
      limits:
        nvidia.com/gpu: 1
        # For MIG-enabled instances, use: nvidia.com/mig-1g.10gb: 1
      requests:
        cpu: 30000m
        memory: 100Gi
        nvidia.com/gpu: 1
        # For MIG-enabled instances, use: nvidia.com/mig-1g.10gb: 1
EOF

Using Amazon S3 as the model source

Imposta un nome per l'endpoint. SageMaker


export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3"

Configura la posizione del bucket Amazon S3 in cui si trova il modello.
```
export S3_MODEL_LOCATION="deepseek-qwen-1-5b"
```

Di seguito è riportato un file yaml di esempio per la creazione di un endpoint con Amazon S3 e un modello. DeepSeek

Nota

cat <<EOF> deploy_s3_inference.yaml
---
apiVersion: inference.sagemaker.aws.amazon.com/v1alpha1
kind: InferenceEndpointConfig
metadata:
  name: $SAGEMAKER_ENDPOINT_NAME
  namespace: $CLUSTER_NAMESPACE
spec:
  modelName: deepseek15b
  endpointName: $SAGEMAKER_ENDPOINT_NAME
  instanceType: ml.g5.8xlarge
  invocationEndpoint: invocations
  modelSourceConfig:
    modelSourceType: s3
    s3Storage:
      bucketName: $S3_MODEL_LOCATION
      region: $REGION
    modelLocation: deepseek15b
    prefetchEnabled: true
  worker:
    resources:
      limits:
        nvidia.com/gpu: 1
        # For MIG-enabled instances, use: nvidia.com/mig-1g.10gb: 1
      requests:
        nvidia.com/gpu: 1
        # For MIG-enabled instances, use: nvidia.com/mig-1g.10gb: 1
        cpu: 25600m
        memory: 102Gi
    image: 763104351884.dkr.ecr.us-east-2.amazonaws.com/djl-inference:0.32.0-lmi14.0.0-cu124
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    environmentVariables:
      - name: PYTHONHASHSEED
        value: "123"
      - name: OPTION_ROLLING_BATCH
        value: "vllm"
      - name: SERVING_CHUNKED_READ_TIMEOUT
        value: "480"
      - name: DJL_OFFLINE
        value: "true"
      - name: NUM_SHARD
        value: "1"
      - name: SAGEMAKER_PROGRAM
        value: "inference.py"
      - name: SAGEMAKER_SUBMIT_DIRECTORY
        value: "/opt/ml/model/code"
      - name: MODEL_CACHE_ROOT
        value: "/opt/ml/model"
      - name: SAGEMAKER_MODEL_SERVER_WORKERS
        value: "1"
      - name: SAGEMAKER_MODEL_SERVER_TIMEOUT
        value: "3600"
      - name: OPTION_TRUST_REMOTE_CODE
        value: "true"
      - name: OPTION_ENABLE_REASONING
        value: "true"
      - name: OPTION_REASONING_PARSER
        value: "deepseek_r1"
      - name: SAGEMAKER_CONTAINER_LOG_LEVEL
        value: "20"
      - name: SAGEMAKER_ENV
        value: "1"
      - name: MODEL_SERVER_TYPE
        value: "vllm"
      - name: SESSION_KEY
        value: "x-user-id"
EOF

Using Amazon S3 as the model source

Imposta un nome per l'endpoint. SageMaker


export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3"

Configura la posizione del bucket Amazon S3 in cui si trova il modello.
```
export S3_MODEL_LOCATION="deepseek-qwen-1-5b"
```

Di seguito è riportato un file yaml di esempio per la creazione di un endpoint con Amazon S3 e un modello. DeepSeek

cat <<EOF> deploy_s3_inference.yaml
---
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: lmcache-test
  namespace: inf-update
spec:
  modelName: Llama-3.1-8B-Instruct
  instanceType: ml.g5.24xlarge
  invocationEndpoint: v1/chat/completions
  replicas: 2
  modelSourceConfig:
    modelSourceType: s3
    s3Storage:
      bucketName: bugbash-ada-resources
      region: us-west-2
    modelLocation: models/Llama-3.1-8B-Instruct
    prefetchEnabled: false
  kvCacheSpec:
    enableL1Cache: true
#    enableL2Cache: true
#    l2CacheSpec:
#      l2CacheBackend: redis/sagemaker
#      l2CacheLocalUrl: redis://redis.redis-system.svc.cluster.local:6379
  intelligentRoutingSpec:
    enabled: true
  tlsConfig:
    tlsCertificateOutputS3Uri: s3://sagemaker-lmcache-fceb9062-tls-6f6ee470
  metrics:
    enabled: true
    modelMetrics:
      port: 8000
  loadBalancer:
    healthCheckPath: /health
  worker:
    resources:
      limits:
        nvidia.com/gpu: "4"
      requests:
        cpu: "6"
        memory: 30Gi
        nvidia.com/gpu: "4"
    image: lmcache/vllm-openai:latest
    args:
      - "/opt/ml/model"
      - "--max-model-len"
      - "20000"
      - "--tensor-parallel-size"
      - "4"
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    environmentVariables:
      - name: PYTHONHASHSEED
        value: "123"
      - name: OPTION_ROLLING_BATCH
        value: "vllm"
      - name: SERVING_CHUNKED_READ_TIMEOUT
        value: "480"
      - name: DJL_OFFLINE
        value: "true"
      - name: NUM_SHARD
        value: "1"
      - name: SAGEMAKER_PROGRAM
        value: "inference.py"
      - name: SAGEMAKER_SUBMIT_DIRECTORY
        value: "/opt/ml/model/code"
      - name: MODEL_CACHE_ROOT
        value: "/opt/ml/model"
      - name: SAGEMAKER_MODEL_SERVER_WORKERS
        value: "1"
      - name: SAGEMAKER_MODEL_SERVER_TIMEOUT
        value: "3600"
      - name: OPTION_TRUST_REMOTE_CODE
        value: "true"
      - name: OPTION_ENABLE_REASONING
        value: "true"
      - name: OPTION_REASONING_PARSER
        value: "deepseek_r1"
      - name: SAGEMAKER_CONTAINER_LOG_LEVEL
        value: "20"
      - name: SAGEMAKER_ENV
        value: "1"
      - name: MODEL_SERVER_TYPE
        value: "vllm"
      - name: SESSION_KEY
        value: "x-user-id"
EOF

Using Hugging Face Hub as the model source

Crea un Kubernetes Secret contenente il tuo token API Hugging Face. Questo token è necessario per i modelli con accesso limitato e consigliato per tutti i download. Puoi generare un token su huggingface. co/settings/token.

Importante
L'implementazione di modelli da Hugging Face Hub richiede l'accesso a Internet in uscita dai nodi del cluster ai domini Hugging Face, inclusi e. *.huggingface.co *.hf.co Assicurati che la configurazione di rete VPC (gateway NAT, gruppi di sicurezza e ACL di rete) consenta l'uscita HTTPS verso questi domini. Senza accesso a Internet, il download del modello avrà esito negativo.

Nota
Per gli ambienti di produzione, consigliamo di utilizzare Amazon S3 o Amazon FSx come sorgente del modello anziché Hugging Face Hub. Con Amazon S3 e Amazon FSx, gli artefatti del modello vengono archiviati all'interno AWS dell'account, eliminando la dipendenza dalla connettività Internet esterna e garantendo tempi di implementazione più prevedibili. Hugging Face Hub è più adatto per lo sviluppo, la sperimentazione e la prototipazione rapida, laddove è conveniente l'accesso diretto all'archivio dei modelli Hugging Face.
```
kubectl create secret generic hf-token-secret \
  --from-literal=token=hf_YOUR_TOKEN_HERE \
  -n $CLUSTER_NAMESPACE
```

SageMaker Imposta un nome per l'endpoint.


export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf"

Di seguito è riportato un file YAML di esempio per la distribuzione di un modello Mistral 7B da Hugging Face Hub utilizzando VLLm come runtime di inferenza. ConprefetchEnabled: true, l'operatore utilizza un contenitore init per scaricare il modello prima dell'avvio del contenitore di inferenza.

Nota

Per i cluster con il partizionamento GPU abilitato, sostituiscilo nvidia.com/gpu con il nome della risorsa MIG appropriato, ad esempio. nvidia.com/mig-1g.10gb Per ulteriori informazioni, consulta Invio di attività con MIG.

cat <<EOF> deploy_hf_inference.yaml
---
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: $SAGEMAKER_ENDPOINT_NAME
  namespace: $CLUSTER_NAMESPACE
spec:
  modelName: mistral-7b
  modelSourceConfig:
    modelSourceType: huggingface
    prefetchEnabled: true
    huggingFaceModel:
      modelId: "mistralai/Mistral-7B-Instruct-v0.3"
      tokenSecretRef:
        name: hf-token-secret
        key: token
  instanceType: "ml.g5.24xlarge"
  invocationEndpoint: v1/chat/completions
  worker:
    image: "vllm/vllm-openai:v0.10.1"
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    resources:
      requests:
        nvidia.com/gpu: "4"
        memory: "96Gi"
        cpu: "16"
      limits:
        nvidia.com/gpu: "4"
        memory: "96Gi"
        cpu: "16"
    args:
      - "--model"
      - "/opt/ml/model"
      - "--port"
      - "8000"
      - "--tensor-parallel-size"
      - "4"
      - "--served-model-name"
      - "mistralai/Mistral-7B-Instruct-v0.3"
    environmentVariables:
      - name: VLLM_REQUEST_TIMEOUT
        value: "600"
EOF

I campi chiave di configurazione di Hugging Face sono:
- modelSourceType(obbligatorio) — Impostato su. huggingface
- huggingFaceModel.modelId(obbligatorio) — L'identificatore del modello Hugging Face Hub in org/model formato (ad esempio,). mistralai/Mistral-7B-Instruct-v0.3
- huggingFaceModel.commitSHA(opzionale) — Un commit SHA Git di 40 caratteri per aggiungere una versione specifica del modello. Se omesso, il valore predefinito è il ramo. main
- huggingFaceModel.tokenSecretRef(opzionale) — Riferimento a un Kubernetes Secret contenente il token dell'API Hugging Face. Obbligatorio per i modelli recintati. Il token viene utilizzato solo durante il download del modello e non è esposto al contenitore di inferenza.
- prefetchEnabled(opzionale) — Quando true un contenitore init scarica il modello prima dell'avvio del contenitore di inferenza. Quandofalse, il runtime di inferenza (vLLm, TGI, sgLang) scarica il modello in modo nativo all'avvio. L’impostazione predefinita è false.

Configura la memorizzazione nella cache KV e il routing intelligente per migliorare le prestazioni

Abilita la memorizzazione nella cache KV impostando enableL1Cache e enableL2Cache su true .Quindi, imposta redis e aggiorna l2CacheLocalUrl con l'URL del l2CacheSpec cluster Redis.
```
  kvCacheSpec:
    enableL1Cache: true
    enableL2Cache: true
    l2CacheSpec:
      l2CacheBackend: <redis | tieredstorage>
      l2CacheLocalUrl: <redis cluster URL if l2CacheBackend is redis >
```
Nota
Se il cluster redis non si trova all'interno dello stesso Amazon VPC HyperPod del cluster, la crittografia dei dati in transito non è garantita.

Nota
Non è necessario l2 CacheLocalUrl se è selezionato lo storage su più livelli.
Abilita il routing intelligente impostando su under. enabled true intelligentRoutingSpec È possibile specificare la strategia di routing da utilizzare. routingStrategy Se non viene specificata alcuna strategia di routing, l'impostazione predefinita è. prefixaware
```
intelligentRoutingSpec:
    enabled: true
    routingStrategy: <routing strategy to use>
```
Abilita le metriche del router e le metriche di memorizzazione nella cache impostando su under. enabled true metrics Il port valore deve essere lo stesso del valore inferiore. containerPort modelInvocationPort
```
metrics:
    enabled: true
    modelMetrics:
      port: <port value>
    ...
    modelInvocationPort:
      containerPort: <port value>
```

Implementa il tuo modello da Amazon S3, Amazon FSx o Hugging Face Hub

Ottieni il nome del cluster Amazon EKS dall'ARN del HyperPod cluster per l'autenticazione kubectl.


export EKS_CLUSTER_NAME=$(aws --region $REGION sagemaker describe-cluster --cluster-name $HYPERPOD_CLUSTER_NAME \
  --query 'Orchestrator.Eks.ClusterArn' --output text | \
  cut -d'/' -f2)
aws eks update-kubeconfig --name $EKS_CLUSTER_NAME --region $REGION

Implementa il tuo InferenceEndpointConfig modello con una delle seguenti opzioni:
Deploy with Amazon FSx as a source
```
kubectl apply -f deploy_fsx_luster_inference.yaml
```
Deploy with Amazon S3 as a source
```
kubectl apply -f deploy_s3_inference.yaml
```
Deploy with Hugging Face Hub as a source
```
kubectl apply -f deploy_hf_inference.yaml
```
Se la distribuzione fallisce, controlla gli InferenceEndpointConfig eventi per informazioni diagnostiche. Per problemi comuni come errori nei token, connettività di rete e modello non trovato, consultaErrori di implementazione del modello Hugging Face Hub.

Verifica dello stato dell’implementazione

Verifica se il modello è stato implementato correttamente.


kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

Verifica che l’endpoint sia stato creato correttamente.


kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

Testa l’endpoint implementato per verificare che funzioni correttamente. Questa fase conferma che il modello è stato implementato correttamente e può elaborare le richieste di inferenza.


aws sagemaker-runtime invoke-endpoint \
  --endpoint-name $SAGEMAKER_ENDPOINT_NAME \
  --content-type "application/json" \
  --body '{"inputs": "What is AWS SageMaker?"}' \
  --region $REGION \
  --cli-binary-format raw-in-base64-out \
  /dev/stdout

Gestione dell’implementazione

Al termine dei test sull’implementazione, utilizza i comandi seguenti per pulire le risorse.

Nota

Verifica di non aver più bisogno del modello implementato o dei dati archiviati prima di procedere.

Pulizia delle risorse

Elimina l’implementazione dell’inferenza e le risorse Kubernetes associate. Ciò interrompe l'esecuzione dei contenitori del modello e rimuove l' SageMakerendpoint.
```
kubectl delete inferenceendpointconfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
```

Verifica che la pulizia sia stata eseguita correttamente.


# # Check that Kubernetes resources are removed
kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $CLUSTER_NAMESPACE


# Verify SageMaker endpoint is deleted (should return error or empty)
aws sagemaker describe-endpoint --endpoint-name $SAGEMAKER_ENDPOINT_NAME --region $REGION

Risoluzione dei problemi

Utilizza questi comandi di debug se l’implementazione non funziona come previsto.

Controlla lo stato dell’implementazione di Kubernetes.


kubectl describe deployment $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

Controlla lo InferenceEndpointConfig stato per vedere lo stato di implementazione di alto livello e gli eventuali problemi di configurazione.
```
kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
```
Controlla lo stato di tutti gli oggetti Kubernetes. Ottieni una visione completa di tutte le risorse Kubernetes correlate nel tuo namespace. Questa funzionalità ti offre una panoramica rapida su tutto ciò che è in esecuzione e sugli eventuali elementi mancanti.
```
kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $CLUSTER_NAMESPACE
```

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Distribuisci modelli usando kubectl JumpStart

Distribuisci modelli dallo storage NVMe locale usando kubectl

Distribuisci modelli da Amazon S3, Amazon FSx o Hugging Face Hub usando kubectl

Prerequisiti

Installazione e configurazione

Nota

Nota

Nota

Importante

Nota

Nota

Configura la memorizzazione nella cache KV e il routing intelligente per migliorare le prestazioni

Nota

Nota

Implementa il tuo modello da Amazon S3, Amazon FSx o Hugging Face Hub

Verifica dello stato dell’implementazione

Gestione dell’implementazione

Nota

Pulizia delle risorse

Risoluzione dei problemi