Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Aproveitar as Citações nos Resultados

Aula 3 de 14 Atualizada a 30 de julho de 2026 Iniciante
Nesta página
  1. Respostas Rastreáveis com Citações
  2. Citações Globais: A Lista Completa de Fontes
  3. Citações Inline: Referências no Texto
  4. O Esquema de Anotação Estruturada
  5. Comportamento em Streaming
  6. Criar uma Interface com Fontes
  7. Citações de Coleções
  8. Prática Prática
  9. Pontos-chave

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.

Citações e fontes nas respostas do Grok

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://)