Hub documentation

Checklist de lançamento de modelo(s)

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Checklist de lançamento de modelo(s)

O Hugging Face Hub é a plataforma de referência para compartilhar modelos de machine learning. Um lançamento bem executado pode aumentar a visibilidade e o impacto do seu modelo. Esta seção aborda as etapas essenciais para um lançamento de modelo conciso, informativo e amigável ao usuário.

Lançando com um agente de código? Instale a hf CLI Skill para que seu agente gerencie o upload, o model card e os metadados por você.

⏳ Preparando seu modelo para lançamento

Carregar pesos do modelo

Ao enviar modelos para o Hub, siga estas melhores práticas:

Use repositórios separados para diferentes pesos de modelo: Crie repositórios individuais para cada variante da mesma arquitetura. Isso permite agrupá-los em uma coleção, que é mais fácil de navegar do que listagens de diretórios. Também melhora a visibilidade, pois cada modelo tem sua própria URL (hf.co/org/model-name), facilita a busca e fornece contagens de download para cada um dos seus modelos. Um ótimo exemplo é a recente coleção Qwen3-VL, que apresenta diversas variantes da arquitetura VL.
Preferir safetensors em vez de pickle para serialização de pesos.: safetensors é mais seguro e rápido que o pickle ou pth do Python. Se você tiver um arquivo pickle .bin, use a ferramenta de conversão de pesos para convertê-lo.

Escreva um cartão de modelo abrangente

Um cartão de modelo bem elaborado (o README.md no seu repositório) é essencial para a descoberta, a reprodutibilidade e o compartilhamento eficaz. Certifique-se de abordar:

Configuração de metadados: A seção de metadados (YAML) no topo do seu cartão de modelo é fundamental para busca e categorização. Inclua:

---
pipeline_tag: text-generation    # Specify the task
library_name: transformers       # Specify the library
language:
  - en                           # List languages your model supports
license: apache-2.0              # Specify a license
datasets:
  - username/dataset             # List datasets used for training
base_model: username/base-model  # If applicable (your model is a fine-tune, quantized, merged version of another model)
tags:                            # Add extra tags which would make the repo searchable using the tag
  - tag1 
  - tag2
---

Se você criar o README.md na interface web, verá um formulário com os campos de metadados mais importantes que recomendamos 🤗.


Formulário de Metadados na Interface do Usuário do Hub

Descrição detalhada do modelo: Forneça uma explicação clara sobre o que seu modelo faz, sua arquitetura e seus casos de uso pretendidos. Ajude os usuários a decidirem rapidamente se ele atende às suas necessidades.
Exemplos de uso: Forneça trechos de código claros, prontos para copiar e executar, para inferência, ajuste fino ou outras tarefas comuns. Mantenha ao mínimo as edições necessárias por parte dos usuários.

Bônus: Adicione um notebook.ipynb bem estruturado no repositório mostrando inferência ou ajuste fino, para que os usuários possam abri-lo diretamente no Google Colab e Kaggle Notebooks.

Botões de uso do Google e Kaggle
Especificações técnicas: Inclua os parâmetros de treinamento, as necessidades de hardware e outros detalhes que ajudem os usuários a executar o modelo de forma eficaz.
Métricas de desempenho: Compartilhe benchmarks e resultados de avaliação. Inclua métricas quantitativas e exemplos qualitativos para demonstrar pontos fortes e limitações.
Limitações e vieses: Documente as limitações, os vieses e as considerações éticas conhecidas para que os usuários possam tomar decisões informadas.


Botões de uso do Google e Kaggle

Para tornar o processo mais fluido, clique em Import model card template para preencher os README.mds com espaços reservados.


O botão para importar o modelo de cartão de modelo	Uma seção do modelo importado

Melhorar a descoberta e a usabilidade de modelos

Para maximizar o alcance e a usabilidade:

Integração de bibliotecas: Adicione suporte a uma das muitas bibliotecas integradas ao Hugging Face Hub (como transformers, diffusers, sentence-transformers, timm). Essa integração aumenta significativamente a acessibilidade do seu modelo e fornece aos usuários trechos de código para trabalhar com ele.

Por exemplo, para especificar que seu modelo funciona com a biblioteca transformers:
```
---
library_name: transformers
---
```
Aba de trecho de código

