Библиотеки

Центр данных поддерживает несколько библиотек из экосистемы с открытым исходным кодом. Благодаря библиотеке huggingface_hub для Python легко настроить публикацию ваших наборов данных в Центре. Мы рады приветствовать в Центре ряд библиотек с открытым исходным кодом, которые способствуют развитию машинного обучения.

Таблица библиотек

Таблица ниже обобщает поддерживаемые библиотеки и уровень их интеграции.

* Требует передачи дополнительных аргументов для записи оптимизированных файлов Parquet

Библиотеки обработки данных

Потоковая передача

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

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

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

Оптимизированные файлы Parquet

Файлы Parquet на Hugging Face оптимизированы для повышения эффективности хранения, ускорения загрузки и выгрузки, а также для обеспечения эффективного потокового чтения и редактирования наборов данных.

Оптимизированные файлы Parquet — это файлы Parquet с дополнительными возможностями:

• Разбиение содержимого Parquet на блоки оптимизирует Parquet для Xet, хранилища Hugging Face. Это ускоряет загрузку и скачивание благодаря дедупликации на уровне блоков и позволяет эффективно редактировать файлы
• Page index ускоряет фильтрацию при потоковой передаче и обеспечивает эффективный случайный доступ, например, в Dataset Viewer

Некоторые библиотеки требуют дополнительный аргумент для записи файлов Optimized Parquet, например Pandas и PyArrow:

• use_content_defined_chunking=True для включения Parquet Content Defined Chunking, для дедупликации и редактирования
• write_page_index=True для включения индекса страниц в метаданные Parquet, что обеспечивает потоковую обработку и доступ в произвольном порядке

Библиотеки для обучения

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

* SFTTrainer и DPOTrainer поддерживают потоковую обработку; GRPOTrainer пока не поддерживает потоковый ввод

Потоковая загрузка из Hub

Стриминг позволяет обучать модели на огромных наборах данных без их предварительной загрузки. Это ценно в следующих случаях:

• Ваш набор данных слишком большой, чтобы поместиться на диске
• Вы хотите сразу приступить к обучению
• Вы используете HF Jobs, где вычислительные ресурсы, размещённые в одном месте, обеспечивают более быструю потоковую передачу

Благодаря недавним улучшениям стриминг стал до 100 раз эффективнее за счёт более быстрого запуска, предварительной выборки и лучшей масштабируемости на большое количество рабочих процессов.

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

Логирование в Hub

Некоторые инструменты могут передавать данные обучения обратно в Hub в процессе обучения:

• Trackio: транслирует метрики обучения в набор данных Hub в реальном времени

Интеграция библиотек и инструментов для работы с данными с Hub

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

В руководстве рассматриваются:

• Возможные подходы к загрузке данных из Hub в вашу библиотеку/инструмент
• Возможные подходы к загрузке данных из вашей библиотеки/инструмента в Hub

Загрузка данных из Hub

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

В целом мы рекомендуем использовать существующие библиотеки, такие как datasets, pandas или polars, если у вас нет конкретной причины реализовывать собственное решение. Если вам требуется более точный контроль над процессом загрузки, вы можете использовать библиотеку huggingface_hub, которая, например, позволяет загрузить определённый подмножество файлов из репозитория.

Подробнее о загрузке данных из Hub можно узнать здесь.

Интеграция через Dataset Viewer и файлы Parquet

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

Если датасет ещё не в формате Parquet, Hub автоматически конвертирует первые 5 ГБ каждого датасета в формат Parquet для работы просмотрщика датасетов и обеспечения единообразных паттернов доступа. Эта стандартизация даёт несколько преимуществ для интеграций с библиотеками:

