Formatação de comandos do Gemma 4

A partir do Gemma 4, apresentamos novos tokens de controle. Para o Gemma 3 e versões anteriores, consulte o documento anterior.

As seções a seguir especificam os tokens de controle usados pelo Gemma 4 e os casos de uso deles. Os tokens de controle são reservados e específicos para nosso tokenizador.

• Token para indicar uma instrução do sistema: system
• Token para indicar uma ação do usuário: user
• Token para indicar uma troca de modelo: model
• Token para indicar o início de uma rodada de diálogo: <|turn>
• Token para indicar o fim de uma troca de diálogo: <turn|>

Confira um exemplo de diálogo:

<|turn>system
You are a helpful assistant.<turn|>
<|turn>user
Hello.<turn|>

Multimodalidades

Usamos dois tokens especiais de marcador de posição (<|image|> e <|audio|>) para especificar onde os tokens de imagem e áudio devem ser inseridos. Depois da tokenização, esses tokens são substituídos pelas incorporações flexíveis reais dentro do modelo.

Confira um exemplo de diálogo:

prompt = """<|turn>user
Describe this image: <|image|>

And translate these audio:

a. <|audio|>
b. <|audio|><turn|>
<|turn>model"""

Tokens de controle de raciocínio e de agente

Para oferecer suporte a fluxos de trabalho de agentes, a Gemma usa tokens de controle especializados que delineiam o raciocínio interno (pensamento) das ações externas (chamada de função). Esses tokens permitem que o modelo processe uma lógica complexa antes de fornecer uma resposta final ou interagir com ferramentas externas.

Chamada de função

A Gemma 4 é treinada com seis tokens especiais para gerenciar o ciclo de vida do "uso de ferramentas".

Delimitador para valores de string: <|"|>

Um único token, <|"|>, é usado como delimitador para todos os valores de string nos blocos de dados estruturados.

• Finalidade:esse token garante que todos os caracteres especiais (como {, }, , ou aspas) em uma string sejam tratados como texto literal e não como parte da sintaxe subjacente da estrutura de dados.
• Uso:todos os literais de string nas declarações, chamadas e respostas de função precisam ser incluídos usando este token (por exemplo, key:<|"|>string value<|"|>).

Modo de raciocínio

Para ativar o modo de pensamento, inclua o token de controle <|think|> na instrução do sistema.

Confira um exemplo de diálogo:

<|turn>system
<|think|><turn|>
<|turn>user
What is the water formula?<turn|>
<|turn>model
<|channel>thought
...
<channel|>The most common interpretation of "the water formula" refers...<turn|>

O modo de pensamento foi criado para ser ativado no nível da conversa. Isso deve ser consolidado em uma única ação do sistema junto com suas outras instruções do sistema, como definições de ferramentas.

Exemplo de raciocínio e chamada de função

Em uma ação independente, o modelo pode "pensar" em particular antes de decidir chamar uma função. O ciclo de vida segue esta sequência:

1. Consulta do usuário: o usuário faz uma pergunta.
2. Raciocínio interno: o modelo pensa em particular no canal de pensamento.
3. Solicitação de ferramenta: o modelo interrompe a geração para pedir uma chamada de ferramenta.
4. Execução e injeção: o aplicativo executa a ferramenta e anexa a resposta.
5. Resposta final: o modelo lê a resposta e gera a resposta final.

O exemplo a seguir demonstra um modelo usando uma ferramenta de clima:

<|turn>system
<|think|>You are a helpful assistant.<|tool>declaration:get_current_temperature{...}<tool|><turn|>
<|turn>user
What's the temperature in London?<turn|>
<|turn>model
<|channel>thought
...
<channel|><|tool_call>call:get_current_temperature{location:<|"|>London<|"|>}<tool_call|><|tool_response>

O aplicativo precisa analisar a resposta do modelo para extrair o nome da função e os argumentos, executar a função e anexar tool_calls e tool_responses ao histórico de chat na função assistant.

<|turn>model
<|tool_call>call:get_current_weather{location:<|"|>London<|"|>}<tool_call|><|tool_response>response:get_current_weather{temperature:15,weather:<|"|>sunny<|"|>}<tool_response|>

Por fim, a Gemma lê a resposta da ferramenta e responde ao usuário.

The temperature in London is 15 degrees and it is sunny.<turn|>

Este é o histórico de chat JSON completo para este exemplo:

