你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

将模型从 HuggingFace 中心部署到 Azure 机器学习联机终结点以进行实时推理

项目
09/03/2024

Microsoft 已与 Hugging Face 合作，将 Hugging Face Hub 中的开源模型引入 Azure 机器学习。 Hugging Face 是 Transformers 的创建者，Transformers 是一个广受欢迎的库，用于生成大型语言模型。 Hugging Face 模型中心具有数千个开源模型。通过与 Azure 机器学习集成，可以将所选开源模型部署到 Azure 上安全且可缩放的推理基础结构。你可以在 Azure 机器学习模型目录中搜索数以千计的 Transformers 模型，并通过引导式向导轻松地将模型部署到托管联机终结点。部署后，托管联机终结点会提供安全的 REST API，以便对模型进行实时评分。

注意

Hugging Face 中的模型受 Hugging Face 模型详细信息页上提供的第三方许可条款的约束。你有责任遵守模型的许可条款。

使用联机终结点进行实时推理的好处

Azure 机器学习中的托管联机终结点可帮助你以统包方式将模型部署到 Azure 中功能强大的 CPU 和 GPU 计算机。托管联机终结点负责处理、缩放、保护和监视你的模型，使你没有设置和管理底层基础结构的开销。部署模型时，会代表你预配虚拟机。你可以有多个部署，并将流量拆分或镜像到这些部署。镜像流量可帮助在生产流量上测试新版本的模型，而无需释放它们的生产环境。拆分流量使你可以在观察性能的同时逐渐增加流向新模型版本的生产流量。通过自动缩放，可以根据工作负载动态增加或缩减资源。可以根据利用率指标、特定计划或两者的组合来配置缩放。基于利用率指标进行缩放的一个示例是在 CPU 利用率高于 70% 时添加节点。基于计划的缩放的一个示例是根据高峰营业时间添加节点。

使用 Studio 部署 HuggingFace Hub 模型

若要查找要部署的模型，请在 Azure 机器学习工作室中打开模型目录。选择“所有筛选器”，然后在“按集合筛选”部分中选择“HuggingFace”。选择“模型”磁贴以打开“模型”页。

部署模型

选择“实时部署”选项以打开“快速部署”对话框。指定以下选项：

选择 GPU 或 CPU 的模板。 CPU 实例类型适用于测试，GPU 实例类型可在生产中提供更好的性能。大型模型不适合 CPU 实例类型。
选择实例类型。此实例列表将筛选为模型预期部署的实例，而不会耗尽内存。
选择实例数。一个实例足以进行测试，但我们建议考虑将两个或更多实例用于生产。
（可选）指定终结点和部署名称。
选择“部署”。然后你将导航到终结点页，这可能需要几秒钟时间。根据模型大小和实例类型，部署需要几分钟才能完成。

注意：如果要部署到现有终结点，请从快速部署对话框中选择 More options 并使用完整的部署向导。

测试已部署的模型

部署完成后，可以在终结点页中找到模型的 REST 终结点，该终结点可用于对模型进行评分。可以找到添加更多部署、管理流量和缩放终结点中心的选项。还可以使用终结点页上的“测试”选项卡通过示例输入测试模型。模型页上提供了示例输入。可以在 Hugging Face 中心推理 API 文档中找到输入格式、参数和示例输入。

使用 Python SDK 部署 HuggingFace Hub 模型

设置 Python SDK。

查找要部署的模型

在 Azure 机器学习工作室中浏览模型目录，并找到要部署的模型。复制要部署的模型名称。导入所需的库。目录中显示的模型是从 HuggingFace 注册表中列出的。使用从模型目录和 HuggingFace 注册表中复制的模型名称创建 model_id。使用本示例中的最新版本部署 bert_base_uncased 模型。

from azure.ai.ml import MLClient
from azure.ai.ml.entities import (
    ManagedOnlineEndpoint,
    ManagedOnlineDeployment,
    Model,
    Environment,
    CodeConfiguration,
)
registry_name = "HuggingFace"
model_name = "bert_base_uncased"
model_id = f"azureml://registries/{registry_name}/models/{model_name}/labels/latest"

