Hub Python Library documentation

Endpoints de Inferência

Hub Python Library

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v2.4.0).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Endpoints de Inferência

Inference Endpoints oferece uma solução de produção segura para implantar modelos com facilidade em uma infraestrutura dedicada e com escala automática gerenciada pela Hugging Face. Um Inference Endpoint é construído a partir de um modelo do Hub. Esta página é uma referência para a integração do huggingface_hub com o Inference Endpoints. Para mais informações sobre o produto Inference Endpoints, consulte sua documentação oficial.

Confira o guia relacionado para aprender a usar o huggingface_hub para gerenciar seus Inference Endpoints programaticamente.

Os Inference Endpoints podem ser totalmente gerenciados via API. Os endpoints são documentados com Swagger. A classe InferenceEndpoint é um wrapper simples construído sobre essa API.

Métodos

Um subconjunto dos recursos do Inference Endpoint é implementado em HfApi:

get_inference_endpoint() e list_inference_endpoints() para obter informações sobre seus Inference Endpoints
list_inference_endpoints_hardware() para listar o hardware em que você pode implantar um Inference Endpoint
create_inference_endpoint(), update_inference_endpoint() e delete_inference_endpoint() para implantar e gerenciar Inference Endpoints
list_inference_catalog() e create_inference_endpoint_from_catalog() para navegar e implantar o Model Catalog curado
pause_inference_endpoint() e resume_inference_endpoint() para pausar e retomar um Inference Endpoint
scale_to_zero_inference_endpoint() para escalar manualmente um Endpoint para 0 réplicas

InferenceEndpoint

A dataclass principal é InferenceEndpoint. Ela contém informações sobre um InferenceEndpoint implantado, incluindo sua configuração e estado atual. Uma vez implantado, você pode executar inferência no Endpoint usando as propriedades InferenceEndpoint.client e InferenceEndpoint.async_client, que retornam, respectivamente, um objeto InferenceClient e um objeto AsyncInferenceClient.

classe huggingface_hub.InferenceEndpoint

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

Parâmetros

name (str) — O nome exclusivo do Inference Endpoint.
namespace (str) — O namespace onde o Inference Endpoint está localizado.
repository (str) — O nome do repositório do modelo implantado neste Inference Endpoint.
status (InferenceEndpointStatus) — O status atual do Inference Endpoint.
url (str, opcional) — A URL do Inference Endpoint, se disponível. Apenas um Inference Endpoint implantado terá uma URL.
framework (str) — O framework de machine learning usado para o modelo.
revision (str) — A revisão específica do modelo implantada no Inference Endpoint.
task (str) — A tarefa associada ao modelo implantado.
created_at (datetime.datetime) — O timestamp de quando o Inference Endpoint foi criado.
updated_at (datetime.datetime) — O timestamp da última atualização do Inference Endpoint.
type (InferenceEndpointType) — O tipo do Inference Endpoint (público, autenticado, privado).
raw (dict) — Os dados de dicionário brutos retornados pela API.
token (str ou bool, opcional) — Token de autenticação para o Inference Endpoint, se definido ao solicitar a API. Se não for fornecido, será usado o token salvo localmente. Passe token=False se você não quiser enviar seu token para o servidor.

Contém informações sobre um Inference Endpoint implantado.

Exemplo:

>>> 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 )

Inicializa o objeto a partir de um dicionário bruto.

client

( ) → InferenceClient

Retorna

InferenceClient

um cliente de inferência apontando para o endpoint implantado.

Exceções

InferenceEndpointError

InferenceEndpointError — Se o Inference Endpoint ainda não estiver implantado.

Retorna um cliente para fazer previsões neste Inference Endpoint.

async_client

( ) → AsyncInferenceClient

Retorna

AsyncInferenceClient

um cliente de inferência compatível com asyncio apontando para o endpoint implantado.

Exceções

InferenceEndpointError

InferenceEndpointError — Se o Inference Endpoint ainda não estiver implantado.

Retorna um cliente para fazer previsões neste Inference Endpoint.

excluir

( )

Exclua o Inference Endpoint.

Esta operação não é reversível. Se você não deseja ser cobrado por um Inference Endpoint, é preferível pausá-lo com InferenceEndpoint.pause() ou reduzi-lo a zero com InferenceEndpoint.scale_to_zero().

Este é um alias para HfApi.delete_inference_endpoint().

fetch

( ) → InferenceEndpoint

Retorna

InferenceEndpoint

o mesmo Inference Endpoint, mutado no local com os dados mais recentes.

Obtenha as informações mais recentes sobre o Inference Endpoint.

pausar

( ) → InferenceEndpoint

Retorna

InferenceEndpoint

o mesmo Inference Endpoint, mutado no local com os dados mais recentes.

Pare o Inference Endpoint.

Um Inference Endpoint pausado não será cobrado. Ele pode ser retomado a qualquer momento usando InferenceEndpoint.resume(). Isso é diferente de escalar o Inference Endpoint para zero com InferenceEndpoint.scale_to_zero(), o que seria reiniciado automaticamente quando uma solicitação fosse feita a ele.