Você também pode registrar sua própria biblioteca de modelos ou adicionar suporte ao Hub à sua biblioteca e base de código, para que os usuários saibam como baixar os pesos dos modelos do Hub.

Escrevemos um guia extenso sobre melhores práticas de upload aqui.

O uso de uma biblioteca registrada também permite que você acompanhe os downloads do seu modelo ao longo do tempo.
Metadados corretos:
- Tag de pipeline: Escolha a tag de pipeline correta para que seu modelo apareça nas buscas e widgets adequados.
Exemplos de tags comuns de pipeline:
- text-generation - Para modelos de linguagem que geram texto
- text-to-image - Para modelos de geração de texto para imagem
- image-text-to-text - Para modelos de visão-linguagem (VLMs) que geram texto
- text-to-speech - Para modelos que geram áudio a partir de texto
- Licença: As informações de licença são cruciais para que os usuários entendam como podem usar o modelo.
Artigos de pesquisa: Se o seu modelo tiver artigos associados, cite-os no cartão do modelo. Eles serão interligados automaticamente.
```
## References

* [Model Paper](https://arxiv.org/abs/xxxx.xxxxx)
```
Coleções: Se você estiver publicando vários modelos ou variantes relacionados, organize-os em uma coleção. As coleções ajudam os usuários a descobrir modelos relacionados e a entender as relações entre as versões.
Demonstrações: Crie um Hugging Face Space com uma demonstração interativa. Isso permite que os usuários testem seu modelo sem escrever código. Você também pode vincular o modelo a partir do Space para que ele apareça na interface da página do modelo.
```
## Demo

Try this model directly in your browser: [Space Demo](https://huggingface.co/spaces/username/model-demo)
```
Ao criar uma demonstração, baixe o modelo do repositório do Hub (e não de fontes externas, como o Google Drive). Isso cria links cruzados entre os artefatos e melhora a visibilidade
Versiones quantizadas: Considere enviar versões quantizadas (por exemplo, GGUF) em um repositório separado para melhorar a acessibilidade para usuários com recursos de computação limitados. Vincule essas versões usando o campo de metadados base_model nos cartões de modelo quantizados e documente as diferenças de desempenho.
```
---
base_model: username/original-model
base_model_relation: quantized
---
```
Árvore de modelos mostrando versões quantizadas
Vinculando conjuntos de dados na página do modelo: Vincule conjuntos de dados nos seus metadados para que apareçam diretamente na sua página do modelo.
```
---
datasets:
- username/dataset
- username/dataset-2
---
```
Nova versão do modelo: Se o seu modelo for uma atualização de um modelo existente, especifique isso no card do modelo anterior. Isso exibirá um banner na página anterior com um link para a atualização.
```
---
new_version: username/updated-model
---
```
Exemplos visuais: Para modelos de geração de imagem ou vídeo, inclua exemplos diretamente na sua página de modelo usando o componente de cartão <Gallery>.
```
<Gallery>
![Example 1](./images/example1.png)
![Example 2](./images/example2.png)
</Gallery>
```


Aba de trecho de código


Árvore de modelos mostrando versões quantizadas

Emissões de carbono: Se possível, especifique as emissões de carbono do treinamento.

---
co2_eq_emissions:
  emissions: 123.45
  source: "CodeCarbon"
  training_type: "pre-training"
  geographical_location: "US-East"
  hardware_used: "8xA100 GPUs"
---

Controle de Acesso e Visibilidade

Configurações de visibilidade: Quando estiver pronto para compartilhar seu modelo, alterne-o para público em suas configurações do modelo. Antes de fazer isso, verifique duas vezes toda a documentação e os exemplos de código para garantir que estejam precisos e completos.
Acesso controlado: Se o seu modelo requer acesso controlado, use o recurso de acesso controlado e declare claramente as condições que os usuários devem atender. Isso é importante para modelos com preocupações de uso duplo ou restrições comerciais.

🏁 Após a publicação do seu modelo

Um lançamento de modelo bem-sucedido vai além da publicação inicial. Para manter a qualidade e maximizar o impacto:

Manutenção e Engajamento da Comunidade

Verificar a funcionalidade: Após o lançamento, teste todos os trechos de código em um ambiente limpo para confirmar que funcionam como esperado. Isso garante que os usuários possam executar seu modelo sem erros ou confusão.

