# Utilitários de Dados

## is_conversational[[trl.is_conversational]]

#### trl.is_conversational[[trl.is_conversational]]

```python
trl.is_conversational(example: dict[str, typing.Any])
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.2/trl/data_utils.py#L126)

**Parâmetros:**

example (`dict[str, Any]`) : Uma única entrada de dados de um conjunto de dados. O exemplo pode ter diferentes chaves dependendo do tipo de conjunto de dados.

**Retorna:** `bool`

`True` se os dados estão em um formato conversacional, `False` caso contrário.

Verifique se o exemplo está em um formato conversacional.

Exemplos:

```python
>>> example = {"prompt": [{"role": "user", "content": "What color is the sky?"}]}
>>> is_conversational(example)
True

>>> example = {"prompt": "The sky is"}
>>> is_conversational(example)
False
```

## maybe_convert_to_chatml[[trl.maybe_convert_to_chatml]]

#### trl.maybe_convert_to_chatml[[trl.maybe_convert_to_chatml]]

```python
trl.maybe_convert_to_chatml(example: dict[str, list])
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.2/trl/data_utils.py#L967)

**Parâmetros:**

example (`dict[str, list]`) : Uma única entrada de dados contendo uma lista de mensagens.

**Retorna:** `dict[str, list]`

Exemplo reformulado no estilo ChatML.

Convert um conjunto de dados conversacional com os campos `from` e `value` para o formato ChatML.

Esta função modifica dados conversacionais para alinhá-los ao formato ChatML da OpenAI:
- Substitui a chave `"from"` por `"role"` nos dicionários de mensagens.
- Substitui a chave `"value"` por `"content"` nos dicionários de mensagens.
- Renomeia `"conversations"` para `"messages"` para consistência com o ChatML.

Exemplo:
```python
>>> from trl import maybe_convert_to_chatml

>>> example = {
...     "conversations": [
...         {"from": "user", "value": "What color is the sky?"},
...         {"from": "assistant", "value": "It is blue."},
...     ]
... }
>>> maybe_convert_to_chatml(example)
{'messages': [{'role': 'user', 'content': 'What color is the sky?'},
              {'role': 'assistant', 'content': 'It is blue.'}]}
```

## extract_prompt[[trl.extract_prompt]]

#### trl.extract_prompt[[trl.extract_prompt]]

```python
trl.extract_prompt(example: dict[str, collections.abc.Sequence])
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.2/trl/data_utils.py#L548)

**Parâmetros:**

example (`dict[str, list]`) : Um dicionário representando uma única entrada de dados no conjunto de dados de preferências. Ele deve conter as chaves `"chosen"` e `"rejected"`, onde cada valor é conversacional ou padrão (`str`).

**Retorna:** `dict[str, list]`

Um dicionário contendo:
- `"prompt"`: O prefixo comum mais longo entre as conclusões "chosen" e "rejected".
- `"chosen"`: O restante da conclusão "chosen", com o prompt removido.
- `"rejected"`: O restante da conclusão "rejected", com o prompt removido.

Extrai o prompt compartilhado de um exemplo de dados de preferência, onde o prompt é implícito tanto nas conclusões escolhidas quanto nas rejeitadas.

A função identifica a sequência comum mais longa (prefixo) de turnos de conversa entre as conclusões "chosen" e "rejected" e extrai isso como o prompt. Em seguida, remove esse prompt das respectivas conclusões "chosen" e "rejected".

Exemplos:

```python
>>> example = {
...     "chosen": [
...         {"role": "user", "content": "What color is the sky?"},
...         {"role": "assistant", "content": "It is blue."},
...     ],
...     "rejected": [
...         {"role": "user", "content": "What color is the sky?"},
...         {"role": "assistant", "content": "It is green."},
...     ],
... }
>>> extract_prompt(example)
{'prompt': [{'role': 'user', 'content': 'What color is the sky?'}],
 'chosen': [{'role': 'assistant', 'content': 'It is blue.'}],
 'rejected': [{'role': 'assistant', 'content': 'It is green.'}]}
```

Ou, com o método `map` de [Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset):

```python
>>> from trl import extract_prompt
>>> from datasets import Dataset

>>> dataset_dict = {
...     "chosen": [
...         [
...             {"role": "user", "content": "What color is the sky?"},
...             {"role": "assistant", "content": "It is blue."},
...         ],
...         [
...             {"role": "user", "content": "Where is the sun?"},
...             {"role": "assistant", "content": "In the sky."},
...         ],
...     ],
...     "rejected": [
...         [
...             {"role": "user", "content": "What color is the sky?"},
...             {"role": "assistant", "content": "It is green."},
...         ],
...         [
...             {"role": "user", "content": "Where is the sun?"},
...             {"role": "assistant", "content": "In the sea."},
...         ],
...     ],
... }
>>> dataset = Dataset.from_dict(dataset_dict)
>>> dataset = dataset.map(extract_prompt)
>>> dataset[0]
{'prompt': [{'role': 'user', 'content': 'What color is the sky?'}],
 'chosen': [{'role': 'assistant', 'content': 'It is blue.'}],
 'rejected': [{'role': 'assistant', 'content': 'It is green.'}]}
```

## unpair_preference_dataset[[trl.unpair_preference_dataset]]

#### trl.unpair_preference_dataset[[trl.unpair_preference_dataset]]

```python
trl.unpair_preference_dataset(dataset: typing.Union[~DatasetType, ~IterableDatasetType], **map_kwargs)
```

[Fonte](https://github.com/huggingface/trl/blob/v1.18.2/trl/data_utils.py#L445)

**Parâmetros:**

dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) ou [DatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.DatasetDict) ou [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset) ou [IterableDatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDatasetDict)) : Conjunto de dados de preferências para desparear. O conjunto de dados deve ter as colunas `"chosen"`, `"rejected"` e, opcionalmente, `"prompt"`.

- ****map_kwargs** (`dict`, *opcional*) : Argumentos de palavra-chave adicionais para passar ao método map do dataset ao desparear preferências.

**Retorna:**

[Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) ou [DatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.DatasetDict) ou [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset) ou [IterableDatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDatasetDict): O conjunto de dados de preferências não pareadas.

Desparear um conjunto de dados de preferências.

A saída contém `"prompt"`, `"completion"` e `"label"`, além de quaisquer colunas extras, que são duplicadas para cada linha escolhida e rejeitada.

Exemplo:

```python
>>> from datasets import Dataset

>>> dataset_dict = {
...     "prompt": ["The sky is", "The sun is"],
...     "chosen": [" blue.", "in the sky."],
...     "rejected": [" green.", " in the sea."],
... }
>>> dataset = Dataset.from_dict(dataset_dict)
>>> dataset = unpair_preference_dataset(dataset)
>>> dataset
Dataset({
    features: ['prompt', 'completion', 'label'],
    num_rows: 4
})

>>> dataset[0]
{'prompt': 'The sky is', 'completion': ' blue.', 'label': True}
```

