# Padrões de mensagens de chat

Modelos de chat esperam conversas como uma lista de dicionários. Cada dicionário usa as chaves `role` e `content`. A chave `content` contém a mensagem do usuário passada ao modelo. Modelos de linguagem de grande porte aceitam texto e ferramentas, e modelos multimodais combinam texto com imagens, vídeos e áudio.

O Transformers utiliza um formato unificado no qual cada tipo de modalidade é especificado explicitamente, o que torna simples combinar e alternar entradas em uma única mensagem.

Este guia aborda os padrões de formatação de mensagens para cada modalidade, ferramentas, inferência em lote e conversas de múltiplas rodadas.

## Texto

Texto é o tipo de conteúdo mais básico. Ele é a base para todos os outros padrões. Passe sua mensagem para `"content"` como uma string.

```py
message = [
    {
        "role": "user",
        "content": "Explain the French Bread Law."
    }
]
```

Você também pode usar o formato explícito `"type": "text"` para manter seu código consistente quando adicionar imagens, vídeos ou áudio posteriormente.

```py
message = [
    {
        "role": "user",
        "content": [{"type": "text", "text": "Explain the French Bread Law."}]
    }
]
```

## Ferramentas

[Ferramentas](./chat_extras) são funções que um modelo de chat pode chamar, como obter dados de clima em tempo real, em vez de gerá-los por conta própria.

O papel `assistant` trata a solicitação da ferramenta. Defina `"type": "function"` na chave `"tool_calls"` e forneça sua ferramenta na chave `"function"`. Adicione a solicitação da ferramenta do assistente à sua mensagem.

```py
weather = {"name": "get_current_temperature", "arguments": {"location": "Paris, France", "unit": "celsius"}}
message.append(
    {
        "role": "assistant", 
        "tool_calls": [{"type": "function", "function": weather}]
    }
)
```

A função `tool` trata o resultado. Adicione-o em `"content"`. Esse valor deve ser sempre uma string.

```py
message.append({"role": "tool", "content": "22"})
```

## Multimodal

Modelos multimodais estendem esse formato para lidar com imagens, vídeos e áudio. Cada entrada especifica seu `"type"` e fornece a mídia com `"url"` ou `"path"`.

### Imagem

Defina `"type": "image"` e use `"url"` para links ou `"path"` para arquivos locais.

```py
message = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://assets.bonappetit.com/photos/57ad4ebc53e63daf11a4ddc7/master/w_1280,c_limit/kouign-amann.jpg"},
            {"type": "text", "text": "What pastry is shown in the image?"}
        ]
    }
]
```

### Vídeo

Defina `"type": "video"` e use `"url"` para links ou `"path"` para arquivos locais.

```py
message = [
    {
        "role": "user",
        "content": [
            {"type": "video", "url": "https://static01.nyt.com/images/2019/10/01/dining/01Sourdough-GIF-1/01Sourdough-GIF-1-superJumbo.gif"},
            {"type": "text", "text": "What is shown in this video?"}
        ]
    }
]
```

### Áudio

Defina `"type": "audio"` e use `"url"` para links ou `"path"` para arquivos locais.

```py
message = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "url": "https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac"},
            {"type": "text", "text": "Transcribe the speech."}
        ]
    }
]
```

### Múltiplos misturados

A lista `content` aceita qualquer combinação de tipos. O modelo processa todas as entradas em conjunto, permitindo comparações ou raciocínio entre modalidades.

```py
message = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://assets.bonappetit.com/photos/57ad4ebc53e63daf11a4ddc7/master/w_1280,c_limit/kouign-amann.jpg"},
            {"type": "video", "url": "https://static01.nyt.com/images/2019/10/01/dining/01Sourdough-GIF-1/01Sourdough-GIF-1-superJumbo.gif"},
            {"type": "text", "text": "What does the image and video share in common?"},
        ],
    },
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://assets.bonappetit.com/photos/57ad4ebc53e63daf11a4ddc7/master/w_1280,c_limit/kouign-amann.jpg"},
            {"type": "image", "url": "https://assets.bonappetit.com/photos/57e191f49f19b4610e6b7693/master/w_1600%2Cc_limit/undefined"},
            {"type": "text", "text": "What type of pastries are these?"},
        ],
    }
]
```

## Lote

A inferência em lote processa várias conversas em uma única passagem para melhorar a taxa de transferência e a eficiência. Envolver cada conversa em sua própria lista e, em seguida, passá-las juntas como uma lista de listas.

```py
messages = [
    [
        {"role": "user",
        "content": [
                {"type": "image", "url": "https://assets.bonappetit.com/photos/57ad4ebc53e63daf11a4ddc7/master/w_1280,c_limit/kouign-amann.jpg"},
                {"type": "text", "text": "What type of pastry is this?"}
            ]
        },
    ],
    [
        {"role": "user",
        "content": [
                {"type": "image", "url": "https://assets.bonappetit.com/photos/57e191f49f19b4610e6b7693/master/w_1600%2Cc_limit/undefined"},
                {"type": "text", "text": "What type of pastry is this?"}
            ]
        },
    ],
]
```

## Múltiplas rodadas

As conversas abrangem múltiplas trocas, alternando entre os papéis `"user"` e `"assistant"`. Cada turno adiciona uma nova mensagem à lista, dando ao modelo acesso ao histórico completo da conversa. Esse contexto ajuda o modelo a gerar respostas mais adequadas.

```py
message = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://assets.bonappetit.com/photos/57ad4ebc53e63daf11a4ddc7/master/w_1280,c_limit/kouign-amann.jpg"},
            {"type": "text", "text": "What pastry is shown in the image?"}
        ]
    },
    {
        "role": "assistant",
        "content": [{"type": "text", "text": "This is kouign amann, a laminated dough pastry (i.e., dough folded with layers of butter) that also incorporates sugar between layers so that during baking the sugar caramelizes."}]
    },
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://static01.nyt.com/images/2023/07/21/multimedia/21baguettesrex-hbkc/21baguettesrex-hbkc-videoSixteenByNineJumbo1600.jpg"},
            {"type": "text", "text": "Compare it to this image now."}
        ]
    }
]
```