在 GKE 上从 GCS 部署 BGE Base v1.5 与 TEI DLC

BGE 代表 BAAI 通用嵌入，是 BAAI 发布的一组嵌入模型的集合，它是一个用于通用嵌入任务的英语基础模型，在 MTEB 排行榜中名列前茅。文本嵌入推理 (TEI) 是 Hugging Face 开发的一个工具包，用于部署和服务开源文本嵌入和序列分类模型；它能够为最流行的模型（包括 FlagEmbedding、Ember、GTE 和 E5）提供高性能提取。此外，Google Kubernetes Engine (GKE) 是 Google Cloud 中一个完全托管的 Kubernetes 服务，可以使用 GCP 的基础设施以大规模部署和运行容器化应用程序。

此示例展示了如何在运行专用容器的 GKE 集群上从 Google Cloud Storage (GCS) 存储桶部署文本嵌入模型，以便在使用 Hugging Face TEI DLC 的安全和托管环境中部署文本嵌入模型。

设置/配置

首先，您需要在本地机器上安装 gcloud 和 kubectl，它们分别是 Google Cloud 和 Kubernetes 的命令行工具，分别用于与 GCP 和 GKE 集群交互。

• 要安装 gcloud，请按照Cloud SDK 文档 - 安装 gcloud CLI中的说明进行操作。
• 要安装 kubectl，请按照Kubernetes 文档 - 安装工具中的说明进行操作。

可选地，为了简化本教程中命令的使用，您需要为 GCP 设置以下环境变量

export PROJECT_ID=your-project-id
export LOCATION=your-location
export CLUSTER_NAME=your-cluster-name
export BUCKET_NAME=hf-models-gke-bucket

然后，您需要登录到您的 GCP 帐户并将项目 ID 设置为您要用于部署 GKE 集群的项目 ID。

gcloud auth login
gcloud auth application-default login  # For local development
gcloud config set project $PROJECT_ID

登录后，您需要在 GCP 中启用必要的服务 API，例如 Google Kubernetes Engine API、Google Container Registry API 和 Google Container File System API，这些 API 对于部署 GKE 集群和 Hugging Face TEI DLC 是必需的。

gcloud services enable container.googleapis.com
gcloud services enable containerregistry.googleapis.com
gcloud services enable containerfilesystem.googleapis.com

此外，要将 kubectl 与 GKE 集群凭据一起使用，您还需要安装 gke-gcloud-auth-plugin，可以使用 gcloud 如下安装

gcloud components install gke-gcloud-auth-plugin

创建 GKE 集群

一切设置完成后，您可以继续创建 GKE 集群和节点池，在本例中，它将是一个单一的 CPU 节点，因为对于大多数工作负载而言，CPU 推理足以服务大多数文本嵌入模型，而它可以从 GPU 服务中获益匪浅。

要部署 GKE 集群，将使用“自动驾驶仪”模式，因为它是大多数工作负载的推荐模式，因为底层基础设施由 Google 管理。或者，您也可以使用“标准”模式。

gcloud container clusters create-auto $CLUSTER_NAME \
    --project=$PROJECT_ID \
    --location=$LOCATION \
    --release-channel=stable \
    --cluster-version=1.28 \
    --no-autoprovisioning-enable-insecure-kubelet-readonly-port

gcloud container get-server-config \
    --flatten="channels" \
    --filter="channels.channel=STABLE" \
    --format="yaml(channels.channel,channels.defaultVersion)" \
    --location=$LOCATION

创建 GKE 集群后，您可以使用以下命令获取通过 kubectl 访问它的凭据

gcloud container clusters get-credentials $CLUSTER_NAME --location=$LOCATION

可选：将模型从 Hugging Face Hub 上传到 GCS

本教程中的这一步是可选的，因为您可能希望在 GCS 存储桶中重用现有的模型，如果确实如此，请随时跳到教程的下一步，了解如何配置 GCS 的 IAM，以便您可以从 GKE 集群中的 Pod 访问存储桶。

否则，要将模型从 Hugging Face Hub 上传到 GCS 存储桶，您可以使用脚本 scripts/upload_model_to_gcs.sh，该脚本将从 Hugging Face Hub 下载模型并将其上传到 GCS 存储桶（如果存储桶不存在则创建）。

应通过 gcloud 安装 gsutil 组件，并且还应安装 Python 包 huggingface_hub（带有额外功能 hf_transfer）和包 crcmod。

gcloud components install gsutil
pip install --upgrade --quiet "huggingface_hub[hf_transfer]" crcmod

然后，您可以运行脚本从 Hugging Face Hub 下载模型，然后将其上传到 GCS 存储桶。

./scripts/upload_model_to_gcs.sh --model-id BAAI/bge-base-en-v1.5 --gcs gs://$BUCKET_NAME/bge-base-en-v1.5

