# Utilitários de scripts

## ScriptArguments[[trl.ScriptArguments]]

#### trl.ScriptArguments[[trl.ScriptArguments]]

```python
trl.ScriptArguments(dataset_name: str | None = None, dataset_config: str | None = None, dataset_train_split: str = 'train', dataset_test_split: str = 'test', dataset_streaming: bool = False, ignore_bias_buffers: bool = False)
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.0/trl/scripts/utils.py#L146)

**Parâmetros:**

dataset_name (`str`,, *opcional*) : Caminho ou nome do conjunto de dados a ser carregado. Se `datasets` for fornecido, isso será ignorado.

dataset_config (`str`, *opcional*) : Nome da configuração do conjunto de dados. Corresponde ao argumento `name` da função [load_dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/loading_methods#datasets.load_dataset). Se `datasets` for fornecido, isso será ignorado.

dataset_train_split (`str`, *opcional*, padrão `"train"`) : Divisão do conjunto de dados a ser usada para o treinamento. Se `datasets` for fornecido, isso será ignorado.

dataset_test_split (`str`, *opcional*, padrão `"test"`) : Divisão do dataset a ser usada para avaliação. Se `datasets` for fornecido, isso será ignorado.

dataset_streaming (`bool`, *opcional*, padrão `False`) : Se deve transmitir o dataset. Se True, o dataset será carregado em modo de streaming. Se `datasets` for fornecido, isso será ignorado.

ignore_bias_buffers (`bool`, *opcional*, padrão `False`) : Argumento de depuração para treinamento distribuído. Correção para problemas de DDP com buffers de viés/máscara de LM - tipo de escalar inválido, operação in-place. Veja https://github.com/huggingface/transformers/issues/22482#issuecomment-1595790992.

Argumentos comuns a todos os scripts.

## TrlParser[[trl.TrlParser]]

#### trl.TrlParser[[trl.TrlParser]]

```python
trl.TrlParser(dataclass_types: typing.Union[trl.scripts._hf_argparser.DataClassType, collections.abc.Iterable[trl.scripts._hf_argparser.DataClassType], NoneType] = None, **kwargs)
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.0/trl/scripts/utils.py#L234)

**Parâmetros:**

dataclass_types (`DataClassType | Iterable[DataClassType]`, *opcional*) : Tipos de dataclass a serem usados para a análise de argumentos.

- ****kwargs** : Argumentos de palavra-chave adicionais passados para o construtor do [transformers.HfArgumentParser](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser).

Uma subclasse de [transformers.HfArgumentParser](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser) projetada para analisar argumentos de linha de comando com configurações baseadas em dataclasses, além de suportar o carregamento de arquivos de configuração e o gerenciamento de variáveis de ambiente.

Exemplos:

```yaml
# config.yaml
env:
    VAR1: value1
arg1: 23
```

```python
# main.py
import os
from dataclasses import dataclass
from trl import TrlParser

@dataclass
class MyArguments:
    arg1: int
    arg2: str = "alpha"

parser = TrlParser(dataclass_types=[MyArguments])
training_args = parser.parse_args_and_config()

print(training_args, os.environ.get("VAR1"))
```

```bash
$ python main.py --config config.yaml
(MyArguments(arg1=23, arg2='alpha'),) value1

$ python main.py --arg1 5 --arg2 beta
(MyArguments(arg1=5, arg2='beta'),) None
```

#### parse_args_and_config[[trl.TrlParser.parse_args_and_config]]

```python
parse_args_and_config(args: collections.abc.Iterable[str] | None = None, return_remaining_strings: bool = False, fail_with_unknown_args: bool = True, separate_remaining_strings: bool = False)
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.0/trl/scripts/utils.py#L303)

Analisa os argumentos de linha de comando e o arquivo de configuração em instâncias dos tipos de dataclass especificados.

Este método encapsula [transformers.HfArgumentParser.parse_args_into_dataclasses](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser.parse_args_into_dataclasses) e também analisa o arquivo de configuração especificado com a flag `--config`. O arquivo de configuração (em formato YAML) fornece valores de argumentos que substituem os valores padrão nos dataclasses. Os argumentos da linha de comando podem sobrescrever os valores definidos pelo arquivo de configuração. O método também define as variáveis de ambiente especificadas no campo `env` do arquivo de configuração.

#### parse_args_into_dataclasses[[trl.TrlParser.parse_args_into_dataclasses]]

```python
parse_args_into_dataclasses(args = None, return_remaining_strings = False, look_for_args_file = True, args_filename = None, args_file_flag = None)
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.0/trl/scripts/_hf_argparser.py#L298)

**Parâmetros:**

args : Lista de strings para analisar. O valor padrão é obtido de sys.argv. (igual a argparse.ArgumentParser)

return_remaining_strings : Se verdadeiro, também retorna uma lista de strings de argumentos restantes.

look_for_args_file : Se true, procurará um arquivo ".args" com o mesmo nome base que o script de ponto de entrada para este processo e adicionará seu conteúdo potencial aos argumentos da linha de comando.

args_filename : Se não for None, usará este arquivo em vez do arquivo ".args" especificado no argumento anterior.

args_file_flag : Se não for None, procurará um arquivo nos argumentos de linha de comando especificados com esta flag. A flag pode ser especificada várias vezes e a precedência é determinada pela ordem (a última tem prioridade).

**Retorna:** `Tuple consisting of`

- as instâncias de dataclass na mesma ordem em que foram passadas para o inicializador.abspath
- se aplicável, um namespace adicional para mais argumentos (não baseados em dataclass) adicionados ao parser após a inicialização.
- A lista potencial de strings de argumentos restantes. (igual a argparse.ArgumentParser.parse_known_args)

