View a markdown version of this page

Implante modelos do Amazon S3, Amazon FSx ou Hugging Face Hub usando kubectl - SageMaker IA da Amazon
Pré-requisitosDefinição e configuraçãoImplante seu modelo a partir do Amazon S3, Amazon FSx ou Hugging Face HubVerificar o status da implantaçãoGerenciar a implantação

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ê:

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=<region>

  2. 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.24xlarge for Llama 3.1 8B model which has sufficient memory and GPU
instance_type="ml.g5.24xlarge"

  3. 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>"

  4. 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="llama-fsx"

    2. Configure o ID do sistema de arquivos do Amazon FSx a ser usado.

      export FSX_FILE_SYSTEM_ID="fs-1234abcd"

    3. Veja a seguir um exemplo de arquivo yaml para criar um endpoint com o Amazon FSx e um modelo Llama.

      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: $SAGEMAKER_ENDPOINT_NAME
  namespace: $CLUSTER_NAMESPACE
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: Llama-3.1-8B-Instruct
    modelSourceType: fsx
  worker:
    image: vllm/vllm-openai:v0.19.1
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      mountPath: /opt/ml/model
      name: model-weights
    resources:
      limits:
        nvidia.com/gpu: 4
      requests:
        cpu: 30000m
        memory: 100Gi
        nvidia.com/gpu: 4
    args:
      - "--model"
      - "/opt/ml/model"
      - "--port"
      - "8000"
      - "--tensor-parallel-size"
      - "4"
      - "--served-model-name"
      - "Llama-3.1-8B-Instruct"
    environmentVariables:
      - name: VLLM_REQUEST_TIMEOUT
        value: "600"
EOF
    Using Amazon S3 as the model source

    1. Configure um nome SageMaker de endpoint.

      export SAGEMAKER_ENDPOINT_NAME="llama-s3"

    2. Configure o local do bucket do Amazon S3 no qual o modelo está localizado.

      export S3_MODEL_LOCATION="<your-s3-bucket-name>"

    3. Veja a seguir um exemplo de arquivo yaml para criar um endpoint com o Amazon S3 e um modelo Llama usando o vLLM como o tempo de execução 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.

      cat <<EOF> deploy_s3_inference.yaml
---
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: $SAGEMAKER_ENDPOINT_NAME
  namespace: $CLUSTER_NAMESPACE
spec:
  modelName: Llama-3.1-8B-Instruct
  instanceType: ml.g5.24xlarge
  invocationEndpoint: v1/chat/completions
  replicas: 2
  modelSourceConfig:
    modelSourceType: s3
    s3Storage:
      bucketName: $S3_MODEL_LOCATION
      region: $REGION
    modelLocation: Llama-3.1-8B-Instruct
    prefetchEnabled: true
  worker:
    image: vllm/vllm-openai:v0.19.1
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    resources:
      limits:
        nvidia.com/gpu: 4
      requests:
        cpu: 30000m
        memory: 100Gi
        nvidia.com/gpu: 4
    args:
      - "--model"
      - "/opt/ml/model"
      - "--port"
      - "8000"
      - "--tensor-parallel-size"
      - "4"
      - "--served-model-name"
      - "Llama-3.1-8B-Instruct"
    environmentVariables:
      - name: VLLM_REQUEST_TIMEOUT
        value: "600"
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.

      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

    2. Configure um nome SageMaker de endpoint.

      export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf"

    3. 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

      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_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.19.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

    4. 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.
nota

Para configurar o cache KV e o roteamento inteligente para melhorar o desempenho, consulte. Configure o cache KV e o roteamento inteligente

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

  2. 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

  1. Verifique se o modelo foi implantado com êxito.

    kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

  2. Verifique se o endpoint foi criado com êxito.

    kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

  3. 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

  2. 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

  2. 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

  3. 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