Ejecutar inferencia en servidores

La inferencia es el proceso de utilizar un modelo entrenado para realizar predicciones sobre nuevos datos. Dado que este proceso puede ser intensivo en cómputo, ejecutarlo en un servicio dedicado o externo puede ser una opción interesante. La biblioteca huggingface_hub proporciona una interfaz unificada para ejecutar inferencia en múltiples servicios para modelos alojados en Hugging Face Hub:

Proveedores de inferencia: un acceso unificado y simplificado a cientos de modelos de aprendizaje automático, impulsado por nuestros socios de inferencia serverless. Este nuevo enfoque se basa en nuestra anterior API de inferencia serverless, ofreciendo más modelos, un rendimiento mejorado y una mayor fiabilidad gracias a proveedores de primer nivel. Consulta la documentación para obtener una lista de los proveedores compatibles.
Inference Endpoints: un producto para desplegar modelos en producción de forma sencilla. La inferencia se ejecuta en Hugging Face en una infraestructura dedicada y totalmente gestionada en un proveedor de nube de su elección.
Puntos finales locales: también puede ejecutar inferencia con servidores de inferencia locales como llama.cpp, Ollama, vLLM, LiteLLM o Text Generation Inference (TGI) conectando el cliente a estos puntos finales locales.

InferenceClient es un cliente de Python que realiza llamadas HTTP a nuestras APIs. Si deseas realizar las llamadas HTTP directamente con tu herramienta preferida (curl, postman, …), consulta la documentación de Inference Providers o las páginas de documentación de Inference Endpoints.

Para el desarrollo web, se ha publicado un cliente JS. Si te interesa el desarrollo de videojuegos, puedes echar un vistazo a nuestro proyecto de C#.

Primeros pasos

Empecemos con una tarea de texto a imagen:

>>> from huggingface_hub import InferenceClient

# Example with an external provider (e.g. replicate)
>>> replicate_client = InferenceClient(
    provider="replicate",
    api_key="my_replicate_api_key",
)
>>> replicate_image = replicate_client.text_to_image(
    "A flying car crossing a futuristic cityscape.",
    model="black-forest-labs/FLUX.1-schnell",
)
>>> replicate_image.save("flying_car.png")

En el ejemplo anterior, inicializamos un InferenceClient con un proveedor de terceros, Replicate. Al usar un proveedor, debe especificar el modelo que desea utilizar. El id del modelo debe ser el id del modelo en Hugging Face Hub, no el id del modelo del proveedor de terceros. En nuestro ejemplo, generamos una imagen a partir de un prompt de texto. El valor devuelto es un objeto PIL.Image que se puede guardar en un archivo. Para más detalles, consulte la documentación de text_to_image().

Veamos ahora un ejemplo que utiliza la API chat_completion(). Esta tarea usa un LLM para generar una respuesta a partir de una lista de mensajes:

>>> from huggingface_hub import InferenceClient
>>> messages = [
    {
        "role": "user",
        "content": "What is the capital of France?",
    }
]
>>> client = InferenceClient(
    provider="together",
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    api_key="my_together_api_key",
)
>>> client.chat_completion(messages, max_tokens=100)
ChatCompletionOutput(
    choices=[
        ChatCompletionOutputComplete(
            finish_reason="eos_token",
            index=0,
            message=ChatCompletionOutputMessage(
                role="assistant", content="The capital of France is Paris.", name=None, tool_calls=None
            ),
            logprobs=None,
        )
    ],
    created=1719907176,
    id="",
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    object="text_completion",
    system_fingerprint="2.0.4-sha-f426a33",
    usage=ChatCompletionOutputUsage(completion_tokens=8, prompt_tokens=17, total_tokens=25),
)

En el ejemplo anterior, utilizamos un proveedor de terceros (Together AI) y especificamos qué modelo queríamos usar ("meta-llama/Meta-Llama-3-8B-Instruct"). A continuación, proporcionamos una lista de mensajes para completar (en este caso, una sola pregunta) y pasamos un parámetro adicional a la API (max_token=100). La salida es un objeto ChatCompletionOutput que sigue la especificación de OpenAI. El contenido generado se puede acceder con output.choices[0].message.content. Para más detalles, consulta la documentación de chat_completion().

La API está diseñada para ser sencilla. No todos los parámetros y opciones están disponibles o descritos para el usuario final. Consulta esta página si te interesa aprender más sobre todos los parámetros disponibles para cada tarea.

Usar un proveedor específico