[
  {
    "role": "system",
    "content": "You are a helpful assistant."
  },
  {
    "role": "user",
    "content": "What's the temperature in London?"
  },
  {
    "role": "assistant",
    "tool_calls": [
      {
        "function": {
          "name": "get_current_weather",
          "arguments": {
            "location": "London"
          }
        }
      }
    ],
    "tool_responses": [
      {
        "name": "get_current_weather",
        "response": {
          "temperature": 15,
          "weather": "sunny"
        }
      }
    ],
    "content": "The temperature in London is 15 degrees and it is sunny."
  }
]

Gerenciar o contexto de pensamento entre turnos

Gerenciar adequadamente os pensamentos gerados pelo modelo é fundamental para manter o desempenho em conversas multiturno.

• Conversas padrão de várias interações:é necessário remover (extrair) os pensamentos gerados pelo modelo da interação anterior antes de transmitir o histórico da conversa de volta ao modelo para a próxima interação. Se você quiser desativar o modo de pensamento no meio de uma conversa, remova o token <|think|> ao remover os pensamentos anteriores.
• Chamada de função (exceção): se uma única interação do modelo envolver chamadas de função ou de ferramenta, os pensamentos NÃO poderão ser removidos entre as chamadas de função.

Fluxos de trabalho com agentes e tarefas de longa duração

Como os pensamentos brutos são removidos entre as conversas padrão, os desenvolvedores que criam agentes de longa duração podem querer manter o contexto de raciocínio para evitar que o modelo entre em loops de raciocínio cíclico.

• Resumindo ideias:uma técnica de inferência altamente recomendada é extrair, resumir e inserir as ideias anteriores do modelo na janela de contexto como texto padrão.
• Restrições de formatação:como o Gemma 4 não foi treinado explicitamente com ideias brutas incluídas no comando (fora do cenário específico de chamada de ferramenta mencionado acima), não há um formato estrito ou específico esperado pelo modelo para essas ideias injetadas. Você tem a flexibilidade de formatar o raciocínio resumido da maneira que melhor se adequar à sua arquitetura de agente específica.

Observações sobre a integração

• Estado interno:os tokens <|channel> e <channel|> são normalmente usados para o processamento de linha de raciocínio (CoT). Em aplicativos padrão voltados ao usuário, esse conteúdo geralmente fica oculto para o usuário final.
• Loop de ferramentas:os tokens tool_call e tool_response facilitam um "handshake" entre o modelo e o ambiente do aplicativo. O aplicativo intercepta o tool_call, executa o código subjacente e envia o resultado de volta ao modelo nos tokens tool_response.
• Comportamento do modelo:modelos maiores (por exemplo, gemma-4-26B-A4B-it, gemma-4-31B-it) podem gerar um canal de pensamento ocasionalmente, mesmo quando o modo de pensamento está explicitamente desativado. Para estabilizar o comportamento do modelo nesses casos extremos, considere adicionar um token de pensamento vazio ao comando.

Dica: ajuste de modelos grandes com conjuntos de dados sem pensamento

Ao ajustar modelos maiores do Gemma com um conjunto de dados que não inclui pensamento, é possível alcançar resultados melhores adicionando o canal vazio aos seus comandos de treinamento:

<|turn>model
<|channel>thought
<channel|>

Dica: eficiência de pensamento adaptativo usando instruções do sistema

Embora o "pensamento" no Gemma 4 seja oficialmente compatível como um recurso booleano ATIVADO ou DESATIVADO, o modelo tem recursos excepcionalmente fortes de obediência a instruções que permitem modular o comportamento de pensamento de forma dinâmica.

Em vez de depender de um parâmetro de framework codificado para pensamento "alto" ou "baixo", use as instruções do sistema (SI, na sigla em inglês) para guiar o modelo a um modo de pensamento reduzido. Ao instruir explicitamente o modelo a pensar de forma eficiente ou com uma profundidade menor (um conceito que chamamos de instrução de pensamento "BAIXA"), é possível alcançar uma eficiência de pensamento adaptativa.

• Custo reduzido:os testes mostraram que aplicar uma instrução de sistema de pensamento "BAIXO" pode reduzir o número de tokens de pensamento gerados em aproximadamente 20%.
• Prova de conceito:como esse comportamento é um subproduto da capacidade de instrução do modelo, e não de um treinamento específico, não existe um comando "perfeito". A instrução "LOW" é uma prova de conceito.
• Personalização:recomendamos que os desenvolvedores testem as próprias instruções personalizadas do sistema. É possível ajustar a profundidade, a extensão e o estilo do processo de pensamento do modelo para equilibrar perfeitamente a latência, o custo e a qualidade da saída para seus casos de uso específicos.