# Carregar

Seus dados podem ser armazenados em vários locais; eles podem estar no disco da sua máquina local, em um repositório do Github e em estruturas de dados em memória, como dicionários Python e DataFrames do Pandas. Independentemente de onde um conjunto de dados está armazenado, o 🤗 Datasets pode ajudar você a carregá-lo.

Este guia mostrará como carregar um conjunto de dados de:

- O Hugging Face Hub
- Arquivos locais
- Dados em memória
- Offline
- Um slice específico de um split

Para mais detalhes específicos sobre o carregamento de outras modalidades de dataset, consulte o guia de carregamento de dataset de áudio, o guia de carregamento de dataset de imagem, o guia de carregamento de dataset de vídeo, o guia de carregamento de dataset de malha, o guia de carregamento de dataset de texto ou o guia de carregamento de tarefas de avaliação de agentes.

## Hugging Face Hub

Você também pode carregar um dataset de qualquer repositório de datasets no Hub! Comece [criando um repositório de dataset](share#create-the-repository) e faça o upload dos seus arquivos de dados. Agora você pode usar a função [load_dataset()](/docs/datasets/main/pt/package_reference/loading_methods#datasets.load_dataset) para carregar o dataset.

Por exemplo, tente carregar os arquivos deste [repositório de demonstração](https://huggingface.co/datasets/lhoestq/demo1) fornecendo o namespace do repositório e o nome do conjunto de dados. Este repositório de conjunto de dados contém arquivos CSV, e o código abaixo carrega o conjunto de dados a partir dos arquivos CSV:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("lhoestq/demo1")
```

Alguns conjuntos de dados podem ter mais de uma versão com base em tags, branches ou commits do Git. Use o parâmetro `revision` para especificar a versão do conjunto de dados que você deseja carregar:

```py
>>> dataset = load_dataset(
...   "lhoestq/custom_squad",
...   revision="main"  # tag name, or branch name, or commit hash
... )
```

> [!TIP]
> Consulte o tutorial [Upload de um dataset para o Hub](./upload_dataset) para mais detalhes sobre como criar um repositório de dataset no Hub e como enviar seus arquivos de dados.

Um dataset carrega por padrão todos os dados na divisão `train`, ou verifica menções ou nomes de divisões nos nomes dos arquivos de dados (por exemplo, "train", "test" e "validation"). Use o parâmetro `data_files` para mapear arquivos de dados para divisões como `train`, `validation` e `test`:

```py
>>> data_files = {"train": "train.csv", "test": "test.csv"}
>>> dataset = load_dataset("namespace/your_dataset_name", data_files=data_files)
```

> [!WARNING]
> Se você não especificar quais arquivos de dados usar, [load_dataset()](/docs/datasets/main/pt/package_reference/loading_methods#datasets.load_dataset) retornará todos os arquivos de dados. Isso pode levar muito tempo se você carregar um conjunto de dados grande, como o C4, que contém aproximadamente 13 TB de dados.

Você também pode carregar um subconjunto específico dos arquivos com o parâmetro `data_files` ou `data_dir`. Esses parâmetros podem aceitar um caminho relativo que é resolvido em relação ao caminho base correspondente à origem de carregamento do conjunto de dados.

```py
>>> from datasets import load_dataset

# load files that match the grep pattern
>>> c4_subset = load_dataset("allenai/c4", data_files="en/c4-train.0000*-of-01024.json.gz")

# load dataset from the en directory on the Hub
>>> c4_subset = load_dataset("allenai/c4", data_dir="en")
```

O parâmetro `split` também pode mapear um arquivo de dados para um split específico:

```py
>>> data_files = {"validation": "en/c4-validation.*.json.gz"}
>>> c4_validation = load_dataset("allenai/c4", data_files=data_files, split="validation")
```

## Arquivos locais e remotos

Os datasets podem ser carregados de arquivos locais armazenados no seu computador e de arquivos remotos. Os datasets provavelmente estão armazenados como arquivos `csv`, `json`, `txt`, `parquet` ou `tsfile`. A função [load_dataset()](/docs/datasets/main/pt/package_reference/loading_methods#datasets.load_dataset) pode carregar cada um desses tipos de arquivo.

### CSV

🤗 O Datasets pode ler um conjunto de dados composto por um ou vários arquivos CSV (neste caso, passe seus arquivos CSV como uma lista):

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("csv", data_files="my_file.csv")
```

> [!TIP]
> Para mais detalhes, consulte o guia [como carregar datasets tabulares de arquivos CSV](tabular_load#csv-files).

### JSON

Arquivos JSON são carregados diretamente com [load_dataset()](/docs/datasets/main/pt/package_reference/loading_methods#datasets.load_dataset), conforme mostrado abaixo:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("json", data_files="my_file.json")
```

Arquivos JSON possuem formatos diversos, mas acreditamos que o formato mais eficiente é ter múltiplos objetos JSON; cada linha representa uma linha individual de dados. Por exemplo:

```json
{"a": 1, "b": 2.0, "c": "foo", "d": false}
{"a": 4, "b": -5.5, "c": null, "d": true}
```

Outro formato de JSON que você pode encontrar é o de campo aninhado, no qual será necessário especificar o argumento `field` conforme mostrado a seguir:

```py
{"version": "0.1.0",
 "data": [{"a": 1, "b": 2.0, "c": "foo", "d": false},
          {"a": 4, "b": -5.5, "c": null, "d": true}]
}

>>> from datasets import load_dataset
>>> dataset = load_dataset("json", data_files="my_file.json", field="data")
```

Para carregar arquivos JSON remotos via HTTP, passe as URLs em vez disso:

```py
>>> base_url = "https://rajpurkar.github.io/SQuAD-explorer/dataset/"
>>> dataset = load_dataset("json", data_files={"train": base_url + "train-v1.1.json", "validation": base_url + "dev-v1.1.json"}, field="data")
```

Embora esses sejam os formatos JSON mais comuns, você verá outros conjuntos de dados formatados de maneira diferente. O Datasets reconhece esses outros formatos e usará os métodos de carregamento de JSON do Python como alternativa para tratá-los.

### Parquet

Arquivos Parquet são armazenados em um formato colunar, ao contrário de arquivos baseados em linhas, como um CSV. Grandes conjuntos de dados podem ser armazenados em um arquivo Parquet, pois ele é mais eficiente e rápido ao retornar sua consulta.

Para carregar um arquivo Parquet:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("parquet", data_files={'train': 'train.parquet', 'test': 'test.parquet'})
```

Para carregar arquivos Parquet remotos via HTTP, passe as URLs em vez disso:

```py
>>> base_url = "https://huggingface.co/datasets/wikimedia/wikipedia/resolve/main/20231101.ab/"
>>> data_files = {"train": base_url + "train-00000-of-00001.parquet"}
>>> wiki = load_dataset("parquet", data_files=data_files, split="train")
```

### Arrow

Arquivos Arrow são armazenados em um formato colunar em memória, ao contrário de formatos baseados em linhas, como CSV, e formatos não compactados, como Parquet.

Para carregar um arquivo Arrow:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("arrow", data_files={'train': 'train.arrow', 'test': 'test.arrow'})
```

Para carregar arquivos Arrow remotos via HTTP, passe as URLs em vez disso:

```py
>>> base_url = "https://huggingface.co/datasets/croissantllm/croissant_dataset/resolve/main/english_660B_11/"
>>> data_files = {"train": base_url + "train/data-00000-of-00080.arrow"}
>>> wiki = load_dataset("arrow", data_files=data_files, split="train")
```

Arrow é o formato de arquivo usado pelo 🤗 Datasets por baixo dos panos, portanto, você pode carregar um arquivo Arrow local usando diretamente [Dataset.from_file()](/docs/datasets/main/pt/package_reference/main_classes#datasets.Dataset.from_file):

```py
>>> from datasets import Dataset
>>> dataset = Dataset.from_file("data.arrow")
```

Diferentemente de [load_dataset()](/docs/datasets/main/pt/package_reference/loading_methods#datasets.load_dataset), [Dataset.from_file()](/docs/datasets/main/pt/package_reference/main_classes#datasets.Dataset.from_file) faz o mapeamento de memória do arquivo Arrow sem preparar o dataset no cache, economizando espaço em disco. Nesse caso, o diretório de cache para armazenar os resultados intermediários de processamento será o diretório do arquivo Arrow.

Por enquanto, apenas o formato de streaming Arrow é suportado. O formato de arquivo Arrow IPC (também conhecido como Feather V2) não é suportado.

### Lance

[Lance](https://lance.org) é um formato de tabela de lakehouse multimodal aberto para IA. As tabelas Lance podem armazenar nativamente não apenas texto e valores escalares, mas também objetos binários grandes (blobs), como imagens, áudio e vídeo, junto com seus dados tabulares.

```py
>>> from datasets import load_dataset
>>> lance_base_url = "lance-format/laion-1m"
```

Para transmitir o conjunto de dados sem copiá-lo para sua máquina local, especifique o parâmetro `streaming=True`:

```py
ds = load_dataset(lance_base_url, split="train", streaming=True)
# Take first three rows
for row in ds.take(3):
    print(row["caption"], row["image"])
```

Isso retornará a legenda da imagem e os bytes da imagem em uma única solicitação.

### Vortex

[Vortex](https://docs.vortex.dev) é um formato de arquivo colunar projetado para varreduras rápidas sobre dados comprimidos. Instale-o com `pip install vortex-data` e, em seguida, carregue arquivos `.vortex` como qualquer outro formato empacotado:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("vortex", data_files="data.vortex", split="train")
```

Colunas e filtros são empurrados para o scan do Vortex, de modo que apenas as linhas e colunas solicitadas são lidas. Isso funciona também durante o streaming, o que permite filtrar um dataset no Hub sem baixar as partes que não correspondem:

```py
>>> filters = [("label", "==", 1)]
>>> dataset = load_dataset(vortex_dataset_id, columns=["text", "label"], filters=filters, streaming=True, split="train")
```

Os filtros utilizam a mesma forma normal disjuntiva do carregador Parquet: uma lista de predicados `(column, operator, value)` é uma conjunção, e uma lista desses é uma disjunção. Nulos seguem a semântica SQL — um nulo não satisfaz nenhuma comparação, portanto, uma linha cuja coluna filtrada é nula nunca é retornada, inclusive para `not in`. Para qualquer coisa que essa forma não possa expressar, passe uma expressão Vortex em vez disso:

```py
>>> import vortex.expr as ve
>>> dataset = load_dataset(vortex_dataset_id, filters=ve.column("score") >= 0.5, split="train")
```

Vortex abre os arquivos por conta própria, em vez de usar o fsspec, portanto `data_files` pode apontar para caminhos locais, datasets do Hub e os locais remotos que o Vortex lê nativamente (HTTP e os object stores comuns) — mas não dentro de arquivos compactados (`zip://...`) ou outros protocolos exclusivos do fsspec.

### Arquivos HDF5

Arquivos [HDF5](https://www.hdfgroup.org/solutions/hdf5/) são comumente usados para armazenar grandes quantidades de dados numéricos em computação científica e aprendizado de máquina. Carregar arquivos HDF5 com 🤗 Datasets é semelhante a carregar arquivos CSV:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("hdf5", data_files="data.h5")
```

Observe que o carregador HDF5 pressupõe que o arquivo tenha uma estrutura "tabular", ou seja, que todos os conjuntos de dados no arquivo tenham (o mesmo número de) linhas em sua primeira dimensão.

### TsFile

[TsFile](https://tsfile.apache.org/) é um formato de arquivo colunar projetado para dados de séries temporais, usado como a camada de armazenamento nativa do [Apache IoTDB](https://iotdb.apache.org/). Ele representa nativamente timestamps, tags de dispositivos e campos de medição, e mantém um índice de tempo interno que permite a poda eficiente de intervalos de tempo.

Cada linha no dataset resultante corresponde a um **device** (identificado pelas colunas TAG); a coluna `time` e todas as colunas FIELD são colunas de lista contendo a série temporal completa daquele device, ordenada em ordem crescente de tempo.

Para carregar um TsFile:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("tsfile", data_files="my_data.tsfile")
```

Filtrar por intervalo de tempo — os limites são propagados para o índice de tempo interno do TsFile e aceitam `int` epochs, `datetime`, `date`, strings ISO-8601 ou escalares de timestamp do `pyarrow`:

```py
>>> from datetime import datetime
>>> dataset = load_dataset(
...     "tsfile",
...     data_files="my_data.tsfile",
...     start_time=datetime(2023, 11, 14),
...     end_time=datetime(2023, 11, 15),
... )
```

> [!TIP]
> Para mais detalhes, consulte o guia [como carregar dados TsFile](tsfile_load).

### Harbor

Os conjuntos de dados [Harbor](https://harborframework.com/docs) são coleções de *tarefas* usadas para avaliar agentes de IA. Eles são compostos por diretórios, em vez de arquivos de dados: cada tarefa é um diretório com um arquivo de configuração `task.toml` e um arquivo `instruction.md`, além do seu ambiente, verificador e solução.

Cada linha do dataset resultante descreve uma tarefa (sua instrução, seu `task.toml`, os arquivos que ela distribui) e o carregamento nunca executa nada:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("harborframework/terminal-bench")
>>> dataset["train"][0]["task_id"]
'tasks/atrx-vep-crispr'
```

> [!TIP]
> Para mais detalhes, consulte o guia [como carregar tarefas de avaliação de agentes](harbor_load).

### PDB

[PDB](https://www.wwpdb.org/documentation/file-format) (Protein Data Bank) é o formato legado de largura fixa para representar estruturas macromoleculares 3D. Embora o mmCIF seja o padrão moderno, o PDB continua amplamente utilizado e muitos conjuntos de dados históricos estão nesse formato.

Cada linha é um arquivo de estrutura, seguindo o mesmo layout de pastas do `ImageFolder`: os nomes das subpastas se tornam rótulos e um arquivo `metadata.csv`/`metadata.jsonl` adiciona metadados por estrutura. A coluna `structure` usa [BioStructure](/docs/datasets/main/pt/package_reference/main_classes#datasets.BioStructure) com `format="pdb"` e decodifica para um objeto `Bio.PDB.Structure.Structure` contendo os modelos, cadeias, resíduos e átomos do arquivo. A decodificação requer `biopython`; sem ele, acessar uma estrutura decodificada levanta `ImportError`.

Para carregar arquivos PDB de um diretório:

```py
>>> from datasets import BioStructure, load_dataset
>>> dataset = load_dataset("pdb", data_dir="path/to/structures")
>>> dataset["train"].features["structure"]
BioStructure(format='pdb', decode=True)
```

Para acessar o dicionário subjacente `{"bytes": ..., "path": ...}` sem decodificar ou exigir biopython, converta a coluna com `decode=False`:

```py
>>> dataset = dataset.cast_column("structure", BioStructure(format="pdb", decode=False))
```

As extensões `.pdb` e `.ent` são suportadas.

### SQL

Leia o conteúdo do banco de dados com [from_sql()](/docs/datasets/main/pt/package_reference/main_classes#datasets.Dataset.from_sql) especificando o URI para se conectar ao seu banco de dados. Você pode ler tanto nomes de tabelas quanto consultas:

```py
>>> from datasets import Dataset
# load entire table
>>> dataset = Dataset.from_sql("data_table_name", con="sqlite:///sqlite_file.db")
# load from query
>>> dataset = Dataset.from_sql("SELECT text FROM table WHERE length(text) > 100 LIMIT 10", con="sqlite:///sqlite_file.db")
```

> [!TIP]
> Para mais detalhes, consulte o guia [como carregar conjuntos de dados tabulares de bancos de dados SQL](tabular_load#databases).

### WebDataset

O formato [WebDataset](https://github.com/webdataset/webdataset) é baseado em arquivos TAR e é adequado para grandes conjuntos de dados de imagens. Devido ao seu tamanho, os WebDatasets geralmente são carregados em modo de streaming (usando `streaming=True`).

Você pode carregar um WebDataset da seguinte forma:

```python
>>> from datasets import load_dataset
>>>
>>> path = "path/to/train/*.tar"
>>> dataset = load_dataset("webdataset", data_files={"train": path}, split="train", streaming=True)
```

Para carregar WebDatasets remotos via HTTP, passe as URLs em vez disso:

```python
>>> from datasets import load_dataset
>>>
>>> base_url = "https://huggingface.co/datasets/lhoestq/small-publaynet-wds/resolve/main/publaynet-train-{i:06d}.tar"
>>> urls = [base_url.format(i=i) for i in range(4)]
>>> dataset = load_dataset("webdataset", data_files={"train": urls}, split="train", streaming=True)
```

### mmCIF

[mmCIF](https://mmcif.wwpdb.org/) (arquivo de informações cristalográficas de macromoléculas) é o formato padrão moderno para representar estruturas tridimensionais de macromoléculas, utilizado pelo Banco de Dados de Proteínas (PDB) desde 2014.

Cada linha é um arquivo de estrutura, seguindo o mesmo layout de pastas do `ImageFolder`: os nomes das subpastas se tornam rótulos e um arquivo `metadata.csv`/`metadata.jsonl` adiciona metadados por estrutura. A coluna `structure` usa [BioStructure](/docs/datasets/main/pt/package_reference/main_classes#datasets.BioStructure) com `format="mmcif"` e decodifica para um objeto `Bio.PDB.Structure.Structure` contendo os modelos, cadeias, resíduos e átomos do arquivo. A decodificação requer `biopython`; sem ele, acessar uma estrutura decodificada levanta `ImportError`.

Para carregar arquivos mmCIF de um diretório:

```py
>>> from datasets import BioStructure, load_dataset
>>> dataset = load_dataset("mmcif", data_dir="path/to/structures")
>>> dataset["train"].features["structure"]
BioStructure(format='mmcif', decode=True)
```

Para acessar o dicionário subjacente `{"bytes": ..., "path": ...}` sem decodificar ou exigir biopython, converta a coluna com `decode=False`:

```py
>>> dataset = dataset.cast_column("structure", BioStructure(format="mmcif", decode=False))
```

As extensões `.cif` e `.mmcif` são suportadas.

### GenBank

[GenBank](https://www.ncbi.nlm.nih.gov/genbank/) é um formato baseado em texto da NCBI para sequências de nucleotídeos e proteínas, juntamente com suas anotações. Os arquivos usam a extensão `.gb`, `.gbk` ou `.genbank` (opcionalmente comprimidos) e a seção `FEATURES` de cada registro é decodificada em objetos estruturados.

Além das colunas analisadas leves, cada linha inclui uma coluna `record` do tipo `BioSequence(format="genbank")`, que é decodificada para um `Bio.SeqRecord.SeqRecord` quando o `biopython` está instalado. Converta esta coluna para `BioSequence(format="genbank", decode=False)` para acessar os bytes do registro original como `{"bytes": ..., "path": None}`, ou omita-a com `columns=[...]` para usar apenas as colunas analisadas sem o `biopython`.

Para carregar arquivos GenBank:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("genbank", data_files="*.gb", split="train")
```

Você pode testá-lo em um pequeno conjunto de dados de exemplo com registros reais da NCBI (um deles está compactado em gzip para mostrar que arquivos compactados são carregados de forma transparente):

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("ermiaazarkhalili/datasets-genbank-test", data_files="*.gb*", split="train")
>>> dataset[0]["locus_name"], dataset[0]["organism"], dataset[0]["length"]
```

### FASTQ

[FASTQ](https://en.wikipedia.org/wiki/FASTQ_format) é um formato baseado em texto para armazenar sequências de nucleotídeos junto com seus escores de qualidade, amplamente utilizado para dados de sequenciamento de alto rendimento.

Carregar um arquivo FASTQ:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("fastq", data_files="reads.fq")
```

O carregador retorna cinco colunas:

| Coluna | Tipo | Descrição |
|--------|------|-------------|
| `id` | string | Identificador da sequência (primeira palavra após `@`) |
| `description` | string | Linha de descrição completa (tudo após o id) |
| `sequence` | large_string | A sequência de nucleotídeos |
| `quality` | large_string | Pontuações de qualidade codificadas em ASCII |
| `record` | [BioSequence](/docs/datasets/main/pt/package_reference/main_classes#datasets.BioSequence) | Com `format="fastq"`, armazena os bytes originais de cada registro, decodificados para um `SeqRecord` do Biopython quando acessado. |

Ler as colunas analisadas não requer Biopython; exclua `record` com `columns` ou use `dataset.cast_column("record", BioSequence(decode=False))` (importado de `datasets`) para acessar seu armazenamento `{"bytes": ..., "path": None}` sem decodificação.

Carregue apenas colunas específicas:

```py
>>> dataset = load_dataset("fastq", data_files="reads.fq", columns=["sequence", "quality"])
```

Arquivos compactados (.fq.gz, .fastq.gz, .fq.bz2, .fq.xz) são detectados e descompactados automaticamente.

### FASTA

[FASTA](https://en.wikipedia.org/wiki/FASTA_format) é um formato baseado em texto para representar sequências de nucleotídeos (DNA/RNA) ou sequências de peptídeos (proteínas), amplamente utilizado em bioinformática.

Para carregar um arquivo FASTA:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("fasta", data_files="sequences.fasta")
```

Isso retorna um conjunto de dados com as seguintes colunas:
- `id`: Identificador da sequência (primeira palavra após `>`)
- `description`: Linha de descrição completa (tudo após o id)
- `sequence`: A sequência biológica (DNA/RNÁ/proteína)
- `record`: Um [BioSequence](/docs/datasets/main/pt/package_reference/main_classes#datasets.BioSequence) com `format="fasta"` que armazena os bytes originais de cada registro, decodificados para um `SeqRecord` do Biopython quando acessado.

Ler as colunas analisadas não requer Biopython; exclua `record` com `columns` ou use `dataset.cast_column("record", BioSequence(decode=False))` (importado de `datasets`) para acessar seu armazenamento `{"bytes": ..., "path": None}` sem decodificação.

Você também pode carregar apenas colunas específicas:

```py
>>> dataset = load_dataset("fasta", data_files="sequences.fa", columns=["id", "sequence"])
```

Arquivos FASTA com várias extensões são suportados: `.fa`, `.fasta`, `.fna` (ácido nucleico), `.ffn` (nucleotídeo de regiões gênicas), `.faa` (ácido amino) e `.frn` (RNA não codificante). Arquivos compactados (gzip, bzip2, xz) são detectados e descompactados automaticamente.

## Arquivos remotos

Se você tiver arquivos remotos, provavelmente armazenados como `csv`, `json`, `txt`, `parquet` ou qualquer formato suportado, a função [load_dataset()](/docs/datasets/main/pt/package_reference/loading_methods#datasets.load_dataset) pode carregá-los se você especificar seus caminhos remotos:

- URLs `https://` para arquivos públicos online, por exemplo, `data_files=["https://rajpurkar.github.io/SQuAD-explorer/dataset/train-v2.0.json"]`
- URLs `hf://` para arquivos em qualquer [repositório de Dataset](https://huggingface.co/docs/hub/datasets-overview) ou [Storage Bucket](https://huggingface.co/docs/hub/storage-buckets) no Hugging Face, por exemplo, `data_files=["hf://datasets/karpathy/tinystories-gpt4-clean/tinystories_gpt4_clean.parquet"]` ou `data_files=["hf://buckets/julien-c/my-training-bucket/julien/affluence.csv"]`

## Multiprocessamento

Quando um conjunto de dados é composto por vários arquivos (que chamamos de "shards"), é possível acelerar significativamente a etapa de download e preparação do conjunto de dados.

Você pode escolher quantos processos deseja usar para preparar um dataset em paralelo usando `num_proc`. Neste caso, cada processo recebe um subconjunto de shards para preparar:

```python
from datasets import load_dataset

imagenet = load_dataset("timm/imagenet-1k-wds", num_proc=8)
ml_librispeech_spanish = load_dataset("facebook/multilingual_librispeech", "spanish", num_proc=8)
```

## Dados em memória

🤗 O Datasets também permitirá que você crie um [Dataset](/docs/datasets/main/pt/package_reference/main_classes#datasets.Dataset) diretamente a partir de estruturas de dados em memória, como dicionários Python e DataFrames do Pandas.

### Dicionário Python

Carregue dicionários Python com [from_dict()](/docs/datasets/main/pt/package_reference/main_classes#datasets.Dataset.from_dict):

```py
>>> from datasets import Dataset
>>> my_dict = {"a": [1, 2, 3]}
>>> dataset = Dataset.from_dict(my_dict)
```

### Lista de dicionários em Python

Carregue uma lista de dicionários Python com [from_list()](/docs/datasets/main/pt/package_reference/main_classes#datasets.Dataset.from_list):

```py
>>> from datasets import Dataset
>>> my_list = [{"a": 1}, {"a": 2}, {"a": 3}]
>>> dataset = Dataset.from_list(my_list)
```

### Gerador Python

Crie um dataset a partir de um gerador Python com [from_generator()](/docs/datasets/main/pt/package_reference/main_classes#datasets.Dataset.from_generator):

```py
>>> from datasets import Dataset
>>> def my_gen():
...     for i in range(1, 4):
...         yield {"a": i}
...
>>> dataset = Dataset.from_generator(my_gen)
```

Essa abordagem suporta o carregamento de dados maiores que a memória disponível.

Você também pode definir um conjunto de dados particionado passando listas para `gen_kwargs`:

```py
>>> def gen(shards):
...     for shard in shards:
...         with open(shard) as f:
...             for line in f:
...                 yield {"line": line}
...
>>> shards = [f"data{i}.txt" for i in range(32)]
>>> ds = IterableDataset.from_generator(gen, gen_kwargs={"shards": shards})
>>> ds = ds.shuffle(seed=42, buffer_size=10_000)  # shuffles the shards order + uses a shuffle buffer
>>> from torch.utils.data import DataLoader
>>> dataloader = DataLoader(ds.with_format("torch"), num_workers=4)  # give each worker a subset of 32/4=8 shards
```

### Pandas DataFrame

Carregue DataFrames do Pandas com [from_pandas()](/docs/datasets/main/pt/package_reference/main_classes#datasets.Dataset.from_pandas):

```py
>>> from datasets import Dataset
>>> import pandas as pd
>>> df = pd.DataFrame({"a": [1, 2, 3]})
>>> dataset = Dataset.from_pandas(df)
```

> [!TIP]
> Para mais detalhes, consulte o guia [como carregar datasets tabulares de DataFrames do Pandas](tabular_load#pandas-dataframes).

## Offline

Mesmo sem uma conexão com a internet, ainda é possível carregar um conjunto de dados. Desde que você tenha baixado um conjunto de dados do repositório do Hub anteriormente, ele deve estar em cache. Isso significa que você pode recarregar o conjunto de dados do cache e usá-lo offline.

Se você sabe que não terá acesso à internet, pode executar o 🤗 Datasets em modo totalmente offline. Isso economiza tempo, pois, em vez de aguardar o tempo limite do download do Dataset builder, o 🤗 Datasets buscará diretamente no cache. Defina a variável de ambiente `HF_HUB_OFFLINE` como `1` para habilitar o modo totalmente offline.

## Divisão em fatias

Você também pode escolher carregar apenas fatias específicas de um split. Há duas opções para fatiar um split: usar strings ou a API [ReadInstruction](/docs/datasets/main/pt/package_reference/builder_classes#datasets.ReadInstruction). Strings são mais compactas e legíveis para casos simples, enquanto [ReadInstruction](/docs/datasets/main/pt/package_reference/builder_classes#datasets.ReadInstruction) é mais fácil de usar com parâmetros de fatiamento variáveis.

Concatene um split `train` e um split `test` por:

```py
>>> train_test_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train+test")
===STRINGAPI-READINSTRUCTION-SPLIT===
>>> ri = datasets.ReadInstruction("train") + datasets.ReadInstruction("test")
>>> train_test_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split=ri)
```

Selecione linhas específicas do split `train`:

```py
>>> train_10_20_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[10:20]")
===STRINGAPI-READINSTRUCTION-SPLIT===
>>> train_10_20_ds = datasets.load_dataset("rojagtap/bookcorpus", split=datasets.ReadInstruction("train", from_=10, to=20, unit="abs"))
```

Ou selecione uma porcentagem de uma divisão com:

```py
>>> train_10pct_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[:10%]")
===STRINGAPI-READINSTRUCTION-SPLIT===
>>> train_10_20_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split=datasets.ReadInstruction("train", to=10, unit="%"))
```

Selecione uma combinação de porcentagens de cada divisão:

```py
>>> train_10_80pct_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[:10%]+train[-80%:]")
===STRINGAPI-READINSTRUCTION-SPLIT===
>>> ri = (datasets.ReadInstruction("train", to=10, unit="%") + datasets.ReadInstruction("train", from_=-80, unit="%"))
>>> train_10_80pct_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split=ri)
```

Por fim, você pode até mesmo criar splits validados por validação cruzada. O exemplo abaixo cria splits de validação cruzada com 10 dobras. Cada conjunto de validação é um bloco de 10%, e o conjunto de treinamento compõe o bloco complementar restante de 90%:

```py
>>> val_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split=[f"train[{k}%:{k+10}%]" for k in range(0, 100, 10)])
>>> train_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split=[f"train[:{k}%]+train[{k+10}%:]" for k in range(0, 100, 10)])
===STRINGAPI-READINSTRUCTION-SPLIT===
>>> val_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", [datasets.ReadInstruction("train", from_=k, to=k+10, unit="%") for k in range(0, 100, 10)])
>>> train_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", [(datasets.ReadInstruction("train", to=k, unit="%") + datasets.ReadInstruction("train", from_=k+10, unit="%")) for k in range(0, 100, 10)])
```

### Corte e arredondamento por porcentagem

O comportamento padrão é arredondar as fronteiras para o inteiro mais próximo em conjuntos de dados em que as fronteiras do slice solicitado não dividem uniformemente por 100. Como mostrado abaixo, alguns slices podem conter mais exemplos do que outros. Por exemplo, se a seguinte divisão de treinamento incluir 999 registros, então:

```py
# 19 records, from 500 (included) to 519 (excluded).
>>> train_50_52_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[50%:52%]")
# 20 records, from 519 (included) to 539 (excluded).
>>> train_52_54_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[52%:54%]")
```

Se você deseja splits de tamanhos iguais, use o arredondamento `pct1_dropremainder` em vez disso. Isso trata os limites de porcentagem especificados como múltiplos de 1%.

```py
# 18 records, from 450 (included) to 468 (excluded).
>>> train_50_52pct1_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split=datasets.ReadInstruction("train", from_=50, to=52, unit="%", rounding="pct1_dropremainder"))
# 18 records, from 468 (included) to 486 (excluded).
>>> train_52_54pct1_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split=datasets.ReadInstruction("train",from_=52, to=54, unit="%", rounding="pct1_dropremainder"))
# Or equivalently:
>>> train_50_52pct1_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[50%:52%](pct1_dropremainder)")
>>> train_52_54pct1_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[52%:54%](pct1_dropremainder)")
```

> [!WARNING]
> O arredondamento `pct1_dropremainder` pode truncar os últimos exemplos de um conjunto de dados se o número de exemplos no seu conjunto de dados não for divisível por 100.

## Solução de problemas

Às vezes, você pode obter resultados inesperados ao carregar um conjunto de dados. Dois dos problemas mais comuns que você pode encontrar são o download manual de um conjunto de dados e a especificação de recursos de um conjunto de dados.

### Especificar recursos

Ao criar um dataset a partir de arquivos locais, os [Features](/docs/datasets/main/pt/package_reference/main_classes#datasets.Features) são inferidos automaticamente pelo [Apache Arrow](https://arrow.apache.org/docs/). No entanto, os recursos do dataset nem sempre podem corresponder às suas expectativas, ou você pode querer definir os recursos por conta própria. O exemplo a seguir mostra como adicionar rótulos personalizados com o recurso [ClassLabel](/docs/datasets/main/pt/package_reference/main_classes#datasets.ClassLabel).

Comece definindo seus próprios rótulos com a classe [Features](/docs/datasets/main/pt/package_reference/main_classes#datasets.Features):

```py
>>> class_names = ["sadness", "joy", "love", "anger", "fear", "surprise"]
>>> emotion_features = Features({'text': Value('string'), 'label': ClassLabel(names=class_names)})
```

Em seguida, especifique o parâmetro `features` em [load_dataset()](/docs/datasets/main/pt/package_reference/loading_methods#datasets.load_dataset) com os recursos que você acabou de criar:

```py
>>> dataset = load_dataset('csv', data_files=file_dict, delimiter=';', column_names=['text', 'label'], features=emotion_features)
```

Agora, ao examinar os recursos do seu conjunto de dados, você pode ver que ele usa os rótulos personalizados que você definiu:

```py
>>> dataset['train'].features
{'text': Value('string'),
'label': ClassLabel(names=['sadness', 'joy', 'love', 'anger', 'fear', 'surprise'])}
```