Hub Python Library documentation
Endpoints de Inferência
Endpoints de Inferência
O Inference Endpoints oferece uma solução de produção segura para implantar facilmente qualquer modelo de transformers, sentence-transformers e diffusers em uma infraestrutura dedicada e com autoscaling gerenciada pela Hugging Face. Um Inference Endpoint é construído a partir de um modelo do Hub.
Neste guia, aprenderemos a gerenciar Inference Endpoints programaticamente com huggingface_hub. Para mais informações sobre o próprio produto Inference Endpoints, consulte sua documentação oficial.
Este guia pressupõe que huggingface_hub esteja corretamente instalado e que sua máquina esteja conectada. Consulte o guia de Início Rápido caso ainda não seja o caso. A versão mínima que suporta a API de Inference Endpoints é v0.19.0.
Novo: agora é possível implantar um Inference Endpoint a partir do catálogo de modelos do HF com uma simples chamada de API. O catálogo é uma lista cuidadosamente curada de modelos que podem ser implantados com configurações otimizadas. Você não precisa configurar nada, nós cuidamos de toda a parte complexa! Todos os modelos e configurações são garantidos como testados para oferecer o melhor equilíbrio entre custo e desempenho. create_inference_endpoint_from_catalog() funciona da mesma forma que create_inference_endpoint(), com muito menos parâmetros para passar. Você pode usar list_inference_catalog() para recuperar o catálogo programaticamente.
Observe que esta ainda é uma funcionalidade experimental. Diga-nos o que você acha se a utilizar!
Cada modelo do catálogo é implantado por meio de uma receita: uma combinação de hardware e motor que foi testada para ele. list_inference_catalog() retorna os modelos com suas receitas e aceita filtros no servidor (accelerator, engine, license, task, search, limit):
>>> from huggingface_hub import list_inference_catalog
>>> catalog = list_inference_catalog(task="text-generation", accelerator="neuron")
>>> catalog[0]
InferenceCatalogModel(repo_id='meta-llama/Llama-3.1-8B-Instruct', name='Llama-3.1-8B-Instruct', ...)
>>> catalog[0].recipes
[InferenceCatalogRecipe(id='sizzling-biryani-g4xsi1ac', accelerator='gpu', engine='vllm', gguf_file=None, revision=None),
InferenceCatalogRecipe(id='artisanal-quinoa-yz9ynamx', accelerator='neuron', engine='vllmNeuron', gguf_file=None, revision=None)]Passe um repo_id para create_inference_endpoint_from_catalog() para implantar a receita padrão de um modelo, opcionalmente restrita com accelerator ("cpu", "gpu" ou "neuron") e gguf_file, ou passe um recipe_id para implantar uma receita exata:
>>> from huggingface_hub import create_inference_endpoint_from_catalog
>>> endpoint = create_inference_endpoint_from_catalog(repo_id="openai/gpt-oss-120b")
>>> endpoint = create_inference_endpoint_from_catalog(recipe_id="artisanal-quinoa-yz9ynamx")Encontre hardware para implantar
Os valores de accelerator, vendor, region, instance_type e instance_size aceitos por create_inference_endpoint() dependem uns dos outros. Use list_inference_endpoints_hardware() para listar as combinações válidas, juntamente com o preço por hora e a cota de acelerador do seu namespace:
>>> from huggingface_hub import list_inference_endpoints_hardware
>>> for hw in list_inference_endpoints_hardware():
... if hw.accelerator == "gpu" and hw.status == "available":
... print(hw.vendor, hw.region, hw.instance_type, hw.instance_size, hw.price_per_hour)
aws us-east-1 nvidia-l4 x1 0.8
aws us-east-1 nvidia-l4 x4 3.8
...A cota é por namespace, então passe o namespace em que você vai fazer o deploy (o padrão é a sua própria conta):
>>> list_inference_endpoints_hardware(namespace="my-org")Ou via CLI:
hf endpoints hardware --accelerator gpu
Criar um Endpoint de Inferência
O primeiro passo é criar um Inference Endpoint usando 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="authenticated",
... instance_size="x2",
... instance_type="intel-icl"
... )Ou via CLI:
hf endpoints deploy my-endpoint-name --repo gpt2 --framework pytorch --accelerator cpu --vendor aws --region us-east-1 --instance-size x2 --instance-type intel-icl --task text-generation
# Deploy from the catalog with a single command
hf endpoints catalog deploy --repo openai/gpt-oss-120b
# Deploy from the catalog with a specific accelerator
hf endpoints catalog deploy --repo openai/gpt-oss-120b --accelerator gpu
# Deploy an exact catalog recipe, as listed by 'hf endpoints catalog ls'
hf endpoints catalog deploy --recipe artisanal-quinoa-yz9ynamxNeste exemplo, criamos um Inference Endpoint authenticated chamado "my-endpoint-name", para servir gpt2 para text-generation. Um Inference Endpoint authenticated significa que seu token é necessário para acessar a API. Também precisamos fornecer informações adicionais para configurar os requisitos de hardware, como fornecedor, região, acelerador, tipo de instância e tamanho. Você pode verificar a lista de recursos disponíveis aqui. Alternativamente, você pode criar um Inference Endpoint manualmente usando a interface Web para maior conveniência. Consulte este guia para detalhes sobre configurações avançadas e seu uso.
O valor retornado por create_inference_endpoint() é um objeto InferenceEndpoint:
>>> endpoint
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)Ou via CLI:
hf endpoints describe my-endpoint-name
É uma dataclass que armazena informações sobre o endpoint. Você pode acessar atributos importantes como name, repository, status, task, created_at, updated_at, etc. Se necessário, você também pode acessar a resposta bruta do servidor com endpoint.raw.
Depois que o seu Inference Endpoint for criado, você pode encontrá-lo no seu painel pessoal.
Usando uma imagem personalizada
Por padrão, o Inference Endpoint é construído a partir de uma imagem docker fornecida pela Hugging Face. No entanto, é possível especificar qualquer imagem docker usando o parâmetro custom_image. Um caso de uso comum é executar LLMs usando o framework text-generation-inference. Isso pode ser feito da seguinte forma:
# 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="authenticated",
... instance_size="x1",
... instance_type="nvidia-a10g",
... custom_image={
... "healthRoute": "/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",
... },
... )O valor a ser passado como custom_image é um dicionário contendo uma URL para o container docker e a configuração para executá-lo. Para mais detalhes sobre isso, consulte a documentação do Swagger.
Para uma imagem hospedada em um registro de contêiner privado, passe container_registry_username e, quando exigido pelo registro, container_registry_password. As credenciais são suportadas apenas para um contêiner customizado simples:
>>> endpoint = create_inference_endpoint(
... # Other endpoint and hardware arguments omitted for brevity.
... custom_image={"url": "private.registry.example/my-image:latest", "port": 8080},
... container_registry_username="user",
... container_registry_password="password",
... )As opções equivalentes de CLI são --container-registry-username e --container-registry-password:
hf endpoints deploy my-endpoint ... --custom-image private.registry.example/my-image:latest \ --container-registry-username user --container-registry-password password
custom_image também aceita os tipos de contêiner específicos de cada engine suportados pela API, usando o nome da engine como chave no dicionário (vLLM, vLLMNeuron, sGLang, tgi, tgiNeuron, tei, llamacpp, hfServe, …) em vez de mantê-lo plano. Cada engine aceita os campos de contêiner usuais (url, port, healthRoute) além de suas próprias opções de ajuste. Qualquer dicionário sem um url no nível superior é encaminhado à API sem alterações, de modo que engines adicionados à API posteriormente funcionam sem a necessidade de atualizar o huggingface_hub:
# Start an Inference Endpoint running the vLLM engine image
>>> endpoint = create_inference_endpoint(
... "llama-3-1-8b-instruct-vllm",
... repository="meta-llama/Llama-3.1-8B-Instruct",
... framework="pytorch",
... task="text-generation",
... accelerator="gpu",
... vendor="aws",
... region="us-east-1",
... instance_size="x1",
... instance_type="nvidia-l4",
... custom_image={
... "vLLM": {
... "url": "vllm/vllm-openai:v0.23.0",
... "healthRoute": "/health",
... "port": 8000,
... "tensorParallelSize": 1,
... }
... },
... )Sem a chave do engine, o mesmo dicionário é enviado como um contêiner personalizado simples, de modo que as opções específicas do engine (aqui, tensorParallelSize) são descartadas.
Para contêineres que precisam de um entrypoint personalizado ou flags de runtime, passe container_command e/ou container_args (cada um uma lista de tokens). Eles correspondem a model.command e model.args no payload da API. Eles não estão vinculados a imagens personalizadas: as imagens de engine gerenciadas (por exemplo, vLLM, SGLang) também aceitam flags de engine por meio de container_args. O mesmo está disponível na CLI via hf endpoints deploy ... --container-command "..." --container-args "...".
Paralelismo em instâncias multi-acelerador
O vLLM e o SGLang usam um acelerador por padrão, enquanto o endpoint é alocado com todos os aceleradores da instância. Portanto, deixar o paralelismo não definido carregaria o modelo em um único acelerador e deixaria os demais ociosos, ainda assim reportando saúde, fazendo com que você pague por todos e obtenha a taxa de transferência de apenas um. É por isso que a API agora rejeita esse tipo de implantação. (O TGI deriva sua contagem de shards da instância e não é afetado.) Defina tensorParallelSize para dividir uma cópia do modelo entre os aceleradores, ou dataParallelSize (somente vLLM) para executar uma cópia por acelerador:
>>> endpoint = create_inference_endpoint(
... "gpt-oss-120b-vllm",
... repository="openai/gpt-oss-120b",
... framework="custom",
... accelerator="gpu",
... instance_size="x8",
... instance_type="nvidia-h200",
... region="us-east-1",
... vendor="aws",
... custom_image={"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "tensorParallelSize": 8}},
... )A partir da CLI, --engine seleciona a imagem do mecanismo gerenciado e as duas flags são gravadas em sua configuração:
hf endpoints deploy gpt-oss-120b-vllm --repo openai/gpt-oss-120b --framework custom \ --accelerator gpu --instance-size x8 --instance-type nvidia-h200 --region us-east-1 --vendor aws \ --engine vllm --custom-image vllm/vllm-openai:v0.23.0 --tensor-parallel-size 8
Para retreinar um endpoint implantado, passe apenas tensor_parallel_size para update() ou hf endpoints update. model.image é enviado como um todo e requer url, portanto, a imagem atual do endpoint é obtida
e atualizada no local:
>>> endpoint.update(tensor_parallel_size=4)container_args (--tp 8) não é equivalente: ele chega ao engine como uma flag de linha de comando, e não como a configuração model.image que a API valida em relação à quantidade de aceleradores da instância. Use-o para flags de engine que não possuem campo de imagem, e para
containers customizados simples, que não possuem campos de paralelismo.
Obter ou listar Inference Endpoints existentes
Em alguns casos, você pode precisar gerenciar Inference Endpoints que criou anteriormente. Se você souber o nome, pode obtê-lo usando get_inference_endpoint(), que retorna um objeto InferenceEndpoint. Alternativamente, você pode usar list_inference_endpoints() para recuperar uma lista de todos os Inference Endpoints. Ambos os métodos aceitam um parâmetro opcional namespace. Você pode definir o namespace para qualquer organização da qual você faz parte. Caso contrário, o padrão é o seu nome de usuário.
>>> 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), ...]Ou via CLI:
hf endpoints describe my-endpoint-name
hf endpoints ls --namespace huggingface
hf endpoints ls --namespace '*'Verifique o status da implantação
No restante deste guia, assumiremos que temos um objeto InferenceEndpoint chamado endpoint. Você pode ter notado que o endpoint possui um atributo status do tipo InferenceEndpointStatus. Quando o Inference Endpoint é implantado e acessível, o status deve ser "running" e o atributo url é definido:
>>> endpoint
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud')Antes de atingir o estado "running", o Inference Endpoint geralmente passa por uma fase de "initializing" ou "pending". Você pode obter o novo estado do endpoint executando fetch(). Assim como todos os outros métodos de InferenceEndpoint que fazem uma solicitação ao servidor, os atributos internos de endpoint são mutados no local:
>>> endpoint.fetch()
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None)Ou via CLI:
hf endpoints describe my-endpoint-name
Em vez de buscar o status do Inference Endpoint enquanto espera que ele entre em execução, você pode chamar diretamente wait(). Este helper recebe como entrada um parâmetro timeout e um parâmetro fetch_every (em segundos) e bloqueará a thread até que o Inference Endpoint seja implantado. Os valores padrão são, respectivamente, None (sem timeout) e 5 segundos.
# 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')Se timeout estiver definido e o Inference Endpoint levar muito tempo para carregar, um erro de timeout InferenceEndpointTimeoutError será lançado.
Executar inferência
Quando seu Inference Endpoint estiver no ar e em execução, você poderá finalmente executar inferência nele!
InferenceEndpoint possui duas propriedades, client e async_client, que retornam, respectivamente, objetos InferenceClient e 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")Se o Inference Endpoint não estiver em execução, uma exceção InferenceEndpointError será lançada:
>>> 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.Para mais detalhes sobre como usar o InferenceClient, consulte o guia de inferência.
Gerenciar ciclo de vida
Agora que vimos como criar um Inference Endpoint e executar inferência nele, vamos ver como gerenciar seu ciclo de vida.
Nesta seção, veremos métodos como pause(), resume(), scale_to_zero(), update() e delete(). Todos esses métodos são aliases adicionados ao InferenceEndpoint para conveniência. Se preferir, você também pode usar os métodos genéricos definidos em
HfApi: pause_inference_endpoint(), resume_inference_endpoint(), scale_to_zero_inference_endpoint(), update_inference_endpoint() e delete_inference_endpoint().
Pausar ou escalar para zero
Para reduzir custos quando seu Inference Endpoint não está em uso, você pode escolher pausá-lo usando pause() ou escalá-lo para zero usando scale_to_zero().
Um Inference Endpoint que está pausado ou escalonado para zero não custa nada. A diferença entre esses dois é que um endpoint pausado precisa ser explicitamente retomado usando resume(). Por outro lado, um endpoint escalonado para zero será iniciado automaticamente se uma chamada de inferência for feita a ele, com um atraso adicional de inicialização a frio. Um Inference Endpoint também pode ser configurado para escalar para zero automaticamente após um determinado período de inatividade.
# 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.Ou via CLI:
hf endpoints pause my-endpoint-name hf endpoints resume my-endpoint-name hf endpoints scale-to-zero my-endpoint-name
Atualizar requisitos de modelo ou hardware
Em alguns casos, você também pode querer atualizar seu Inference Endpoint sem criar um novo. Você pode atualizar o modelo hospedado ou os requisitos de hardware para executar o modelo. Você pode fazer isso usando 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)
# Update the container arguments, e.g. engine flags on an endpoint running vLLM or SGLang.
# Replaces the current value, it is not appended.
>>> endpoint.update(container_args=["--enable-auto-tool-choice", "--tool-call-parser", "lfm2"])
InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None)Ou via CLI:
hf endpoints update my-endpoint-name --repo gpt2-large
hf endpoints update my-endpoint-name --min-replica 2 --max-replica 6
hf endpoints update my-endpoint-name --accelerator cpu --instance-size x4 --instance-type intel-icl
hf endpoints update my-endpoint-name --container-args "--enable-auto-tool-choice --tool-call-parser lfm2"
# Merged into the image currently configured on the endpoint.
hf endpoints update my-endpoint-name --tensor-parallel-size 8
# Or replace the image entirely, in which case pass back the settings you want to keep.
hf endpoints update my-endpoint-name --engine vllm --custom-image vllm/vllm-openai:v0.23.0 --port 8000Excluir o endpoint
Por fim, se você não for mais usar o Inference Endpoint, basta chamar ~InferenceEndpoint.delete().
Esta é uma ação irreversível que removerá completamente o endpoint, incluindo sua configuração, logs e métricas de uso. Não é possível restaurar um Inference Endpoint excluído.
Um exemplo de ponta a ponta
Um caso de uso típico dos Inference Endpoints é processar um lote de tarefas de uma vez para limitar os custos de infraestrutura. Você pode automatizar esse processo usando o que vimos neste guia:
>>> 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 = await asyncio.gather(*[async_client.text_generation(...) for job in jobs])
# Pause endpoint
>>> endpoint.pause()Ou se seu Inference Endpoint já existir e estiver pausado:
>>> 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 = await asyncio.gather(*[async_client.text_generation(...) for job in jobs])
# Pause endpoint
>>> endpoint.pause()