Hugging Face 的 LOGO

文字嵌入推理文件

在 Google Cloud Run 上部署 TEI

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

在 Google Cloud Run 上部署 TEI

在 Google Cloud Platform (GCP) 上部署文字嵌入推理 (TEI) 可以利用底層 Kubernetes 技術，該技術可確保 TEI 根據需求自動擴充套件或縮減。

在 Google Cloud 上，有 3 個主要選項可用於部署 TEI（或任何其他 Docker 容器）

  • Cloud Run
  • Vertex AI 端點
  • GKE（Google Kubernetes Engine）。

本指南將介紹如何在 Cloud Run 上部署 TEI，Cloud Run 是 Google 提供的一項完全託管的服務。Cloud Run 是一種所謂的無伺服器產品。這意味著伺服器基礎設施由 Google 處理，您只需提供一個 Docker 容器。這樣做的好處是，您只在應用程式有需求時才為計算付費。當有需求時，Cloud Run 會自動啟動伺服器；當沒有需求時，它會縮減到零例項。

我們將展示如何部署任何帶或不帶 GPU 的文字嵌入模型。

[!NOTE] 截至撰寫本文時，Cloud Run 上的 GPU 支援在 4 個區域已普遍可用。如果您有興趣使用它，請申請增加配額，用於`每個專案每個區域的總 Nvidia L4 GPU 分配`。目前，NVIDIA L4 GPU（24GiB 視訊記憶體）是 Cloud Run 上唯一可用的 GPU；預設情況下，它支援自動擴充套件到最多 7 個例項（透過配額可以獲得更多），並在沒有請求時縮減到零例項。

設定/配置

本指南假設您已設定 Google Cloud 專案並已啟用結算功能。您可以在 https://console.cloud.google.com/ 完成此操作。

首先，您需要在本地機器上安裝 gcloud CLI。這允許以程式設計方式與您的 Google Cloud 專案互動。

或者，為了簡化本教程中命令的使用，您需要為 GCP 設定以下環境變數

export PROJECT_ID=your-project-id
export LOCATION=europe-west1  # or any location you prefer: https://cloud.google.com/run/docs/locations
export CONTAINER_URI="gcr.io/deeplearning-platform-release/huggingface-text-embeddings-inference-cpu.1-6"
export SERVICE_NAME="text-embedding-server" # choose a name for your service
export MODEL_ID="ibm-granite/granite-embedding-278m-multilingual" # choose any embedding model

一些澄清

  • 我們根據 README 提供最新的官方 Docker 映象 URI。
  • 我們選擇部署 IBM granite 嵌入模型，因為它具有強大的多語言能力。當然，您可以從 Hub 中選擇任何其他嵌入模型。建議查詢標記為 `feature-extraction`、`sentence-similarity` 或 `text-ranking` 的模型。

然後您需要登入您的 Google Cloud 賬戶並設定您要用於部署 Cloud Run 的專案 ID。

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

登入後，您需要啟用 Cloud Run API，這是 Hugging Face DLC for TEI 在 Cloud Run 上部署所必需的。

gcloud services enable run.googleapis.com

在 Cloud Run 上部署 TEI

一切就緒後，您可以呼叫 `gcloud run deploy` 命令來部署 Docker 映象。

