As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Implante modelos do Amazon S3, Amazon FSx ou Hugging Face Hub usando kubectl As etapas a seguir mostram como implantar modelos armazenados no Amazon S3, no Amazon FSx ou no Hugging Face Hub em um cluster da Amazon usando kubectl. SageMaker HyperPod As instruções a seguir contêm células de código e comandos projetados para serem executados em um terminal. Certifique-se de ter configurado seu ambiente com AWS credenciais antes de executar esses comandos. ## Pré-requisitos Antes de começar, verifique se você: + Configure recursos de inferência em seus SageMaker HyperPod clusters da Amazon. Para obter mais informações, consulte [Configurando seus HyperPod clusters para implantação de modelos](sagemaker-hyperpod-model-deployment-setup.md). + Instalou o utilitário [kubectl](https://kubernetes.io/docs/reference/kubectl/) e configurou o [jq](https://jqlang.org/) em seu terminal. ## Definição e configuração Substitua todos os valores de espaço reservado por seus identificadores de recursos. 1. Selecione sua região em seu ambiente. ``` export REGION= ``` 1. Inicialize o nome do seu cluster. Isso identifica o HyperPod cluster em que seu modelo será implantado. **nota** Consulte o administrador do cluster para garantir que as permissões sejam concedidas a esse perfil ou usuário. É possível executar `!aws sts get-caller-identity --query "Arn"` para verificar qual perfil ou usuário você está usando no seu terminal. ``` # 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. Inicialize o namespace do seu cluster. O administrador do cluster já deve ter criado uma conta de serviço hyperpod-inference em seu namespace. ``` cluster_namespace="" ``` 1. Crie uma CRD usando uma das seguintes opções: ------ #### [ Using Amazon FSx as the model source ] 1. Configure um nome SageMaker de endpoint. ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-fsx" ``` 1. Configure o ID do sistema de arquivos do Amazon FSx a ser usado. ``` export FSX_FILE_SYSTEM_ID="fs-1234abcd" ``` 1. Veja a seguir um exemplo de arquivo yaml para criar um endpoint com o Amazon FSx e um modelo. DeepSeek **nota** Para clusters com particionamento de GPU ativado, `nvidia.com/gpu` substitua pelo nome do recurso MIG apropriado, como. `nvidia.com/mig-1g.10gb` Para obter mais informações, consulte [Envio de tarefas com o 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. Configure um nome SageMaker de endpoint. ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3" ``` 1. Configure o local do bucket do Amazon S3 no qual o modelo está localizado. ``` export S3_MODEL_LOCATION="deepseek-qwen-1-5b" ``` 1. Veja a seguir um exemplo de arquivo yaml para criar um endpoint com o Amazon S3 e um modelo. DeepSeek **nota** Para clusters com particionamento de GPU ativado, `nvidia.com/gpu` substitua pelo nome do recurso MIG apropriado, como. `nvidia.com/mig-1g.10gb` Para obter mais informações, consulte [Envio de tarefas com o 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. Configure um nome SageMaker de endpoint. ``` export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3" ``` 1. Configure o local do bucket do Amazon S3 no qual o modelo está localizado. ``` export S3_MODEL_LOCATION="deepseek-qwen-1-5b" ``` 1. Veja a seguir um exemplo de arquivo yaml para criar um endpoint com o Amazon S3 e um modelo. 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. Crie um segredo do Kubernetes contendo seu token da API Hugging Face. Esse token é necessário para modelos fechados e recomendado para todos os downloads. Você pode gerar um token no [huggingface. co/settings/tokens](https://huggingface.co/settings/tokens). **Importante** A implantação de modelos do Hugging Face Hub requer acesso de saída à Internet dos nós do cluster para os domínios do Hugging Face, incluindo e. `*.huggingface.co` `*.hf.co` Certifique-se de que sua configuração de rede VPC (gateway NAT, grupos de segurança e ACLs de rede) permita a saída HTTPS para esses domínios. Sem acesso à Internet, o download do modelo falhará. **nota** Para ambientes de produção, recomendamos usar o Amazon S3 ou o Amazon FSx como fonte do modelo em vez do Hugging Face Hub. Com o Amazon S3 e o Amazon FSx, os artefatos do modelo são armazenados em sua AWS conta, eliminando a dependência da conectividade externa com a Internet e fornecendo tempos de implantação mais previsíveis. O Hugging Face Hub é mais adequado para desenvolvimento, experimentação e prototipagem rápida, onde o acesso direto ao repositório de modelos Hugging Face é conveniente. ``` kubectl create secret generic hf-token-secret \ --from-literal=token=hf_YOUR_TOKEN_HERE \ -n $CLUSTER_NAMESPACE ``` 1. Configure um nome SageMaker de endpoint. ``` export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf" ``` 1. A seguir está um exemplo de arquivo YAML para implantar um modelo Mistral 7B do Hugging Face Hub usando o vLLM como tempo de execução de inferência. Com`prefetchEnabled: true`, o operador usa um contêiner de inicialização para baixar o modelo antes do início do contêiner de inferência. **nota** Para clusters com particionamento de GPU ativado, `nvidia.com/gpu` substitua pelo nome do recurso MIG apropriado, como. `nvidia.com/mig-1g.10gb` Para obter mais informações, consulte [Envio de tarefas com o 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. Os principais campos de configuração do Hugging Face são: + `modelSourceType`(obrigatório) — Defina como`huggingface`. + `huggingFaceModel.modelId`(obrigatório) — O identificador do modelo Hugging Face Hub em `org/model` formato (por exemplo,). `mistralai/Mistral-7B-Instruct-v0.3` + `huggingFaceModel.commitSHA`(opcional) — Um SHA do Git commit de 40 caracteres para fixar uma versão específica do modelo. Se omitido, o padrão é a ramificação. `main` + `huggingFaceModel.tokenSecretRef`(opcional) — Referência a um segredo do Kubernetes contendo seu token da API Hugging Face. Necessário para modelos fechados. O token é usado somente durante o download do modelo e não é exposto ao contêiner de inferência. + `prefetchEnabled`(opcional) — Quando`true`, um contêiner de inicialização baixa o modelo antes do início do contêiner de inferência. Quando`false`, o tempo de execução de inferência (vLLM, TGI, SGlang) baixa o modelo nativamente na inicialização. O padrão é `false`. ------ ## Configure o cache KV e o roteamento inteligente para melhorar o desempenho 1. Ative o armazenamento em cache KV definindo `enableL1Cache` e `enableL2Cache` como `true` .Em seguida, `l2CacheSpec` defina `redis` e atualize `l2CacheLocalUrl` com a URL do cluster Redis. ``` kvCacheSpec: enableL1Cache: true enableL2Cache: true l2CacheSpec: l2CacheBackend: l2CacheLocalUrl: ``` **nota** Se o cluster redis não estiver na mesma Amazon VPC que HyperPod o cluster, a criptografia dos dados em trânsito não é garantida. **nota** Não é necessário l2 CacheLocalUrl se o armazenamento em camadas estiver selecionado. 1. Ative o roteamento inteligente configurando como `enabled` `true` abaixo`intelligentRoutingSpec`. Você pode especificar em `routingStrategy` qual estratégia de roteamento usar. Se nenhuma estratégia de roteamento for especificada, o padrão será. `prefixaware` ``` intelligentRoutingSpec: enabled: true routingStrategy: ``` 1. Ative as métricas do roteador e as métricas de armazenamento em cache definindo `enabled` como `true` abaixo`metrics`. O `port` valor precisa ser igual ao `containerPort` valor abaixo`modelInvocationPort`. ``` metrics: enabled: true modelMetrics: port: ... modelInvocationPort: containerPort: ``` ## Implante seu modelo a partir do Amazon S3, Amazon FSx ou Hugging Face Hub 1. Obtenha o nome do cluster Amazon EKS do ARN do HyperPod cluster para autenticação 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. Implante seu InferenceEndpointConfig modelo com uma das seguintes opções: ------ #### [ 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 a implantação falhar, verifique os InferenceEndpointConfig eventos para obter informações de diagnóstico. Para problemas comuns, como erros de token, conectividade de rede e modelo não encontrado, consulte[Falhas na implantação do modelo Hugging Face Hub](sagemaker-hyperpod-model-deployment-ts-huggingface.md). ------ ## Verificar o status da implantação 1. Verifique se o modelo foi implantado com êxito. ``` kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. Verifique se o endpoint foi criado com êxito. ``` kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. Teste o endpoint implantado para verificar se ele está funcionando corretamente. Essa etapa confirma que seu modelo foi implantado com êxito e pode processar solicitações de inferência. ``` 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 ``` ## Gerenciar a implantação Quando você concluir o teste de implantação, use os comandos a seguir para limpar seus recursos. **nota** Antes de continuar, verifique se você não precisa mais do modelo implantado ou dos dados armazenados. **Limpe os seus recursos** 1. Exclua a implantação de inferência e os recursos associados do Kubernetes. Isso interrompe a execução dos contêineres do modelo e remove o SageMaker endpoint. ``` kubectl delete inferenceendpointconfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. Verifique se a limpeza foi feita com êxito. ``` # # 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 ``` **Solução de problemas** Use esses comandos de depuração se a implantação não estiver funcionando conforme o esperado. 1. Verifique o status da implantação do Kubernetes. ``` kubectl describe deployment $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. Verifique o InferenceEndpointConfig status para ver o estado de implantação de alto nível e quaisquer problemas de configuração. ``` kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE ``` 1. Verifique o status de todos os objetos do Kubernetes. Obtenha uma visão abrangente de todos os recursos relacionados do Kubernetes em seu namespace. Isso oferece uma visão geral rápida do que está em execução e do que pode estar faltando. ``` kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $CLUSTER_NAMESPACE ```