Hugging Face's logo

Hub Python Library documentation

推理端点

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

推理端点

Inference Endpoints 提供了一种安全的生产级解决方案，可轻松将模型部署在由 Hugging Face 管理的专用且支持自动扩缩容的基础设施上。Inference Endpoint 基于 Hub 上的模型构建。本页是 huggingface_hub 与 Inference Endpoints 集成的参考文档。有关 Inference Endpoints 产品的更多信息，请参阅其官方文档。

查看相关指南，了解如何使用huggingface_hub以编程方式管理您的 Inference Endpoints。

Inference Endpoints 可通过 API 完全进行管理。这些端点使用 Swagger 进行了文档说明。InferenceEndpoint 类是基于该 API 构建的简单封装。

方法

HfApi 中实现了 Inference Endpoint 的部分功能：

InferenceEndpoint

主要数据类是 InferenceEndpoint。它包含已部署的 InferenceEndpoint 的相关信息，包括其配置和当前状态。部署完成后，您可以使用 InferenceEndpoint.client 和 InferenceEndpoint.async_client 属性在 Endpoint 上运行推理，它们分别返回一个 InferenceClient 对象和一个 AsyncInferenceClient 对象。

类 huggingface_hub.InferenceEndpoint

< >

( namespace: strraw: dict_token: str | bool | None_api: HfApi )

参数

  • name (str) — Inference Endpoint 的唯一名称。
  • namespace (str) — Inference Endpoint 所在的命名空间。
  • repository (str) — 部署在此推理端点上的模型仓库名称。
  • status (InferenceEndpointStatus) — 推理端点的当前状态。
  • url (str, 可选) — Inference Endpoint 的 URL（如果可用）。只有已部署的 Inference Endpoint 才会有 URL。
  • framework (str) — 用于该模型的机器学习框架。
  • revision (str) — 部署在推理端点上的特定模型修订版本。
  • task (str) — 与已部署模型关联的任务。
  • created_at (datetime.datetime) — Inference Endpoint 创建时的时间戳。
  • updated_at (datetime.datetime) — Inference Endpoint 上次更新的时间戳。
  • type (InferenceEndpointType) — Inference Endpoint 的类型（public、authenticated、private）。
  • raw (dict) — 从 API 返回的原始字典数据。
  • token (str 或 bool，可选) — Inference Endpoint 的认证令牌，如果在请求 API 时已设置。如果未提供，则默认使用本地保存的令牌。如果不想将令牌发送到服务器，请传入 token=False。

包含已部署推理端点的相关信息。

示例：

>>> from huggingface_hub import get_inference_endpoint
>>> endpoint = get_inference_endpoint("my-text-to-image")
>>> endpoint
InferenceEndpoint(name='my-text-to-image', ...)

# Get status
>>> endpoint.status
'running'
>>> endpoint.url
'https://68a0f3b5c6ee5c9dcc0e0a01.endpoints.huggingface.cloud'

# Run inference
>>> endpoint.client.text_to_image(...)

# Pause endpoint to save $$$
>>> endpoint.pause()

# ...
# Resume and wait for deployment
>>> endpoint.resume()
>>> endpoint.wait()
>>> endpoint.client.text_to_image(...)

from_raw

< >

( raw: dictnamespace: strtoken: str | bool | None = Noneapi: typing.Optional[ForwardRef('HfApi')] = None )

从原始字典初始化对象。

客户端

< >

( ) → InferenceClient

返回值

InferenceClient

一个指向已部署端点的推理客户端。

引发

InferenceEndpointError

返回一个客户端，用于在此推理端点上执行预测。

async_client

< >

( ) → AsyncInferenceClient

返回值

AsyncInferenceClient

一个指向已部署端点的 asyncio 兼容推理客户端。

引发

InferenceEndpointError

返回一个客户端，用于在此推理端点上执行预测。

删除

< >

( )

删除推理端点。