Este é um alias para HfApi.pause_inference_endpoint(). O objeto atual é mutado no local com os dados mais recentes do servidor.

retomar

( running_ok: bool = True ) → InferenceEndpoint

Parâmetros

running_ok (bool, opcional) — Se True, o método não lançará um erro se o Inference Endpoint já estiver em execução. O valor padrão é True.

Retorna

InferenceEndpoint

o mesmo Inference Endpoint, mutado no local com os dados mais recentes.

Resuma o Inference Endpoint.

Este é um alias para HfApi.resume_inference_endpoint(). O objeto atual é mutado no local com os dados mais recentes do servidor.

scale_to_zero

( ) → InferenceEndpoint

Retorna

InferenceEndpoint

o mesmo Inference Endpoint, mutado no local com os dados mais recentes.

Escale o Endpoint de Inferência para zero.

Um Inference Endpoint escalado para zero não será cobrado. Ele será retomado na próxima solicitação a ele, com um atraso de inicialização a frio. Isso é diferente de pausar o Inference Endpoint com InferenceEndpoint.pause(), o que exigiria uma retomada manual com InferenceEndpoint.resume().

Este é um alias para HfApi.scale_to_zero_inference_endpoint(). O objeto atual é mutado no local com os dados mais recentes do servidor.

atualizar

( 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

Parâmetros

accelerator (str, opcional) — O acelerador de hardware a ser usado para inferência (por exemplo, "cpu").
instance_size (str, opcional) — O tamanho ou o tipo da instância a ser usada para hospedar o modelo (por exemplo, "x4").
instance_type (str, opcional) — O tipo de instância de nuvem onde o Inference Endpoint será implantado (por exemplo, "intel-icl").
min_replica (int, opcional) — O número mínimo de réplicas (instâncias) a manter em execução para o Inference Endpoint.
max_replica (int, opcional) — O número máximo de réplicas (instâncias) para as quais o Inference Endpoint deve ser dimensionado.
scale_to_zero_timeout (int, opcional) — A duração, em minutos, antes de um endpoint inativo ser reduzido a zero.
repository (str, opcional) — O nome do repositório de modelos associado ao Inference Endpoint (por exemplo, "gpt2").
framework (str, opcional) — O framework de machine learning usado para o modelo (por exemplo, "custom").
revision (str, opcional) — A revisão específica do modelo a ser implantada no Inference Endpoint (por exemplo, "6c0e6080953db56375760c0471a8c5f2929baf11").
task (str, opcional) — A tarefa na qual o modelo será implantado (por exemplo, "text-classification").
custom_image (dict, opcional) — A imagem de container a ser executada. Pode ser um dicionário com chaves por variante de imagem (por exemplo, {"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}‌}, também sGLang, tgi, tei, llamacpp, hfServe, …), que é encaminhado como está, ou um dicionário plano descrevendo um container personalizado (por exemplo, {"url": ..., "port": ...}), que é enviado como {"custom": ...}.
container_command (list[str], opcional) — Substitui o comando de entrada do container (corresponde a model.command no payload da API). Funciona com imagens de engine gerenciadas (por exemplo, vLLM, SGLang) e imagens personalizadas.
container_args (list[str], opcional) — Argumentos adicionados ao entrypoint do container (corresponde a model.args no payload da API). Funciona com imagens de engine gerenciadas (por exemplo, vLLM, SGLang) e imagens personalizadas.
tensor_parallel_size (int, opcional) — Número de aceleradores para dividir uma única cópia do modelo (imagens vLLM e SGLang). Quando custom_image não é fornecido, a imagem atualmente configurada no endpoint é obtida e atualizada no local, pois a API requer model.image como um todo.
data_parallel_size (int, opcional) — Número de cópias do modelo a serem executadas, uma por acelerador (imagens do vLLM).
secrets (dict[str, str], opcional) — Valores de segredo a serem injetados no ambiente do contêiner.

Retorna

InferenceEndpoint

o mesmo Inference Endpoint, mutado no local com os dados mais recentes.

Atualize o Inference Endpoint.

Este método permite a atualização da configuração de computação, do modelo implantado ou de ambos. Todos os argumentos são opcionais, mas pelo menos um deve ser fornecido.

Este é um alias para HfApi.update_inference_endpoint(). O objeto atual é mutado no local com os dados mais recentes do servidor.

wait

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

Parâmetros

timeout (int, opcional) — O tempo máximo a ser aguardado para que o Inference Endpoint seja implantado, em segundos. Se None, aguardará indefinidamente.
refresh_every (int, opcional) — O tempo de espera entre cada consulta do status do Inference Endpoint, em segundos. O padrão é 5s.

Retorna

InferenceEndpoint

o mesmo Inference Endpoint, mutado no local com os dados mais recentes.

Exceções

InferenceEndpointError ou InferenceEndpointTimeoutError

InferenceEndpointError — Se o Inference Endpoint terminou em um estado de falha.
InferenceEndpointTimeoutError — Se o Inference Endpoint não for implantado após timeout segundos.

Aguarde a implantação do Inference Endpoint.

As informações do servidor serão obtidas a cada 1s. Se o Inference Endpoint não for implantado após timeout segundos, um InferenceEndpointTimeoutError será lançado. O InferenceEndpoint será modificado no local com os dados mais recentes.

InferenceEndpointHardware

classe 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 )

Parâmetros

id (str) — Identificador único de hardware, por exemplo, "aws-us-east-1-nvidia-l4-x1".
vendor (str) — O provedor de nuvem que hospeda o hardware, por exemplo, "aws".
region (str) — A região da nuvem em que o hardware está disponível, por exemplo, "us-east-1".
accelerator (str) — O tipo de acelerador de hardware, por exemplo, "cpu", "gpu" ou "neuron".
instance_type (str) — O tipo de instância na nuvem, por exemplo, "nvidia-l4".
instance_size (str) — O multiplicador do tamanho da instância, por exemplo, "x1".
architecture (str) — Descrição de hardware legível por humanos, por exemplo, "Nvidia L4".
num_accelerators (int) — Número de unidades de acelerador por réplica.
num_cpus (int, opcional) — Número de vCPUs por réplica.
memory_gb (float) — RAM por réplica, em GB.
gpu_memory_gb (int, opcional) — Memória total da GPU por réplica, em GB (ou seja, somada sobre num_accelerators). None para hardware não-GPU.
price_per_hour (float) — Custo por réplica por hora, em USD.
status (str) — Disponibilidade do hardware: "available", "low_availability", "not_available", "reserved" ou "deprecated".
max_accelerators (int) — Número máximo de aceleradores deste tipo que o namespace está autorizado a executar.
used_accelerators (int) — Número de aceleradores deste tipo atualmente usados pelo namespace.

Contém informações sobre uma configuração de hardware disponível para Inference Endpoints.

Os campos vendor, region, accelerator, instance_type e instance_size são exatamente os valores a serem passados para create_inference_endpoint() (ou hf endpoints deploy) para implantar neste hardware.

Exemplo:

>>> 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 )

Inicializa um objeto a partir de um dicionário de computação bruto, aninhado sob um fornecedor e uma região na resposta da API.

InferenceCatalogModel

classe huggingface_hub.InferenceCatalogModel

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

Parâmetros

repo_id (str) — O id do repositório do modelo no Hub, por exemplo, "meta-llama/Llama-3.1-8B-Instruct".
name (str) — O nome do modelo, ou seja, a parte de repo_id após o autor, por exemplo, "Llama-3.1-8B-Instruct".
author (str) — O autor do repositório do modelo, por exemplo, "meta-llama".
license (str) — A licença do modelo, por exemplo, "Apache 2.0".
task (str) — A tarefa na qual o modelo é implantado, por exemplo, "text-generation".
created_at (datetime) — A data em que o modelo foi adicionado ao catálogo.
recipes (list[InferenceCatalogRecipe]) — As formas testadas de implantar este modelo.

Contém informações sobre um modelo disponível no Inference Catalog.

Exemplo:

>>> 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 )

