Puntos de inferencia

Inference Endpoints ofrece una solución de producción segura para desplegar fácilmente cualquier modelo de transformers, sentence-transformers y diffusers en una infraestructura dedicada y con escalado automático gestionada por Hugging Face. Un Inference Endpoint se crea a partir de un modelo del Hub. En esta guía, aprenderemos a gestionar Inference Endpoints de forma programática con huggingface_hub. Para obtener más información sobre el propio producto Inference Endpoints, consulta su documentación oficial.

Esta guía asume que huggingface_hub está instalado correctamente y que tu máquina ha iniciado sesión. Consulta la guía de inicio rápido si aún no es así. La versión mínima que admite la API de Inference Endpoints es v0.19.0.

Novedad: ahora es posible desplegar un Inference Endpoint desde el catálogo de modelos de HF con una simple llamada a la API. El catálogo es una lista cuidadosamente seleccionada de modelos que pueden desplegarse con configuraciones optimizadas. No necesitas configurar nada, ¡nos encargamos de todo lo complejo! Se garantiza que todos los modelos y configuraciones han sido probados para ofrecer el mejor equilibrio entre coste y rendimiento. create_inference_endpoint_from_catalog() funciona igual que create_inference_endpoint(), pero con muchos menos parámetros que pasar. Puedes usar list_inference_catalog() para recuperar el catálogo de forma programática.

Tenga en cuenta que esta sigue siendo una función experimental. ¡Háganos saber qué opina si la utiliza!

Cada modelo del catálogo se despliega mediante una receta: una combinación de hardware y motor que ha sido probada para él. list_inference_catalog() devuelve los modelos con sus recetas y acepta filtros del lado del 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)]

Pase un repo_id a create_inference_endpoint_from_catalog() para desplegar la receta predeterminada de un modelo, opcionalmente restringida con accelerator ("cpu", "gpu" o "neuron") y gguf_file, o pase un recipe_id para desplegar una receta exacta:

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

Encuentra hardware para desplegar

Los valores de accelerator, vendor, region, instance_type y instance_size aceptados por create_inference_endpoint() dependen entre sí. Utilice list_inference_endpoints_hardware() para listar las combinaciones válidas, junto con su precio por hora y la cuota de acelerador de su espacio de nombres:

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

La cuota es por espacio de nombres, así que pasa el namespace en el que desplegarás (por defecto, tu propia cuenta):

>>> list_inference_endpoints_hardware(namespace="my-org")

O mediante la CLI:

hf endpoints hardware --accelerator gpu

Crear un punto de inferencia

El primer paso es crear un 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"
... )

O mediante la 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-yz9ynamx

En este ejemplo, creamos un Inference Endpoint authenticated llamado "my-endpoint-name" para servir gpt2 para text-generation. Un Inference Endpoint authenticated significa que se requiere su token para acceder a la API. También necesitamos proporcionar información adicional para configurar los requisitos de hardware, como proveedor, región, acelerador, tipo de instancia y tamaño. Puede consultar la lista de recursos disponibles aquí. Alternativamente, puede crear un Inference Endpoint manualmente usando la interfaz web para mayor comodidad. Consulte esta guía para obtener detalles sobre la configuración avanzada y su uso.

El valor devuelto por create_inference_endpoint() es un objeto InferenceEndpoint:

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

O mediante la CLI:

hf endpoints describe my-endpoint-name

Es un dataclass que contiene información sobre el endpoint. Puedes acceder a atributos importantes como name, repository, status, task, created_at, updated_at, etc. Si lo necesitas, también puedes acceder a la respuesta cruda del servidor con endpoint.raw.

Una vez que se crea tu Inference Endpoint, puedes encontrarlo en tu panel personal.

Usar una imagen personalizada

Por defecto, el Inference Endpoint se construye a partir de una imagen de docker proporcionada por Hugging Face. Sin embargo, es posible especificar cualquier imagen de docker mediante el parámetro custom_image. Un caso de uso común es ejecutar LLMs utilizando el framework text-generation-inference. Esto se puede hacer de la siguiente manera:

