Migrando para o huggingface_hub v1.0

O lançamento da v1.0 é um marco importante para a biblioteca huggingface_hub. Ele marca nosso compromisso com a estabilidade da API e a maturidade da biblioteca. Fizemos várias melhorias e alterações que quebram a compatibilidade para tornar a biblioteca mais robusta e fácil de usar.

Este guia tem como objetivo ajudá-lo a migrar seu código existente para a nova versão. Se você tiver alguma dúvida ou feedback, por favor, nos informe abrindo uma issue no GitHub.

Python 3.9+

huggingface_hub agora requer Python 3.9 ou superior. O Python 3.8 não é mais suportado.

Migração para HTTPX

A biblioteca huggingface_hub agora usa httpx em vez de requests para requisições HTTP. Essa mudança foi feita para melhorar o desempenho e para suportar requisições síncronas e assíncronas da mesma forma. Portanto, removemos as dependências de requests e aiohttp.

Alterações que quebram a compatibilidade

Esta é uma mudança significativa que afeta toda a biblioteca. Embora tenhamos tentado tornar essa mudança o mais transparente possível, em alguns casos você pode precisar atualizar seu código. Aqui está uma lista das mudanças que quebram a compatibilidade introduzidas no processo:

• Configuração de proxy: os proxies “por método” não são mais suportados. Os proxies devem ser configurados globalmente usando as variáveis de ambiente HTTP_PROXY e HTTPS_PROXY.
• Backend HTTP personalizado: a função configure_http_backend foi removida. Agora você deve usar set_client_factory() e set_async_client_factory() para configurar os clientes HTTP.
• Tratamento de erros: os erros HTTP não são mais herdados de requests.HTTPError, mas de httpx.HTTPError. Recomendamos capturar HfHubHTTPError (importado com from huggingface_hub.utils import HfHubHTTPError), que é uma subclasse de requests.HTTPError na v0.x e de httpx.HTTPError na v1.x. Capturar a partir do erro do huggingface_hub garante que seu código seja compatível com ambas as versões, antiga e nova, da biblioteca.
• SSLError: o httpx não possui o conceito de SSLError. Agora é um httpx.ConnectError genérico.
• LocalEntryNotFoundError: Este erro não herda mais de HTTPError. Agora definimos um EntryNotFoundError (novo) que é herdado tanto por LocalEntryNotFoundError (se o arquivo não for encontrado no cache local) quanto por RemoteEntryNotFoundError (se o arquivo não for encontrado no repositório no Hub). Apenas o erro remoto herda de HTTPError.
• InferenceClient: o InferenceClient agora pode ser usado como um gerenciador de contexto. Isso é especialmente útil ao transmitir tokens de um modelo de linguagem, garantindo que a conexão seja fechada corretamente.
• AsyncInferenceClient: O parâmetro trust_env foi removido do construtor do AsyncInferenceClient. As variáveis de ambiente são confiadas por padrão pelo httpx. Se você explicitamente não deseja confiar no ambiente, deve configurá-lo com set_async_client_factory().

Para mais detalhes, você pode verificar o PR #3328 que introduziu o httpx.

Por que httpx?

A migração de requests para httpx traz várias melhorias importantes que aprimoram o desempenho, a confiabilidade e a manutenibilidade da biblioteca:

Segurança de threads e reutilização de conexões: httpx é seguro para threads por design, permitindo reutilizar o mesmo cliente com segurança entre múltiplas threads. Essa reutilização de conexões reduz o sobrecusto de estabelecer novas conexões para cada requisição HTTP, melhorando o desempenho, especialmente ao fazer requisições frequentes ao Hub.

Suporte a HTTP/2: httpx oferece suporte nativo a HTTP/2, o que proporciona maior eficiência ao realizar múltiplas requisições ao mesmo servidor (exatamente nosso caso de uso). Isso se traduz em menor latência e menor consumo de recursos em comparação com o HTTP/1.1.

API unificada de sincronização/assincronização: Diferentemente da nossa configuração anterior, que usava dependências separadas de requests (síncrona) e aiohttp (assíncrona), o httpx fornece clientes síncronos e assíncronos com comportamento idêntico. Isso garante que InferenceClient e AsyncInferenceClient tenham funcionalidade consistente e elimina as sutis diferenças de comportamento que existiam anteriormente entre as duas implementações.

Tratamento aprimorado de erros de SSL: httpx trata erros de SSL de forma mais adequada, facilitando e tornando mais confiável a depuração de problemas de conexão.

Arquitetura à prova do futuro: httpx é ativamente mantido e projetado para aplicações Python modernas. Em contraste, requests está em modo de manutenção e não receberá atualizações importantes, como melhorias de segurança de threads ou suporte a HTTP/2.

Tratamento aprimorado de variáveis de ambiente: httpx oferece um tratamento mais consistente de variáveis de ambiente em ambos os contextos, síncrono e assíncrono, eliminando as inconsistências anteriores em que requests lia variáveis de ambiente locais por padrão, enquanto aiohttp não o fazia.

