# 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 el Hugging Face Hub:

1.  [Proveedores de inferencia](https://huggingface.co/docs/inference-providers/index): 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](https://huggingface.co/docs/inference-providers/index#partners) para obtener una lista de los proveedores compatibles.
2.  [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index): 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.
3.  Puntos finales locales: también puede ejecutar inferencia con servidores de inferencia locales como [llama.cpp](https://github.com/ggerganov/llama.cpp), [Ollama](https://ollama.com/), [vLLM](https://github.com/vllm-project/vllm), [LiteLLM](https://docs.litellm.ai/docs/simple_proxy) o [Text Generation Inference (TGI)](https://github.com/huggingface/text-generation-inference) conectando el cliente a estos puntos finales locales.

> [!TIP]
> [InferenceClient](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.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](https://huggingface.co/docs/inference-providers/index) o las páginas de documentación de [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index).
>
> Para el desarrollo web, se ha publicado un [cliente JS](https://huggingface.co/docs/huggingface.js/inference/README). Si te interesa el desarrollo de videojuegos, puedes echar un vistazo a nuestro [proyecto de C#](https://github.com/huggingface/unity-api).

## Primeros pasos

Empecemos con una tarea de texto a imagen:

```python
>>> 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](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient) con un proveedor de terceros, [Replicate](https://replicate.com/). Al usar un proveedor, debes especificar el modelo que deseas utilizar. El id del modelo debe ser el id del modelo en el 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, consulta la documentación de [text_to_image()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_image).

Veamos ahora un ejemplo que utiliza la API [chat_completion()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion). Esta tarea usa un LLM para generar una respuesta a partir de una lista de mensajes:

```python
>>> 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](https://www.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()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion).

> [!WARNING]
> 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](https://huggingface.co/docs/api-inference/detailed_parameters) 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](#supported-providers-and-tasks) para obtener una lista de los proveedores compatibles.

```python
>>> 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:

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

> [!TIP]
> 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](https://huggingface.co/models?inference=warm) en el Hub para explorar los modelos disponibles a través de Inference Providers.

### Uso de puntos de inferencia

Los ejemplos que vimos arriba utilizan proveedores de inferencia. Si bien resultan muy útiles para prototipar y probar cosas rápidamente, cuando estés listo para desplegar tu modelo en producción, necesitarás utilizar una infraestructura dedicada. Ahí es donde entra [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index). Te permite desplegar cualquier modelo y exponerlo como una API privada. Una vez desplegado, obtendrás una URL a la que puedes conectarte utilizando exactamente el mismo código que antes, cambiando solo el parámetro `model`:

```python
>>> 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](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.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.

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

> [!TIP]
> De manera similar al cliente de Python de OpenAI, [InferenceClient](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.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](https://huggingface.co/docs/hub/security-tokens). Puede proporcionar su token de Hugging Face directamente usando el parámetro `api_key`:

```python
>>> 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](https://huggingface.co/docs/huggingface_hub/quick-start#authentication) para obtener detalles sobre el inicio de sesión.

```python
>>> 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:
```python
>>> client = InferenceClient(
    provider="replicate",
    api_key="r8_****"  # Your Replicate API key
)
```

Para más detalles, consulte la [documentación de precios de Inference Providers](https://huggingface.co/docs/inference-providers/pricing#routed-requests-vs-direct-calls).

## Proveedores y tareas compatibles

El objetivo de [InferenceClient](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.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()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.audio_classification)           | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [audio_to_audio()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.audio_to_audio)                 | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [automatic_speech_recognition()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.automatic_speech_recognition)   | ❌      | ❌        | ❌      | ✅         | ✅      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ✅         | ❌        | ❌        | ❌         | ❌   |
| [chat_completion()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion)                | ✅      | ✅        | ✅      | ✅         | ❌      | ✅              | ✅            | ✅    | ✅            | ✅         | ✅      | ✅                     | ✅         | ❌         | ✅        | ✅        | ❌         | ✅   |
| [document_question_answering()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.document_question_answering)    | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [feature_extraction()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.feature_extraction)             | ❌      | ❌        | ❌      | ✅         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ✅        | ✅        | ❌         | ❌   |
| [fill_mask()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.fill_mask)                      | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [image_classification()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.image_classification)           | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [image_segmentation()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.image_segmentation)             | ❌      | ❌        | ❌      | ❌         | ✅      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [image_to_image()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.image_to_image)                 | ❌      | ❌        | ❌      | ❌         | ✅      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ✅         | ❌        | ✅        | ✅         | ❌   |
| [image_to_video()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.image_to_video)                 | ❌      | ❌        | ❌      | ❌         | ✅      | ❌              | ❌            | ❌    | ❌            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ✅        | ✅         | ❌   |
| [image_to_text()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.image_to_text)                  | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [object_detection()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.object_detection)               | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [question_answering()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.question_answering)             | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [sentence_similarity()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.sentence_similarity)            | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [summarization()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.summarization)                  | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [table_question_answering()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.table_question_answering)       | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [text_classification()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.text_classification)            | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [text_generation()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.text_generation)                | ❌      | ❌        | ❌      | ✅         | ❌      | ✅              | ❌            | ❌    | ✅            | ✅         | ❌      | ❌                     | ❌         | ❌         | ❌        | ✅        | ❌         | ❌   |
| [text_to_image()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_image)                  | ❌      | ❌        | ❌      | ❌         | ✅      | ❌              | ❌            | ❌    | ✅            | ❌         | ✅      | ❌                     | ❌         | ✅         | ❌        | ✅        | ✅         | ✅   |
| [text_to_speech()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_speech)                 | ❌      | ❌        | ❌      | ✅         | ✅      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ✅         | ❌        | ✅        | ❌         | ❌   |
| [text_to_video()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.text_to_video)                  | ❌      | ❌        | ❌      | ❌         | ✅      | ❌              | ❌            | ❌    | ❌            | ✅         | ❌      | ❌                     | ❌         | ✅         | ❌        | ✅        | ✅         | ❌   |
| [tabular_classification()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.tabular_classification)         | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [tabular_regression()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.tabular_regression)             | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [token_classification()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.token_classification)           | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [translation()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.translation)                    | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [visual_question_answering()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.visual_question_answering)      | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [zero_shot_image_classification()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.zero_shot_image_classification) | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |
| [zero_shot_classification()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.zero_shot_classification)       | ❌      | ❌        | ❌      | ❌         | ❌      | ❌              | ❌            | ❌    | ✅            | ❌         | ❌      | ❌                     | ❌         | ❌         | ❌        | ❌        | ❌         | ❌   |

> [!TIP]
> Consulta la página [Tasks](https://huggingface.co/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](https://github.com/openai/openai-python). ¿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.

```diff
- 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](https://huggingface.co/models?pipeline_tag=text-generation&other=conversational,text-generation-inference&sort=trending) de los modelos compatibles. Para la autenticación, debes pasar un [User Access Token](https://huggingface.co/settings/tokens) válido como `api_key` o autenticarte usando `huggingface_hub` (consulta la [guía de autenticación](https://huggingface.co/docs/huggingface_hub/quick-start#authentication)).

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](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.AsyncInferenceClient) para ejecutar inferencia con `asyncio`:

```diff
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](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient) en lugar del cliente de OpenAI. Hay varias razones para ello:
1. [InferenceClient](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.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.
2. [InferenceClient](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.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.
3. [InferenceClient](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.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](./inference_endpoints) para más detalles.

> [!TIP]
> `InferenceClient.chat.completions.create` es simplemente un alias de `InferenceClient.chat_completion`. Consulte la referencia del paquete de [chat_completion()](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient.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](https://novita.ai/) como proveedor de inferencia:

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

```

> [!TIP]
> 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](https://www.cerebras.ai/) como proveedor de inferencia:

```python
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)
```
> [!TIP]
> 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](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.AsyncInferenceClient). Su inicialización y APIs son estrictamente las mismas que las de la versión solo síncrona.

```py
# 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](https://docs.python.org/3/library/asyncio.html).

## Cliente MCP

La biblioteca `huggingface_hub` incluye ahora un [MCPClient](/docs/huggingface_hub/v2.4.0/es/package_reference/mcp#huggingface_hub.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](https://modelcontextprotocol.io) (MCP). Este cliente extiende un [AsyncInferenceClient](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.AsyncInferenceClient) para integrar el uso de Herramientas de manera fluida.

El [MCPClient](/docs/huggingface_hub/v2.4.0/es/package_reference/mcp#huggingface_hub.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](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.AsyncInferenceClient)). Si el LLM decide utilizar una herramienta, [MCPClient](/docs/huggingface_hub/v2.4.0/es/package_reference/mcp#huggingface_hub.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](https://huggingface.co/Qwen/Qwen2.5-72B-Instruct) a través del proveedor de inferencia [Novita](https://novita.ai/). 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.

```python
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](/docs/huggingface_hub/v2.4.0/es/package_reference/mcp#huggingface_hub.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](/docs/huggingface_hub/v2.4.0/es/package_reference/mcp#huggingface_hub.MCPClient). Está diseñado para ser un simple bucle while construido directamente sobre un [MCPClient](/docs/huggingface_hub/v2.4.0/es/package_reference/mcp#huggingface_hub.MCPClient). Puede ejecutar estos agentes directamente desde la línea de comandos:

```bash
# 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](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.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](https://huggingface.co/docs/api-inference/pricing#features-using-inference-providers).

```py
>>> 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](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.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](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceTimeoutError), que puede capturar en su código:

```python
>>> 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](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.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
que se envían a la API.

```py
>>> 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'}, ...]
```