# 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",
...     },
... )

El valor que se debe pasar como custom_image es un diccionario que contiene una url al contenedor docker y la configuración para ejecutarlo. Para más detalles al respecto, consulta la documentación de Swagger.

Para una imagen alojada en un registro de contenedores privado, pase container_registry_username y, cuando el registro lo requiera, container_registry_password. Las credenciales solo se admiten para un contenedor personalizado simple:

>>> 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",
... )

Las opciones de CLI equivalentes son --container-registry-username y --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 también acepta los tipos de contenedor específicos de cada motor que soporta la API, usando el nombre del motor (vLLM, vLLMNeuron, sGLang, tgi, tgiNeuron, tei, llamacpp, hfServe, …) como clave del diccionario en lugar de dejarlo plano. Cada motor toma los campos habituales del contenedor (url, port, healthRoute) más sus propias opciones de ajuste. Cualquier diccionario sin un url de nivel superior se reenvía a la API sin modificar, por lo que los motores que se añadan a la API en el futuro funcionarán sin necesidad de actualizar 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,
...         }
...     },
... )

Sin la clave del motor, el mismo diccionario se envía como un contenedor personalizado plano, por lo que las opciones específicas del motor (aquí tensorParallelSize) se descartan.

Para los contenedores que requieren un punto de entrada personalizado o banderas de tiempo de ejecución, pase container_command y/o container_args (cada uno una lista de tokens). Se mapean a model.command y model.args en la carga de la API. No están vinculados a imágenes personalizadas: las imágenes de motor administradas (p. ej. vLLM, SGLang) también aceptan banderas de motor a través de container_args. Lo mismo está disponible desde la CLI mediante hf endpoints deploy ... --container-command "..." --container-args "...".

Paralelismo en instancias multiacelerador

vLLM y SGLang usan un solo acelerador por defecto, mientras que el endpoint se asigna con todos los aceleradores de su instancia, por lo que dejar el paralelismo sin configurar cargaría el modelo en uno y dejaría el resto inactivo, aunque el sistema siga reportando un estado saludable, de modo que se paga por todos ellos pero se obtiene el rendimiento de uno. Por eso la API ahora rechaza este tipo de despliegue. (TGI deriva su número de fragmentos de la instancia y no se ve afectado.) Establezca tensorParallelSize para fragmentar una copia del modelo entre los aceleradores, o dataParallelSize (solo vLLM) para ejecutar una copia 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}},
... )

Desde la CLI, --engine selecciona la imagen del motor gestionado y las dos banderas se escriben en su configuración:

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 retunear un endpoint desplegado, pase tensor_parallel_size por separado a update() o hf endpoints update. model.image se envía como un todo y requiere url, por lo que se obtiene la imagen actual del endpoint y se actualiza en su lugar:

>>> endpoint.update(tensor_parallel_size=4)

container_args (--tp 8) no es equivalente: llega al motor como una bandera de línea de comandos, no como la configuración model.image que la API valida contra la cantidad de aceleradores de la instancia. Úsalo para banderas del motor que no tienen un campo de imagen, y para contenedores personalizados simples, que no tienen campos de paralelismo.

Obtener o listar puntos de inferencia existentes

En algunos casos, es posible que necesites gestionar los Inference Endpoints que creaste anteriormente. Si conoces el nombre, puedes obtenerlo usando get_inference_endpoint(), que devuelve un objeto InferenceEndpoint. Alternativamente, puedes usar list_inference_endpoints() para recuperar una lista de todos los Inference Endpoints. Ambos métodos aceptan un parámetro opcional namespace. Puedes establecer namespace como cualquier organización de la que seas miembro. De lo contrario, se usa tu nombre de usuario por defecto.

>>> 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), ...]

O mediante la CLI:

hf endpoints describe my-endpoint-name
hf endpoints ls --namespace huggingface
hf endpoints ls --namespace '*'

Comprobar el estado de la implementación

