# Integre sua biblioteca com o Hub

O Hugging Face Hub tem como objetivo facilitar o compartilhamento de modelos de aprendizado de máquina, checkpoints e artefatos. Esse esforço inclui a integração do Hub em muitas das incríveis bibliotecas de terceiros da comunidade. Algumas das que já foram integradas incluem [spaCy](https://spacy.io/usage/projects#huggingface_hub), [Sentence Transformers](https://sbert.net/), [OpenCLIP](https://github.com/mlfoundations/open_clip) e [timm](https://huggingface.co/docs/timm/index), entre muitas outras. A integração significa que os usuários podem baixar e enviar arquivos para o Hub diretamente da sua biblioteca. Esperamos que você integre sua biblioteca e se junte a nós na democratização da inteligência artificial para todos.

A integração do Hub com sua biblioteca oferece muitos benefícios, incluindo:

- Hospedagem gratuita de modelos para você e seus usuários.
- Versionamento de arquivos integrado - mesmo para arquivos enormes - viabilizado pelo [Git-Xet](./xet/using-xet-storage#git-xet).
- Recursos da comunidade (discussões, pull requests, curtidas).
- Métricas de uso de todos os modelos executados com sua biblioteca.

Este tutorial ajudará você a integrar o Hub à sua biblioteca para que seus usuários possam se beneficiar de todos os recursos oferecidos pelo Hub.

Antes de começar, recomendamos que você crie uma [conta do Hugging Face](https://huggingface.co/join) para gerenciar seus repositórios e arquivos.

Se você precisar de ajuda com a integração, sinta-se à vontade para abrir um [issue](https://github.com/huggingface/huggingface_hub/issues/new/choose) e teremos todo o prazer em ajudá-lo.

## Implementação

Implementar uma integração de uma biblioteca com o Hub geralmente significa fornecer métodos embutidos para carregar modelos do Hub e permitir que os usuários enviem novos modelos para o Hub. Esta seção abordará os fundamentos de como fazer isso usando a biblioteca `huggingface_hub`. Para orientações mais detalhadas, consulte [este guia](https://huggingface.co/docs/huggingface_hub/guides/integrations).

### Instalação

Para integrar sua biblioteca ao Hub, você precisará adicionar a biblioteca `huggingface_hub` como uma dependência:

```bash
pip install huggingface_hub
```

Para mais detalhes sobre a instalação do `huggingface_hub`, confira [este guia](https://huggingface.co/docs/huggingface_hub/installation).

> [!TIP]
> Neste guia, focaremos em bibliotecas Python. Se você implementou sua biblioteca em JavaScript, pode usar [`@huggingface/hub`](https://www.npmjs.com/package/@huggingface/hub) no lugar. O restante da lógica (ou seja, hospedagem de arquivos, exemplos de código, etc.) não depende da linguagem de código.
>
> ```
> npm add @huggingface/hub
> ```

Os usuários precisarão se autenticar após instalarem com sucesso a biblioteca `huggingface_hub`. A maneira mais fácil de autenticar é salvar o token na máquina. Os usuários podem fazer isso pelo terminal usando o comando `login()`:

```
hf auth login
```

O comando informa se eles já estão conectados e solicita o token. O token é então validado e salvo no diretório `HF_HOME` (padrão: `~/.cache/huggingface/token`). Qualquer script ou biblioteca que interaja com o Hub usará esse token ao enviar solicitações.

Alternativamente, os usuários podem fazer login programaticamente usando `login()` em um notebook ou script:

```py
from huggingface_hub import login
login()
```

A autenticação é opcional ao baixar arquivos de repositórios públicos no Hub.

### Baixar arquivos do Hub

Integrações permitem que os usuários baixem um modelo do Hub e o instanciem diretamente a partir da sua biblioteca. Isso geralmente é viabilizado ao fornecer um método (geralmente chamado de `from_pretrained` ou `load_from_hf`) que deve ser específico para a sua biblioteca. Para instanciar um modelo do Hub, a sua biblioteca deve:
- baixar arquivos do Hub. É sobre isso que vamos falar agora.
- instanciar o modelo Python a partir desses arquivos.

Use o método [`hf_hub_download`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.hf_hub_download) para baixar arquivos de um repositório no Hub. Os arquivos baixados são armazenados no cache: `~/.cache/huggingface/hub`. Os usuários não precisarão baixar o arquivo novamente na próxima vez que o utilizarem, o que economiza muito tempo para arquivos grandes. Além disso, se o repositório for atualizado com uma nova versão do arquivo, o `huggingface_hub` baixará automaticamente a versão mais recente e a armazenará no cache. Os usuários não precisam se preocupar em atualizar seus arquivos manualmente.

Por exemplo, baixe o arquivo `config.json` do repositório [lysandre/arxiv-nlp](https://huggingface.co/lysandre/arxiv-nlp):

```python
>>> from huggingface_hub import hf_hub_download
>>> config_path = hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
>>> config_path
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'
```

`config_path` agora contém um caminho para o arquivo baixado. É garantido que o arquivo existe e está atualizado.

Se a sua biblioteca precisa baixar um repositório inteiro, use [`snapshot_download`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.snapshot_download). Ele cuidará do download de todos os arquivos em paralelo. O valor retornado é um caminho para o diretório contendo os arquivos baixados.

```py
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'
```

Existem muitas opções para baixar arquivos de uma revisão específica, filtrar quais arquivos baixar, fornecer um diretório de cache personalizado, baixar para um diretório local, etc. Consulte o [guia de download](https://huggingface.co/docs/huggingface_hub/en/guides/download) para mais detalhes.

### Envie arquivos para o Hub

Você também pode querer fornecer um método para que os usuários possam enviar seus próprios modelos para o Hub. Isso permite que a comunidade construa um ecossistema de modelos compatíveis com a sua biblioteca. A biblioteca `huggingface_hub` oferece métodos para criar repositórios e enviar arquivos:

- `create_repo` cria um repositório no Hub.
- `upload_file` e `upload_folder` enviam arquivos para um repositório no Hub.

O método `create_repo` cria um repositório no Hub. Use o parâmetro `repo_id` para fornecer um nome para o seu repositório:

```python
>>> from huggingface_hub import create_repo
>>> create_repo(repo_id="test-model")
'https://huggingface.co/lysandre/test-model'
```

Ao verificar sua conta do Hugging Face, você deve agora ver um repositório `test-model` sob seu namespace.

O método [`upload_file`](https://huggingface.co/docs/huggingface_hub/en/package_reference/hf_api#huggingface_hub.HfApi.upload_file) faz o upload de um arquivo para o Hub. Este método requer o seguinte:

- Um caminho para o arquivo a ser enviado.
- O caminho final no repositório.
- O repositório para o qual você deseja enviar os arquivos.

Por exemplo:

```python
>>> from huggingface_hub import upload_file
>>> upload_file(
...    path_or_fileobj="/home/lysandre/dummy-test/README.md", 
...    path_in_repo="README.md", 
...    repo_id="lysandre/test-model"
... )
'https://huggingface.co/lysandre/test-model/blob/main/README.md'
```

Se você verificar sua conta do Hugging Face, deve ver o arquivo dentro do seu repositório.

Normalmente, uma biblioteca serializa o modelo em um diretório local e, em seguida, envia a pasta inteira para o Hub de uma só vez. Isso pode ser feito usando [`upload_folder`](https://huggingface.co/docs/huggingface_hub/en/package_reference/hf_api#huggingface_hub.HfApi.upload_folder):

```py
>>> from huggingface_hub import upload_folder
>>> upload_folder(
...     folder_path="/home/lysandre/dummy-test",
...     repo_id="lysandre/test-model",
... )
```

Para mais detalhes sobre como enviar arquivos, consulte o [guia de upload](https://huggingface.co/docs/huggingface_hub/en/guides/upload).

## Cartões de modelo

Model cards são arquivos que acompanham os modelos e fornecem informações úteis. Por baixo dos panos, model cards são arquivos Markdown simples com metadados adicionais. Model cards são essenciais para descoberta, reprodutibilidade e compartilhamento! Você pode encontrar um model card como o arquivo README.md em qualquer repositório de modelo. Consulte o [guia de model cards](./model-cards) para mais detalhes sobre como criar um bom model card.

Se a sua biblioteca permite enviar um modelo para o Hub, é recomendável gerar um cartão de modelo mínimo com metadados pré-preenchidos (tipicamente `library_name`, `pipeline_tag` ou `tags`) e informações sobre como o modelo foi treinado. Isso ajudará a ter uma descrição padronizada para todos os modelos criados com a sua biblioteca.

## Registre sua biblioteca

Muito bem! Agora você deve ter uma biblioteca capaz de carregar um modelo do Hub e, eventualmente, enviar novos modelos. O próximo passo é garantir que seus modelos no Hub estejam bem documentados e integrados à plataforma. Para isso, as bibliotecas podem ser registradas no Hub, o que traz alguns benefícios para os usuários:
- um rótulo mais apresentável pode ser exibido na página do modelo (por exemplo, `KerasNLP` em vez de `keras-nlp`)
- um link para o repositório e a documentação da sua biblioteca é adicionado a cada página de modelo
- é possível definir uma regra personalizada de contagem de downloads
- code snippets podem ser gerados para mostrar como carregar o modelo usando sua biblioteca

Para registrar uma nova biblioteca, abra um Pull Request [aqui](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/model-libraries.ts) seguindo as instruções abaixo:
- O id da biblioteca deve estar em minúsculas e separado por hífens (exemplo: `"adapter-transformers"`). Certifique-se de manter a ordem alfabética ao abrir o PR.
- Defina `repoName` e `prettyLabel` com uma capitalização amigável para o usuário (exemplo: `DeepForest`).
- Defina `repoUrl` com um link para o código-fonte da biblioteca (geralmente um repositório do GitHub).
- (opcional) defina `docsUrl` com um link para a documentação da biblioteca. Se a documentação estiver no repositório do GitHub referenciado acima, não é necessário defini-la duas vezes.
- Defina `filter` como `false`.
- (opcional) defina como os downloads devem ser contados configurando `countDownload`. Os downloads podem ser rastreados por extensões de arquivo ou nomes de arquivo. Certifique-se de não duplicar a contagem. Por exemplo, se o carregamento de um modelo exigir 3 arquivos, a regra de contagem de downloads deve contabilizar os downloads apenas em 1 dos 3 arquivos. Caso contrário, a contagem de downloads será superestimada.
**Observação:** se a biblioteca usa um dos arquivos de configuração padrão (`config.json`, `config.yaml`, `hyperparams.yaml`, `params.json` e `meta.yaml`, veja [aqui](https://huggingface.co/docs/hub/models-download-stats#which-are-the-query-files-for-different-libraries)), não é necessário definir manualmente uma regra de contagem de downloads.
- (opcional) defina `snippets` para informar ao usuário como ele pode instanciar rapidamente um modelo. Mais detalhes abaixo.

Antes de abrir o PR, verifique se pelo menos um modelo é referenciado em https://huggingface.co/models?other=my-library-name. Caso contrário, os metadados do cartão do modelo dos modelos relevantes devem ser atualizados com `library_name: my-library-name` (veja [exemplo](https://huggingface.co/google/gemma-scope/blob/main/README.md?code=true#L3)). Se você não for o proprietário dos modelos no Hub, abra PRs (veja [exemplo](https://huggingface.co/MCG-NJU/VFIMamba/discussions/1)).

Aqui está um [exemplo](https://github.com/huggingface/huggingface.js/pull/885/files) mínimo adicionando integração para VFIMamba.

### Trechos de código

Recomendamos adicionar um trecho de código para explicar como usar um modelo na sua biblioteca de nível inferior.

Para adicionar um trecho de código, você deve atualizar o arquivo [model-libraries-snippets.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/model-libraries-snippets.ts) com as instruções para o seu modelo. Por exemplo, a integração [Asteroid](https://huggingface.co/asteroid-team) inclui um breve trecho de código sobre como carregar e usar um modelo Asteroid:

```typescript
const asteroid = (model: ModelData) =>
`from asteroid.models import BaseModel
  
model = BaseModel.from_pretrained("${model.id}")`;
```

Fazer isso também adicionará uma tag ao seu modelo, permitindo que os usuários identifiquem rapidamente os modelos da sua biblioteca.

Depois que seu trecho de código tiver sido adicionado a [model-libraries-snippets.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/model-libraries-snippets.ts), você pode referenciá-lo em [model-libraries.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/model-libraries.ts) conforme descrito acima.

## Documente sua biblioteca

Por fim, você pode adicionar sua biblioteca à documentação do Hub. Veja, por exemplo, o [PR do Setfit](https://github.com/huggingface/hub-docs/pull/1150) que adicionou o [SetFit](./setfit) à documentação.