Exploatarea citărilor în rezultate
Pe această pagină
Răspunsuri trasabile cu citări
Când un utilizator adresează aplicației dumneavoastră o întrebare factuală, acesta dorește să verifice informația. Citările API Grok răspund exact acestei nevoi: fiecare fapt recuperat prin căutare web vine însoțit de sursa sa. Acest lucru vă permite să construiți interfețe în care fiecare afirmație este clicabilă și verificabilă.

API-ul oferă două mecanisme complementare de citare: citări globale și citări inline. Înțelegerea funcționării lor vă permite să creați experiențe de utilizator profesionale și transparente.
Citări globale: Lista completă a surselor
Citările globale sunt returnate implicit în atributul citations al răspunsului. Acestea conțin o listă a tuturor URL-urilor consultate de model, chiar și a celor care nu sunt referențiate direct în textul răspunsului.
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}")
Nu este necesară nicio configurare suplimentară. Acesta este comportamentul nativ al API-ului.
Citări inline: Referințe în text
Citările inline inserează link-uri Markdown direct în textul răspunsului, folosind formatul [[N]](url), unde N este un număr secvențial începând de la 1. Dacă aceeași sursă este citată de mai multe ori, numărul original este reutilizat.
Comportamentul implicit depinde de SDK-ul utilizat:
- API Responses direct: citările inline sunt activate implicit
- SDK xAI: citările inline sunt dezactivate implicit (opt-in)
Activarea citărilor inline cu SDK-ul xAI
response = client.responses.create(
model="grok-4.5",
input="Current status of the European AI Act",
tools=[{"type": "web_search"}],
include=["inline_citations"]
)
Dezactivarea citărilor inline pe API-ul Responses
response = client.responses.create(
model="grok-4.5",
input="Current status of the European AI Act",
tools=[{"type": "web_search"}],
include=["no_inline_citations"]
)
Schema de adnotare structurată
Fiecare citare inline generează un obiect de adnotare cu metadate precise. Această structură permite procesarea programatică avansată:
{
"type": "url_citation",
"url": "https://eur-lex.europa.eu/eli/reg/2024/1689",
"start_index": 145,
"end_index": 178,
"title": "1"
}
Câmpurile start_index și end_index respectă convenția de slice din Python. Le puteți utiliza pentru a extrage textul exact citat sau pentru a crea o redare HTML personalizată:
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}")
Comportament în modul streaming
Atunci când utilizați modul streaming, citările inline apar progresiv în fragmentele de text. Totuși, adnotările complete sunt disponibile doar în răspunsul final. Planificați o procesare în două etape dacă interfața dumneavoastră afișează sursele în timp real.
Construirea unei interfețe cu surse
Iată un exemplu de transformare a citărilor în HTML structurat:
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
Citări din colecții
Dacă utilizați instrumentul collections_search alături de web_search, citările provenite din documentele încărcate de dumneavoastră folosesc un format specific de URI: collections://collection_id/files/file_id. Distingeți-le de citările web standard pentru a adapta redarea front-end.
Exercițiu practic
Creați o aplicație care afișează rezultatele căutării Grok cu un sistem de note de subsol. Fiecare fapt ar trebui să facă trimitere la sursa sa originală. Testați cu întrebări despre actualitate și verificați manual dacă link-urile sunt valide și relevante.
Puncte cheie
- Citările globale (lista de URL-uri) sunt returnate implicit, fără configurare
- Citările inline (link-uri în text) sunt activate prin parametrul
include - Comportamentul implicit al citărilor inline variază în funcție de SDK
- Fiecare adnotare conține URL-ul, indicii de poziție și numărul citării
- În modul streaming, adnotările complete sunt disponibile doar în răspunsul final
- Citările din colecții folosesc un format distinct de URI (
collections://)