# 脚本 实用工具

## 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)
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.1/trl/scripts/utils.py#L146)

**参数：**

dataset_name (`str`,, *可选*) : 要加载的数据集的路径或名称。如果提供了 `datasets`，则此参数将被忽略。

dataset_config (`str`, *可选*) : 数据集配置名称。对应于 [load_dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/loading_methods#datasets.load_dataset) 函数的 `name` 参数。如果提供了 `datasets`，则此参数将被忽略。

dataset_train_split (`str`，*可选*，默认为 `"train"`)：用于训练的 Dataset split。如果提供了 `datasets`，此参数将被忽略。

dataset_test_split (`str`，*可选*，默认为 `"test"`)：用于评估的数据集拆分。如果提供了 `datasets`，此参数将被忽略。

dataset_streaming (`bool`，*可选*，默认为 `False`)：是否以流式方式加载数据集。如果为 True，数据集将以流式模式加载。如果提供了 `datasets`，此参数将被忽略。

ignore_bias_buffers (`bool`, *可选*, 默认为 `False`) : 用于分布式训练的调试参数。修复 DDP 中与 LM bias/mask 缓冲区相关的问题 - 无效的标量类型、原地操作。参见 https://github.com/huggingface/transformers/issues/22482#issuecomment-1595790992。

所有脚本共有的参数。

## 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)
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.1/trl/scripts/utils.py#L234)

**参数：**

dataclass_types (`DataClassType | Iterable[DataClassType]`, *可选*) : 用于参数解析的 Dataclass 类型。

- ****kwargs** : 传递给 [transformers.HfArgumentParser](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser) 构造函数的其他关键字参数。

[transformers.HfArgumentParser](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser) 的子类，旨在解析基于 dataclass 配置的命令行参数，同时支持加载配置文件和管理环境变量。

示例：

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

[源代码](https://github.com/huggingface/trl/blob/v1.18.1/trl/scripts/utils.py#L303)

将命令行参数和配置文件解析为指定 dataclass 类型的实例。

此方法封装了 [transformers.HfArgumentParser.parse_args_into_dataclasses](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser.parse_args_into_dataclasses)，同时解析通过 `--config` 标志指定的配置文件。该配置文件（采用 YAML 格式）提供用于替换 dataclasses 中默认值的参数值。命令行参数可以覆盖配置文件中设置的值。此方法还会设置配置文件中 `env` 字段指定的任何环境变量。

#### 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)
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.1/trl/scripts/_hf_argparser.py#L298)

**参数：**

args : 要解析的字符串列表。默认值取自 sys.argv。（与 argparse.ArgumentParser 相同）

return_remaining_strings : 如果为 true，还会返回剩余参数字符串列表。

look_for_args_file : 如果为 true，将查找与当前进程入口点脚本具有相同基本名称的 .args 文件，并将其潜在内容追加到命令行参数中。

args_filename : 如果不为 None，将使用此文件，而不是上一个参数中指定的 .args 文件。

args_file_flag : 如果不为 None，将在命令行参数中查找使用此标志指定的文件。该标志可以多次指定，优先级由顺序决定（最后一个生效）。

**返回：** `Tuple consisting of`

- 以传递给初始化器的相同顺序返回数据类实例.abspath
- 如适用，一个额外的命名空间，用于在初始化后添加到解析器的更多（非 dataclass 支持的）参数。
- 剩余参数字符串的潜在列表。（与 argparse.ArgumentParser.parse_known_args 相同）

将命令行参数解析为指定 dataclass 类型的实例。

这依赖于 argparse 的 `ArgumentParser.parse_known_args`。请参阅文档：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)
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.1/trl/scripts/utils.py#L361)

使用通过关键字参数提供的值覆盖解析器的默认值，包括子解析器。

任何具有更新默认值的参数，如果之前是必需的，现在也会被标记为非必需。

返回一个字符串列表，其中包含解析器未消费的内容。

## get_dataset[[trl.get_dataset]]

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

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

[源代码](https://github.com/huggingface/trl/blob/v1.18.1/trl/scripts/utils.py#L414)

**参数：**

mixture_config ([DatasetMixtureConfig](/docs/trl/v1.18.1/zh/script_utils#trl.DatasetMixtureConfig))：包含数据集配置的脚本参数。

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

来自混合配置的合并数据集，如果设置了`test_split_size`，则可选进行训练/测试划分。

根据配置加载数据集的混合。

示例：
```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)
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.1/trl/scripts/utils.py#L40)

**参数：**

path (`str`) : 数据集的路径或名称。

name (`str`, *可选*) : 定义数据集配置的名称。

data_dir (`str`, *可选*) : 定义数据集配置的 `data_dir`。如果为通用构建器（csv、text 等）或 Hub 数据集指定了该参数，且 `data_files` 为 `None`，则其行为等同于将 `os.path.join(data_dir, **)` 作为 `data_files` 传入，以引用目录中的所有文件。

data_files (`str` 或 `Sequence` 或 `Mapping`，*可选*)：源数据文件的路径。

split (`str`，*可选*，默认为 `"train"`)：要加载的数据集划分。

columns (`list[str]`, *可选*) : 要从数据集中选择的列名列表。如果为 `None`，则选择所有列。

fraction (`float`, *可选*) : 该数据集在最终混合中的目标占比。所有数据集的占比会被归一化，使其总和为一，并且混合大小会被限制，以确保没有数据集被过度采样：每个数据集保留前 `round(fraction * N)` 行，其中 `N` 是避免过度采样的最大混合大小。必须为混合中的所有数据集或所有数据集都不设置此参数。不支持流式数据集。如果未设置，则直接拼接完整的数据集。

数据集的配置。

此类与 [load_dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/loading_methods#datasets.load_dataset) 的签名一致，参数会直接用于 [load_dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/loading_methods#datasets.load_dataset) 函数。有关更多详细信息，请参阅 [load_dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/loading_methods#datasets.load_dataset) 文档。

## 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)
```

[源代码](https://github.com/huggingface/trl/blob/v1.18.1/trl/scripts/utils.py#L81)

**参数：**

datasets (`list[DatasetConfig]`) : 要包含在混合中的数据集配置列表。

streaming (`bool`，*可选*，默认为 `False`)：是否以流式方式加载数据集。如果为 `True`，数据集将以流式模式加载。

test_split_size (`float`, *可选*) : 测试集的大小。有关更多详细信息，请参阅 `train_test_split` 函数中的 `test_size` 参数。如果为 `None`，则数据集不会被拆分为训练集和测试集。

用于数据集混合的配置类。

使用 [HfArgumentParser](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser)，我们可以将该类转换为可在命令行中指定的 [argparse](https://docs.python.org/3/library/argparse#module-argparse) 参数。

用法：

使用 CLI 时，您可以在 YAML 配置文件中添加以下部分：

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