Si deseas usar un proveedor específico, puedes especificarlo al inicializar el cliente. El valor predeterminado es “auto”, que seleccionará el primero de los proveedores disponibles para el modelo, ordenados según la preferencia del usuario en https://hf.co/settings/inference-providers. Consulta la sección Proveedores y tareas compatibles para obtener una lista de los proveedores compatibles.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(provider="replicate", api_key="my_replicate_api_key")

Usar un modelo específico

¿Qué pasa si quieres usar un modelo específico? Puedes especificarlo como parámetro o directamente a nivel de instancia:

>>> from huggingface_hub import InferenceClient
# Initialize client for a specific model
>>> client = InferenceClient(provider="together", model="meta-llama/Llama-3.1-8B-Instruct")
>>> client.text_to_image(...)
# Or use a generic client but pass your model as an argument
>>> client = InferenceClient(provider="together")
>>> client.text_to_image(..., model="meta-llama/Llama-3.1-8B-Instruct")

Al usar el proveedor “hf-inference”, cada tarea viene con un modelo recomendado de los más de 1M de modelos disponibles en el Hub. Sin embargo, esta recomendación puede cambiar con el tiempo, por lo que es mejor establecer explícitamente un modelo una vez que hayas decidido cuál usar. Para los proveedores de terceros, siempre debes especificar un modelo compatible con ese proveedor.

Visita la página Models en el Hub para explorar los modelos disponibles a través de Inference Providers.

Uso de puntos de inferencia

Los ejemplos que vimos arriba usan proveedores de inferencia. Si bien estos resultan muy útiles para prototipar y probar cosas rápidamente, cuando estés listo para desplegar tu modelo en producción, necesitarás usar una infraestructura dedicada. Ahí es donde entra Inference Endpoints. Te permite desplegar cualquier modelo y exponerlo como una API privada. Una vez desplegado, obtendrás una URL a la que puedes conectarte usando exactamente el mismo código que antes, cambiando solo el parámetro model:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if")
# or
>>> client = InferenceClient()
>>> client.text_to_image(..., model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if")

Tenga en cuenta que no puede especificar tanto una URL como un proveedor, ya que son mutuamente excluyentes. Las URLs se utilizan para conectarse directamente a puntos de conexión desplegados.

Uso de puntos finales locales

Puede usar InferenceClient para ejecutar la finalización de chat con servidores de inferencia locales (llama.cpp, vllm, litellm server, TGI, mlx, etc.) que se ejecutan en su propia máquina. La API debe ser compatible con la API de OpenAI.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(model="http://localhost:8080")

>>> response = client.chat.completions.create(
...     messages=[
...         {"role": "user", "content": "What is the capital of France?"}
...     ],
...     max_tokens=100
... )
>>> print(response.choices[0].message.content)

De manera similar al cliente de Python de OpenAI, InferenceClient se puede utilizar para ejecutar inferencia de Chat Completion con cualquier punto final compatible con la API REST de OpenAI.

Autenticación

La autenticación se puede realizar de dos formas:

Ruteado a través de Hugging Face : Usa Hugging Face como proxy para acceder a proveedores de terceros. Las llamadas se enrutarán a través de la infraestructura de Hugging Face utilizando nuestras claves de proveedor, y el uso se facturará directamente a tu cuenta de Hugging Face.

Puede autenticarse usando un User Access Token. Puede proporcionar su token de Hugging Face directamente usando el parámetro api_key:

>>> client = InferenceClient(
    provider="replicate",
    api_key="hf_****"  # Your HF token
)

Si no pasas una api_key, el cliente intentará encontrar y usar un token almacenado localmente en tu máquina. Esto suele ocurrir si has iniciado sesión previamente. Consulta la Guía de autenticación para obtener detalles sobre el inicio de sesión.

>>> client = InferenceClient(
    provider="replicate",
    token="hf_****"  # Your HF token
)

Acceso directo al proveedor: Utilice su propia clave de API para interactuar directamente con el servicio del proveedor:

>>> client = InferenceClient(
    provider="replicate",
    api_key="r8_****"  # Your Replicate API key
)

Para más detalles, consulte la documentación de precios de Inference Providers.

Proveedores y tareas compatibles

El objetivo de InferenceClient es ofrecer la interfaz más sencilla para ejecutar inferencia en modelos de Hugging Face, en cualquier proveedor. Cuenta con una API simple que admite las tareas más comunes. A continuación se muestra una tabla con los proveedores que admiten cada tarea:

Tarea	Baseten	Cerebras	Cohere	DeepInfra	fal-ai	Featherless AI	Fireworks AI	Groq	HF Inference	Novita AI	Nscale	OVHcloud AI Endpoints	IA pública	Replicar	Scaleway	Juntos	Wavespeed	Zai
audio_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
audio_to_audio()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
automatic_speech_recognition()	❌	❌	❌	✅	✅	❌	❌	❌	✅	❌	❌	❌	❌	✅	❌	❌	❌	❌
chat_completion()	✅	✅	✅	✅	❌	✅	✅	✅	✅	✅	✅	✅	✅	❌	✅	✅	❌	✅
document_question_answering()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
feature_extraction()	❌	❌	❌	✅	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	✅	✅	❌	❌
fill_mask()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
image_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
image_segmentation()	❌	❌	❌	❌	✅	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
image_to_image()	❌	❌	❌	❌	✅	❌	❌	❌	✅	❌	❌	❌	❌	✅	❌	✅	✅	❌
image_to_video()	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	✅	✅	❌
image_to_text()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
object_detection()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
question_answering()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
sentence_similarity()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
summarization()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
table_question_answering()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
text_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
text_generation()	❌	❌	❌	✅	❌	✅	❌	❌	✅	✅	❌	❌	❌	❌	❌	✅	❌	❌
text_to_image()	❌	❌	❌	❌	✅	❌	❌	❌	✅	❌	✅	❌	❌	✅	❌	✅	✅	✅
text_to_speech()	❌	❌	❌	✅	✅	❌	❌	❌	✅	❌	❌	❌	❌	✅	❌	✅	❌	❌
text_to_video()	❌	❌	❌	❌	✅	❌	❌	❌	❌	✅	❌	❌	❌	✅	❌	✅	✅	❌
tabular_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
tabular_regression()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
token_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
translation()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
visual_question_answering()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
zero_shot_image_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
zero_shot_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌

Consulta la página Tasks para obtener más información sobre cada tarea.

Compatibilidad con OpenAI

La tarea chat_completion sigue la sintaxis del cliente de Python de OpenAI. ¿Qué significa esto para ti? Significa que, si estás acostumbrado a trabajar con las APIs de OpenAI, podrás cambiar a huggingface_hub.InferenceClient para trabajar con modelos de código abierto actualizando solo 2 líneas de código.

- from openai import OpenAI
+ from huggingface_hub import InferenceClient

- client = OpenAI(
+ client = InferenceClient(
    base_url=...,
    api_key=...,
)


output = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Count to 10"},
    ],
    stream=True,
    max_tokens=1024,
)

