Datasets documentation
ビルダークラス
ビルダークラス
ビルダー
🤗 Datasetsは、データセットの構築プロセスにおいて、主にDatasetBuilderとBuilderConfigの2つのクラスに依存しています。
class datasets.DatasetBuilder
< source >( cache_dir: typing.Optional[str] = Nonedataset_name: typing.Optional[str] = Noneconfig_name: typing.Optional[str] = Nonehash: typing.Optional[str] = Nonebase_path: typing.Optional[str] = Noneinfo: typing.Optional[datasets.info.DatasetInfo] = Nonefeatures: typing.Optional[datasets.features.features.Features] = Nonetoken: typing.Union[bool, str, NoneType] = Nonerepo_id: typing.Optional[str] = Nonedata_files: typing.Union[str, list, dict, datasets.data_files.DataFilesDict, NoneType] = Nonedata_dir: typing.Optional[str] = Nonestorage_options: typing.Optional[dict] = Nonewriter_batch_size: typing.Optional[int] = Noneconfig_id: typing.Optional[str] = None**config_kwargs )
パラメータ
- cache_dir (
str, 任意) — データをキャッシュするディレクトリ。デフォルトは"~/.cache/huggingface/datasets"です。 - dataset_name (
str, 任意) — ビルダー名と異なる場合のデータセット名。csv、imagefolder、audiofolderなどのパッケージ化されたビルダーを使用するデータセット間で、同じパッケージ化ビルダーを使用しているにもかかわらず異なる点を反映するために有用です。 - config_name (
str, 省略可) — データセットの構成の名前。 ディスク上に生成されるデータに影響します。異なる構成は、それぞれ独自のサブディレクトリとバージョンを持ちます。 指定しない場合、デフォルトの構成が使用されます（存在する場合）。2.3.0で追加
パラメータ
nameはconfig_nameに名前が変更されました。 - hash (
str, 任意) — データセットビルダーのコードに固有のハッシュ。データセットビルダーのコードが更新された際に、キャッシュディレクトリを更新するために使用されます（古いデータの再利用を避けるため）。 典型的なキャッシュディレクトリ（self._relative_data_dirで定義）はname/version/hash/です。 - base_path (
str, 省略可) — ファイルのダウンロードに使用される相対パスのベースパスです。 リモートURLを指定することもできます。 - features (Features、任意) — このデータセットで使用する Features の型です。 例えば、データセットの Features の型を変更するために使用できます。
- token (
strまたはbool、省略可能) — Datasets Hub 上のリモートファイルの Bearer トークンとして使用する文字列またはブール値。Trueの場合、"~/.huggingface"からトークンを取得します。 - repo_id (
str, 省略可) — データセットリポジトリの ID。 同じ名前を持つが異なる名前空間由来のビルダーを区別するために使用されます。例えば、“rajpurkar/squad” と “lhoestq/squad” のリポジトリ ID の場合、後者のビルダー名は “lhoestq___squad” になります。 - data_files (
strまたはSequenceまたはMapping、省略可) — ソースデータファイルへのパス。 “csv” や “json” のような、ユーザーがデータファイルを指定する必要があるビルダー向けです。ローカルファイルでもリモートファイルでも構いません。利便性のため、DataFilesDictを使用できます。 - data_dir (
str, 省略可) — ソースデータファイルを含むディレクトリへのパス。data_filesが渡されない場合のみ使用してください。この場合、data_filesとしてos.path.join(data_dir, "**")を渡すことと同等です。 手動でのダウンロードが必要なビルダーでは、手動でダウンロードしたデータを含むローカルディレクトリへのパスである必要があります。 - storage_options (
dict, 任意) — データセットのファイルシステムバックエンドに渡すためのキー/値のペア（該当する場合）。 - writer_batch_size (
int, 任意) — ArrowWriter が使用するバッチサイズです。 メモリに保持されるサンプル数、および arrow チャンクの長さを定義します。 None の場合、ArrowWriter はデフォルト値を使用します。 - **config_kwargs (追加のキーワード引数) — 対応するビルダー設定クラスに渡すキーワード引数です。このクラスは、クラス属性 DatasetBuilder.BUILDER_CONFIG_CLASS に設定されます。ビルダー設定クラスは BuilderConfig またはそのサブクラスです。
すべてのデータセットの抽象基底クラス。
DatasetBuilderには3つの主要なメソッドがあります：
DatasetBuilder.info: 特徴量の名前、型、形状、バージョン、スプリット、引用情報などを含む、データセットのドキュメントです。- DatasetBuilder.download_and_prepare(): ソースデータをダウンロードし、ディスクに書き込みます。
- DatasetBuilder.as_dataset(): Datasetを生成します。
一部のDatasetBuilderは、BuilderConfigのサブクラスを定義し、構築時に設定オブジェクト（または名前）を受け取ることで、データセットの複数のバリアントを公開します。設定可能なデータセットは、DatasetBuilder.builder_configs()で定義済みの設定のセットを公開します。
as_dataset
< source >( split: typing.Union[str, datasets.splits.Split, list[str], list[datasets.splits.Split], NoneType] = Nonein_memory = False )
パラメータ
- split (
datasets.Split) — 返すデータのサブセットを指定します。 - verification_mode (VerificationMode または
str, デフォルトはBASIC_CHECKS) — ダウンロード/処理されたデータセットの情報（チェックサム/サイズ/スプリット/…）に対して実行するチェックを決定する検証モード。2.9.1で追加
- in_memory (
bool, デフォルトはFalse) — データをメモリ内にコピーするかどうか。
指定されたスプリット用のDatasetを返します。
download_and_prepare
< source >( output_dir: typing.Optional[str] = Nonedownload_config: typing.Optional[datasets.download.download_config.DownloadConfig] = Nonedownload_mode: typing.Union[datasets.download.download_manager.DownloadMode, str, NoneType] = Noneverification_mode: typing.Union[datasets.utils.info_utils.VerificationMode, str, NoneType] = Nonedl_manager: typing.Optional[datasets.download.download_manager.DownloadManager] = Nonebase_path: typing.Optional[str] = Nonefile_format: str = 'arrow'max_shard_size: typing.Union[str, int, NoneType] = Nonenum_proc: typing.Optional[int] = Nonestorage_options: typing.Optional[dict] = None**download_and_prepare_kwargs )
パラメータ
- output_dir (
str, 省略可能) — データセットの出力ディレクトリ。 デフォルトでは、このビルダーのcache_dir, 内にある~/.cache/huggingface/datasetsがデフォルトです。2.5.0で追加
- download_config (
DownloadConfig、省略可) — 特定のダウンロード設定パラメータ。 - download_mode (DownloadMode または
str、省略可) — ダウンロード/生成モードを選択します。デフォルトはREUSE_DATASET_IF_EXISTSです。 - verification_mode (VerificationMode または
str, デフォルトはBASIC_CHECKS) — ダウンロード/処理されたデータセットの情報（チェックサム/サイズ/スプリット/…）に対して実行するチェックを決定する検証モード。2.9.1で追加
- dl_manager (
DownloadManager、任意) — 使用する特定のDownloadManger。 - base_path (
str, 省略可) — ファイルのダウンロードに使用される相対パスのベースパスです。リモート URL を指定できます。 指定しない場合、base_path属性 (self.base_path) の値が代わりに使用されます。 - file_format (
str, 省略可) — データセットが書き込まれるデータファイルの形式です。 サポートされている形式: “arrow”、“parquet”。デフォルトは “arrow” 形式です。 形式が “parquet” の場合、画像データと音声データはローカルファイルへの参照ではなく、Parquet ファイルに埋め込まれます。2.5.0で追加
- max_shard_size (
Union[str, int], 省略可) — シャードごとに書き込まれるバイト数の上限。デフォルト値は “500MB” です。 サイズは非圧縮データに基づいて計算されるため、Parquet 圧縮などにより、実際のシャードファイルはmax_shard_sizeよりも小さくなる場合があります。2.5.0で追加
- num_proc (
int, 省略可能, デフォルトはNone) — ローカルでデータセットをダウンロードおよび生成する際のプロセス数。 デフォルトではマルチプロセッシングは無効です。2.7.0で追加
- storage_options (
dict, 省略可) — キャッシュファイルシステムバックエンドに渡すキー/値のペア（該当する場合）。2.5.0で追加
- **download_and_prepare_kwargs (追加のキーワード引数) — キーワード引数。
読み取り用にデータセットをダウンロードして準備します。
例:
builder.as_dataset() によって Dataset として読み込める Arrow ファイルとして、データセットをダウンロードして準備します:
>>> from datasets import load_dataset_builder
>>> builder = load_dataset_builder("cornell-movie-review-data/rotten_tomatoes")
>>> builder.download_and_prepare()ローカルで、シャード化された Parquet ファイルとしてデータセットをダウンロードして準備します:
>>> from datasets import load_dataset_builder
>>> builder = load_dataset_builder("cornell-movie-review-data/rotten_tomatoes")
>>> builder.download_and_prepare("./output_dir", file_format="parquet")クラウドストレージに、シャード化された Parquet ファイルとしてデータセットをダウンロードして準備します:
>>> from datasets import load_dataset_builder
>>> storage_options = {"key": aws_access_key_id, "secret": aws_secret_access_key}
>>> builder = load_dataset_builder("cornell-movie-review-data/rotten_tomatoes")
>>> builder.download_and_prepare("s3://my-bucket/my_rotten_tomatoes", storage_options=storage_options, file_format="parquet")このクラスまたはサブクラスのモジュールのパスを返します。
class datasets.GeneratorBasedBuilder
< source >( cache_dir: typing.Optional[str] = Nonedataset_name: typing.Optional[str] = Noneconfig_name: typing.Optional[str] = Nonehash: typing.Optional[str] = Nonebase_path: typing.Optional[str] = Noneinfo: typing.Optional[datasets.info.DatasetInfo] = Nonefeatures: typing.Optional[datasets.features.features.Features] = Nonetoken: typing.Union[bool, str, NoneType] = Nonerepo_id: typing.Optional[str] = Nonedata_files: typing.Union[str, list, dict, datasets.data_files.DataFilesDict, NoneType] = Nonedata_dir: typing.Optional[str] = Nonestorage_options: typing.Optional[dict] = Nonewriter_batch_size: typing.Optional[int] = Noneconfig_id: typing.Optional[str] = None**config_kwargs )
dictジェネレーターに基づくデータ生成を行うデータセットの基底クラス。
GeneratorBasedBuilder は、DatasetBuilder のデータ書き込みと読み取りの多くを抽象化する便利なクラスです。サブクラスには、データセットの各スプリットにわたる特徴量辞書のジェネレーター（_split_generators）を実装することが期待されます。詳細はメソッドのドキュメント文字列を参照してください。
class datasets.ArrowBasedBuilder
< source >( cache_dir: typing.Optional[str] = Nonedataset_name: typing.Optional[str] = Noneconfig_name: typing.Optional[str] = Nonehash: typing.Optional[str] = Nonebase_path: typing.Optional[str] = Noneinfo: typing.Optional[datasets.info.DatasetInfo] = Nonefeatures: typing.Optional[datasets.features.features.Features] = Nonetoken: typing.Union[bool, str, NoneType] = Nonerepo_id: typing.Optional[str] = Nonedata_files: typing.Union[str, list, dict, datasets.data_files.DataFilesDict, NoneType] = Nonedata_dir: typing.Optional[str] = Nonestorage_options: typing.Optional[dict] = Nonewriter_batch_size: typing.Optional[int] = Noneconfig_id: typing.Optional[str] = None**config_kwargs )
Arrowの読み込み関数（CSV/JSON/Parquet）に基づくデータ生成を行うデータセットの基底クラスです。
class datasets.BuilderConfig
< source >( name: str = 'default'version: typing.Union[datasets.utils.version.Version, str, NoneType] = 0.0.0data_dir: typing.Optional[str] = Nonedata_files: typing.Union[datasets.data_files.DataFilesDict, datasets.data_files.DataFilesPatternsDict, NoneType] = Nonedescription: typing.Optional[str] = None )
DatasetBuilderのデータ設定の基底クラスです。
データ設定オプションを持つDatasetBuilderのサブクラスは、BuilderConfigを継承し、独自のプロパティを追加する必要があります。
create_config_id
< source >( config_kwargs: dictcustom_features: typing.Optional[datasets.features.features.Features] = None )
config id はキャッシュディレクトリを構築するために使用されます。 デフォルトでは、config の名前と等しくなります。 ただし、config の名前だけでは、生成されるデータセットの一意な識別子として十分ではありません。 以下の要素が考慮されていないためです:
- 属性を上書きするために使用できるconfigのkwargs
- データセットの作成に使用されるカスタム機能
- json/text/csv/pandas データセットの data_files
したがって、config idは、これらの情報に基づく任意のサフィックス付きのconfig名です。
ダウンロード
class datasets.DownloadManager
< source >( dataset_name: typing.Optional[str] = Nonedata_dir: typing.Optional[str] = Nonedownload_config: typing.Optional[datasets.download.download_config.DownloadConfig] = Nonebase_path: typing.Optional[str] = Nonerecord_checksums = False )
ダウンロード
< source >( url_or_urls ) → str or list or dict
指定されたURLをダウンロードします。
デフォルトでは、ダウンロードに1つのプロセスのみが使用されます。この動作を変更するには、カスタマイズされたdownload_config.num_procを渡します。
download_and_extract
< source >( url_or_urls ) → extracted_path(s)
url_or_urlsをダウンロードして展開します。
extract
< source >( path_or_paths ) → extracted_path(s)
指定されたパスを抽出します。
iter_archive
< source >( path_or_buf: typing.Union[str, _io.BufferedReader] ) → tuple[str, io.BufferedReader]
アーカイブ内のファイルを反復処理します。
iter_files
< source >( paths: typing.Union[str, list[str]] ) → str
ファイルパスを反復します。
class datasets.StreamingDownloadManager
< source >( dataset_name: typing.Optional[str] = Nonedata_dir: typing.Optional[str] = Nonedownload_config: typing.Optional[datasets.download.download_config.DownloadConfig] = Nonebase_path: typing.Optional[str] = None )
”::”区切り文字を使用して（リモートの場合もある）圧縮アーカイブをナビゲートするダウンロードマネージャーです。
通常のDownloadManagerとは異なり、downloadおよびextractメソッドは実際にデータをダウンロードしたり抽出したりせず、代わりにxopen関数によって開くことのできるパスまたはURLを返します。xopen関数は組み込みのopen関数を拡張し、リモートファイルからデータをストリーミングします。
ダウンロード
< source >( url_or_urls ) → url(s)
ストリーミングでデータを取得するファイルのURLを正規化します。
これは、ストリーミング用のDownloadManager.downloadの遅延評価版です。
download_and_extract
< source >( url_or_urls ) → url(s)
url_or_urlsをストリーミング用に準備します（抽出プロトコルを追加）。
これはストリーミング用のDownloadManager.download_and_extractの遅延実行版です。
extract
< source >( url_or_urls ) → url(s)
ストリーミング用に、指定されたURLの抽出プロトコルを追加します。
これはストリーミング用のDownloadManager.extractの遅延評価版です。
iter_archive
< source >( urlpath_or_buf: typing.Union[str, _io.BufferedReader] ) → tuple[str, io.BufferedReader]
アーカイブ内のファイルを反復処理します。
iter_files
< source >( urlpaths: typing.Union[str, list[str]] ) → str
ファイルを反復処理します。
class datasets.DownloadConfig
< source >( cache_dir: typing.Union[str, pathlib.Path, NoneType] = Noneforce_download: bool = Falseresume_download: bool = Falselocal_files_only: bool = Falseproxies: typing.Optional[dict] = Noneuser_agent: typing.Optional[str] = Noneextract_compressed_file: bool = Falseforce_extract: bool = Falsedelete_extracted: bool = Falseextract_on_the_fly: bool = Falseuse_etag: bool = Truenum_proc: typing.Optional[int] = Nonemax_retries: int = 1token: typing.Union[str, bool, NoneType] = Nonestorage_options: dict = <factory>download_desc: typing.Optional[str] = Nonedisable_tqdm: bool = False )
パラメータ
- cache_dir (
strまたはPath、任意) — ファイルを保存するキャッシュディレクトリを指定します（デフォルトのキャッシュディレクトリを上書きします）。 - force_download (
bool、デフォルトはFalse) —Trueの場合、ファイルがキャッシュディレクトリに既に存在していても、再ダウンロードします。 - resume_download (
bool、デフォルトはFalse) —Trueの場合、不完全に受信されたファイルが見つかったときにダウンロードを再開します。 - proxies (
dict, 省略可) — 非推奨であり、無視されます。代わりに、HTTP_PROXY/HTTPS_PROXY環境変数を設定するか、huggingface_hub.set_client_factory で HTTP クライアントを設定してください。 - user_agent (
str, 省略可) — リモートリクエストの user-agent に追加される任意の文字列または dict。 - extract_compressed_file (
bool、デフォルトはFalse) —Trueの場合、パスがzipファイルまたはtarファイルを指している場合、アーカイブと同じフォルダに圧縮ファイルを展開します。 - force_extract (
bool、デフォルトはFalse) —extract_compressed_fileがTrueの場合、アーカイブがすでに展開済みであっても、Trueに設定するとアーカイブを再展開し、展開先フォルダを上書きします。 - delete_extracted (
bool, デフォルトはFalse) — 抽出されたファイルを削除（または保持）するかどうか。 - extract_on_the_fly (
bool, デフォルトはFalse) —Trueの場合、読み込み中に圧縮ファイルを展開します。 - use_etag (
bool、デフォルトはTrue) — ETag HTTPレスポンスヘッダーを使用して、キャッシュされたファイルを検証するかどうかを指定します。 - num_proc (
int, 省略可) — ファイルを並列でダウンロードするために起動するプロセスの数。 - max_retries (
int、デフォルトは1) — HTTP リクエストが失敗した場合に再試行する回数。 - token (
strまたはbool、省略可) — Datasets Hub 上のリモートファイルに使用する Bearer トークンとして用いる任意の文字列またはブール値。Trueの場合、または指定されていない場合は、~/.huggingfaceからトークンを取得します。 - storage_options (
dict, 任意) — データセットのファイルシステムバックエンドに渡すためのキー/値のペア（該当する場合）。 - download_desc (
str, 省略可能) — ファイルのダウンロード中に、プログレスバーとともに表示される説明です。 - disable_tqdm (
bool、デフォルトはFalse) — 個別ファイルのダウンロード進捗バーを無効にするかどうか
キャッシュされたパスマネージャーの設定。
class datasets.DownloadMode
< source >( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )
既存のダウンロードおよびデータの扱い方を指定するためのEnum。
デフォルトモードはREUSE_DATASET_IF_EXISTSで、存在する場合は生のダウンロードと準備済みのデータセットの両方を再利用します。
生成モード:
| ダウンロード | データセット | |
|---|---|---|
REUSE_DATASET_IF_EXISTS（デフォルト） | 再利用 | 再利用 |
REUSE_CACHE_IF_EXISTS | 再利用 | フレッシュ |
FORCE_REDOWNLOAD | フレッシュ | フレッシュ |
検証
class datasets.VerificationMode
< source >( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1 )
実行する検証チェックを指定するEnum。
デフォルトモードはBASIC_CHECKSであり、データセットを初めて生成/ダウンロードする際の遅延を避けるため、基本的なチェックのみを実行します。
検証モード:
| 検証チェック | |
|---|---|
ALL_CHECKS | ダウンロードされたファイルの分割チェックおよび妥当性（ファイル数、チェックサム） |
BASIC_CHECKS（デフォルト） | ALL_CHECKSと同じですが、ダウンロードされたファイルのチェックは行いません |
NO_CHECKS | None |
分割
class datasets.SplitGenerator
< source >( name: strgen_kwargs: dict = <factory> )
ジェネレータの分割情報を定義します。
GeneratorBasedBuilder._split_generators の戻り値として使用してください。
詳細と使用例については、GeneratorBasedBuilder._split_generators を参照してください。
データセットの分割用のEnum。
データセットは通常、トレーニングや評価のさまざまな段階で使用するために、異なるサブセットに分割されます。
TRAIN: 学習データ。VALIDATION: 検証データ。存在する場合、モデルの反復処理（ハイパーパラメータの変更、モデルアーキテクチャの変更など）中に評価データとして使用されます。TEST: テストデータです。これはメトリクスを報告するために使用するデータです。モデルの反復処理中にこれを使用すると、データに過学習する可能性があるため、通常は使用しません。ALL: 定義されたすべてのデータセット分割の和集合。
すべてのスプリット（構成を含む）はdatasets.SplitBaseを継承します。
分割に関する詳細は、ガイドを参照してください。
例:
>>> datasets.SplitGenerator(
... name=datasets.Split.TRAIN,
... gen_kwargs={"split_key": "train", "files": dl_manager.download_and extract(url)},
... ),
... datasets.SplitGenerator(
... name=datasets.Split.VALIDATION,
... gen_kwargs={"split_key": "validation", "files": dl_manager.download_and extract(url)},
... ),
... datasets.SplitGenerator(
... name=datasets.Split.TEST,
... gen_kwargs={"split_key": "test", "files": dl_manager.download_and extract(url)},
... )名前付き分割（train、test など）に対応するディスクリプタ。
例:
各ディスクリプタは、加算またはスライスによって他のディスクリプタと組み合わせることができます。
split = datasets.Split.TRAIN.subsplit(datasets.percent[0:25]) + datasets.Split.TEST生成される分割は、train分割の25%とtest分割の100%をマージしたものに相当します。
同じ分割を2回追加することはできないため、以下のコードは失敗します:
split = (
datasets.Split.TRAIN.subsplit(datasets.percent[:25]) +
datasets.Split.TRAIN.subsplit(datasets.percent[75:])
) # Error
split = datasets.Split.TEST + datasets.Split.ALL # Error定義されたすべてのデータセットの分割の和集合に対応する分割。
class datasets.ReadInstruction
< source >( split_namerounding = Nonefrom_ = Noneto = Noneunit = None )
データセットの読み取り指示。
例:
# The following lines are equivalent:
ds = datasets.load_dataset('ylecun/mnist', split='test[:33%]')
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction.from_spec('test[:33%]'))
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction('test', to=33, unit='%'))
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction(
'test', from_=0, to=33, unit='%'))
# The following lines are equivalent:
ds = datasets.load_dataset('ylecun/mnist', split='test[:33%]+train[1:-1]')
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction.from_spec(
'test[:33%]+train[1:-1]'))
ds = datasets.load_dataset('ylecun/mnist', split=(
datasets.ReadInstruction('test', to=33, unit='%') +
datasets.ReadInstruction('train', from_=1, to=-1, unit='abs')))
# The following lines are equivalent:
ds = datasets.load_dataset('ylecun/mnist', split='test[:33%](pct1_dropremainder)')
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction.from_spec(
'test[:33%](pct1_dropremainder)'))
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction(
'test', from_=0, to=33, unit='%', rounding="pct1_dropremainder"))
# 10-fold validation:
tests = datasets.load_dataset(
'ylecun/mnist',
[datasets.ReadInstruction('train', from_=k, to=k+10, unit='%')
for k in range(0, 100, 10)])
trains = datasets.load_dataset(
'ylecun/mnist',
[datasets.ReadInstruction('train', to=k, unit='%') + datasets.ReadInstruction('train', from_=k+10, unit='%')
for k in range(0, 100, 10)])from_spec
< source >( spec )
文字列の仕様からReadInstructionインスタンスを作成します。
例:
test: test split.
test + validation: test split + validation split.
test[10:]: test split, minus its first 10 records.
test[:10%]: first 10% records of test split.
test[:20%](pct1_dropremainder): first 10% records, rounded with the pct1_dropremainder rounding.
test[:-5%]+train[40%:60%]: first 95% of test + middle 20% of train.指示を絶対的な指示のリストに変換します。
これらの絶対的な指示は、その後、合計されます。
バージョン
class datasets.Version
< source >( version_str: strdescription: typing.Optional[str] = Nonemajor: typing.Union[str, int, NoneType] = Noneminor: typing.Union[str, int, NoneType] = Nonepatch: typing.Union[str, int, NoneType] = None )
データセットのバージョン MAJOR.MINOR.PATCH。