Pré-requisitos Definição e configuração Configure o cache KV e o roteamento inteligente para melhorar o desempenho Implante seu modelo a partir do Amazon S3, Amazon FSx ou Hugging Face Hub Verificar o status da implantação Gerenciar a implantação

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.
Instalou o utilitário kubectl e configurou o jq em seu terminal.

Definição e configuração

Substitua todos os valores de espaço reservado por seus identificadores de recursos.

Selecione sua região em seu ambiente.
```
export REGION=<region>
```
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="<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"
```
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="<namespace>"
```

Crie uma CRD usando uma das seguintes opções:

Using Amazon FSx as the model source

Configure um nome SageMaker de endpoint.


export SAGEMAKER_ENDPOINT_NAME="deepseek15b-fsx"

Configure o ID do sistema de arquivos do Amazon FSx a ser usado.
```
export FSX_FILE_SYSTEM_ID="fs-1234abcd"
```

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.

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

Configure um nome SageMaker de endpoint.


export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3"

Configure o local do bucket do Amazon S3 no qual o modelo está localizado.
```
export S3_MODEL_LOCATION="deepseek-qwen-1-5b"
```

Veja a seguir um exemplo de arquivo yaml para criar um endpoint com o Amazon S3 e um modelo. 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

Configure um nome SageMaker de endpoint.


export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3"

Configure o local do bucket do Amazon S3 no qual o modelo está localizado.
```
export S3_MODEL_LOCATION="deepseek-qwen-1-5b"
```

Veja a seguir um exemplo de arquivo yaml para criar um endpoint com o Amazon S3 e um modelo. 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

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.

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

Configure um nome SageMaker de endpoint.


export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf"

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. ComprefetchEnabled: 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

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

Os principais campos de configuração do Hugging Face são:
- modelSourceType(obrigatório) — Defina comohuggingface.
- 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) — Quandotrue, um contêiner de inicialização baixa o modelo antes do início do contêiner de inferência. Quandofalse, 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

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: <redis | tieredstorage>
      l2CacheLocalUrl: <redis cluster URL if l2CacheBackend is redis >
```
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.
Ative o roteamento inteligente configurando como enabled true abaixointelligentRoutingSpec. 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: <routing strategy to use>
```
Ative as métricas do roteador e as métricas de armazenamento em cache definindo enabled como true abaixometrics. O port valor precisa ser igual ao containerPort valor abaixomodelInvocationPort.
```
metrics:
    enabled: true
    modelMetrics:
      port: <port value>
    ...
    modelInvocationPort:
      containerPort: <port value>
```

Implante seu modelo a partir do Amazon S3, Amazon FSx ou Hugging Face Hub

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

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, consulteFalhas na implantação do modelo Hugging Face Hub.

Verificar o status da implantação

Verifique se o modelo foi implantado com êxito.


kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

Verifique se o endpoint foi criado com êxito.


kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

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

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

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.

Verifique o status da implantação do Kubernetes.


kubectl describe deployment $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

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

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Implante modelos JumpStart usando kubectl

Implante modelos do armazenamento NVMe local usando kubectl

Implante modelos do Amazon S3, Amazon FSx ou Hugging Face Hub usando kubectl

Pré-requisitos

Definição e configuração

nota

nota

nota

Importante

nota

nota

Configure o cache KV e o roteamento inteligente para melhorar o desempenho

nota

nota

Implante seu modelo a partir do Amazon S3, Amazon FSx ou Hugging Face Hub

Verificar o status da implantação

Gerenciar a implantação

nota

Limpe os seus recursos

Solução de problemas