先決條件設定與組態設定 KV 快取和智慧型路由以提升效能從 Amazon S3、Amazon FSx 或 Hugging Face Hub 部署您的模型驗證部署的狀態管理您的部署

使用 kubectl 從 Amazon S3、Amazon FSx 或 Hugging Face Hub 部署模型

下列步驟說明如何使用 kubectl，將存放在 Amazon S3、Amazon FSx 或 Hugging Face Hub 上的模型部署至 Amazon SageMaker HyperPod 叢集。

下列指示包含設計在終端機中執行的程式碼儲存格和命令。執行這些命令之前，請確定您已使用 AWS 登入資料設定環境。

先決條件

開始之前，請確認您已：

在 Amazon SageMaker HyperPod 叢集上設定推論功能。如需詳細資訊，請參閱設定 HyperPod 叢集以進行模型部署。
在終端機中安裝 kubectl 公用程式並設定 jq。

設定與組態

將所有預留位置值取代為您的實際資源識別碼。

在您的環境中選取您的區域。
```
export REGION=<region>
```
初始化您的叢集名稱。這可識別將在其中部署您模型的 HyperPod 叢集。

注意
請洽詢您的叢集管理員，確保已為此角色或使用者授與許可。您可以執行 !aws sts get-caller-identity --query "Arn" 來檢查您在終端機中使用的角色或使用者。
```
# 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"
```
初始化您的叢集命名空間。您的叢集管理員應該已在命名空間中建立 Hyperpod-inference 服務帳戶。
```
cluster_namespace="<namespace>"
```

請使用下列其中一個選項建立 CRD：

Using Amazon FSx as the model source

設定 SageMaker 端點名稱。


export SAGEMAKER_ENDPOINT_NAME="deepseek15b-fsx"

設定要使用的 Amazon FSx 檔案系統 ID。
```
export FSX_FILE_SYSTEM_ID="fs-1234abcd"
```

下列是使用 Amazon FSx 和 DeepSeek 模型建立端點的範例 yaml 檔案。

注意

對於已啟用 GPU 分割的叢集，請將取代nvidia.com/gpu為適當的 MIG 資源名稱，例如 nvidia.com/mig-1g.10gb。如需詳細資訊，請參閱使用 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

設定 SageMaker 端點名稱。


export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3"

設定模型所在的 Amazon S3 儲存貯體位置。
```
export S3_MODEL_LOCATION="deepseek-qwen-1-5b"
```

下列是使用 Amazon S3 和 DeepSeek 模型建立端點的範例 yaml 檔案。

注意

對於已啟用 GPU 分割的叢集，請將取代nvidia.com/gpu為適當的 MIG 資源名稱，例如 nvidia.com/mig-1g.10gb。如需詳細資訊，請參閱使用 MIG 提交任務。

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

設定 SageMaker 端點名稱。


export SAGEMAKER_ENDPOINT_NAME="deepseek15b-s3"

設定模型所在的 Amazon S3 儲存貯體位置。
```
export S3_MODEL_LOCATION="deepseek-qwen-1-5b"
```

下列是使用 Amazon S3 和 DeepSeek 模型建立端點的範例 yaml 檔案。

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

建立包含 Hugging Face API 權杖的 Kubernetes 秘密。門控模型需要此字符，並建議所有下載使用。您可以在 https：//huggingface.co/settings/tokens 產生字符。

重要
從 Hugging Face Hub 部署模型需要從叢集節點到 Hugging Face 網域的傳出網際網路存取，包括 *.huggingface.co和 *.hf.co。確保您的 VPC 聯網組態 (NAT 閘道、安全群組和網路 ACLs) 允許 HTTPS 輸出到這些網域。如果沒有網際網路存取，模型下載將會失敗。

注意
對於生產環境，建議使用 Amazon S3 或 Amazon FSx 作為模型來源，而不是 Hugging Face Hub。使用 Amazon S3 和 Amazon FSx，模型成品會存放在 AWS 您的帳戶中，消除對外部網際網路連線的依賴，並提供更可預測的部署時間。Hugging Face Hub 最適合開發、實驗和快速原型設計，其中直接存取 Hugging Face 模型儲存庫非常方便。
```
kubectl create secret generic hf-token-secret \
  --from-literal=token=hf_YOUR_TOKEN_HERE \
  -n $CLUSTER_NAMESPACE
```

設定 SageMaker 端點名稱。


export SAGEMAKER_ENDPOINT_NAME="mistral7b-hf"

以下是使用 vLLM 作為推論執行時間，從 Hugging Face Hub 部署 Mistral 7B 模型的範例 YAML 檔案。使用時prefetchEnabled: true，運算子會使用初始化容器在推論容器啟動之前下載模型。

注意

