Funções e Mensagens
Nesta página
O Núcleo do Protocolo Conversacional
A API de Completions de Chat não aceita texto simples. Ela espera um array de mensagens estruturadas, cada uma atribuída a uma função específica. Este sistema de funções permite ao modelo distinguir quem está a falar, qual é o contexto e como deve responder. O mesmo texto — «Responda sempre em JSON» — tem um peso diferente consoante chegue como uma instrução do programador ou como um input do utilizador. Dominar esta estrutura é o que separa um chatbot coerente de um sistema que se desvia do tema após três trocas de mensagens.
As Quatro Funções
A API da Mistral reconhece quatro funções distintas, cada uma com uma função precisa na conversa.
A Função system
A mensagem de sistema define o comportamento global do modelo. Colocada em primeiro lugar, é lida antes de qualquer troca ocorrer. É aqui que define o tom, as restrições e o contexto da sua aplicação. Imagine um assistente concebido para um escritório de advogados; a mensagem de sistema equivale à nota de briefing que entregaria a um novo associado antes do seu primeiro caso.
messages = [
{
"role": "system",
"content": "You are a legal assistant specializing in French law. "
"Respond precisely and cite relevant legal articles. "
"If you are unsure, state it explicitly."
}
]
O programador gere esta mensagem, nunca o utilizador final, e ela nunca aparece na interface da sua aplicação.
A Função user
Em seguida vem a mensagem do utilizador humano: a pergunta, a instrução ou o texto a processar. Esta é a única parte da conversa que os seus utilizadores controlam diretamente.
messages.append({
"role": "user",
"content": "What are the statutes of limitations in civil law?"
})
A Função assistant
Esta função contém as respostas anteriores do modelo. Torna-se essencial assim que a conversa ultrapassa uma única volta. Sem ela, um utilizador que pergunte «E quanto à dívida comercial?» receberia uma resposta fora de contexto, porque o modelo não saberia o que estava a ser discutido.
messages.append({
"role": "assistant",
"content": "In French civil law, the standard statute of limitations is 5 years..."
})
A Função tool
A última função entra em jogo durante a chamada de funções. Quando o modelo solicita a execução de uma função externa — consultar uma API meteorológica, por exemplo —, executa essa função no seu lado e devolve o resultado sob esta função, referenciando o ID da chamada específica:
messages.append({
"role": "tool",
"content": '{"temperature": 22, "city": "Paris"}',
"tool_call_id": "call_abc123"
})
Estrutura Completa de uma Troca de Múltiplas Voltas
Vejamos estas funções em ação durante uma conversa real em que o utilizador refina o seu pedido após uma resposta inicial:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
conversation = [
{
"role": "system",
"content": "You are a French chef. Propose simple and tasty recipes."
},
{
"role": "user",
"content": "I want to make a dessert with apples."
}
]
# First turn
response = client.chat.complete(
model="mistral-large-latest",
messages=conversation
)
assistant_reply = response.choices[0].message.content
print(assistant_reply)
# Add response to history
conversation.append({"role": "assistant", "content": assistant_reply})
# Second turn
conversation.append({
"role": "user",
"content": "Can you adapt this recipe for 8 people?"
})
response = client.chat.complete(
model="mistral-large-latest",
messages=conversation
)
print(response.choices[0].message.content)
Repare no que este código faz realmente: a cada volta, envia de volta o histórico completo. O modelo não tem memória persistente entre pedidos. «Esta receita» só faz sentido porque a resposta anterior ainda está no array. É inteiramente responsável por gerir o estado da conversa.
Conteúdo Estruturado
O campo content aceita duas formas. A mais comum é uma string simples. Mas assim que transmite algo que não seja texto — uma imagem para descrever, por exemplo —, muda para uma lista de blocos tipados:
# Simple content (text)
{"role": "user", "content": "Describe this image."}
# Structured content (multimodal)
{"role": "user", "content": [
{"type": "text", "text": "Describe this image."},
{"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}
A Flag de Prefixo
A Mistral oferece uma funcionalidade única: a flag de prefixo. Escreve você mesmo o início da resposta do assistente e o modelo é forçado a continuar a partir daí. Isto é incrivelmente eficaz quando precisa de analisar o output com margem zero para erro.
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "You always respond in JSON."},
{"role": "user", "content": "List 3 European capitals."},
{"role": "assistant", "content": '{"capitals": [', "prefix": True}
]
)
O modelo retoma a geração após {"capitals": [, eliminando imediatamente o risco de ver aparecer «Claro, aqui está o seu JSON:» antes da chave de abertura. Em produção, esta garantia de formato vale muitas vezes mais do que uma instrução repetida três vezes na mensagem de sistema.
Adote dois hábitos desde já. Mantenha a mensagem de sistema concisa: um parágrafo bem escrito produz melhores resultados do que duas páginas de regras, parte das quais o modelo acabará por ignorar. E nunca invente respostas falsas do assistente para orientar o modelo, com uma exceção — a aprendizagem few-shot, que abordaremos na Lição 10. Para conversas longas, envie o histórico completo, mas monitore a janela de contexto e elimine as voltas mais antigas antes de a exceder.
Pontos-chave
- Quatro funções:
system(comportamento),user(pedido),assistant(resposta),tool(resultado da função) - A mensagem de sistema vai em primeiro lugar e define o enquadramento da aplicação
- O modelo não tem memória: envie o histórico completo com cada pedido
- A flag de prefixo força o início da resposta para controlar o formato do output