hugs 文档

在 AWS 上结合 Inferentia 和 Trainium 使用 HUGS

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

在 AWS 上结合 Inferentia 和 Trainium 使用 HUGS

Hugging Face 生成式 AI 服务 (Hugging Face Generative AI Services),又称 HUGS,可以通过 AWS Marketplace 产品部署在亚马逊网络服务 (Amazon Web Services, AWS) 上。

此次合作为 AWS 客户带来了 Hugging Face 庞大的预训练模型库及其文本生成推理 (Text Generation Inference, TGI) 解决方案,实现了在 AWS 基础设施内无缝集成最先进的大语言模型 (Large Language Models, LLMs)。

HUGS 提供了经过精心挑选和手动基准测试的、托管在 Hugging Face Hub 上的性能最佳、最新的开放 LLM 集合,并将其提供给经过 TGI 优化的容器应用程序,允许用户在 AWS 或本地环境中部署第三方 Kubernetes 应用程序。

借助 HUGS,开发人员可以轻松地使用 AWS 基础设施查找、订阅和部署 Hugging Face 模型,利用 AWS Neuron Inferentia2 在优化的、零配置的 TGI 容器上的强大功能。

HUGS 在 HUGS 0.2.0 版本中提供了以下与 AWS Neuron 兼容的模型(下方列出了 Hugging Face 模型 ID 及其 HUGS IMAGE_NAME

您可以在支持的模型中找到 HUGS 支持的所有模型。

在 AWS Marketplace 上订阅 HUGS

  1. 前往 HUGS AWS Marketplace 列表

    HUGS on AWS Marketplace

  2. 按照页面上的说明在 AWS Marketplace 中订阅该产品。在撰写本文时(2024 年 12 月),步骤如下:

    1. 点击 `Continue to Subscribe`(继续订阅),然后进入下一页。
    2. 点击 `Continue to Configuration`(继续配置),然后进入下一页。
    3. 选择交付选项,例如 `HUGS v2 for NVIDIA GPUs and AWS Inferentia2`,以及软件版本,例如 `0.2.0`。请注意,AWS Neuron Inferentia2 支持已从 0.2.0 版本开始包含。

    HUGS Configuration on AWS Marketplace

  3. 然后点击 `Continue to Launch`(继续启动)。您就成功订阅了 HUGS。现在,您可以按照以下步骤,使用提供的容器 URI,通过 Amazon EKS 部署您偏好的 HUGS 容器和模型。

要了解您是否已订阅,您可以查看产品页面顶部是否出现蓝色弹窗,上面写着“您有权访问此产品”,这意味着您或您组织中的其他人已经为您的账户申请了访问权限;或者,您可以进入 AWS 控制台中的 AWS Marketplace 服务,搜索“HUGS (HUgging Face Generative AI Services)”是否列在您已订阅的产品中。

在 Amazon EKS 上部署 HUGS

本示例展示了如何在 Amazon EKS 上创建 Kubernetes 集群,如何创建一个具有必要权限和计算需求的 Inferentia2 节点组,以及如何使用 Helm 模板在运行于 Inferentia2 上的 Amazon EKS 上部署 HUGS。

本示例假设您有一个 AWS 账户,已经安装并设置了 AWS CLI,并且已经使用具有必要权限的账户登录,可以订阅 AWS Marketplace 中的产品,以及创建和管理 IAM 权限和资源,如弹性 Kubernetes 服务 (EKS)、弹性容器服务 (ECS) 和 EC2。

要求

在继续之前,您需要安装 `kubectl`、`eksctl` 和 `helm`,以便分别与 Kubernetes 集群交互、在 Amazon EKS 上创建、配置和删除资源,以及与 Helm 模板交互。

要安装 `kubectl` 和 `eksctl`,您可以按照 Amazon EKS 文档 - 设置 kubectl 和 eksctl 中的说明进行操作。而对于 `helm`,您可以按照 Helm 文档 - 安装 Helm 中的说明进行操作。

最后,为了方便起见,将设置以下环境变量:

export REGION="us-east-1"
export NAMESPACE="default"
export CLUSTER_NAME="hugs-cluster"
export CLUSTER_VERSION="1.30"
export NODE_GROUP_NAME="hugs-node-group"
export SERVICE_ACCOUNT_NAME="hugs-service-account"
export DEPLOYMENT_NAME="hugs"
export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
export AMI_ID=$(aws ssm get-parameter --name /aws/service/eks/optimized-ami/$CLUSTER_VERSION/amazon-linux-2-gpu/recommended/image_id --region $REGION --query "Parameter.Value" --output text)

如果您的 AWS 账户有多个配置文件,请记得将 `AWS_PROFILE` 环境变量设置为您的配置文件,以便 EKS 命令使用正确的配置文件。

可选地,在创建集群之前,您可能需要创建启用 AWS LoadBalancer Controller 所需的 IAM 策略,即 `AWSLoadBalancerControllerIAMPolicy`,以便部署需要启用 AWS LoadBalancer Controller 的 ingress,具体请参阅 使用 Helm 安装 AWS Load Balancer Controller - 步骤 1:使用 eksctl 创建 IAM 角色

curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.7.2/docs/install/iam_policy.json
aws iam create-policy \
    --policy-name AWSLoadBalancerControllerIAMPolicy \
    --policy-document file://iam_policy.json

请注意,该策略每个账户只需创建一次,这意味着如果已经创建,您可以重复使用现有的。否则,您也可以使用不同的名称创建该策略,但在本示例中,该策略假定名为 `AWSLoadBalancerControllerIAMPolicy`。

最后,请注意,本指南默认将向您展示如何使用 `inf2.xlarge` 实例的 Nodegroup 创建 EKS 集群,因此请确保您有足够的 EC2 配额来启动 AWS Inferentia2 实例,更多信息请参阅 AWS re:Post - Inferentia 和 Trainium 服务配额

设置 Amazon EKS

要创建 EKS 集群、节点组并添加必要的 IAM 权限,您应该使用提供的配置文件 `eks-cluster.yaml` 运行 `eksctl`,该文件如下所示:

# Specifies the API version and kind of the configuration
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

# Defines the basic cluster metadata
metadata:
  name: $CLUSTER_NAME # Cluster name, used in various AWS resource names
  region: $REGION # AWS region where the cluster will be created
  version: $CLUSTER_VERSION # Kubernetes version to use for the cluster

# IAM configuration for the cluster
iam:
  withOIDC: true # Enables IAM roles for service accounts (IRSA) using OIDC
  serviceAccounts:
    # Configures a service account for marketplace metering
    - metadata:
        name: $SERVICE_ACCOUNT_NAME
        namespace: $NAMESPACE
      attachPolicyARNs:
        - arn:aws:iam::aws:policy/AWSMarketplaceMeteringRegisterUsage
    # Configures a service account for the AWS Load Balancer Controller (just required
    # if ingress is enabled within the HUGS Helm Template)
    - metadata:
        name: aws-load-balancer-controller
        namespace: $NAMESPACE
      attachPolicyARNs:
        - arn:aws:iam::$AWS_ACCOUNT_ID:policy/AWSLoadBalancerControllerIAMPolicy
      roleName: AmazonEKSLoadBalancerControllerRole

# Defines the managed node group for the cluster
managedNodeGroups:
  - name: $NODE_GROUP_NAME
    instanceType: inf2.48xlarge # Inf2-enabled instance type, required by HUGS
    minSize: 1
    maxSize: 2 # Set to a greater number if you want to enable auto-scaling
    desiredCapacity: 1 # Fixed size node group, can be adjusted for scaling
    volumeSize: 500
    ami: $AMI_ID
    amiFamily: AmazonLinux2
    iam:
      attachPolicyARNs:
      - arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy
      - arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly
      - arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore
      - arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess
    overrideBootstrapCommand: |
      #!/bin/bash

      /etc/eks/bootstrap.sh $CLUSTER_NAME

# Specifies the EKS add-ons to be installed (default ones)
# All the addons below will be installed within the `kube-system` namespace
addons:
  - name: vpc-cni # Amazon VPC CNI plugin for Kubernetes
  - name: coredns # CoreDNS for Kubernetes DNS services
  - name: kube-proxy # kube-proxy for Kubernetes network proxy

# Configures CloudWatch logging for the cluster
cloudWatch:
  clusterLogging:
    enableTypes: ["*"] # Enables all types of control plane logging

由于 AWS LoadBalancer Controller 是可选的并且是 Ingress 所需的,如果您决定稍后不部署 Ingress,那么在进入下一步之前,您应该删除 `aws-load-balancer-controller` 的 `iam.serviceAccounts` 部分,即应从上述文件中删除以下内容:

    # Configures a service account for the AWS Load Balancer Controller (just required
    # if ingress is enabled within the HUGS Helm Template)
    - metadata:
        name: aws-load-balancer-controller
        namespace: $NAMESPACE
      attachPolicyARNs:
        - arn:aws:iam::$AWS_ACCOUNT_ID:policy/AWSLoadBalancerControllerIAMPolicy
      roleName: AmazonEKSLoadBalancerControllerRole

然后您需要运行以下命令,该命令会将上面环境变量中设置的值替换到 `huggingface/hugs-helm-chart` 中提供的 `eks-cluster.yaml` 文件中。为了在 `eks-cluster.yaml` 文件中替换环境变量的值,将使用 `envsubst`,Windows 用户可能无法使用此工具。

envsubst < eks-cluster.yaml > cluster.yaml

一旦 `cluster.yaml` 文件更新后,您只需运行以下命令:

eksctl create cluster --config-file cluster.yaml

可选地,如果您想启用或使用 AWS LoadBalancer Controller,您将需要在部署 HUGS 之前单独部署它,以便启用 Ingress;否则,请随意跳到下面的 HUGS 部署部分。

helm repo add eks https://aws.github.io/eks-charts
helm repo update eks
helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
    --namespace $NAMESPACE \
    --set clusterName=$CLUSTER_NAME \
    --set serviceAccount.create=false \
    --set serviceAccount.name=aws-load-balancer-controller

如果您决定在 HUGS 部署中部署 AWS LoadBalancer Controller 并启用 Ingress,那么在部署 HUGS 之前,您需要等到 ALB 控制器运行起来。为此,您可以使用以下 `kubectl` 命令:

kubectl wait --namespace $NAMESPACE \
    --for=condition=ready pod \
    --selector=app.kubernetes.io/name=aws-load-balancer-controller \
    --timeout=90s

使用 Helm 在 Amazon EKS 上部署 HUGS

最后,您可以安装 Helm 模板以从 `huggingface/hugs-helm-chart` 部署 HUGS,如下所示:

helm repo add hugs https://raw.githubusercontent.com/huggingface/hugs-helm-chart/0.0.4/charts/hugs
helm repo update hugs

安装后,要为给定模型(例如 `neuron-meta-llama-meta-llama-3.1-8b-instruct`)部署 HUGS 容器,您需要在订阅并配置后访问 AWS Marketplace 中 HUGS 产品的“Launch this Software”选项卡,在那里您将看到所有可用的 `CONTAINER_URI`。在这种情况下,由于我们想展示如何在 AWS Inferentia2 上部署 LLM,您需要选择任何以 `neuron-...` 开头的容器 URI,因为这些是与 AWS Neuron 设备兼容的,例如 `XXXXXXXXXXXX.dkr.ecr.us-east-1.amazonaws.com/hugging-face/neuron-meta-llama-meta-llama-3.1-8b-instruct`,然后只需导出以下环境变量:

export IMAGE_REGISTRY="XXXXXXXXXXXX.dkr.ecr.us-east-1.amazonaws.com"
export IMAGE_REPOSITORY="hugging-face"
export IMAGE_NAME="neuron-meta-llama-meta-llama-3.1-8b-instruct"

在这种情况下,我们使用了 `neuron-meta-llama-meta-llama-3.1-8b-instruct` 模型,但您可以选择/使用本指南引言中列出的任何可用模型,或者您可以在支持的模型中浏览所有与 AWS Neuron 兼容的模型。

然后,您可以使用以下任一方法安装 Helm 模板:

  • (推荐)通过自定义 `values.yaml` 文件

    您应该首先创建一个符合 `huggingface/hugs-helm-chart` 值的 `values.yaml` 文件,然后更新与 AWS Inferentia2 相关的部分:

    image:
      registry: $IMAGE_REGISTRY # Add your custom HUGS Registry here
      repository: $IMAGE_REPOSITORY # For AWS should always be "hugging-face"
      name: $IMAGE_NAME
      tag: latest
    
    serviceAccountName: $SERVICE_ACCOUNT_NAME
    
    securityContext:
      privileged: true
    
    ingress:
      enabled: true
      className: alb
      annotations:
        alb.ingress.kubernetes.io/scheme: internet-facing
      hosts:
        - host: ""
          paths:
            - path: /
              pathType: Prefix
    
    resources:
      requests:
        aws.amazon.com/neuron: 1
      limits:
        aws.amazon.com/neuron: 1
    
    nodeSelector:
      eks.amazonaws.com/nodegroup: $NODE_GROUP_NAME

    上面创建的 `values.yaml` 文件仅包含与我们的特定配置以及 AWS Inferentia2 和 AWS EKS 限制相关的必要值。然后,我们需要像之前一样使用 `envsubst` 替换上面定义的变量,从教程开始时定义的环境变量中获取值:

    envsubst < values.yaml > values-replaced.yaml

    最后,使用 `helm install` 安装替换后的文件 `values-replaced.yaml`:

    helm install -f values-replaced.yaml $DEPLOYMENT_NAME hugs/hugs

    为了测试替换是否正确并检查 Helm 模板将创建什么,您可以随时调用完全相同的命令,但使用 `helm template` 而不是 `helm install`,并检查将应用于 EKS 集群的生成/生成的 Kubernetes Manifest 文件。

    helm template -f values-replaced.yaml $DEPLOYMENT_NAME hugs/hugs
  • 通过在运行 `helm install` 时使用 `--set` 选项

    helm install $DEPLOYMENT_NAME hugs/hugs \
        --set image.registry=$IMAGE_REGISTRY \
        --set image.repository=$IMAGE_REPOSITORY \
        --set image.name=$IMAGE_NAME \
        --set image.tag="0.2.0" \
        --set resources.requests."aws\.amazon\.com/neuron"=1 \
        --set resources.limits."aws\.amazon\.com/neuron"=1 \
        --set serviceAccountName=$SERVICE_ACCOUNT_NAME \
        --set nodeSelector."eks\.amazonaws\.com/nodegroup"=$NODE_GROUP_NAME

    请注意,对于嵌套值或复杂值,使用 CLI 参数可能会有些棘手,尤其是在字符转义方面。

在 HUGS 上进行推理

要对已部署的 HUGS 服务运行推理,您可以选择以下任一方式:

  • 通过端口转发将端口转发到本地端口,例如 8080(以便您可以通过 `localhost` 向服务发送请求),使用以下命令:

    kubectl port-forward service/$DEPLOYMENT_NAME 8080:80
  • 使用 ingress 的外部 IP 或主机名,仅当 AWS LoadBalancer Controller 已部署到 EKS 集群,并且在 Helm 模板的 `values.yaml` 文件中设置了 `ingress.enabled: true` 并带有正确的 `alb` 配置。这可以通过以下命令获取:

    kubectl get ingress $DEPLOYMENT_NAME -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

然后,您可以从正在运行的 Pod 外部,通过 `localhost`、ingress IP 或 ingress 主机名向 Messages API 发送请求。

在下面的推理示例指南中,主机假定为 `localhost`,这是通过 Kubernetes 使用端口转发部署 HUGS 的情况。如果您已在 Kubernetes 上使用具有特定 IP、主机和/或 SSL (HTTPS) 的 ingress 部署 HUGS,请注意您应将下面的 `localhost` 引用更新为您的主机或 IP。

要在部署 HUGS 后运行推理,您可以从一个简单的 `cURL` 命令开始,向 HUGS 暴露的 OpenAI API 兼容端点发送请求,如下所示:

curl https://:8080/v1/chat/completions \
    -X POST \
    -d '{"model":"tgi","messages":[{"role":"user","content":"What is Deep Learning?"}],"temperature":0.7,"top_p":0.95,"max_tokens":128}}' \
    -H 'Content-Type: application/json'

有关在 HUGS 上运行推理的更多信息和不同替代方案,您应参考指南 在 HUGS 上运行推理

卸载 HUGS

由于 HUGS 是通过 `helm install` 安装的,您可以简单地卸载它:

helm uninstall $DEPLOYMENT_NAME

`helm uninstall` 将删除所有创建的工作负载,在这种情况下是 Deployment、Service、Ingress 和 Horizontal Pod Autoscaler (HPA);另外,如果您也安装了 AWS LoadBalancer Controller,您也可以按如下方式卸载它:

helm uninstall aws-load-balancer-controller

或者,当您使用完 Amazon EKS 集群后,可以安全地删除它以避免产生不必要的费用,如下所示:

eksctl delete cluster --name=$CLUSTER_NAME --region=$REGION
< > 在 GitHub 上更新