Aproveitar as Citações nos Resultados
Nesta página
Respostas Rastreáveis com Citações
Quando um utilizador faz uma pergunta factual à sua aplicação, quer poder verificar a informação. As citações da API Grok respondem exatamente a esta necessidade: cada facto recuperado através de pesquisa na web vem acompanhado da sua fonte. Isto permite-lhe criar interfaces onde cada afirmação é clicável e verificável.

A API oferece dois mecanismos de citação complementares: citações globais e citações inline. Compreender o seu funcionamento permite-lhe criar experiências de utilizador profissionais e transparentes.
Citações Globais: A Lista Completa de Fontes
As citações globais são devolvidas por predefinição no atributo citations da resposta. Contêm uma lista de todos os URLs consultados pelo modelo, mesmo aqueles que não são diretamente referenciados no texto da resposta.
response = client.responses.create(
model="grok-4.5",
input="What are the latest AI regulations in Europe?",
tools=[{"type": "web_search"}]
)
# Access global citations
for citation in response.citations:
print(f"Source: {citation.url}")
Não é necessária qualquer configuração adicional. Este é o comportamento nativo da API.
Citações Inline: Referências no Texto
As citações inline inserem ligações Markdown diretamente no texto da resposta, utilizando o formato [[N]](url), onde N é um número sequencial que começa em 1. Se a mesma fonte for citada várias vezes, o número original é reutilizado.
O comportamento por predefinição depende do SDK utilizado:
- API de Respostas Diretas: citações inline ativadas por predefinição
- xAI SDK: citações inline desativadas por predefinição (ativação opcional)
Ativar Citações Inline com o xAI SDK
response = client.responses.create(
model="grok-4.5",
input="Current status of the European AI Act",
tools=[{"type": "web_search"}],
include=["inline_citations"]
)
Desativar Citações Inline na API de Respostas
response = client.responses.create(
model="grok-4.5",
input="Current status of the European AI Act",
tools=[{"type": "web_search"}],
include=["no_inline_citations"]
)
O Esquema de Anotação Estruturada
Cada citação inline gera um objeto de anotação com metadados precisos. Esta estrutura permite um processamento programático avançado:
{
"type": "url_citation",
"url": "https://eur-lex.europa.eu/eli/reg/2024/1689",
"start_index": 145,
"end_index": 178,
"title": "1"
}
Os campos start_index e end_index seguem a convenção de fatiamento (slice) do Python. Pode utilizá-los para extrair o texto exato citado ou criar uma renderização HTML personalizada:
text = response.output_text
for annotation in response.annotations:
cited_text = text[annotation.start_index:annotation.end_index]
print(f"Cited text: {cited_text}")
print(f"Source: {annotation.url}")
Comportamento em Streaming
Ao utilizar o streaming, as citações inline aparecem progressivamente nos blocos de texto. No entanto, as anotações completas apenas estão disponíveis na resposta final. Planeie um processamento em duas fases se a sua interface apresentar fontes em tempo real.
Criar uma Interface com Fontes
Eis um exemplo de como transformar citações em HTML estruturado:
def format_response_with_sources(response):
text = response.output_text
sources = []
# Collect unique sources
seen_urls = set()
for citation in response.citations:
if citation.url not in seen_urls:
sources.append(citation.url)
seen_urls.add(citation.url)
# Build the render
html = f"<div class='response'>{text}</div>"
html += "<div class='sources'><h4>Sources</h4><ul>"
for i, url in enumerate(sources, 1):
html += f"<li><a href='{url}'>[{i}] {url}</a></li>"
html += "</ul></div>"
return html
Citações de Coleções
Se utilizar a ferramenta collections_search em conjunto com web_search, as citações provenientes dos seus documentos carregados utilizam um formato URI específico: collections://collection_id/files/file_id. Distinga estas citações das citações web padrão para adaptar a renderização no front-end.
Prática Prática
Crie uma aplicação que apresente os resultados da pesquisa do Grok com um sistema de notas de rodapé. Cada facto deve ter uma ligação para a sua fonte original. Teste com perguntas sobre atualidade e verifique manualmente se as ligações são válidas e relevantes.
Pontos-chave
- As citações globais (lista de URLs) são devolvidas por predefinição, sem configuração
- As citações inline (ligações no texto) são ativadas através do parâmetro
include - O comportamento predefinido das citações inline varia consoante o SDK
- Cada anotação contém o URL, os índices de posição e o número da citação
- Em streaming, as anotações completas apenas estão disponíveis na resposta final
- As citações de coleções utilizam um formato URI distinto (
collections://)