# 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](https://github.com/huggingface/huggingface_hub/issues). ## 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`](https://www.python-httpx.org/) 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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.set_client_factory) e [set_async_client_factory()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.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](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.errors.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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.set_async_client_factory). Para mais detalhes, você pode verificar o [PR #3328](https://github.com/huggingface/huggingface_hub/pull/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`](../package_reference/environment_variables) em vez disso. ## classe `Repository` 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`: | Método `Repository` | método `HfApi` | | ------------------------------------------ | ----------------------------------------------------- | | `repo.clone_from` | `snapshot_download` | | `repo.git_add` + `git_commit` + `git_push` | [upload_file()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_file), [upload_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_folder), [create_commit()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.create_commit) | | `repo.git_tag` | `create_tag` | | `repo.git_branch` | `create_branch` | ## classe `HfFolder` `HfFolder` era usado para gerenciar o token de acesso do usuário. Use [login()](/docs/huggingface_hub/v2.4.0/pt/package_reference/authentication#huggingface_hub.login) para salvar um novo token, [logout()](/docs/huggingface_hub/v2.4.0/pt/package_reference/authentication#huggingface_hub.logout) para excluí-lo e [whoami()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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](/docs/huggingface_hub/v2.4.0/pt/package_reference/inference_client#huggingface_hub.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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.upload_file) e [upload_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.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()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.create_commit), [delete_file()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.delete_file) e [delete_folder()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.delete_folder).