Hub Python Library documentation
Execute Inferência em servidores
Execute Inferência em servidores
Inferência é o processo de usar um modelo treinado para fazer previsões em novos dados. Como esse processo pode ser intensivo em computação, executá-lo em um serviço dedicado ou externo pode ser uma opção interessante.
A biblioteca huggingface_hub fornece uma interface unificada para executar inferência em vários serviços para modelos hospedados no Hugging Face Hub:
- Provedores de Inferência: acesso simplificado e unificado a centenas de modelos de machine learning, impulsionado por nossos parceiros de inferência serverless. Essa nova abordagem se baseia na nossa anterior API de Inferência Serverless, oferecendo mais modelos, desempenho aprimorado e maior confiabilidade graças a provedores de classe mundial. Consulte a documentação para obter a lista de provedores suportados.
- Inference Endpoints: um produto para implantar modelos em produção com facilidade. A inferência é executada pela Hugging Face em uma infraestrutura dedicada e totalmente gerenciada em um provedor de nuvem de sua escolha.
- Endpoints locais: você também pode executar inferência com servidores de inferência locais, como llama.cpp, Ollama, vLLM, LiteLLM ou Text Generation Inference (TGI), conectando o cliente a esses endpoints locais.
InferenceClient é um cliente em Python que faz chamadas HTTP para nossas APIs. Se você quiser fazer as chamadas HTTP diretamente usando sua ferramenta preferida (curl, postman, ...), consulte a documentação de Inference Providers ou as páginas de documentação de Inference Endpoints.
Para desenvolvimento web, um cliente JS foi lançado. Se você tem interesse em desenvolvimento de jogos, pode dar uma olhada no nosso projeto em C#.
Começando
Vamos começar com uma tarefa de texto para imagem:
>>> 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")
No exemplo acima, inicializamos um InferenceClient com um provedor de terceiros, Replicate. Ao usar um provedor, você deve especificar o modelo que deseja usar. O id do modelo deve ser o id do modelo no Hugging Face Hub, não o id do modelo do provedor de terceiros.
No nosso exemplo, geramos uma imagem a partir de um prompt de texto. O valor retornado é um objeto PIL.Image que pode ser salvo em um arquivo. Para mais detalhes, consulte a documentação de text_to_image().
Vamos agora ver um exemplo usando a API chat_completion(). Esta tarefa usa um LLM para gerar uma resposta a partir de uma lista de mensagens:
>>> 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),
)No exemplo acima, usamos um provedor de terceiros (Together AI) e especificamos qual modelo queremos usar ("meta-llama/Meta-Llama-3-8B-Instruct"). Em seguida, fornecemos uma lista de mensagens para completar (aqui, uma única pergunta) e passamos um parâmetro adicional para a API (max_token=100). A saída é um objeto ChatCompletionOutput que segue a especificação da OpenAI. O conteúdo gerado pode ser acessado com output.choices[0].message.content. Para mais detalhes, consulte a documentação de chat_completion().
A API foi projetada para ser simples. Nem todos os parâmetros e opções estão disponíveis ou descritos para o usuário final. Consulte esta página se você estiver interessado em aprender mais sobre todos os parâmetros disponíveis para cada tarefa.
Usando um provedor específico
Se você deseja usar um provedor específico, pode especificá-lo ao inicializar o cliente. O valor padrão é “auto”, que selecionará o primeiro dos provedores disponíveis para o modelo, ordenados pela ordem do usuário em https://hf.co/settings/inference-providers. Consulte a seção Provedores e tarefas suportados para obter uma lista dos provedores suportados.
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(provider="replicate", api_key="my_replicate_api_key")Usando um modelo específico
E se você quiser usar um modelo específico? Você pode especificá-lo como um parâmetro ou diretamente em nível de instância:
>>> 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")Ao usar o provedor “hf-inference”, cada tarefa vem com um modelo recomendado entre os mais de 1M de modelos disponíveis no Hub. No entanto, essa recomendação pode mudar com o tempo, então é melhor definir explicitamente um modelo assim que você decidir qual usar. Para provedores de terceiros, você deve sempre especificar um modelo compatível com aquele provedor.
Acesse a página Models no Hub para explorar os modelos disponíveis por meio dos Inference Providers.
Usando Inference Endpoints
Os exemplos que vimos acima usam provedores de inferência. Embora sejam muito úteis para prototipagem e testes rápidos, quando estiver pronto para implantar seu modelo em produção, será necessário usar uma infraestrutura dedicada. É aí que os Inference Endpoints entram em ação. Eles permitem implantar qualquer modelo e expô-lo como uma API privada. Após a implantação, você receberá uma URL à qual pode se conectar usando exatamente o mesmo código de antes, alterando apenas o 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")Observe que você não pode especificar simultaneamente uma URL e um provedor - eles são mutuamente exclusivos. As URLs são usadas para se conectar diretamente a endpoints implantados.
Usando endpoints locais
Você pode usar InferenceClient para executar chat completion com servidores de inferência locais (llama.cpp, vllm, litellm server, TGI, mlx, etc.) rodando na sua própria máquina. A API deve ser compatível com a OpenAI API.
>>> 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 forma semelhante ao cliente Python da OpenAI, o InferenceClient pode ser usado para executar inferência de Chat Completion em qualquer endpoint compatível com a API REST da OpenAI.
Autenticação
A autenticação pode ser feita de duas maneiras:
Roteado através do Hugging Face : Use o Hugging Face como proxy para acessar provedores de terceiros. As chamadas serão roteadas pela infraestrutura do Hugging Face usando as chaves dos nossos provedores, e o uso será cobrado diretamente na sua conta do Hugging Face.
Você pode autenticar usando um User Access Token. Você pode fornecer seu token do Hugging Face diretamente usando o parâmetro api_key:
>>> client = InferenceClient(
provider="replicate",
api_key="hf_****" # Your HF token
)Se você não passar uma api_key, o cliente tentará encontrar e usar um token armazenado localmente na sua máquina. Isso geralmente acontece se você já fez login anteriormente. Consulte o Guia de Autenticação para obter detalhes sobre o login.
>>> client = InferenceClient(
provider="replicate",
token="hf_****" # Your HF token
)Acesso direto ao provedor: Use sua própria chave de API para interagir diretamente com o serviço do provedor:
>>> client = InferenceClient(
provider="replicate",
api_key="r8_****" # Your Replicate API key
)Para mais detalhes, consulte a documentação de preços dos Inference Providers.
Provedores e tarefas suportados
O objetivo do InferenceClient é fornecer a interface mais simples para executar inferência em modelos do Hugging Face, em qualquer provedor. Ele possui uma API simples que suporta as tarefas mais comuns. A seguir, uma tabela mostrando quais provedores suportam quais tarefas:
| Tarefa | 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() | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
Confira a página Tarefas para saber mais sobre cada tarefa.
Compatibilidade com a OpenAI
A tarefa chat_completion segue a sintaxe do cliente Python da OpenAI. O que isso significa para você? Significa que, se você está acostumado a trabalhar com as APIs da OpenAI, poderá alternar para o huggingface_hub.InferenceClient para trabalhar com modelos de código aberto atualizando apenas 2 linhas 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)E é isso! As únicas alterações obrigatórias são substituir from openai import OpenAI por from huggingface_hub import InferenceClient e client = OpenAI(...) por client = InferenceClient(...). Você pode escolher qualquer modelo de LLM do Hugging Face Hub passando seu id de modelo como parâmetro model. Aqui está uma lista dos modelos suportados. Para autenticação, você deve passar um User Access Token válido como api_key ou autenticar usando huggingface_hub (veja o guia de autenticação).
Todos os parâmetros de entrada e o formato de saída são estritamente os mesmos. Em particular, você pode passar stream=True para receber os tokens à medida que são gerados. Você também pode usar o AsyncInferenceClient para executar inferência usando 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())Você pode se perguntar por que usar o InferenceClient em vez do cliente da OpenAI? Há algumas razões para isso:
- InferenceClient é configurado para os serviços da Hugging Face. Você não precisa fornecer um
base_urlpara executar modelos com os Inference Providers. Também não é necessário fornecer umtokenouapi_keyse sua máquina já estiver corretamente conectada. - InferenceClient foi desenvolvido para os frameworks Text-Generation-Inference (TGI) e
transformers, o que garante que ele estará sempre alinhado com as atualizações mais recentes. - InferenceClient é integrado ao nosso serviço de Inference Endpoints, facilitando a criação de um Inference Endpoint, a verificação de seu status e a execução de inferência nele. Consulte o guia de Inference Endpoints para mais detalhes.
InferenceClient.chat.completions.createé simplesmente um alias paraInferenceClient.chat_completion. Consulte a referência do pacote de chat_completion() para mais detalhes. Os parâmetrosbase_urleapi_keyao instanciar o cliente também são aliases paramodeletoken. Esses aliases foram definidos para reduzir a fricção ao migrar doOpenAIpara oInferenceClient.
Chamada de Função
O function calling permite que LLMs interajam com ferramentas externas, como funções definidas ou APIs. Isso permite que os usuários construam facilmente aplicações adaptadas a casos de uso específicos e tarefas do mundo real. InferenceClient implementa a mesma interface de tool calling que a API de Chat Completions da OpenAI. Aqui está um exemplo simples de tool calling usando Novita como provedor de inferência:
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 a documentação dos provedores para verificar quais modelos são suportados por eles para Function/Tool Calling.
Saídas Estruturadas & Modo JSON
O InferenceClient suporta o modo JSON para respostas JSON sintaticamente válidas e Structured Outputs para respostas com esquema aplicado. O modo JSON fornece dados legíveis por máquina sem uma estrutura estrita, enquanto o Structured Outputs garante tanto o JSON válido quanto a aderência a um esquema predefinido para um processamento subsequente confiável.
Seguimos as especificações da API da OpenAI tanto para o modo JSON quanto para Structured Outputs. Você pode ativá-los por meio do argumento response_format. Aqui está um exemplo de Structured Outputs usando Cerebras como provedor de inferência:
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 a documentação dos provedores para verificar quais modelos são suportados por eles para Structured Outputs e JSON Mode.
Cliente assíncrono
Também é fornecida uma versão assíncrona do cliente, baseada em asyncio e httpx2. Todos os endpoints de API assíncronos estão disponíveis por meio de AsyncInferenceClient. Sua inicialização e APIs são estritamente as mesmas da versão apenas 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 mais informações sobre o módulo asyncio, consulte a documentação oficial.
Cliente MCP
A biblioteca huggingface_hub agora inclui um MCPClient experimental, projetado para capacitar Modelos de Linguagem de Grande Escala (LLMs) com a capacidade de interagir com Ferramentas externas por meio do Model Context Protocol (MCP). Este cliente estende um AsyncInferenceClient para integrar o uso de Ferramentas de forma transparente.
O MCPClient se conecta a servidores MCP (seja scripts locais stdio ou serviços remotos http/sse) que expõem ferramentas. Ele fornece essas ferramentas a um LLM (via AsyncInferenceClient). Se o LLM decidir usar uma ferramenta, o MCPClient gerencia a solicitação de execução ao servidor MCP e repassa a saída da ferramenta de volta ao LLM, frequentemente transmitindo os resultados em tempo real.
No exemplo a seguir, usamos o modelo Qwen/Qwen2.5-72B-Instruct por meio do provedor de inferência Novita. Em seguida, adicionamos um servidor MCP remoto, neste caso, um servidor SSE que disponibilizou a ferramenta de geração de imagens Flux para o 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://huggingface.co/proxy/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 um desenvolvimento ainda mais simples, oferecemos uma classe Agent de nível superior. Este ‘Tiny Agent’ simplifica a criação de Agentes conversacionais ao gerenciar o loop de chat e o estado, atuando essencialmente como um wrapper ao redor de MCPClient. Ele foi projetado para ser um simples loop while construído diretamente sobre um MCPClient. Você pode executar esses Agentes diretamente pela linha de comando:
# 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
Ao ser iniciado, o Agent carregará e listará as Tools que ele descobriu em seus servidores MCP conectados, e então estará pronto para receber seus prompts!
Dicas avançadas
Na seção acima, vimos os principais aspectos do InferenceClient. Vamos explorar algumas dicas mais avançadas.
Faturamento
Como usuário do HF, você recebe créditos mensais para executar inferência por meio de vários provedores no Hub. A quantidade de créditos que você recebe depende do tipo da sua conta (Free ou PRO ou Enterprise Hub). Você é cobrado por cada solicitação de inferência, de acordo com a tabela de preços do provedor. Por padrão, as solicitações são faturadas para a sua conta pessoal. No entanto, é possível configurar o faturamento para que as solicitações sejam cobradas de uma organização da qual você faz parte, simplesmente passando bill_to="<your_org_name>" para InferenceClient. Para que isso funcione, sua organização deve estar assinante do Enterprise Hub. Para mais detalhes sobre faturamento, confira este guia.
>>> 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")Observe que NÃO é possível cobrar outro usuário ou uma organização da qual você não faz parte. Se você deseja conceder créditos a outra pessoa, deve criar uma organização conjunta com ela.
Timeout
Chamadas de inferência podem levar um tempo considerável. Por padrão, o InferenceClient aguarda “indefinidamente” até que a inferência seja concluída. Se você deseja mais controle no seu fluxo de trabalho, pode definir o parâmetro timeout para um valor específico em segundos. Se o tempo limite expirar, uma InferenceTimeoutError é lançada, que você pode capturar no seu 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 binárias
Algumas tarefas exigem entradas binárias, por exemplo, ao lidar com imagens ou arquivos de áudio. Nesse caso, o InferenceClient tenta ser o mais permissivo possível e aceitar diferentes tipos:
bytesbruto- um objeto semelhante a arquivo, aberto como binário (
with open("audio.flac", "rb") as f: ...) - um caminho (
strouPath) apontando para um arquivo local - uma URL (
str) apontando para um arquivo remoto (por exemplo,https://...). Nesse caso, o arquivo será baixado localmente antes de ser enviado para a 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'}, ...]