Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # 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](sagemaker-hyperpod-model-deployment-setup.md). + Installato l’utilità [kubectl](https://kubernetes.io/docs/reference/kubectl/) e configurato [jq](https://jqlang.org/) nel terminale. ## Installazione e configurazione Sostituisci tutti i valori segnaposto con gli tuoi identificatori delle risorse effettivi. 1. Seleziona la tua Regione nell’ambiente. ``` export REGION= ``` 1. 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="" # 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" ``` 1. Inizializza il namespace del cluster. L’amministratore del cluster dovrebbe aver già creato un account di servizio hyperpod-inference nel tuo namespace. ``` cluster_namespace="" ``` 1. Crea una CRD utilizzando una delle seguenti opzioni: ------ #### [ Using Amazon FSx as the model source ] 1. Imposta un nome per l' SageMaker endpoint. ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-fsx" ``` 1. Configura l’ID del file system Amazon FSx da utilizzare. ``` export FSX_FILE_SYSTEM_ID="fs-1234abcd" ``` 1. 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](sagemaker-hyperpod-eks-gpu-partitioning-task-submission.md). ``` cat < 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 ] 1. Imposta un nome per l'endpoint. SageMaker ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3" ``` 1. Configura la posizione del bucket Amazon S3 in cui si trova il modello. ``` export S3_MODEL_LOCATION="deepseek-qwen-1-5b" ``` 1. Di seguito è riportato un file yaml di esempio per la creazione di un endpoint con Amazon S3 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](sagemaker-hyperpod-eks-gpu-partitioning-task-submission.md). ``` cat < 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 ] 1. Imposta un nome per l'endpoint. SageMaker ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3" ``` 1. Configura la posizione del bucket Amazon S3 in cui si trova il modello. ``` export S3_MODEL_LOCATION="deepseek-qwen-1-5b" ``` 1. Di seguito è riportato un file yaml di esempio per la creazione di un endpoint con Amazon S3 e un modello. DeepSeek ``` cat < 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 ] 1. 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.](https://huggingface.co/settings/tokens) **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 ``` 1. SageMaker Imposta un nome per l'endpoint. ``` export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf" ``` 1. 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. Con`prefetchEnabled: 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](sagemaker-hyperpod-eks-gpu-partitioning-task-submission.md). ``` cat < 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 ``` 1. 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. Quando`false`, 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 1. 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: l2CacheLocalUrl: ``` **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. 1. 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: ``` 1. 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: ... modelInvocationPort: containerPort: ``` ## Implementa il tuo modello da Amazon S3, Amazon FSx o Hugging Face Hub 1. 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 ``` 1. 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, consulta[Errori di implementazione del modello Hugging Face Hub](sagemaker-hyperpod-model-deployment-ts-huggingface.md). ------ ## Verifica dello stato dell’implementazione 1. Verifica se il modello è stato implementato correttamente. ``` kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. Verifica che l’endpoint sia stato creato correttamente. ``` kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. 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** 1. 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 ``` 1. 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. 1. Controlla lo stato dell’implementazione di Kubernetes. ``` kubectl describe deployment $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. 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 ``` 1. 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 ```