對於已啟用 GPU 分割的叢集，請將取代nvidia.com/gpu為適當的 MIG 資源名稱，例如 nvidia.com/mig-1g.10gb。如需詳細資訊，請參閱使用 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

金鑰 Hugging Face 組態欄位為：
- modelSourceType （必要） — 設定為 huggingface。
- huggingFaceModel.modelId （必要） — Hugging Face Hub 模型識別符的org/model格式（例如，mistralai/Mistral-7B-Instruct-v0.3)。
- huggingFaceModel.commitSHA （選用） — 40 個字元的 Git 遞交 SHA 以鎖定特定模型版本。如果省略，會預設為main分支。
- huggingFaceModel.tokenSecretRef （選用） — 參考包含 Hugging Face API 字符的 Kubernetes 秘密。門控模型需要。字符僅在模型下載期間使用，不會公開到推論容器。
- prefetchEnabled （選用） — 當時true，初始化容器會在推論容器啟動之前下載模型。當時false，推論執行時間 (vLLM、TGI、SGLang) 會在啟動時原生下載模型。預設為 false。

設定 KV 快取和智慧型路由以提升效能

透過將 enableL1Cache和設定為 enableL2Cache來啟用 KV 快取true。然後，將 l2CacheSpec 設定為 redis並使用 l2CacheLocalUrl Redis 叢集 URL 更新。
```
  kvCacheSpec:
    enableL1Cache: true
    enableL2Cache: true
    l2CacheSpec:
      l2CacheBackend: <redis | tieredstorage>
      l2CacheLocalUrl: <redis cluster URL if l2CacheBackend is redis >
```
注意
如果 redis 叢集不在與 HyperPod 叢集相同的 Amazon VPC 內，則不保證傳輸中資料的加密。

注意
如果選取分層儲存，則不需要 l2CacheLocalUrl。
透過將 enabled設定為 true下的來啟用智慧型路由intelligentRoutingSpec。您可以在下指定要使用的路由策略routingStrategy。如果未指定路由策略，則預設為 prefixaware。
```
intelligentRoutingSpec:
    enabled: true
    routingStrategy: <routing strategy to use>
```
在 true下將 enabled設定為，以啟用路由器指標和快取指標metrics。該port值必須與下containerPort的值相同modelInvocationPort。
```
metrics:
    enabled: true
    modelMetrics:
      port: <port value>
    ...
    modelInvocationPort:
      containerPort: <port value>
```

從 Amazon S3、Amazon FSx 或 Hugging Face Hub 部署您的模型

從 HyperPod 叢集 ARN 取得 Amazon EKS 叢集名稱，以進行 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

使用下列其中一個選項部署您的 InferenceEndpointConfig 模型：
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
```
如果部署失敗，請檢查 InferenceEndpointConfig 事件以取得診斷資訊。如需常見問題，例如字符錯誤、網路連線和找不到模型，請參閱 Hugging Face Hub 模型部署失敗。

驗證部署的狀態

檢查是否已成功部署模型。


kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

檢查是否已成功建立端點。


kubectl describe SageMakerEndpointRegistration $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

測試部署的端點，以驗證其是否正常運作。此步驟確認您的模型已成功部署，並且可以處理推論請求。


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

管理您的部署

完成了測試您的部署時，請使用下列命令來清除資源。

注意

在繼續之前，請驗證您不再需要部署的模型或存放的資料。

清除您的資源

刪除推論部署和相關聯的 Kubernetes 資源。這會停止執行中的模型容器，並移除 SageMaker 端點。
```
kubectl delete inferenceendpointconfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
```

驗證是否已成功完成清除。


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

疑難排解

如果您的部署未如預期般運作，請使用這些偵錯命令。

檢查 Kubernetes 部署狀態。


kubectl describe deployment $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE

檢查 InferenceEndpointConfig 狀態，以查看高階部署狀態和任何組態問題。
```
kubectl describe InferenceEndpointConfig $SAGEMAKER_ENDPOINT_NAME -n $CLUSTER_NAMESPACE
```
檢查所有 Kubernetes 物件的狀態。全面檢視命名空間中所有相關的 Kubernetes 資源。這可讓您快速了解正在執行的內容和可能缺少的內容。
```
kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n $CLUSTER_NAMESPACE
```

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用 kubectl 從 JumpStart 部署模型

使用 kubectl 從本機 NVMe 儲存體部署模型

使用 kubectl 從 Amazon S3、Amazon FSx 或 Hugging Face Hub 部署模型

先決條件

設定與組態

注意

注意

注意

重要

注意

注意

設定 KV 快取和智慧型路由以提升效能

注意

注意

從 Amazon S3、Amazon FSx 或 Hugging Face Hub 部署您的模型

驗證部署的狀態

管理您的部署

注意

清除您的資源

疑難排解