Citações Automáticas e Melhores Práticas
Nesta página
Respostas Fundamentadas e Confiáveis
Quando o modelo utiliza a pesquisa na Web ou a pesquisa no X, a API de Respostas inclui automaticamente citações na resposta. Estas citações permitem que os seus utilizadores verifiquem as fontes e fortaleçam a confiança nas respostas geradas.
Como Funcionam as Citações
As citações aparecem no array annotations de cada item de conteúdo:
{
"output": [{
"type": "message",
"content": [{
"type": "output_text",
"text": "According to the latest data, the AI market...",
"annotations": [
{
"type": "url_citation",
"url": "https://example.com/article",
"title": "AI Market Analysis in 2026",
"start_index": 35,
"end_index": 68
}
]
}]
}]
}
Campos da Citação
| Campo | Descrição |
|---|---|
type | Sempre url_citation |
url | URL da fonte |
title | Título da página de origem |
start_index | Posição inicial no texto |
end_index | Posição final no texto |
Exibir Citações na Sua Aplicação
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest advancements in AI?",
tools=[{"type": "web_search"}]
)
text = response.output[0].content[0].text
annotations = response.output[0].content[0].annotations
# Construir texto com notas de rodapé
footnotes = []
for i, ann in enumerate(annotations, 1):
footnotes.append(f"[{i}] {ann.title} — {ann.url}")
print(text)
print("\n--- Sources ---")
for fn in footnotes:
print(fn)
Em HTML
def render_with_citations(text, annotations):
# Ordenar por posição (do fim para o início para evitar deslocar índices)
sorted_anns = sorted(annotations, key=lambda a: a.start_index, reverse=True)
html = text
for i, ann in enumerate(sorted_anns):
ref_num = len(sorted_anns) - i
link = f'<a href="{ann.url}" title="{ann.title}" target="_blank">[{ref_num}]</a>'
html = html[:ann.end_index] + link + html[ann.end_index:]
return html
Melhores Práticas para Produção
1. Validar Sempre o Estado
response = client.responses.create(...)
if response.status != "completed":
handle_error(response)
return
2. Gerir Respostas Vazias
if not response.output or not response.output[0].content:
return "The model did not generate a response."
text = response.output[0].content[0].text
3. Registar Métricas
Para cada pedido em produção, registe:
response.idpara rastreabilidadeusage.total_tokenspara consumousage.cost_in_nano_usdpara custos- Tempo de resposta no lado do cliente
- Estado da resposta
4. Proteger a Sua Chave de API
- Armazene-a numa variável de ambiente, nunca no código
- Utilize um gestor de segredos em produção (Vault, AWS Secrets Manager)
- Rode as suas chaves regularmente
- Nunca as exponha no lado do cliente (navegador)
5. Gerir Conteúdo Gerado
As respostas do modelo podem conter conteúdo inadequado, apesar dos filtros. Implemente uma camada de moderação se exibir respostas publicamente.
6. Planear a Escalabilidade
- Utilize streaming para reduzir o tempo de espera percecionado
- Implemente um sistema de filas para pedidos pesados
- Coloque em cache respostas frequentes
- Monitore as suas quotas de limitação de taxa
Lista de Verificação de Implementação
- Timeout definido para 3600 segundos
- Nova tentativa com retrocesso exponencial
- Limitação de taxa no lado do cliente
- Registo de métricas (tokens, custos, latência)
- Tratamento de erros (401, 429, 500, timeout)
- Chave de API segura
- Moderação de conteúdo, se necessário
- Monitorização de custos e alertas
- Disjuntor para resiliência
Pontos-chave
- As citações são automáticas quando o modelo utiliza
web_searchoux_search - Contêm o URL, o título e a posição no texto
- Valide sempre o estado e trate as respostas vazias
- Proteja a sua chave de API — nunca no código-fonte nem no lado do cliente
- Implemente registo, novas tentativas, limitação de taxa e monitorização antes de passar para produção
Teste os Seus Conhecimentos
A API de Respostas em profundidade: a verificação final.
1. O que oferece a API de Respostas em comparação com as Conclusões de Chat?
Resposta: O formato moderno: persistência de resposta no lado do servidor (GET/DELETE, encadeamento por ID), ferramentas integradas e funcionalidades recentes — a API onde a xAI foca a evolução.
2. Como encadeia uma conversa?
Resposta: Ao referenciar a resposta anterior: o contexto é mantido no lado do servidor — não é necessário reenviar todo o histórico a cada turno.
3. O que é o raciocínio encriptado?
Resposta: O raciocínio interno do modelo devolvido de forma encriptada: reutilizável nos turnos seguintes sem ser legível — o processo de pensamento viaja, a confidencialidade mantém-se.
4. O que permite a mistura de ferramentas do servidor e do cliente?
Resposta: Combinar ferramentas integradas executadas pela xAI (pesquisa na Web, etc.) e as suas funções personalizadas executadas pelo seu código — cada ferramenta no lugar certo, orquestrada no mesmo pedido.
5. Quais são as melhores práticas para produção?
Resposta: Tratar o timeout e as novas tentativas, acompanhar a faturação (tokens, ferramentas) e aproveitar as citações automáticas para respostas verificáveis — robustez e confiança em conjunto.
Persistência, ferramentas, raciocínio encriptado, citações: a API de Respostas é a fundação moderna — as suas aplicações Grok são construídas aqui.