Few-shot via a API
Nesta página
Ensinar pelo exemplo
O prompting few-shot consiste em fornecer ao modelo alguns exemplos de entrada-saída antes de enviar o seu pedido real. Com a API de Chat Completions, estes exemplos não têm um slot especial: injeta-os no histórico da conversa como pares de mensagens falsos user/assistant, como se a troca tivesse realmente acontecido. O modelo não consegue distinguir entre um turno genuíno e um que fabricou, e é exatamente isso que torna a técnica tão eficaz. Sem fine-tuning, esta é a forma mais fiável de obter um formato de saída preciso.
O truque reside numa inversão: em vez de descrever longamente o formato esperado no system prompt, mostra-o. Para uma tarefa de classificação de sentimentos, três exemplos são suficientes para fazer o modelo compreender que deve responder com um rótulo em maiúsculas e nada mais.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "You classify the sentiment of customer reviews."
},
# Example 1
{"role": "user", "content": "Review: Fast delivery, product as described. Very satisfied!"},
{"role": "assistant", "content": "POSITIVE"},
# Example 2
{"role": "user", "content": "Review: Package arrived damaged, customer service unreachable."},
{"role": "assistant", "content": "NEGATIVE"},
# Example 3
{"role": "user", "content": "Review: The product is fine but a bit pricey for what it is."},
{"role": "assistant", "content": "MIXED"},
# Actual request
{"role": "user", "content": "Review: Excellent quality, I highly recommend this store."}
],
temperature=0.0
)
print(response.choices[0].message.content)
# POSITIVE
O modelo extraiu o padrão — avaliação como entrada, rótulo em maiúsculas como saída — e aplicou-o à nova entrada. Nenhuma instrução de formatação foi escrita explicitamente: os três pares foram suficientes.
Quantos exemplos fornecer
O número de exemplos depende da dificuldade da tarefa, e os retornos decrescentes surgem de forma abrupta.
| Número | Quando utilizar |
|---|---|
| 0 (zero-shot) | Tarefas simples, tratadas naturalmente pelo modelo |
| 1–2 | Formato de saída padrão (JSON, rótulo) |
| 3–5 | Classificação com múltiplas categorias |
| 5–10 | Tarefas complexas ou formatos muito específicos |
Além de dez exemplos, consome muitos tokens de entrada sem ganho proporcional: cada pedido arrasta o mesmo bloco de exemplos, faturado em cada chamada. Nesse ponto, o fine-tuning torna-se a opção economicamente sensata.
Dois usos que alteram a saída
A extração de entidades nomeadas demonstra o que os exemplos acrescentam para além de um esquema descrito na íntegra. Eles fixam não apenas as chaves JSON, mas também como lidar com categorias vazias — o segundo exemplo mostra explicitamente listas vazias em vez de um campo em falta, o que impede o seu analisador de encontrar uma estrutura inesperada.
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Extract named entities in JSON format."
},
# Example 1
{
"role": "user",
"content": "Pierre Martin joined Google France in Paris in January 2025."
},
{
"role": "assistant",
"content": '{"personnes": ["Pierre Martin"], "organisations": ["Google France"], "lieux": ["Paris"], "dates": ["janvier 2025"]}'
},
# Example 2
{
"role": "user",
"content": "The VivaTech conference organized by Publicis will take place in June."
},
{
"role": "assistant",
"content": '{"personnes": [], "organisations": ["Publicis"], "lieux": [], "dates": ["juin"]}'
},
# Actual request
{
"role": "user",
"content": "Sophie Leclerc, director at Mistral AI, announced a partnership with Microsoft at the AI Paris show on March 15, 2026."
}
],
temperature=0.0
)
import json
result = json.loads(response.choices[0].message.content)
print(json.dumps(result, indent=2, ensure_ascii=False))
A transformação de texto segue uma lógica diferente: não está a transmitir um esquema, mas um registo de linguagem. Um único exemplo de simplificação — traduzir a arquitetura transformer numa frase acessível — ensina ao modelo o nível de abstração desejado, algo que nenhuma instrução como «seja pedagógico» conseguiria alcançar com esta precisão.
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Transform technical text into a layperson summary."
},
# Example
{
"role": "user",
"content": "The model uses a transformer encoder-decoder architecture with multi-head attention and pre-layer RMS normalization."
},
{
"role": "assistant",
"content": "This AI system uses advanced technology that lets it understand and generate text by analyzing relationships between words in parallel and efficiently."
},
# Actual request
{
"role": "user",
"content": "The API uses nucleus sampling with top_p to truncate the probability distribution of candidate tokens during autoregressive generation."
}
]
)
print(response.choices[0].message.content)
Few-shot dinâmico
Em produção, um conjunto fixo de exemplos acaba por prejudicar metade dos seus pedidos: exemplos técnicos incham desnecessariamente uma questão de faturação. A solução consiste em construir uma base de exemplos por categoria e injetar apenas aqueles que correspondem ao contexto detetado a montante. A função abaixo monta o system prompt, os exemplos para a categoria e a pergunta real na ordem correta.
# Example base
EXAMPLES = {
"technical": [
{"user": "How do I configure a VPN?", "assistant": "Here are the steps..."},
{"user": "My server is returning a 502 error.", "assistant": "Error 502..."},
],
"sales": [
{"user": "What are your rates?", "assistant": "Our plans start at..."},
{"user": "Is there a trial period?", "assistant": "Yes, 14 days..."},
],
"billing": [
{"user": "I haven't received my invoice.", "assistant": "Check your..."},
{"user": "How do I change plans?", "assistant": "Go to..."},
]
}
def build_messages(category: str, user_question: str) -> list:
"""Build messages with dynamic few-shot."""
messages = [
{"role": "system", "content": "Technical support assistant."}
]
# Add examples for the category
for ex in EXAMPLES.get(category, []):
messages.append({"role": "user", "content": ex["user"]})
messages.append({"role": "assistant", "content": ex["assistant"]})
# Add the actual question
messages.append({"role": "user", "content": user_question})
return messages
# Usage
messages = build_messages("technical", "My Docker deployment is failing.")
response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
O que constitui um bom conjunto de exemplos
O few-shot falha na maioria das vezes devido à falta de diversidade: três avaliações francamente positivas e o modelo classificará tudo como POSITIVE. Cubra casos normais e casos limite, incluindo um exemplo do que o modelo NÃO deve fazer — mostrar uma recusa é frequentemente mais eficaz do que proibi-la com uma regra. A consistência na forma é igualmente importante: se um exemplo devolve POSITIVE e outro Positive, acabou de ensinar ao modelo que a capitalização é livre.
Dois hábitos completam o exercício. Conte os tokens, uma vez que cada exemplo é faturado como entrada em cada chamada — um conjunto de oito pares torna-se rapidamente o principal motor de custos para uma API de classificação de alto volume. E teste primeiro sem exemplos: os modelos recentes lidam em zero-shot com tarefas que exigiam cinco exemplos há dois anos, e poupará o que não precisou de escrever.
Pontos-chave
- O few-shot injeta pares falsos user/assistant antes do pedido real
- 3–5 exemplos são suficientes para a maioria das tarefas de classificação e extração
- Utilize
temperature=0com few-shot para maximizar a consistência - O few-shot dinâmico seleciona exemplos relevantes com base no contexto
- Além de 10 exemplos, considere o fine-tuning em vez do few-shot