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

Citações Automáticas e Melhores Práticas

Aula 16 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Respostas Fundamentadas e Confiáveis
  2. Como Funcionam as Citações
  3. Exibir Citações na Sua Aplicação
  4. Melhores Práticas para Produção
  5. Lista de Verificação de Implementação
  6. Pontos-chave
  7. Teste os Seus Conhecimentos

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

CampoDescrição
typeSempre url_citation
urlURL da fonte
titleTítulo da página de origem
start_indexPosição inicial no texto
end_indexPosiçã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.id para rastreabilidade
  • usage.total_tokens para consumo
  • usage.cost_in_nano_usd para 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_search ou x_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.