for chunk in output:
    print(chunk.choices[0].delta.content)

¡Y eso es todo! Los únicos cambios obligatorios son reemplazar from openai import OpenAI por from huggingface_hub import InferenceClient y client = OpenAI(...) por client = InferenceClient(...). Puedes elegir cualquier modelo LLM del Hugging Face Hub pasando su id de modelo como parámetro model. Esta es una lista de los modelos compatibles. Para la autenticación, debes pasar un User Access Token válido como api_key o autenticarte usando huggingface_hub (consulta la guía de autenticación).

Todos los parámetros de entrada y el formato de salida son estrictamente los mismos. En particular, puedes pasar stream=True para recibir los tokens a medida que se generan. También puedes usar AsyncInferenceClient para ejecutar inferencia con asyncio:

import asyncio
- from openai import AsyncOpenAI
+ from huggingface_hub import AsyncInferenceClient

- client = AsyncOpenAI()
+ client = AsyncInferenceClient()

async def main():
    stream = await client.chat.completions.create(
        model="meta-llama/Meta-Llama-3-8B-Instruct",
        messages=[{"role": "user", "content": "Say this is a test"}],
        stream=True,
    )
    async for chunk in stream:
        print(chunk.choices[0].delta.content or "", end="")

asyncio.run(main())

Es posible que se pregunte por qué usar InferenceClient en lugar del cliente de OpenAI. Hay varias razones para ello:

InferenceClient está configurado para los servicios de Hugging Face. No es necesario proporcionar un base_url para ejecutar modelos con Inference Providers. Tampoco es necesario proporcionar un token o api_key si tu máquina ya está correctamente iniciada en la sesión.
InferenceClient está diseñado tanto para Text-Generation-Inference (TGI) como para el framework transformers, lo que garantiza que siempre estará a la altura de las últimas actualizaciones.
InferenceClient está integrado con nuestro servicio de Inference Endpoints, lo que facilita el lanzamiento de un Inference Endpoint, la comprobación de su estado y la ejecución de inferencia en él. Consulta la guía de Inference Endpoints para más detalles.

InferenceClient.chat.completions.create es simplemente un alias de InferenceClient.chat_completion. Consulte la referencia del paquete de chat_completion() para obtener más detalles. Los parámetros base_url y api_key al instanciar el cliente también son alias de model y token. Estos alias se han definido para reducir la fricción al cambiar de OpenAI a InferenceClient.

