Чек-лист выпуска модели(ей)

Hugging Face Hub — это основная платформа для обмена моделями машинного обучения. Качественный релиз способен повысить видимость и влияние вашей модели. В этом разделе описаны ключевые шаги для создания краткого, информативного и удобного для пользователя релиза модели.

Выпускаете с помощью кодинг-агента? Установите hf CLI Skill, чтобы агент самостоятельно занимался загрузкой, карточкой модели и метаданными.

⏳ Подготовка модели к выпуску

Загрузка весов модели

При загрузке моделей в Hub следуйте этим рекомендациям:

• Используйте отдельные репозитории для разных весов моделей: Создавайте отдельные репозитории для каждого варианта одной и той же архитектуры. Это позволяет сгруппировать их в коллекцию, которая удобнее для навигации, чем список каталогов. Это также повышает видимость, поскольку у каждой модели есть свой URL (hf.co/org/model-name), упрощает поиск и предоставляет счётчики загрузок для каждой из ваших моделей. Отличный пример — недавняя коллекция Qwen3-VL, в которой представлены различные варианты архитектуры VL.

• Для сериализации весов предпочитайте safetensors вместо pickle.: safetensors безопаснее и быстрее, чем pickle или pth в Python. Если у вас есть pickle-файл .bin, используйте инструмент для конвертации весов, чтобы преобразовать его.

Создание подробной карточки модели

Хорошо оформленная карточка модели (файл README.md в вашем репозитории) необходима для обнаружения, воспроизводимости и эффективного обмена. Убедитесь, что вы охватили:

1. Конфигурация метаданных: Раздел metadata (YAML) в начале вашей карточки модели имеет ключевое значение для поиска и категоризации. Включите:

   Скопировано

   ---
   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
   ---

   Если вы создадите README.md в веб-интерфейсе, вы увидите форму с наиболее важными полями метаданных, которые мы рекомендуем 🤗.

   Форма метаданных в интерфейсе Hub

2. Подробное описание модели: Дайте четкое объяснение того, что делает ваша модель, какова ее архитектура и для каких задач она предназначена. Это поможет пользователям быстро определить, подходит ли она для их нужд.

3. Примеры использования: Предоставляйте понятные фрагменты кода, которые можно скопировать и запустить для вывода, дообучения или других типовых задач. Минимизируйте количество правок, которые пользователям придётся вносить.

   Бонус: добавьте в репозиторий хорошо структурированный notebook.ipynb с примером инференса или дообучения, чтобы пользователи могли открыть его напрямую в Google Colab и Kaggle Notebooks.

   Кнопки использования Google и Kaggle

4. Технические характеристики: Включите параметры обучения, требования к аппаратному обеспечению и другие сведения, которые помогут пользователям эффективно запускать модель.

5. Метрики производительности: Делитесь результатами бенчмарков и оценок. Включайте количественные метрики и качественные примеры, чтобы показать сильные стороны и ограничения.

6. Ограничения и предвзятость: Опишите известные ограничения, предвзятость и этические аспекты, чтобы пользователи могли принимать обоснованные решения.

Чтобы сделать процесс более плавным, нажмите Import model card template, чтобы автоматически заполнить README.md с помощью плейсхолдеров.

Кнопка для импорта шаблона карточки модели	Раздел импортированного шаблона

Улучшение обнаруживаемости и удобства использования моделей

Чтобы максимально расширить охват и повысить удобство использования:

1. Интеграция с библиотеками: Добавьте поддержку одной из множества библиотек, интегрированных с Hugging Face Hub (например, transformers, diffusers, sentence-transformers, timm). Эта интеграция значительно повышает доступность вашей модели и предоставляет пользователям фрагменты кода для работы с ней.

   Например, чтобы указать, что ваша модель работает с библиотекой transformers:

   Скопировано

   ---
   library_name: transformers
   ---

   Вкладка с фрагментом кода

   Вы также можете зарегистрировать собственную библиотеку моделей или добавить поддержку Hub в свою библиотеку и кодовую базу, чтобы пользователи знали, как скачивать веса моделей из Hub.

   Мы написали подробное руководство по лучшим практикам загрузки здесь.

   Использование зарегистрированной библиотеки также позволяет отслеживать количество загрузок вашей модели во времени.

