Implementar Citações em Python
Nesta página
Atualizado em 3 de novembro de 2026 com base no guia Citações e Referências da Mistral: o resultado da ferramenta segue o formato documentado — um objeto indexado pelo número da fonte, sem os campos
typeoureference_id— e osreference_idsna resposta são resolvidos através destr(ref_id)dentro desse objeto. Fonte: Citações e Referências.
O Pipeline Completo de Citações
Agora, vai montar um pipeline RAG que cita as suas fontes, desde a primeira chamada à API até à estrutura de dados que a sua interface consome. Mantenha este princípio em mente: o modelo nunca vai buscar documentos por si próprio. Ele sinaliza que precisa de uma pesquisa, você executa essa pesquisa na sua própria base de dados e, em seguida, devolve os excertos juntamente com os seus identificadores. Esta troca produz uma resposta onde cada afirmação permanece ligada a um documento real.
Especificamente, um ciclo completo requer duas chamadas a chat.complete. A primeira desencadeia a chamada à ferramenta; a segunda gera a resposta citada assim que as fontes são injetadas no histórico. Vamos percorrer este ciclo usando um caso simples: um assistente de documentação interna questionado sobre as melhores práticas para implementar um LLM.
Definir o Contrato do Modelo na Mensagem do Sistema
A mensagem do sistema estabelece o contrato: responder com base nas fontes fornecidas, citar sistematicamente e, acima de tudo, admitir quando a informação está em falta em vez de preencher a lacuna. Esta última instrução faz a diferença em produção, porque as respostas tendem a desviar-se em questões mal cobertas pela base de documentação.
from mistralai.client import Mistral
import json
client = Mistral(api_key="your-api-key")
# Mensagem do sistema que incentiva citações
system_message = {
"role": "system",
"content": (
"You are a documentation assistant. "
"Answer questions using the provided sources. "
"Cite your sources systematically. "
"If the information is not in any source, state this explicitly."
)
}
user_message = {
"role": "user",
"content": "What are the best practices for deploying an LLM in production?"
}
messages = [system_message, user_message]
Declarar a Ferramenta de Pesquisa
A ferramenta descreve como é uma pesquisa de documentos no seu sistema: aqui, uma simples função search_documentation que recebe uma consulta de texto. A primeira chamada não espera uma resposta escrita; espera que o modelo formule a consulta que considera relevante, poupando-o de escrever uma camada de reformulação.
reference_tool = {
"type": "function",
"function": {
"name": "search_documentation",
"description": "Searches the documentation database",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query"
}
},
"required": ["query"]
}
}
}
# Primeira chamada: o modelo solicita o uso da ferramenta
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=[reference_tool]
)
Devolver Resultados no Formato de Referência
Este é o passo estrutural. Os resultados do seu motor de pesquisa regressam num ToolMessage cujo conteúdo é o objeto de referência da lição anterior: cada fonte tem um número ("0", "1"…), um URL, um título e os excertos selecionados. São estes números que o modelo reutiliza para marcar as suas citações e que o seu frontend resolverá mais tarde em ligações.
from mistralai.client.models import ToolMessage
# Resultados da pesquisa de documentação, no formato de referência da Mistral
references = {
"0": {
"url": "https://docs.example.com/deployment-guide",
"title": "LLM Deployment Guide",
"snippets": [[
"Always configure rate limits to protect the service.",
"Monitor P99 latency and error rates continuously."
]],
"description": None,
"date": "2026-09-01",
"source": "docs"
},
"1": {
"url": "https://docs.example.com/security",
"title": "AI Application Security",
"snippets": [[
"Filter user inputs to prevent injections.",
"Never expose API keys on the client side."
]],
"description": None,
"date": "2026-08-15",
"source": "docs"
},
"2": {
"url": "https://docs.example.com/scaling",
"title": "Scalability and Performance",
"snippets": [[
"Use semantic caching to reduce API calls.",
"Size instances based on peak traffic."
]],
"description": None,
"date": "2026-07-20",
"source": "docs"
}
}
# Adicionar a chamada à ferramenta e a resposta ao histórico
tool_call = response.choices[0].message.tool_calls[0]
messages.append(response.choices[0].message)
messages.append(
ToolMessage(
tool_call_id=tool_call.id,
name="search_documentation",
content=json.dumps(references, ensure_ascii=False)
)
)
Note que a mensagem original do modelo é reinjetada no histórico antes do ToolMessage: sem este par chamada à ferramenta / resultado da ferramenta, a API recusa a continuação. A segunda chamada já não precisa das definições da ferramenta, uma vez que a pesquisa já ocorreu.
# Segunda chamada: o modelo gera uma resposta com citações
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
Separar Texto de Referências
A resposta citada já não é uma simples cadeia de caracteres, mas uma sequência de blocos alternando prosa e marcas de citação. A análise envolve percorrer esta sequência e classificar: os objetos TextChunk reconstroem o texto legível, enquanto os objetos ReferenceChunk fornecem os reference_ids realmente utilizados. Esta distinção dá-lhe informação valiosa: exatamente quais as fontes que o modelo usou entre as que forneceu.
from mistralai.client.models import TextChunk, ReferenceChunk
def parse_cited_response(response):
"""Extrai texto e referências de uma resposta citada."""
content_parts = response.choices[0].message.content
text_parts = []
cited_refs = set()
for chunk in content_parts:
if isinstance(chunk, TextChunk):
text_parts.append(chunk.text)
elif isinstance(chunk, ReferenceChunk):
for ref_id in chunk.reference_ids:
cited_refs.add(ref_id)
return {
"text": "".join(text_parts),
"references_used": list(cited_refs)
}
result = parse_cited_response(final_response)
print("=== Resposta ===")
print(result["text"])
print("\n=== Fontes Citadas ===")
for ref_id in result["references_used"]:
source = references[str(ref_id)]
print(f" - {source['title']} : {source['url']}")
Preparar a Exibição no Frontend
Achatar a resposta em texto simples faria perder a posição das citações e, consequentemente, o seu valor. É melhor manter a sequência e enriquecê-la: resolver cada ReferenceChunk contra uma tabela de referências para transportar o título e o URL de cada fonte. A sua interface recebe assim uma lista ordenada de blocos que pode renderizar como ligações clicáveis, dicas de ferramenta ou números de citação interativos, sem nunca ter de reinterpretar o texto.
def format_for_frontend(response, reference_map):
"""Formata a resposta com citações para o frontend."""
content_parts = response.choices[0].message.content
formatted = []
for chunk in content_parts:
if isinstance(chunk, TextChunk):
formatted.append({
"type": "text",
"content": chunk.text
})
elif isinstance(chunk, ReferenceChunk):
refs = []
for ref_id in chunk.reference_ids:
source = reference_map.get(str(ref_id))
if source:
refs.append({
"id": ref_id,
"title": source["title"],
"url": source["url"]
})
formatted.append({
"type": "citation",
"references": refs
})
return formatted
Antes de abrir este pipeline à sua base de documentação completa, execute-o com apenas três a cinco fontes, como no exemplo acima. Verá imediatamente se o modelo cita no local certo, se aproveita múltiplos documentos ou se se agarra sistematicamente ao primeiro, permitindo-lhe corrigir a mensagem do sistema antes que o comportamento se perca no volume.
Pontos-chave
- O pipeline segue um fluxo de duas chamadas: chamada à ferramenta e depois resposta citada
- As referências são passadas via
ToolMessage, num objeto indexado pelo número da fonte ("0","1"…) - A resposta contém uma mistura de
TextChunkeReferenceChunkpara analisar - Estruture a saída para que o seu frontend possa exibir citações interativas
- Teste com 3–5 fontes para validar o comportamento antes de passar para produção