推断终结点

推断终结点提供了一个安全的生产解决方案，可以轻松地将任何 transformers、sentence-transformers 和 diffusers 模型部署到由 Hugging Face 管理的专用和自动扩展基础设施上。推断终结点从 Hub 中的模型构建。在本指南中，我们将学习如何使用 huggingface_hub 以编程方式管理推断终结点。有关推断终结点产品本身的更多信息，请查看其官方文档。

本指南假设 huggingface_hub 已正确安装，并且您的机器已登录。如果情况并非如此，请查看快速入门指南。支持推断终结点 API 的最低版本为 v0.19.0。

创建推断终结点

第一步是使用 create_inference_endpoint() 创建推断终结点

>>> from huggingface_hub import create_inference_endpoint

>>> endpoint = create_inference_endpoint(
...     "my-endpoint-name",
...     repository="gpt2",
...     framework="pytorch",
...     task="text-generation",
...     accelerator="cpu",
...     vendor="aws",
...     region="us-east-1",
...     type="protected",
...     instance_size="x2",
...     instance_type="intel-icl"
... )

在这个例子中，我们创建了一个名为"my-endpoint-name"的protected 推断端点，用于为text-generation提供 gpt2 服务。protected 推断端点意味着需要您的令牌才能访问 API。我们还需要提供额外的信息来配置硬件需求，例如供应商、区域、加速器、实例类型和大小。您可以在此处查看可用资源列表。或者，为了方便起见，您也可以使用 Web 界面手动创建推断端点。有关高级设置及其用法的详细信息，请参阅本指南。

由 create_inference_endpoint() 返回的值是一个 InferenceEndpoint 对象。

>>> endpoint
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)

它是一个包含有关端点信息的dataclass。您可以访问重要的属性，例如name、repository、status、task、created_at、updated_at等。如果需要，您也可以使用endpoint.raw访问来自服务器的原始响应。

创建推断端点后，您可以在您的个人仪表板上找到它。

使用自定义镜像

默认情况下，推断端点是使用 Hugging Face 提供的 docker 镜像构建的。但是，可以使用custom_image参数指定任何 docker 镜像。一个常见的用例是使用 text-generation-inference 框架运行 LLMs。这可以通过以下方式完成：

# Start an Inference Endpoint running Zephyr-7b-beta on TGI
>>> from huggingface_hub import create_inference_endpoint
>>> endpoint = create_inference_endpoint(
...     "aws-zephyr-7b-beta-0486",
...     repository="HuggingFaceH4/zephyr-7b-beta",
...     framework="pytorch",
...     task="text-generation",
...     accelerator="gpu",
...     vendor="aws",
...     region="us-east-1",
...     type="protected",
...     instance_size="x1",
...     instance_type="nvidia-a10g",
...     custom_image={
...         "health_route": "/health",
...         "env": {
...             "MAX_BATCH_PREFILL_TOKENS": "2048",
...             "MAX_INPUT_LENGTH": "1024",
...             "MAX_TOTAL_TOKENS": "1512",
...             "MODEL_ID": "/repository"
...         },
...         "url": "ghcr.io/huggingface/text-generation-inference:1.1.0",
...     },
... )

传递给custom_image的值是一个字典，包含指向 docker 容器的 URL 以及运行它的配置。有关它的更多详细信息，请查看 Swagger 文档。

获取或列出已有的推断端点

在某些情况下，您可能需要管理以前创建的推断端点。如果您知道名称，可以使用 get_inference_endpoint()获取它，该函数返回一个 InferenceEndpoint 对象。或者，您可以使用 list_inference_endpoints()来检索所有推断端点的列表。两种方法都接受可选的namespace参数。您可以将namespace设置为您所属的任何组织。否则，它默认为您的用户名。

>>> from huggingface_hub import get_inference_endpoint, list_inference_endpoints

# Get one
>>> get_inference_endpoint("my-endpoint-name")
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)

# List all endpoints from an organization
>>> list_inference_endpoints(namespace="huggingface")
[InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...]

# List all endpoints from all organizations the user belongs to
>>> list_inference_endpoints(namespace="*")
[InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...]

检查部署状态

在本指南的其余部分，我们将假设我们有一个名为endpoint的 InferenceEndpoint 对象。您可能已经注意到，端点有一个类型为 InferenceEndpointStatus 的status属性。当推断端点部署并可访问时，状态应为"running"，并且url属性已设置。

>>> endpoint
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud')

在达到"running"状态之前，推断端点通常会经过"initializing"或"pending"阶段。您可以通过运行 fetch()来获取端点的新状态。与 InferenceEndpoint 中所有其他对服务器发出请求的方法一样，endpoint的内部属性会就地发生变异。

>>> endpoint.fetch()
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)