2. Правильные метаданные:

   • Метка конвейера: Выберите правильную метку конвейера, чтобы ваша модель отображалась в соответствующих поисковых запросах и виджетах.

   Примеры распространённых тегов конвейеров:

   • text-generation - для языковых моделей, генерирующих текст

   • text-to-image - для моделей генерации изображений по тексту

   • image-text-to-text — для моделей «зрение-язык» (VLM), генерирующих текст

   • text-to-speech — для моделей, генерирующих аудио из текста

   • Лицензия: Информация о лицензии имеет решающее значение для понимания того, как пользователи могут использовать модель.

3. Научные статьи: Если для вашей модели есть связанные статьи, укажите их в карточке модели. Они будут автоматически перекрёстно связаны.

   Скопировано

   ## References
   
   * [Model Paper](https://arxiv.org/abs/xxxx.xxxxx)

4. Коллекции: Если вы выпускаете несколько связанных моделей или вариантов, организуйте их в коллекцию. Коллекции помогают пользователям находить связанные модели и понимать связи между версиями.

5. Демо: Создайте Hugging Face Space с интерактивным демо. Это позволяет пользователям попробовать вашу модель без написания кода. Вы также можете связать модель со Space, чтобы она отображалась в интерфейсе страницы модели.

   Скопировано

   ## Demo
   
   Try this model directly in your browser: [Space Demo](https://huggingface.co/spaces/username/model-demo)

   При создании демо загрузите модель из её репозитория на Hub (а не из внешних источников, таких как Google Drive). Это создаёт перекрёстные ссылки на артефакты и повышает видимость

6. Квантованные версии: Рассмотрите возможность загрузки квантованных версий (например, GGUF) в отдельный репозиторий, чтобы повысить доступность для пользователей с ограниченными вычислительными ресурсами. Свяжите эти версии с помощью поля метаданных base_model в карточках квантованных моделей и задокументируйте различия в производительности.

   Скопировано

   ---
   base_model: username/original-model
   base_model_relation: quantized
   ---

   Дерево моделей с отображением квантованных версий

7. Связывание наборов данных на странице модели: Свяжите наборы данных в метаданных, чтобы они отображались непосредственно на странице вашей модели.

   Скопировано

   ---
   datasets:
   - username/dataset
   - username/dataset-2
   ---

8. Новая версия модели: Если ваша модель является обновлением существующей, укажите это на карточке старой модели. Тогда на старой странице отобразится баннер со ссылкой на обновление.

   Скопировано

   ---
   new_version: username/updated-model
   ---

9. Визуальные примеры: Для моделей генерации изображений или видео включайте примеры непосредственно на странице модели с помощью компонента карточки <Gallery>.

   Скопировано

   <Gallery>
   ![Example 1](./images/example1.png)
   ![Example 2](./images/example2.png)
   </Gallery>

10. Выбросы углерода: При возможности укажите выбросы углерода при обучении.

    Скопировано

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

Контроль доступа и видимость

1. Настройки видимости: Когда вы будете готовы поделиться своей моделью, переключите её на публичную в настройках модели. Прежде чем сделать это, дважды проверьте, что вся документация и примеры кода точны и полны.

2. Ограниченный доступ: Если вашей модели требуется контролируемый доступ, используйте функцию ограниченного доступа и четко укажите условия, которые должны выполнить пользователи. Это важно для моделей с рисками двойного использования или коммерческими ограничениями.

🏁 После публикации вашей модели

Успешный релиз модели не ограничивается первичным выпуском. Чтобы поддерживать качество и максимизировать влияние:

Обслуживание и взаимодействие с сообществом

1. Проверка работоспособности: После выпуска протестируйте все фрагменты кода в чистой среде, чтобы убедиться, что они работают как ожидается. Это гарантирует, что пользователи смогут запустить вашу модель без ошибок и путаницы.

   Например, если ваша модель — это LLM, совместимая с 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)

2. Поделиться Поделиться Поделиться: Большинство пользователей находят модели через социальные сети, чат-каналы (например, Slack или Discord) или рассылки. Делитесь ссылками на свои модели в этих пространствах, а также добавляйте их на свой сайт или в репозитории GitHub.

   Чем больше посещений и лайков получает ваша модель, тем выше она поднимается в разделе Hugging Face Trending, что обеспечивает ещё большую видимость

3. Взаимодействие с сообществом: Используйте вкладку Community, чтобы отвечать на вопросы, реагировать на обратную связь и оперативно решать проблемы. Устраняйте недопонимание, принимайте полезные предложения и закрывайте темы, не относящиеся к обсуждению, чтобы дискуссии оставались сфокусированными.

Добавление результатов оценки

Если вы оцениваете модель на одном из поддерживаемых наборов данных для бенчмаркинга на Hub, вы можете добавить результаты оценки в репозиторий вашей модели. Это сделает оценки бенчмарков видимыми непосредственно на странице модели и в таблице лидеров бенчмарков в репозитории набора данных. Полную спецификацию см. в документации по результатам оценки.

Чтобы добавить результаты оценки, создайте файлы YAML в папке .eval_results/ вашего репозитория модели. Каждый файл ссылается на набор данных Hub Benchmark:

# .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

task_id должен соответствовать задаче, определённой в файле eval.yaml набора данных бенчмарка. Доступные бенчмарки и их идентификаторы задач можно найти, проверив файл eval.yaml в репозиториях наборов данных бенчмарков, например HLE.

Любой участник сообщества может отправить результаты оценки для любой модели, создав Pull Request. Оценки, отправленные сообществом, отображаются на странице модели с бейджем «community». Чтобы упростить этот процесс, вы можете использовать репозиторий community-evals, который предоставляет скрипты и агентский навык для автоматического извлечения оценок из карточек моделей и создания PR.

Отслеживание использования и влияния

1. Метрики использования: Отслеживайте загрузки и лайки, чтобы понимать охват и распространение вашей модели. Общие метрики загрузок можно посмотреть в настройках модели.

2. Обзор вкладов сообщества: Регулярно проверяйте репозиторий вашей модели на наличие вкладов от других пользователей. Запросы на слияние и обсуждения сообщества могут предоставить полезную обратную связь, идеи и возможности для сотрудничества.

🏢 Корпоративные функции

Подписка Hugging Face Team & Enterprise предоставляет дополнительные возможности для команд и организаций:

1. Контроль доступа: Настройте группы ресурсов, чтобы управлять доступом для конкретных команд или пользователей. Это гарантирует правильные разрешения и безопасное сотрудничество в рамках вашей организации.

2. Регион хранения: Выберите регион хранения данных (США или ЕС) для файлов вашей модели, чтобы соответствовать региональным нормативным требованиям и стандартам соответствия.

3. Расширенная аналитика: Используйте Publisher Analytics, чтобы получить более глубокое представление о паттернах использования моделей, загрузках и тенденциях внедрения в вашей организации.

4. Расширенное хранилище: Доступ к дополнительному объему приватного хранилища для размещения большего количества моделей и более крупных артефактов по мере расширения портфеля моделей.

5. Посты в блоге организации: Представители корпоративных организаций теперь могут публиковать статьи в блоге непосредственно на Hugging Face. Это позволяет делиться информацией о выпусках моделей, обновлениях исследований и анонсах с более широкой аудиторией, всё из профиля вашей организации.

Следуя этим рекомендациям и примерам, вы сделаете публикацию вашей модели на Hugging Face понятной, полезной и значимой. Это поможет вашему проекту охватить более широкую аудиторию, укрепит сообщество ИИ и повысит видимость вашей модели.

Мы с нетерпением ждём, что вы поделитесь в следующий раз! 🤗