該命令需要您指定以下引數

  • --image：要部署的容器映象 URI。
  • --args：傳遞給容器入口點的引數，對於 Hugging Face DLC for TEI，該引數為 `text-embeddings-inference`。更多關於支援的引數，請此處閱讀。
    • --model-id：要使用的模型 ID，在此例中為 ibm-granite/granite-embedding-278m-multilingual。
    • --quantize：要使用的量化方法。如果未指定，它將從 `config.json` 檔案中的 `quantization_config->quant_method` 中檢索。
    • --max-concurrent-requests：此特定部署的最大併發請求數。設定較低的限制將拒絕客戶端請求，而不是讓它們等待太長時間，這通常有利於正確處理反壓。設定為 64，但預設值為 128。
  • --port：容器監聽的埠。
  • --cpu 和 --memory：分配給容器的 CPU 數量和記憶體量。需要分別設定為 4 和 16Gi (16 GiB)；因為這是使用 GPU 的最低要求。
  • --no-cpu-throttling：停用 CPU 節流，這是使用 GPU 所必需的。
  • --gpu 和 --gpu-type：要使用的 GPU 數量和 GPU 型別。必須分別設定為 1 和 `nvidia-l4`；因為在撰寫本教程時，這些是 Cloud Run on GPUs 上唯一可用的選項。
  • --max-instances：要執行的最大例項數，設定為 3，但預設最大值為 7。另外，也可以設定為 1，但這最終可能導致基礎設施遷移期間停機，因此建議設定為 1 以上。
  • --concurrency：每個例項的最大併發請求數，設定為 64。請注意，此值也與 TEI 中的 --max-concurrent-requests 引數一致。
  • --region：部署 Cloud Run 服務的區域。
  • --no-allow-unauthenticated：停用對服務的未經身份驗證的訪問，這是一個很好的做法，因為它添加了由 Google Cloud IAM 管理的身份驗證層。

[!NOTE] 可選地，您可以包含引數 `—vpc-egress=all-traffic` 和 `—subnet=default`，因為有外部流量傳送到公共網際網路，因此為了加快網路速度，您需要透過設定這些標誌將所有流量路由到 VPC 網路。請注意，除了設定這些標誌外，您還需要設定 Google Cloud NAT 才能訪問公共網際網路，這是一項付費產品。請在Cloud Run 文件 - 網路最佳實踐中找到更多資訊。

gcloud compute routers create nat-router --network=default --region=$LOCATION
gcloud compute routers nats create vm-nat --router=nat-router --region=$LOCATION --auto-allocate-nat-external-ips --nat-all-subnet-ip-ranges

最後，您可以執行 `gcloud run deploy` 命令來部署 Cloud Run 上的 TEI，如下所示：

gcloud run deploy $SERVICE_NAME \
    --image=$CONTAINER_URI \
    --args="--model-id=$MODEL_ID,--max-concurrent-requests=64" \
    --set-env-vars=HF_HUB_ENABLE_HF_TRANSFER=1 \
    --port=8080 \
    --cpu=8 \
    --memory=32Gi \
    --region=$LOCATION \
    --no-allow-unauthenticated

如果您想使用 GPU 部署，請執行以下命令

gcloud run deploy $SERVICE_NAME \
    --image=$CONTAINER_URI \
    --args="--model-id=$MODEL_ID,--max-concurrent-requests=64" \
    --set-env-vars=HF_HUB_ENABLE_HF_TRANSFER=1 \
    --port=8080 \
    --cpu=8 \
    --memory=32Gi \
    --no-cpu-throttling \
    --gpu=1 \
    --gpu-type=nvidia-l4 \
    --max-instances=3 \
    --concurrency=64 \
    --region=$LOCATION \
    --no-allow-unauthenticated

或者，如果您建立了 Cloud NAT，則按如下所示進行

gcloud beta run deploy $SERVICE_NAME \
    --image=$CONTAINER_URI \
    --args="--model-id=$MODEL_ID,--max-concurrent-requests=64" \
    --set-env-vars=HF_HUB_ENABLE_HF_TRANSFER=1 \
    --port=8080 \
    --cpu=8 \
    --memory=32Gi \
    --no-cpu-throttling \
    --gpu=1 \
    --gpu-type=nvidia-l4 \
    --max-instances=3 \
    --concurrency=64 \
    --region=$LOCATION \
    --no-allow-unauthenticated \
    --vpc-egress=all-traffic \
    --subnet=default

[!NOTE] 首次在 Cloud Run 上部署新容器大約需要 5 分鐘，因為它需要從 Google Cloud Artifact Registry 匯入，但在後續部署中，由於映象已提前匯入，因此所需時間會更短。

推理

部署後，您可以透過任何受支援的 TEI 端點向服務傳送請求，請檢視 TEI 的 OpenAPI 規範以檢視所有可用的端點及其各自的引數。