Por exemplo, se o seu modelo for um LLM compatível com transformers:
```
from transformers import pipeline

# This should run without errors
pipe = pipeline("text-generation", model="your-username/your-model")
result = pipe("Your test prompt")
print(result)
```
Compartilhar Compartilhar Compartilhar: A maioria dos usuários descobre modelos por meio de redes sociais, canais de chat (como Slack ou Discord) ou newsletters. Compartilhe os links do seu modelo nesses espaços e também adicione-os ao seu site ou repositórios do GitHub.

Quanto mais visitas e curtidas seu modelo recebe, mais alto ele aparece na seção Hugging Face Trending, trazendo ainda mais visibilidade
Interação com a comunidade: Use a aba Comunidade para responder perguntas, tratar do feedback e resolver problemas com rapidez. Esclareça dúvidas, aceite sugestões úteis e encerre tópicos fora do escopo para manter as discussões focadas.

Adicionar resultados de avaliação

Se você avaliar em qualquer um dos conjuntos de dados de benchmark suportados no Hub, pode adicionar os resultados de avaliação ao repositório do seu modelo. Isso tornará as pontuações de benchmark visíveis diretamente na página do modelo e no ranking de benchmarks no repositório do conjunto de dados. Consulte a documentação de Resultados de Avaliação para a especificação completa.

Para adicionar resultados de avaliação, crie arquivos YAML na pasta .eval_results/ do repositório do seu modelo. Cada arquivo referencia um conjunto de dados de Benchmark do Hub:

# .eval_results/gpqa.yaml
- dataset:
    id: Idavidrein/gpqa
    task_id: diamond
  value: 76.1
  date: "2026-03-19"
  source:
    url: https://huggingface.co/your-org/your-model
    name: Model Card
    user: your-username

O task_id deve corresponder a uma tarefa definida no eval.yaml do conjunto de dados do benchmark. Você pode encontrar os benchmarks disponíveis e seus IDs de tarefa verificando o arquivo eval.yaml em repositórios de conjuntos de dados de benchmarks, como HLE.

Qualquer pessoa da comunidade também pode enviar resultados de avaliação para qualquer modelo abrindo um Pull Request. As pontuações enviadas pela comunidade exibem um selo “community” na página do modelo. Para simplificar esse processo, você pode usar o repositório community-evals, que fornece scripts e uma habilidade de agente para extrair pontuações de model cards e criar PRs automaticamente.

Rastreamento de Uso e Impacto

Métricas de uso: Acompanhe os downloads e os "likes" para entender o alcance e a adoção do seu modelo. Você pode visualizar as métricas totais de downloads nas configurações do seu modelo.
Revisar contribuições da comunidade: Verifique regularmente o repositório do seu modelo em busca de contribuições de outros usuários. Pull requests e discussões da comunidade podem fornecer feedback útil, ideias e oportunidades de colaboração.

🏢 Recursos para empresas

A assinatura Hugging Face Team & Enterprise oferece recursos adicionais para equipes e organizações:

Controle de acesso: Defina grupos de recursos para gerenciar o acesso de equipes ou usuários específicos. Isso garante as permissões adequadas e uma colaboração segura em toda a sua organização.
Região de armazenamento: Escolha a região de armazenamento de dados (EUA ou UE) para os arquivos do seu modelo, a fim de atender às regulamentações e requisitos de conformidade de dados regionais.
Análises avançadas: Use o Publisher Analytics para obter insights mais aprofundados sobre os padrões de uso de modelos, downloads e tendências de adoção em toda a sua organização.
Armazenamento Estendido: Acesse capacidade adicional de armazenamento privado para hospedar mais modelos e artefatos maiores à medida que seu portfólio de modelos se expande.
Posts de blog da organização: Organizações empresariais agora podem publicar artigos de blog diretamente no Hugging Face. Isso permite compartilhar lançamentos de modelos, atualizações de pesquisa e anúncios com a comunidade em geral, tudo a partir do perfil da sua organização.

Ao seguir estas diretrizes e exemplos, você tornará o lançamento do seu modelo no Hugging Face claro, útil e impactante. Isso ajuda seu trabalho a alcançar mais pessoas, fortalece a comunidade de IA e aumenta a visibilidade do seu modelo.

Mal podemos esperar para ver o que você vai compartilhar a seguir! 🤗

Update on GitHub

←Estatísticas de download de modelos Hardware→