除了在等待推断端点运行时获取推断端点状态，您还可以直接调用 wait()。此帮助程序将timeout和fetch_every参数（以秒为单位）作为输入，并将阻塞线程，直到推断端点部署。默认值分别为None（无超时）和 5 秒。

# Pending endpoint
>>> endpoint
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)

# Wait 10s => raises a InferenceEndpointTimeoutError
>>> endpoint.wait(timeout=10)
    raise InferenceEndpointTimeoutError("Timeout while waiting for Inference Endpoint to be deployed.")
huggingface_hub._inference_endpoints.InferenceEndpointTimeoutError: Timeout while waiting for Inference Endpoint to be deployed.

# Wait more
>>> endpoint.wait()
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud')

如果设置了timeout，并且推断端点花费了太长时间来加载，则会引发InferenceEndpointTimeoutError超时错误。

运行推断

推断端点启动并运行后，您终于可以在其上运行推断！

InferenceEndpoint 具有两个属性client和async_client，分别返回 InferenceClient 和 AsyncInferenceClient 对象。

# Run text_generation task:
>>> endpoint.client.text_generation("I am")
' not a fan of the idea of a "big-budget" movie. I think it\'s a'

# Or in an asyncio context:
>>> await endpoint.async_client.text_generation("I am")

如果推断端点未运行，则会引发 InferenceEndpointError 异常。

>>> endpoint.client
huggingface_hub._inference_endpoints.InferenceEndpointError: Cannot create a client for this Inference Endpoint as it is not yet deployed. Please wait for the Inference Endpoint to be deployed using `endpoint.wait()` and try again.

有关如何使用 InferenceClient 的更多详细信息，请查看推断指南。

管理生命周期

现在我们已经了解了如何创建推断端点并在其上运行推断，让我们看看如何管理其生命周期。

在本节中，我们将看到诸如 pause()、resume()、scale_to_zero()、update() 和 delete() 的方法。所有这些方法都是为了方便起见添加到 InferenceEndpoint 中的别名。如果您愿意，也可以使用HfApi中定义的通用方法：pause_inference_endpoint()、resume_inference_endpoint()、scale_to_zero_inference_endpoint()、update_inference_endpoint() 和 delete_inference_endpoint()。

暂停或缩放到零

为了在推断端点未使用时降低成本，您可以选择使用 pause()暂停它，或者使用 scale_to_zero()将其缩放到零。

暂停或缩放到零的推断端点不会产生任何费用。这两者之间的区别在于，暂停的端点需要使用 resume()显式恢复。相反，缩放到零的端点如果对其进行了推断调用，将自动启动，并有额外的冷启动延迟。推断端点也可以配置为在一段时间不活动后自动缩放到零。

# Pause and resume endpoint
>>> endpoint.pause()
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='paused', url=None)
>>> endpoint.resume()
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)
>>> endpoint.wait().client.text_generation(...)
...

# Scale to zero
>>> endpoint.scale_to_zero()
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='scaledToZero', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud')
# Endpoint is not 'running' but still has a URL and will restart on first call.

更新模型或硬件要求

在某些情况下，您可能还想更新推理端点，而无需创建新的端点。您可以更新托管的模型或运行模型的硬件要求。可以使用 update() 来执行此操作。

# Change target model
>>> endpoint.update(repository="gpt2-large")
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None)

# Update number of replicas
>>> endpoint.update(min_replica=2, max_replica=6)
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None)

# Update to larger instance
>>> endpoint.update(accelerator="cpu", instance_size="x4", instance_type="intel-icl")
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None)

删除端点

最后，如果您不再使用推理端点，则可以简单地调用 ~InferenceEndpoint.delete()。

这是一个不可逆的操作，它将完全删除端点，包括其配置、日志和使用指标。您无法恢复已删除的推理端点。

端到端示例

推理端点的一个典型用例是同时处理一批作业，以限制基础设施成本。您可以使用本指南中介绍的内容自动执行此过程。

>>> import asyncio
>>> from huggingface_hub import create_inference_endpoint

# Start endpoint + wait until initialized
>>> endpoint = create_inference_endpoint(name="batch-endpoint",...).wait()

# Run inference
>>> client = endpoint.client
>>> results = [client.text_generation(...) for job in jobs]

# Or with asyncio
>>> async_client = endpoint.async_client
>>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs])

# Pause endpoint
>>> endpoint.pause()

或者，如果您的推理端点已存在且已暂停

>>> import asyncio
>>> from huggingface_hub import get_inference_endpoint

# Get endpoint + wait until initialized
>>> endpoint = get_inference_endpoint("batch-endpoint").resume().wait()

# Run inference
>>> async_client = endpoint.async_client
>>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs])

# Pause endpoint
>>> endpoint.pause()

< > 更新在 GitHub 上

Hub Python 库