Llamada a funciones

El uso de funciones permite que los LLM interactúen con herramientas externas, como funciones definidas o APIs. Esto permite a los usuarios construir fácilmente aplicaciones adaptadas a casos de uso específicos y tareas del mundo real. InferenceClient implementa la misma interfaz de uso de herramientas que la API de Chat Completions de OpenAI. A continuación se muestra un ejemplo sencillo de uso de herramientas utilizando Novita como proveedor de inferencia:

from huggingface_hub import InferenceClient

tools = [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get current temperature for a given location.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "City and country e.g. Paris, France"
                        }
                    },
                    "required": ["location"],
                },
            }
        }
]

client = InferenceClient(provider="novita")

response = client.chat.completions.create(
    model="Qwen/Qwen2.5-72B-Instruct",
    messages=[
    {
        "role": "user",
        "content": "What's the weather like the next 3 days in London, UK?"
    }
    ],
    tools=tools,
    tool_choice="auto",
)

print(response.choices[0].message.tool_calls[0].function.arguments)

Consulte la documentación de los proveedores para verificar qué modelos admiten la función de Function/Tool Calling.

Salidas estructuradas & modo JSON

InferenceClient admite el modo JSON para respuestas JSON sintácticamente válidas y Structured Outputs para respuestas con esquema aplicado. El modo JSON proporciona datos legibles por máquina sin una estructura estricta, mientras que Structured Outputs garantizan tanto un JSON válido como el cumplimiento de un esquema predefinido para un procesamiento posterior confiable.

Seguimos las especificaciones de la API de OpenAI tanto para el modo JSON como para Structured Outputs. Puedes activarlos mediante el argumento response_format. A continuación, se muestra un ejemplo de Structured Outputs utilizando Cerebras como proveedor de inferencia:

from huggingface_hub import InferenceClient

json_schema = {
    "name": "book",
    "schema": {
        "properties": {
            "name": {
                "title": "Name",
                "type": "string",
            },
            "authors": {
                "items": {"type": "string"},
                "title": "Authors",
                "type": "array",
            },
        },
        "required": ["name", "authors"],
        "title": "Book",
        "type": "object",
    },
    "strict": True,
}

client = InferenceClient(provider="cerebras")


completion = client.chat.completions.create(
    model="Qwen/Qwen3-32B",
    messages=[
        {"role": "system", "content": "Extract the books information."},
        {"role": "user", "content": "I recently read 'The Great Gatsby' by F. Scott Fitzgerald."},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": json_schema,
    },
)

print(completion.choices[0].message)

Consulte la documentación de los proveedores para verificar qué modelos admiten Structured Outputs y JSON Mode.

Cliente asíncrono

También se proporciona una versión asíncrona del cliente, basada en asyncio y httpx2. Todos los puntos finales de API asíncronos están disponibles a través de AsyncInferenceClient. Su inicialización y APIs son estrictamente las mismas que las de la versión solo síncrona.

# Code must be run in an asyncio concurrent context.
# $ python -m asyncio
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()

>>> image = await client.text_to_image("An astronaut riding a horse on the moon.")
>>> image.save("astronaut.png")

>>> async for token in await client.text_generation("The Huggingface Hub is", stream=True):
...     print(token, end="")
 a platform for sharing and discussing ML-related content.

Para obtener más información sobre el módulo asyncio, consulte la documentación oficial.

Cliente MCP

La biblioteca huggingface_hub incluye ahora un MCPClient experimental, diseñado para dotar a los Modelos de Lenguaje Grandes (LLM) de la capacidad de interactuar con Herramientas externas a través del Model Context Protocol (MCP). Este cliente extiende un AsyncInferenceClient para integrar el uso de Herramientas de manera fluida.

El MCPClient se conecta a servidores MCP (ya sean scripts locales de stdio o servicios remotos de http/sse) que exponen herramientas. Proporciona estas herramientas a un LLM (a través de AsyncInferenceClient). Si el LLM decide utilizar una herramienta, MCPClient gestiona la solicitud de ejecución al servidor MCP y devuelve la salida de la herramienta al LLM, a menudo transmitiendo los resultados en tiempo real.

En el siguiente ejemplo, utilizamos el modelo Qwen/Qwen2.5-72B-Instruct a través del proveedor de inferencia Novita. A continuación, añadimos un servidor MCP remoto, en este caso, un servidor SSE que pone la herramienta de generación de imágenes Flux a disposición del LLM.

import os

from huggingface_hub import ChatCompletionInputMessage, ChatCompletionStreamOutput, MCPClient