This operation is not reversible. If you don’t want to be charged for an Inference Endpoint, it is preferable to pause it with InferenceEndpoint.pause() or scale it to zero with InferenceEndpoint.scale_to_zero().

这是 HfApi.delete_inference_endpoint() 的别名。

获取

< >

( ) → InferenceEndpoint

返回值

InferenceEndpoint

同一个 Inference Endpoint，使用最新数据就地更新。

获取有关推理端点的最新信息。

暂停

< >

( ) → InferenceEndpoint

返回值

InferenceEndpoint

同一个 Inference Endpoint，使用最新数据就地更新。

暂停推理端点。

已暂停的 Inference Endpoint 不会产生费用。您可以随时使用 InferenceEndpoint.resume() 将其恢复。 这与使用 InferenceEndpoint.scale_to_zero() 将 Inference Endpoint 缩容至零不同，后者会在收到请求时自动重启。

这是 HfApi.pause_inference_endpoint() 的别名。当前对象会被就地修改，以使用来自服务器的最新数据。

恢复

< >

( running_ok: bool = True ) → InferenceEndpoint

参数

  • running_ok (bool, 可选) — 如果为 True，则即使 Inference Endpoint 已在运行，该方法也不会引发错误。默认值为 True。

返回值

InferenceEndpoint

同一个 Inference Endpoint，使用最新数据就地更新。

恢复推理端点。

这是 HfApi.resume_inference_endpoint() 的别名。当前对象会被就地修改，以包含来自服务器的最新数据。

scale_to_zero

< >

( ) → InferenceEndpoint

返回值

InferenceEndpoint

同一个 Inference Endpoint，使用最新数据就地更新。

将推理端点缩放到零。

缩放为零的推理端点不会产生费用。在收到下一个请求时，它将恢复运行，但会产生冷启动延迟。这与使用 InferenceEndpoint.pause() 暂停推理端点不同，后者需要通过 InferenceEndpoint.resume() 手动恢复。

This is an alias for HfApi.scale_to_zero_inference_endpoint(). The current object is mutated in place with the latest data from the server.

更新

< >

( accelerator: str | None = Noneinstance_size: str | None = Noneinstance_type: str | None = Nonemin_replica: int | None = Nonemax_replica: int | None = Nonescale_to_zero_timeout: int | None = Nonerepository: str | None = Noneframework: str | None = Nonerevision: str | None = Nonetask: str | None = Nonecustom_image: dict | None = Nonecontainer_command: list[str] | None = Nonecontainer_args: list[str] | None = Nonetensor_parallel_size: int | None = Nonedata_parallel_size: int | None = Nonesecrets: dict[str, str] | None = None ) → InferenceEndpoint