En el resto de esta guía, asumiremos que tenemos un objeto InferenceEndpoint llamado endpoint. Es posible que hayas notado que el endpoint tiene un atributo status de tipo InferenceEndpointStatus. Cuando el Inference Endpoint está desplegado y accesible, el estado debe ser "running" y el atributo url se establece:

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

Antes de alcanzar el estado "running", el Inference Endpoint suele pasar por una fase de "initializing" o "pending". Puede obtener el nuevo estado del endpoint ejecutando fetch(). Al igual que todos los demás métodos de InferenceEndpoint que realizan una solicitud al servidor, los atributos internos de endpoint se modifican en el lugar:

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

O mediante la CLI:

hf endpoints describe my-endpoint-name

En lugar de obtener el estado del Inference Endpoint mientras espera a que se ejecute, puede llamar directamente a wait(). Este helper toma como entrada un parámetro timeout y un parámetro fetch_every (en segundos) y bloqueará el hilo hasta que el Inference Endpoint esté desplegado. Los valores predeterminados son, respectivamente, None (sin timeout) y 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')

Si timeout está definido y el Inference Endpoint tarda demasiado en cargarse, se genera un error de tiempo de espera InferenceEndpointTimeoutError.

Ejecutar inferencia

Una vez que tu Inference Endpoint esté en funcionamiento, ¡por fin podrás ejecutar inferencia en él!

InferenceEndpoint tiene dos propiedades, client y async_client, que devuelven respectivamente objetos InferenceClient y 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")

Si el Inference Endpoint no está en ejecución, se lanza una excepción 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.

Para más detalles sobre cómo usar InferenceClient, consulta la Guía de inferencia.

Gestionar el ciclo de vida

Ahora que hemos visto cómo crear un Inference Endpoint y ejecutar inferencia en él, veamos cómo gestionar su ciclo de vida.

En esta sección, veremos métodos como pause(), resume(), scale_to_zero(), update() y delete(). Todos esos métodos son alias añadidos a InferenceEndpoint por comodidad. Si lo prefieres, también puedes usar los métodos genéricos definidos en HfApi: pause_inference_endpoint(), resume_inference_endpoint(), scale_to_zero_inference_endpoint(), update_inference_endpoint() y delete_inference_endpoint().

Pausar o escalar a cero

Para reducir los costos cuando su Inference Endpoint no está en uso, puede optar por pausarlo con pause() o escalarlo a cero con scale_to_zero().

Un Inference Endpoint que está en pausa o escalado a cero no tiene ningún coste. La diferencia entre ambos es que un endpoint en pausa debe reanudarse explícitamente mediante resume(). Por el contrario, un endpoint escalado a cero se iniciará automáticamente si se realiza una llamada de inferencia, con un retraso adicional de inicio en frío. Un Inference Endpoint también puede configurarse para que se escale a cero automáticamente tras un cierto período de inactividad.

# 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.

O mediante la CLI:

hf endpoints pause my-endpoint-name
hf endpoints resume my-endpoint-name
hf endpoints scale-to-zero my-endpoint-name

Actualizar los requisitos de modelo o hardware

En algunos casos, también puede ser necesario actualizar su Inference Endpoint sin crear uno nuevo. Puede actualizar el modelo alojado o los requisitos de hardware para ejecutar el modelo. Puede hacer esto 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)

O mediante la 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 8000

Eliminar el punto de conexión

Por último, si ya no vas a usar el Inference Endpoint, simplemente puedes llamar a ~InferenceEndpoint.delete().

Esta es una acción irreversible que eliminará por completo el endpoint, incluida su configuración, registros y métricas de uso. No es posible restaurar un Inference Endpoint eliminado.

Un ejemplo de principio a fin

Un caso de uso típico de Inference Endpoints es procesar un lote de trabajos a la vez para limitar los costos de infraestructura. Puede automatizar este proceso utilizando lo que vimos en esta guía:

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

O si su Inference Endpoint ya existe y está en pausa:

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