async def main():
    async with MCPClient(
        provider="novita",
        model="Qwen/Qwen2.5-72B-Instruct",
        api_key=os.environ["HF_TOKEN"],
    ) as client:
        await client.add_mcp_server(type="sse", url="https://evalstate-flux1-schnell.hf.space/gradio_api/mcp/sse")

        messages = [
            {
                "role": "user",
                "content": "Generate a picture of a cat on the moon",
            }
        ]

        async for chunk in client.process_single_turn_with_tools(messages):
            # Log messages
            if isinstance(chunk, ChatCompletionStreamOutput):
                delta = chunk.choices[0].delta
                if delta.content:
                    print(delta.content, end="")

            # Or tool calls
            elif isinstance(chunk, ChatCompletionInputMessage):
                print(
                    f"\nCalled tool '{chunk.name}'. Result: '{chunk.content if len(chunk.content) < 1000 else chunk.content[:1000] + '...'}'"
                )


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

Para un desarrollo aún más sencillo, ofrecemos una clase Agent de mayor nivel. Este ‘Tiny Agent’ simplifica la creación de agentes conversacionales al gestionar el bucle de chat y el estado, actuando esencialmente como un envoltorio alrededor de MCPClient. Está diseñado para ser un simple bucle while construido directamente sobre un MCPClient. Puede ejecutar estos agentes directamente desde la línea de comandos:

# install latest version of huggingface_hub with the mcp extra
pip install -U huggingface_hub[mcp]
# Run an agent that uses the Flux image generation tool
tiny-agents run julien-c/flux-schnell-generator

Al iniciarse, el Agent cargará y enumerará las Tools que ha descubierto en sus servidores MCP conectados, ¡y estará listo para tus prompts!

Consejos avanzados

En la sección anterior, vimos los aspectos principales de InferenceClient. A continuación, profundizamos en algunos consejos más avanzados.

Facturación

Como usuario de HF, recibes créditos mensuales para ejecutar inferencia a través de diversos proveedores en el Hub. La cantidad de créditos que recibes depende de tu tipo de cuenta (Free o PRO o Enterprise Hub). Se te cobra por cada solicitud de inferencia, según la tabla de precios del proveedor. De forma predeterminada, las solicitudes se facturan a tu cuenta personal. Sin embargo, es posible configurar la facturación para que las solicitudes se cobren a una organización de la que seas miembro, simplemente pasando bill_to="<your_org_name>" a InferenceClient. Para que esto funcione, tu organización debe estar suscrita a Enterprise Hub. Para más detalles sobre la facturación, consulta esta guía.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(provider="fal-ai", bill_to="openai")
>>> image = client.text_to_image(
...     "A majestic lion in a fantasy forest",
...     model="black-forest-labs/FLUX.1-schnell",
... )
>>> image.save("lion.png")

Tenga en cuenta que NO es posible facturar a otro usuario o a una organización de la que no sea miembro. Si desea otorgar créditos a otra persona, debe crear una organización conjunta con ella.

Tiempo de espera

Las llamadas de inferencia pueden tardar bastante tiempo. De forma predeterminada, InferenceClient espera “indefinidamente” hasta que la inferencia se complete. Si desea tener más control en su flujo de trabajo, puede establecer el parámetro timeout en un valor específico en segundos. Si se agota el tiempo de espera, se lanza un InferenceTimeoutError, que puede capturar en su código:

>>> from huggingface_hub import InferenceClient, InferenceTimeoutError
>>> client = InferenceClient(timeout=30)
>>> try:
...     client.text_to_image(...)
... except InferenceTimeoutError:
...     print("Inference timed out after 30s.")

Entradas binarias

Algunas tareas requieren entradas binarias, por ejemplo, al trabajar con imágenes o archivos de audio. En este caso, InferenceClient intenta ser lo más permisivo posible y aceptar diferentes tipos:

bytes en bruto
un objeto similar a un archivo, abierto en modo binario (with open("audio.flac", "rb") as f: ...)
una ruta (str o Path) que apunta a un archivo local
una URL (str) que apunta a un archivo remoto (p. ej. https://...). En este caso, el archivo se descargará localmente antes de enviarse a la API.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
[{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...]

Update on GitHub

Hub Python Library

Ejecutar inferencia en servidores

Primeros pasos

Usar un proveedor específico

Usar un modelo específico

Uso de puntos de inferencia

Uso de puntos finales locales

Autenticación

Proveedores y tareas compatibles

Compatibilidad con OpenAI

Llamada a funciones

Salidas estructuradas & modo JSON

Cliente asíncrono

Cliente MCP

Consejos avanzados

Facturación

Tiempo de espera

Entradas binarias