部署模型

创建联机终结点。接下来，创建部署。最后，将所有流量设置为使用此部署。可以通过从模型目录中的模型页打开“快速部署”对话框，来查找模型的最佳 CPU 或 GPU instance_type。请确保使用具有其配额的 instance_type。

import time
endpoint_name="hf-ep-" + str(int(time.time())) # endpoint name must be unique per Azure region, hence appending timestamp 
ml_client.begin_create_or_update(ManagedOnlineEndpoint(name=endpoint_name) ).wait()
ml_client.online_deployments.begin_create_or_update(ManagedOnlineDeployment(
    name="demo",
    endpoint_name=endpoint_name,
    model=model_id,
    instance_type="Standard_DS2_v2",
    instance_count=1,
)).wait()
endpoint = ml_client.online_endpoints.get(endpoint_name)
endpoint.traffic = {"demo": 100}
ml_client.begin_create_or_update(endpoint).result()

测试已部署的模型

创建包含可提交到联机终结点进行评分的输入的文件。现在已部署 bert-base-uncased 模型，以下是 fill-mask 类型的代码示例输入。可以在 Hugging Face 中心推理 API 文档中找到输入格式、参数和示例输入。

import json
scoring_file = "./sample_score.json"
with open(scoring_file, "w") as outfile:
    outfile.write('{"inputs": ["Paris is the [MASK] of France.", "The goal of life is [MASK]."]}')   
response = workspace_ml_client.online_endpoints.invoke(
    endpoint_name=endpoint_name,
    deployment_name="demo",
    request_file=scoring_file,
)
response_json = json.loads(response)
print(json.dumps(response_json, indent=2))

使用 CLI 部署 HuggingFace Hub 模型

设置 CLI。

查找要部署的模型

在 Azure 机器学习工作室中浏览模型目录，并找到要部署的模型。复制要部署的模型名称。目录中显示的模型是从 HuggingFace 注册表中列出的。使用本示例中的最新版本部署 bert_base_uncased 模型。

部署模型

需要 model 和 instance_type 来部署模型。可以通过从模型目录中的模型页打开“快速部署”对话框，来查找模型的最佳 CPU 或 GPU instance_type。请确保使用具有其配额的 instance_type。

目录中显示的模型是从 HuggingFace 注册表中列出的。使用本示例中的最新版本部署 bert_base_uncased 模型。基于模型名称和注册表的完全限定 model 资产 ID 为 azureml://registries/HuggingFace/models/bert-base-uncased/labels/latest。我们创建用于 az ml online-deployment create 命令内联的 deploy.yml 文件。

创建联机终结点。接下来，创建部署。

# create endpoint
endpoint_name="hf-ep-"$(date +%s)
model_name="bert-base-uncased"
az ml online-endpoint create --name $endpoint_name 

# create deployment file. 
cat <<EOF > ./deploy.yml
name: demo
model: azureml://registries/HuggingFace/models/$model_name/labels/latest
endpoint_name: $endpoint_name
instance_type: Standard_DS3_v2
instance_count: 1
EOF
az ml online-deployment create --file ./deploy.yml --workspace-name $workspace_name --resource-group $resource_group_name

测试已部署的模型

创建包含可提交到联机终结点进行评分的输入的文件。 Hugging Face 作为部署的模型（bert-base-uncased 模型）的 fill-mask 类型的代码示例输入。可以在 Hugging Face 中心推理 API 文档中找到输入格式、参数和示例输入。

scoring_file="./sample_score.json"
cat <<EOF > $scoring_file
{
  "inputs": [
    "Paris is the [MASK] of France.",
    "The goal of life is [MASK]."
  ]
}
EOF
az ml online-endpoint invoke --name $endpoint_name --request-file $scoring_file

Hugging Face 模型示例代码