配置 GCS 的 IAM

在继续在 GKE 集群上部署用于 TEI 的 Hugging Face DLC 之前，您需要为 GCS 存储桶设置 IAM 权限，以便 GKE 集群中的 Pod 可以访问存储桶。为此，您需要在 GKE 集群中创建一个命名空间和一个服务帐户，然后为包含模型的 GCS 存储桶设置 IAM 权限，这些模型可以是从 Hugging Face Hub 上传的，也可以是 GCS 存储桶中已存在的模型。

为方便起见，由于将在后续步骤中使用命名空间和服务帐户的引用，因此将设置环境变量 NAMESPACE 和 SERVICE_ACCOUNT。

export NAMESPACE=hf-gke-namespace
export SERVICE_ACCOUNT=hf-gke-service-account

然后，您可以在 GKE 集群中创建命名空间和服务帐户，从而启用为该命名空间中的 Pod 创建 IAM 权限，以便在使用该服务帐户时访问 GCS 存储桶。

kubectl create namespace $NAMESPACE
kubectl create serviceaccount $SERVICE_ACCOUNT --namespace $NAMESPACE

然后，您需要按如下方式将 IAM 策略绑定添加到存储桶

gcloud storage buckets add-iam-policy-binding \
    gs://$BUCKET_NAME \
    --member "principal://iam.googleapis.com/projects/$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")/locations/global/workloadIdentityPools/$PROJECT_ID.svc.id.goog/subject/ns/$NAMESPACE/sa/$SERVICE_ACCOUNT" \
    --role "roles/storage.objectUser"

部署 TEI

现在，您可以继续进行用于 TEI 的 Hugging Face DLC 的 Kubernetes 部署，从安装在 /data 中的卷提供 BAAI/bge-base-en-v1.5 模型，该卷从模型所在的 GCS 存储桶复制而来。

用于 TEI 的 Hugging Face DLC 将通过 kubectl 部署，来自 cpu-config/ 或 gpu-config/ 目录中的配置文件，具体取决于您是否分别要使用 CPU 或 GPU 加速器。

• deployment.yaml：包含 Pod 的部署详细信息，包括对用于 TEI 的 Hugging Face DLC 的引用，将 MODEL_ID 设置为卷装载中的模型路径，在本例中为 /data/bge-base-en-v1.5。
• service.yaml：包含 Pod 的服务详细信息，为 TEI 服务公开端口 8080。
• storageclass.yaml：包含 Pod 的存储类详细信息，定义卷装载的存储类。
• （可选）ingress.yaml：包含 Pod 的入口详细信息，将服务公开到外部世界，以便可以通过入口 IP 访问它。

kubectl apply -f cpu-config/

kubectl get pods --namespace $NAMESPACE

kubectl wait --for=condition=Available --timeout=700s --namespace $NAMESPACE deployment/tei-deployment

使用 TEI 进行推理

要对已部署的 TEI 服务运行推理，您可以

• 将已部署的 TEI 服务端口转发到端口 8080，以便通过 localhost 访问，使用以下命令

  已复制

  kubectl port-forward --namespace $NAMESPACE service/tei-service 8080:8080

• 通过入口的外部 IP 访问 TEI 服务，这是这里的默认方案，因为您已在 cpu-configs/ingress.yaml 或 gpu-config/ingress.yaml 文件中定义了入口配置（但可以跳过以支持端口转发），可以使用以下命令检索该 IP

  已复制

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

通过 cURL

要使用 cURL 向 TEI 服务发送 POST 请求，您可以运行以下命令

curl http://localhost:8080/embed \
    -X POST \
    -d '{"inputs":"What is Deep Learning?"}' \
    -H 'Content-Type: application/json'

或向入口 IP 发送 POST 请求

curl http://$(kubectl get ingress --namespace=$NAMESPACE tei-ingress -o jsonpath='{.status.loadBalancer.ingress[0].ip}')/embed \
    -X POST \
    -d '{"inputs":"What is Deep Learning?"}' \
    -H 'Content-Type: application/json'

这将产生以下输出（为简洁起见已截断，但原始张量长度为 768，这是 BAAI/bge-base-en-v1.5（即您正在服务的模型）的嵌入维度）。

[[-0.01483098,0.010846359,-0.024679236,0.012507628,0.034231555,...]]

删除 GKE 集群

最后，完成在 GKE 集群上使用 TEI 后，您可以安全地删除 GKE 集群以避免产生不必要的费用。

gcloud container clusters delete $CLUSTER_NAME --location=$LOCATION

或者，如果您想保留集群，也可以将已部署 Pod 的副本缩减为 0，因为使用 GKE 自动驾驶仪模式部署的默认 GKE 集群仅运行一个 e2-small 实例。

kubectl scale --replicas=0 --namespace=$NAMESPACE deployment/tei-deployment