• Одинаковые паттерны доступа к данным независимо от исходного формата
• Встроенный предпросмотр и исследование данных через просмотрщик датасетов Hub. Просмотрщик датасетов также можно встроить в ваши приложения в виде iframe, что упрощает предоставление подробных предпросмотров датасетов. Дополнительную информацию о встраивании просмотрщика см. в документации по встраиванию просмотрщика датасетов.
• Эффективное столбчатое хранилище, оптимизированное для запросов. Например, вы можете использовать инструмент вроде DuckDB для выполнения запросов или фильтрации конкретного подмножества данных.
• Parquet хорошо поддерживается в экосистеме машинного обучения и анализа данных.

Для получения подробной информации о работе с Dataset Viewer API см. документацию Dataset Viewer API

Загрузка данных в Hub

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

В этом руководстве рассматриваются три основных способа загрузки данных в Hub:

• с использованием библиотеки datasets и метода push_to_hub
• используя pandas для записи в Hub
• с использованием библиотеки huggingface_hub и метода upload_folder

Используйте библиотеку datasets

Самый простой способ загрузить данные в Hub — использовать существующий метод push_to_hub из библиотеки datasets. Метод push_to_hub автоматически выполняет следующие действия:

• создание репозитория
• конвертация набора данных в Parquet
• разбиение набора данных на подходящие части
• загрузка данных

Например, если у вас есть библиотека для генерации синтетических данных, которая возвращает список словарей, вы можете просто сделать следующее:

from datasets import Dataset

data = [{"prompt": "Write a cake recipe", "response": "Measure 1 cup ..."}]
ds = Dataset.from_list(data)
ds.push_to_hub("USERNAME_OR_ORG/repo_ID")

Примеры такого рода интеграции:

• Distilabel

Опирайтесь на существующую интеграцию библиотек с Hub

Polars, Pandas, Dask, Spark, DuckDB и Daft могут записывать данные в репозиторий Hugging Face Hub. Подробнее см. в таблице Библиотеки выше.

Если вы уже используете одну из этих библиотек в своём коде, добавление возможности загрузки на Hub не представляет сложности. Например, если у вас есть библиотека генерации синтетических данных, которая может возвращать Pandas DataFrame, вот код, который нужно написать для загрузки на Hub:

from huggingface_hub import HfApi

# Initialize the Hub API
hf_api = HfApi()

# Create a repository (if it doesn't exist)
hf_api.create_repo(repo_id="username/my-dataset", repo_type="dataset", exist_ok=True)

# Convert your data to a DataFrame and save directly to the Hub
df.to_parquet("hf://datasets/username/my-dataset/data.parquet")

Использование библиотеки huggingface_hub для Python

Библиотека huggingface_hub для Python предлагает более гибкий подход к загрузке данных в Hub. С её помощью можно загружать в репозиторий отдельные файлы или их подмножества. Это полезно, если у вас есть большой набор данных, который вы не хотите конвертировать в Parquet, если вам нужно загрузить конкретный поднабор файлов или если вы хотите более детально контролировать структуру репозитория.

В зависимости от вашего сценария использования вы можете загрузить файл или папку в определённой точке вашего кода, например, экспортировать аннотации из инструмента в Hub, когда пользователь нажимает «push to Hub». Например,

from huggingface_hub import HfApi
api = HfApi()

api.upload_folder(
    folder_path="/my-cool-library/data-folder",
    repo_id="username/my-dataset",
    repo_type="dataset",
    commit_message="Push annotations to Hub",
    allow_patterns="*.jsonl",
)

Подробнее о способах загрузки данных в Hub можно узнать здесь.

В качестве альтернативы существуют ситуации, когда вы хотите загружать данные в фоновом режиме, например, синтетические данные, генерируемые каждые 10 минут. В этом случае можно использовать класс CommitScheduler из библиотеки huggingface_hub. Подробнее см. в документации по запланированным загрузкам.

Вы можете увидеть пример использования этого подхода для загрузки данных в Hub в

• Библиотека fastdata
• Это демо-пространство magpie

Дополнительная поддержка

По техническим вопросам интеграции обращайтесь к команде datasets по адресу datasets@huggingface.co.