所有 Cloud Run 服務預設情況下都是私有部署的，這意味著未經請求頭中提供身份驗證憑據，無法訪問它們。這些服務受 IAM 保護，並且只能由專案所有者、專案編輯者、Cloud Run 管理員和 Cloud Run 呼叫者呼叫。

在這種情況下，將展示幾種啟用開發人員訪問的替代方案；而其他用例超出了本示例的範圍，因為它們要麼由於身份驗證被停用而不安全（對於公共訪問場景），要麼需要額外的設定才能用於生產就緒場景（服務到服務身份驗證、終端使用者訪問）。

[!NOTE] 下面提到的替代方案適用於開發場景，不應直接用於生產就緒場景。以下方法遵循Cloud Run 文件 - 身份驗證開發人員中定義的指南；但您可以在Cloud Run 文件 - 身份驗證概述中找到所有其他指南，如上所述。

透過 Cloud Run 代理

Cloud Run 代理在本地主機上執行一個伺服器，該伺服器將請求代理到指定的 Cloud Run 服務並附加憑據；這對於測試和實驗很有用。

gcloud run services proxy $SERVICE_NAME --region $LOCATION

然後，您可以使用 https://:8080 URL 向 Cloud Run 上部署的服務傳送請求，無需身份驗證，如以下示例所示，由代理公開。您可以在瀏覽器中檢視 API 文件：https://:8080/docs。

cURL

要使用 cURL 向 TEI 服務傳送 POST 請求，您可以執行以下命令

curl https://:8080/embed \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{
        "model": "tei",
        "text": "What is deep learning?"
    }'

或者，也可以向相容 OpenAI 的端點發送請求

curl https://:8080/v1/embeddings \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{
        "model": "tei",
        "text": "What is deep learning?"
    }'

Python

要使用 Python 執行推理，您可以使用 huggingface_hub Python SDK（推薦）或 openai Python SDK。

huggingface_hub

您可以透過 `pip install --upgrade --quiet huggingface_hub` 安裝，然後執行

from huggingface_hub import InferenceClient

client = InferenceClient()
embedding = client.feature_extraction("What is deep learning?",
                                      model="https://:8080/embed")
print(len(embedding[0]))

OpenAI

您可以透過 `pip install --upgrade openai` 安裝，然後執行

from openai import OpenAI

client = OpenAI(base_url="https://:8080/v1/embeddings", api_key="")

response = client.embeddings.create(
  model="tei",
  input="What is deep learning?"
)

print(response)

（推薦）透過 Cloud Run 服務 URL

Cloud Run 服務有一個唯一的 URL，可以用於從任何地方傳送請求，使用具有 Cloud Run 呼叫訪問許可權的 Google Cloud 憑據；這是推薦的方法，因為它比使用 Cloud Run 代理更安全、更一致。

Cloud Run 服務的 URL 可以透過以下命令獲取（為方便起見，分配給 SERVICE_URL 變數）

SERVICE_URL=$(gcloud run services describe $SERVICE_NAME --region $LOCATION --format 'value(status.url)')

然後，您可以使用 `SERVICE_URL` 和任何具有 Cloud Run Invoke 訪問許可權的 Google Cloud 憑據向 Cloud Run 上部署的服務傳送請求。設定憑據有多種方法，其中一些列在下面

使用 Google Cloud SDK 中的預設身份令牌

  • 透過 gcloud 如下所示
gcloud auth print-identity-token
  • 透過 Python 如下所示
import google.auth
from google.auth.transport.requests import Request as GoogleAuthRequest

auth_req = GoogleAuthRequest()
creds, _ = google.auth.default()
creds.refresh(auth_req)

id_token = creds.id_token
  • 使用具有 Cloud Run Invoke 訪問許可權的服務帳戶，可以透過以下任何一種方法完成

在建立 Cloud Run 服務之前建立服務帳戶，然後在建立 Cloud Run 服務時將 service-account 標誌設定為服務帳戶電子郵件。並且僅使用 `gcloud auth print-access-token --impersonate-service-account=SERVICE_ACCOUNT_EMAIL` 為該服務帳戶使用訪問令牌。 在建立 Cloud Run 服務之後建立服務帳戶，然後更新 Cloud Run 服務以使用該服務帳戶。並且僅使用 `gcloud auth print-access-token --impersonate-service-account=SERVICE_ACCOUNT_EMAIL` 為該服務帳戶使用訪問令牌。