请单击此链接，查找标记分类、翻译、问答和零样本分类等各种方案的 hugging face 模型示例代码。

故障排除：部署错误和不支持的模型

HuggingFace Hub 有数千个模型，每天更新数百个模型。仅对集合中最常用的模型进行测试，而其他模型可能会失败并出现以下错误之一。

封闭模型

封闭模型要求用户同意共享其联系信息并接受模型所有者的条款和条件才能访问模型。尝试部署此类模型将失败并返回 KeyError。

需要运行远程代码的模型

模型通常使用 Transformers SDK 中的代码，但有些模型运行模型存储库中的代码。此类模型需要将参数 trust_remote_code 设置为 True。请单击此链接，详细了解如何使用远程代码。考虑到安全性，不支持此类模型。尝试部署此类模型将失败并出现以下错误：ValueError: Loading <model> requires you to execute the configuration file in that repo on your local machine. Make sure you have read the code there to avoid malicious use, then set the option trust_remote_code=True to remove this error.

具有错误 tokenizer 的模型

模型包中未正确指定或缺少 tokenizer 可能会导致 OSError: Can't load tokenizer for <model> 错误。

缺少库

某些模型需要其他 python 库。在本地运行模型时，可以安装缺少的库。需要标准 Transformers 库以外的特殊库的模型将失败并出现 ModuleNotFoundError 或 ImportError 错误。

内存不足

如果看到 OutOfQuota: Container terminated due to insufficient memory，请尝试使用具有更多内存的 instance_type。

常见问题

模型权重存储在何处？

Hugging Face 模型通过 HuggingFace 注册表在 Azure 机器学习模型目录中提供。 Hugging Face 创建和管理此注册表，并将其作为社区注册表提供给 Azure 机器学习。模型权重未托管在 Azure 上。部署这些模型时，权重会直接从 Hugging Face Hub 下载到工作区中的联机终结点。 AzureML 中的 HuggingFace 注册表充当目录，可帮助在 Azure 机器学习中发现和部署 HuggingFace Hub 模型。

如何部署模型进行批量推理？ 目前不支持将这些模型部署到批处理终结点进行批量推理。

是否可以使用 HuggingFace 注册表中的模型作为作业的输入，以便使用 Transformers SDK 微调这些模型？ 由于模型权重未存储在 HuggingFace 注册表中，因此无法通过将这些模型用作作业的输入来访问模型权重。

如果我的部署失败或推理未按预期工作，我该如何获得支持？HuggingFace 是一个社区注册表，不在 Microsoft 支持范围内。请查看部署日志，确定问题是与 Azure 机器学习平台相关还是特定于 HuggingFace Transformers。如有任何平台问题，请联系 Microsoft 支持。例如，无法创建联机终结点或对终结点 REST API 的身份验证不起作用。对于特定于 Transformers 的问题，请使用 HuggingFace 论坛或 HuggingFace 支持。

什么是社区注册表？ 社区注册表是由受信任的 Azure 机器学习合作伙伴创建的 Azure 机器学习注册表，可供所有 Azure 机器学习用户使用。

用户可在哪里提交有关 Azure 机器学习中的 Hugging Face 的问题和担忧？ 请在 Azure 机器学习讨论论坛提交问题。

区域可用性

Hugging Face 集合目前仅在公有云的所有区域中可用。

通过

将模型从 HuggingFace 中心部署到 Azure 机器学习联机终结点以进行实时推理

使用联机终结点进行实时推理的好处

使用 Studio 部署 HuggingFace Hub 模型

部署模型

测试已部署的模型

使用 Python SDK 部署 HuggingFace Hub 模型

查找要部署的模型

部署模型

测试已部署的模型

使用 CLI 部署 HuggingFace Hub 模型

查找要部署的模型

部署模型

测试已部署的模型

Hugging Face 模型示例代码

故障排除：部署错误和不支持的模型

封闭模型

需要运行远程代码的模型

具有错误 tokenizer 的模型

缺少库

内存不足

常见问题

区域可用性

反馈

其他资源