Analisa os argumentos da linha de comando em instâncias dos tipos de dataclass especificados.

Isso depende do `ArgumentParser.parse_known_args` do argparse. Consulte a documentação em: docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_args

#### set_defaults_with_config[[trl.TrlParser.set_defaults_with_config]]

```python
set_defaults_with_config(**kwargs)
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.0/trl/scripts/utils.py#L361)

Substitui os valores padrão do parser pelos fornecidos por meio de argumentos de palavra-chave, incluindo para subparsers.

Qualquer argumento com um valor padrão atualizado também será marcado como não obrigatório, caso fosse obrigatório anteriormente.

Retorna uma lista de strings que não foram consumidas pelo parser.

## get_dataset[[trl.get_dataset]]

#### trl.get_dataset[[trl.get_dataset]]

```python
trl.get_dataset(mixture_config: DatasetMixtureConfig)
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.0/trl/scripts/utils.py#L414)

**Parâmetros:**

mixture_config ([DatasetMixtureConfig](/docs/trl/v1.18.0/pt/script_utils#trl.DatasetMixtureConfig)) : Argumentos do script contendo a configuração do dataset.

**Retorna:** [DatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.DatasetDict)

Conjunto(s) de dados combinado(s) da configuração de mistura, com divisão opcional de treino/teste se `test_split_size` estiver definido.

Carrega uma mistura de conjuntos de dados com base na configuração.

Exemplo:
```python
>>> from trl import DatasetMixtureConfig, get_dataset
>>> from trl.scripts.utils import DatasetConfig

>>> mixture_config = DatasetMixtureConfig(datasets=[DatasetConfig(path="trl-lib/tldr")])
>>> get_dataset(mixture_config)
DatasetDict({
    train: Dataset({
        features: ['prompt', 'completion'],
        num_rows: 116722
    })
})
```

## DatasetConfig[[trl.scripts.utils.DatasetConfig]]

#### trl.scripts.utils.DatasetConfig[[trl.scripts.utils.DatasetConfig]]

```python
trl.scripts.utils.DatasetConfig(path: str, name: str | None = None, data_dir: str | None = None, data_files: str | list[str] | dict[str, str] | None = None, split: str = 'train', columns: list[str] | None = None, fraction: float | None = None)
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.0/trl/scripts/utils.py#L40)

**Parâmetros:**

path (`str`) : Caminho ou nome do conjunto de dados.

name (`str`, *opcional*) : Define o nome da configuração do conjunto de dados.

data_dir (`str`, *opcional*) : Define o `data_dir` da configuração do conjunto de dados. Se especificado para os construtores genéricos (csv, text etc.) ou para os conjuntos de dados do Hub e `data_files` for `None`, o comportamento é igual ao de passar `os.path.join(data_dir, **)` como `data_files` para referenciar todos os arquivos em um diretório.

data_files (`str` ou `Sequence` ou `Mapping`, *opcional*) : Caminho(s) para o(s) arquivo(s) de dados de origem.

split (`str`, *opcional*, padrão `"train"`) : Qual divisão dos dados carregar.

columns (`list[str]`, *opcional*) : Lista de nomes de colunas a serem selecionadas do conjunto de dados. Se `None`, todas as colunas são selecionadas.

fraction (`float`, *opcional*) : Proporção-alvo deste conjunto de dados na mistura final. As frações são normalizadas para que a soma entre todos os conjuntos de dados seja igual a um, e o tamanho da mistura é limitado para que nenhum conjunto de dados seja superamostrado: as primeiras `round(fraction * N)` linhas de cada conjunto de dados são mantidas, onde `N` é o maior tamanho de mistura que evita a superamostragem. Deve ser definido para todos os conjuntos de dados da mistura ou para nenhum deles. Não é suportado para conjuntos de dados em streaming. Quando não definido, os conjuntos de dados completos são concatenados.

Configuração para um conjunto de dados.

Esta classe corresponde à assinatura de [load_dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/loading_methods#datasets.load_dataset) e os argumentos são usados diretamente na função [load_dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/loading_methods#datasets.load_dataset). Você pode consultar a documentação de [load_dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/loading_methods#datasets.load_dataset) para mais detalhes.

## DatasetMixtureConfig[[trl.DatasetMixtureConfig]]

#### trl.DatasetMixtureConfig[[trl.DatasetMixtureConfig]]

```python
trl.DatasetMixtureConfig(datasets: list[trl.scripts.utils.DatasetConfig] = <factory>, streaming: bool = False, test_split_size: float | None = None)
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.0/trl/scripts/utils.py#L81)

**Parâmetros:**

datasets (`list[DatasetConfig]`) : Lista de configurações de conjunto de dados a serem incluídas na mistura.

streaming (`bool`, *opcional*, padrão `False`) : Se deve transmitir os conjuntos de dados. Se `True`, os conjuntos de dados serão carregados no modo de transmissão.

test_split_size (`float`, *opcional*) : Tamanho do conjunto de teste. Consulte o parâmetro `test_size` na função `train_test_split` para mais detalhes. Se `None`, o conjunto de dados não será dividido em conjuntos de treino e teste.

Classe de configuração para uma mistura de conjuntos de dados.

Usando [HfArgumentParser](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser), podemos transformar essa classe em argumentos [argparse](https://docs.python.org/3/library/argparse#module-argparse) que podem ser especificados na linha de comando.

Uso:

Ao usar a CLI, você pode adicionar a seguinte seção ao seu arquivo de configuração YAML:

```yaml
datasets:
- path: ...
    name: ...
    data_dir: ...
    data_files: ...
    split: ...
    columns: ...
    fraction: ...
- path: ...
    name: ...
    data_dir: ...
    data_files: ...
    split: ...
    columns: ...
streaming: ...
test_split_size: ...
```