推薦的方法是使用服務帳戶 (SA)，因為訪問可以得到更好的控制，並且許可權更精細；由於 Cloud Run 服務不是使用 SA 建立的（這是另一個不錯的選擇），您現在需要建立 SA，授予其必要的許可權，更新 Cloud Run 服務以使用 SA，然後生成訪問令牌以設定為請求中的身份驗證令牌，該令牌可以在使用完畢後撤銷。

  • 為了方便起見，設定 SERVICE_ACCOUNT_NAME 環境變數
export SERVICE_ACCOUNT_NAME=tei-invoker
  • 建立服務帳戶
gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME
  • 授予服務帳戶 Cloud Run 呼叫者角色
gcloud run services add-iam-policy-binding $SERVICE_NAME \
    --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/run.invoker" \
    --region=$LOCATION

為服務帳戶生成訪問令牌

export ACCESS_TOKEN=$(gcloud auth print-access-token --impersonate-service-account=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com)

訪問令牌是短期的，預設情況下會在 1 小時後過期。如果您想將令牌的生命週期延長到預設時間之外，您必須建立組織策略並在建立令牌時使用 --lifetime 引數。請參閱訪問令牌生命週期以瞭解更多資訊。否則，您也可以透過再次執行相同的命令來生成新令牌。

現在，您已經可以深入研究向已部署的 Cloud Run 服務傳送請求的不同替代方案，使用如上所述的 `SERVICE_URL` 和 `ACCESS_TOKEN`。

cURL

要使用 cURL 向 TEI 服務傳送 POST 請求，您可以執行以下命令

curl $SERVICE_URL/v1/embeddigs \
    -X POST \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{
        "model": "tei",
        "text": "What is deep learning?"
    }'

Python

要使用 Python 執行推理，您可以使用 huggingface_hub Python SDK（推薦）或 openai Python SDK。

huggingface_hub

您可以透過 `pip install --upgrade --quiet huggingface_hub` 安裝，然後執行

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    base_url=os.getenv("SERVICE_URL"),
    api_key=os.getenv("ACCESS_TOKEN"),
)

embedding = client.feature_extraction("What is deep learning?",
                                      model="https://:8080/embed")
print(len(embedding[0]))

OpenAI

您可以透過 `pip install --upgrade openai` 安裝，然後執行

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("SERVICE_URL"),
    api_key=os.getenv("ACCESS_TOKEN"),
)

response = client.embeddings.create(
  model="tei",
  input="What is deep learning?"
)

print(response)

資源清理

最後，一旦您在 Cloud Run 服務上使用完 TEI，就可以安全地刪除它，以避免產生不必要的費用，例如，如果 Cloud Run 服務在免費套餐中意外呼叫次數超過您的每月 Cloud Run 呼叫分配。

要刪除 Cloud Run 服務，您可以前往 Google Cloud 控制檯 https://console.cloud.google.com/run 手動刪除；或者透過 gcloud 使用 Google Cloud SDK，如下所示

gcloud run services delete $SERVICE_NAME --region $LOCATION

此外，如果您按照“透過 Cloud Run 服務 URL”中的步驟操作並生成了服務帳戶和訪問令牌，您可以刪除服務帳戶，或者如果它仍然有效，只需撤銷訪問令牌。

  • （推薦）撤銷訪問令牌，如下所示：
gcloud auth revoke --impersonate-service-account=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com
  • （可選）刪除服務帳戶，如下所示：
gcloud iam service-accounts delete $SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

最後，如果您決定透過 Cloud NAT 啟用 VPC 網路，您還可以刪除 Cloud NAT（這是一個付費產品），如下所示

gcloud compute routers nats delete vm-nat --router=nat-router --region=$LOCATION
gcloud compute routers delete nat-router --region=$LOCATION

參考資料

< > 在 GitHub 上更新

←使用示例 CLI 引數→
© . This site is unofficial and not affiliated with Hugging Face, Inc.