参数

  • accelerator (str，可选) — 用于推理的硬件加速器（例如 "cpu"）。
  • instance_size (str, 可选) — 用于托管模型的实例大小或类型（例如 "x4"）。
  • instance_type (str, 可选) — Inference Endpoint 将部署到的云实例类型（例如 "intel-icl"）。
  • min_replica (int, 可选) — Inference Endpoint 保持运行的最小副本（实例）数量。
  • max_replica (int, 可选) — Inference Endpoint 可扩容到的最大副本（实例）数量。
  • scale_to_zero_timeout (int, 可选) — 非活动端点缩容至零之前的时长（以分钟为单位）。
  • repository (str, 可选) — 与推理端点关联的模型仓库名称（例如 "gpt2"）。
  • framework (str, 可选) — 用于该模型的机器学习框架（例如 "custom"）。
  • revision (str, 可选) — 要在 Inference Endpoint 上部署的特定模型修订版本（例如 "6c0e6080953db56375760c0471a8c5f2929baf11"）。
  • task (str，可选) — 用于部署模型的任务（例如 "text-classification"）。
  • custom_image (dict, 可选) — 要运行的容器镜像。可以是按镜像变体（例如 {"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}‌}，也可以是 sGLang、tgi、tei、llamacpp、hfServe 等）为键的字典，该字典将原样转发；也可以是一个描述自定义容器的扁平字典（例如 {"url": ..., "port": ...}），该字典将作为 {"custom": ...} 发送。
  • container_command (list[str], 可选) — 覆盖容器的入口点命令（对应 API 负载中的 model.command）。适用于托管引擎镜像（例如 vLLM、SGLang）和自定义镜像。
  • container_args (list[str], 可选) — 附加到容器入口点的参数（对应 API 负载中的 model.args）。适用于托管引擎镜像（例如 vLLM、SGLang）和自定义镜像。
  • tensor_parallel_size (int, 可选) — 用于将单个模型副本分片到多少个加速器上（适用于 vLLM 和 SGLang 镜像）。当未提供 custom_image 时，将获取端点当前配置的镜像并就地更新，因为 API 要求将 model.image 作为整体处理。
  • data_parallel_size (int，可选) — 要运行的模型副本数量，每个加速器一个（vLLM 镜像）。
  • secrets (dict[str, str], 可选) — 要注入到容器环境中的机密值。

返回值

InferenceEndpoint

同一个 Inference Endpoint，使用最新数据就地更新。

更新推理端点。

此方法允许更新计算配置、已部署的模型，或两者同时更新。所有参数均为可选，但必须至少提供一个。

这是 HfApi.update_inference_endpoint() 的别名。当前对象会就地使用来自服务器的最新数据进行更新。

等待

< >

( timeout: int | None = Nonerefresh_every: int = 5 ) → InferenceEndpoint

参数

  • timeout (int, 可选) — 等待 Inference Endpoint 部署完成的最长时间，单位为秒。如果为 None，则会无限期等待。
  • refresh_every (int, 可选) — 每次获取 Inference Endpoint 状态之间的等待时间，以秒为单位。默认为 5 秒。

返回值

InferenceEndpoint

同一个 Inference Endpoint，使用最新数据就地更新。

引发

InferenceEndpointError 或 InferenceEndpointTimeoutError

  • InferenceEndpointError — 如果推理端点最终进入失败状态。
  • InferenceEndpointTimeoutError — 如果在 timeout 秒后 Inference Endpoint 仍未部署完成。

等待推理端点部署完成。

服务器信息将每 1 秒获取一次。如果在 timeout 秒后 Inference Endpoint 仍未部署完成，则会引发 InferenceEndpointTimeoutError。InferenceEndpoint 将就地更新为最新数据。

InferenceEndpointHardware

类 huggingface_hub.InferenceEndpointHardware

< >

( id: strvendor: strregion: straccelerator: strinstance_type: strinstance_size: strarchitecture: strnum_accelerators: intnum_cpus: int | Nonememory_gb: floatgpu_memory_gb: int | Noneprice_per_hour: floatstatus: strmax_accelerators: intused_accelerators: int )

参数

  • id (str) — 唯一的硬件标识符，例如 "aws-us-east-1-nvidia-l4-x1"。
  • vendor (str) — 托管硬件的云服务商，例如 "aws"。
  • region (str) — 硬件可用的云区域，例如 "us-east-1"。
  • accelerator (str) — 硬件加速器的类型，例如 "cpu"、"gpu" 或 "neuron"。
  • instance_type (str) — 云实例类型，例如 "nvidia-l4"。
  • instance_size (str) — 实例大小倍数，例如 "x1"。
  • architecture (str) — 人类可读的硬件描述，例如 "Nvidia L4"。
  • num_accelerators (int) — 每个副本的加速器单元数量。
  • num_cpus (int, 可选) — 每个副本的 vCPU 数量。
  • memory_gb (float) — 每个副本的 RAM，单位为 GB。
  • gpu_memory_gb (int, 可选) — 每个副本的 GPU 总内存，单位为 GB（即对 num_accelerators 求和）。对于非 GPU 硬件，值为 None。
  • price_per_hour (float) — 每个副本每小时的成本，以美元计。
  • status (str) — 硬件的可用状态："available"、"low_availability"、"not_available"、"reserved" 或 "deprecated"。
  • max_accelerators (int) — 该命名空间允许运行的此类型加速器的最大数量。
  • used_accelerators (int) — 当前命名空间正在使用的此类型加速器的数量。

包含可用于推理端点的硬件配置信息。

vendor、region、accelerator、instance_type 和 instance_size 字段正是传递给 create_inference_endpoint()（或 hf endpoints deploy）以在此硬件上部署所需的值。

示例：

>>> from huggingface_hub import list_inference_endpoints_hardware
>>> hardware = list_inference_endpoints_hardware()
>>> hardware[0]
InferenceEndpointHardware(id='aws-us-east-1-nvidia-l4-x1', vendor='aws', region='us-east-1', ...)

from_raw

< >

( raw: dictvendor: strregion: str )

从 API 响应中嵌套在供应商和区域下的原始计算字典初始化对象。

InferenceCatalogModel

类 huggingface_hub.InferenceCatalogModel

< >

( repo_id: strname: strauthor: strlicense: strtask: strcreated_at: datetimerecipes: list )

参数

  • repo_id (str) — Hub 上模型仓库的 id，例如 "meta-llama/Llama-3.1-8B-Instruct"。
  • name (str) — 模型名称，即 repo_id 中作者之后的部分，例如 "Llama-3.1-8B-Instruct"。
  • author (str) — 模型仓库的作者，例如 "meta-llama"。
  • license (str) — 模型的许可证，例如 "Apache 2.0"。
  • task (str) — 模型部署的任务，例如 "text-generation"。
  • created_at (datetime) — 模型添加到目录的日期。
  • recipes (list[InferenceCatalogRecipe]) — 经过测试的部署此模型的方式。

包含推理目录中可用模型的相关信息。

示例：

>>> from huggingface_hub import list_inference_catalog
>>> catalog = list_inference_catalog(engine="vllm")
>>> catalog[0]
InferenceCatalogModel(repo_id='Qwen/Qwen2.5-Coder-7B-Instruct', name='Qwen2.5-Coder-7B-Instruct', ...)

from_raw

< >

( raw: dict )

从原始目录项字典初始化对象。

InferenceCatalogRecipe

类 huggingface_hub.InferenceCatalogRecipe

< >

( id: straccelerator: strengine: strgguf_file: str | Nonerevision: str | None )

参数

  • id (str) — The public recipe id, to pass to create_inference_endpoint_from_catalog() as recipe_id.
  • accelerator (str) — 配方运行的硬件加速器类型，例如 "cpu"、"gpu" 或 "neuron"。
  • engine (str) — 配方所运行的推理引擎，例如 "vllm"、"llamacpp"、"tei" 或 "sglang"。
  • gguf_file (str, 可选) — 由该配方部署的 GGUF 文件。仅针对 "llamacpp" 配方设置。
  • revision (str, 可选) — 如果存在，该配方所固定的模型版本。

包含有关从推理目录部署模型的预测试方法的信息。

配方（recipe）是 Inference Endpoints 团队针对特定模型测试过的硬件与引擎组合。一个模型通常只有一个配方，但也可能有多个（例如一个 GPU 配方和一个 Neuron 配方，或每个 GGUF 量化版本各有一个配方）。

from_raw

< >

( raw: dict )

从 API 响应中嵌套在模型下的原始配方字典初始化对象。

InferenceEndpointStatus

类 huggingface_hub.InferenceEndpointStatus

< >

( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )

一个枚举。

InferenceEndpointType

类 huggingface_hub.InferenceEndpointType

< >

( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )

一个枚举。

InferenceEndpointError

类 huggingface_hub.InferenceEndpointError

< >

( )

处理推理端点时出现的通用异常。

Update on GitHub

←推理客户端 MCP 客户端→