Inicializa um objeto a partir de um dicionário de item de catálogo bruto.

InferenceCatalogRecipe

classe huggingface_hub.InferenceCatalogRecipe

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

Parâmetros

id (str) — O id da receita pública, para passar a create_inference_endpoint_from_catalog() como recipe_id.
accelerator (str) — O tipo de acelerador de hardware no qual a receita é executada, por exemplo, "cpu", "gpu" ou "neuron".
engine (str) — O motor de inferência em que a receita é executada, por exemplo, "vllm", "llamacpp", "tei" ou "sglang".
gguf_file (str, opcional) — O arquivo GGUF implantado pela receita. Definido apenas para receitas "llamacpp".
revision (str, opcional) — A revisão do modelo à qual a receita está fixada, se houver.

Contém informações sobre uma maneira pré-testada de implantar um modelo do Inference Catalog.

Uma receita é uma combinação de hardware e motor que a equipe de Inference Endpoints testou para um determinado modelo. Um modelo geralmente possui uma receita, mas pode ter várias (por exemplo, uma para GPU e outra para Neuron, ou uma para cada quantização GGUF).

from_raw

( raw: dict )

Inicialize o objeto a partir de um dicionário de receita bruto, aninhado sob um modelo na resposta da API.

InferenceEndpointStatus

classe huggingface_hub.InferenceEndpointStatus

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

Uma enumeração.

InferenceEndpointType

classe huggingface_hub.InferenceEndpointType

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

Uma enumeração.

InferenceEndpointError

classe huggingface_hub.InferenceEndpointError

( )

Exceção genérica ao lidar com Inference Endpoints.

Update on GitHub

←Inference Client Cliente MCP→