A transição para httpx posiciona o huggingface_hub com um backend HTTP moderno, eficiente e fácil de manter. Embora a maioria dos usuários deva ter uma operação sem interrupções, as melhorias subjacentes proporcionam melhor desempenho e confiabilidade para todas as interações com o Hub.

hf_transfer

Agora que todos os repositórios no Hub têm suporte a Xet e que hf_xet é o método padrão para baixar/enviar arquivos, removemos o suporte ao pacote opcional hf_transfer. A variável de ambiente HF_HUB_ENABLE_HF_TRANSFER é, portanto, ignorada. Use HF_XET_HIGH_PERFORMANCE em vez disso.

Classe de repositório

A classe Repository foi removida na v1.0. Ela era um wrapper fino em torno do CLI git para gerenciar repositórios. Você ainda pode usar o git diretamente no terminal, mas a abordagem recomendada é usar a API baseada em HTTP na biblioteca huggingface_hub para uma experiência mais suave, especialmente ao lidar com arquivos grandes.

Aqui está um mapeamento da classe legada Repository para a nova classe HfApi:

Classe HfFolder

HfFolder era usado para gerenciar o token de acesso do usuário. Use login() para salvar um novo token, logout() para excluí-lo e whoami() para verificar o usuário associado ao token atual. Por fim, use get_token() para recuperar o token do usuário em um script.

Classe InferenceApi

InferenceApi era uma classe para interagir com a Inference API. Agora, recomenda-se usar a classe InferenceClient em seu lugar.

Outros recursos obsoletos

Alguns métodos e parâmetros foram removidos na v1.0. Os listados abaixo já haviam sido descontinuados com uma mensagem de aviso na v0.x.

• constants.hf_cache_home foi removido. Use HF_HOME em vez disso.
• Os parâmetros use_auth_token foram removidos de todos os métodos. Use token em vez disso.
• O método get_token_permission foi removido.
• O método update_repo_visibility foi removido. Use update_repo_settings em vez disso.
• O parâmetro is_write_action foi removido de build_hf_headers, assim como write_permission de login. O conceito de “permissão de escrita” foi removido e não é mais relevante, agora que os tokens de granularidade fina são a abordagem recomendada.
• O parâmetro new_session em login foi renomeado para skip_if_logged_in para maior clareza.
• Os parâmetros resume_download, force_filename e local_dir_use_symlinks foram removidos de hf_hub_download e snapshot_download.
• Os parâmetros library, language, tags e task foram removidos de list_models.

Comandos de cache da CLI

A gestão de cache pela CLI foi redesenhada para seguir um fluxo inspirado no Docker. O huggingface-cli obsoleto foi removido e o hf (introduzido na v0.34) o substitui com uma CLI de recurso-ação mais clara. Os comandos legados hf cache scan e hf cache delete também foram removidos na v1.0 e substituídos pelo novo trio abaixo:

• hf cache ls lista as entradas do cache em uma tabela concisa, com saída em JSON ou CSV. Use --revisions para inspecionar revisões individuais, adicione expressões de --filter como size>1GB ou accessed>30d e combine-as com --quiet quando você precisar apenas dos identificadores.
• hf cache rm remove as entradas de cache selecionadas. Passe um ou mais IDs de repositório (por exemplo, model/bert-base-uncased) ou hashes de revisão e, opcionalmente, adicione --dry-run para visualizar ou --yes para pular o prompt de confirmação. Isso substitui tanto o fluxo interativo do TUI quanto o fluxo --disable-tui do comando anterior.
• hf cache prune executa a tarefa comum de limpeza de excluir revisões não referenciadas de uma só vez. Adicione --dry-run ou --yes da mesma forma que com hf cache rm.

Por fim, o extra [cli] foi removido - o CLI agora é distribuído com o pacote principal huggingface_hub.

Suporte a TensorFlow e Keras 2.x

Todo o código e as dependências relacionados ao TensorFlow foram removidos na v1.0. Isso inclui as seguintes alterações incompatíveis:

• huggingface_hub[tensorflow] não é mais uma dependência extra suportada
• As funções utilitárias split_tf_state_dict_into_shards e get_tf_storage_size foram removidas.
• As versões tensorflow, fastai e fastcore não estão mais incluídas nos cabeçalhos embutidos.

A integração com o Keras 2.x também foi removida. Isso inclui a classe KerasModelHubMixin e as utilitários save_pretrained_keras, from_pretrained_keras e push_to_hub_keras. O Keras 2.x é uma biblioteca legada e sem manutenção. A abordagem recomendada é usar o Keras 3.x, que possui integração estreita com o Hub (ou seja, contém métodos embutidos para carregar/enviar para o Hub). Se você ainda deseja trabalhar com o Keras 2.x, deve fazer o downgrade do huggingface_hub para uma versão v0.x.

valores retornados por upload_file e upload_folder

As funções upload_file() e upload_folder() agora retornam a URL do commit criado no Hub. Anteriormente, elas retornavam a URL do arquivo ou da pasta. Isso foi feito para alinhar com o valor de retorno de create_commit(), delete_file() e delete_folder().