# Utilidades de datos

## is_conversational[[trl.is_conversational]]

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

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

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

**Parámetros:**

example (`dict[str, Any]`) : Una entrada de datos individual de un conjunto de datos. El ejemplo puede tener diferentes claves dependiendo del tipo de conjunto de datos.

**Devuelve:** `bool`

`True` si los datos están en un formato conversacional, `False` en caso contrario.

Comprueba si el ejemplo está en un formato conversacional.

Ejemplos:

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

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

**Parámetros:**

example (`dict[str, list]`) : Una entrada de datos que contiene una lista de mensajes.

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

Ejemplo reformateado al estilo ChatML.

Convierte un conjunto de datos conversacional con los campos `from` y `value` al formato ChatML.

Esta función modifica los datos conversacionales para que se ajusten al formato ChatML de OpenAI:
- Reemplaza la clave `"from"` con `"role"` en los diccionarios de mensajes.
- Reemplaza la clave `"value"` con `"content"` en los diccionarios de mensajes.
- Renombra `"conversations"` a `"messages"` para mantener la consistencia con ChatML.

Ejemplo:
```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])
```

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

**Parámetros:**

example (`dict[str, list]`) : Un diccionario que representa una entrada de datos individual en el conjunto de datos de preferencias. Debe contener las claves `"chosen"` y `"rejected"`, donde cada valor es conversacional o estándar (`str`).

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

Un diccionario que contiene:
- `"prompt"`: El prefijo común más largo entre las completaciones "chosen" y "rejected".
- `"chosen"`: El resto de la finalización "chosen", con el prompt eliminado.
- `"rejected"`: El resto de la finalización "rejected", con el prompt eliminado.

Extrae el prompt compartido de un ejemplo de datos de preferencia, donde el prompt es implícito en ambas completitudes, la elegida y la rechazada.

La función identifica la secuencia común más larga (prefijo) de turnos de conversación entre las finalizaciones "chosen" y "rejected" y la extrae como el prompt. A continuación, elimina este prompt de las finalizaciones "chosen" y "rejected" correspondientes.

Ejemplos:

```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.'}]}
```

O, con el 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)
```

[Fuente](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) o [DatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.DatasetDict) o [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset) o [IterableDatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDatasetDict)) : Conjunto de datos de preferencias para desparear. El conjunto de datos debe tener las columnas `"chosen"`, `"rejected"` y opcionalmente `"prompt"`.

- ****map_kwargs** (`dict`, *opcional*) : Argumentos de palabra clave adicionales para pasar al método map del conjunto de datos al desparear preferencias.

**Devuelve:**

[Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) o [DatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.DatasetDict) o [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset) o [IterableDatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDatasetDict): el conjunto de datos de preferencias no emparejadas.

Desasociar un conjunto de datos de preferencias.

La salida contiene `"prompt"`, `"completion"` y `"label"`, además de cualquier columna extra, que se duplican para cada fila elegida y rechazada.

Ejemplo:

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

