Viittausten hyödyntäminen tuloksissa
Tällä sivulla
Jäljitettävät vastaukset viittauksilla
Kun käyttäjä esittää sovelluksellesi faktuaalisen kysymyksen, hän haluaa varmistaa tiedon luotettavuuden. Grok API:n viittaukset vastaavat tähän tarpeeseen täydellisesti: jokainen verkkohaun kautta haettu fakta sisältää lähteensä. Tämä mahdollistaa käyttöliittymät, joissa jokainen väittämä on napsautettava ja todennettavissa.

API tarjoaa kaksi toisiaan täydentävää viittausmekanismia: globaalit viittaukset ja sisäiset viittaukset. Ymmärtämällä niiden toiminnan voit rakentaa ammattimaisia ja läpinäkyviä käyttäjäkokemuksia.
Globaalit viittaukset: täydellinen lähdeluettelo
Globaalit viittaukset palautetaan oletuksena vastauksen citations-attribuutissa. Ne sisältävät luettelon kaikista mallin käyttämistä URL-osoitteista, myös niistä, joita ei ole suoraan mainittu vastauksen tekstissä.
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}")
Lisäasetuksia ei tarvita. Tämä on API:n natiivi toimintatapa.
Sisäiset viittaukset: viitteet tekstissä
Sisäiset viittaukset lisäävät Markdown-linkkejä suoraan vastauksen tekstiin muodossa [[N]](url), jossa N on ykkösestä alkava järjestysnumero. Jos samaa lähdettä siteerataan useita kertoja, alkuperäistä numeroa käytetään uudelleen.
Oletustoiminta riippuu käytetystä SDK:sta:
- Suora Responses API: sisäiset viittaukset oletuksena käytössä
- xAI SDK: sisäiset viittaukset oletuksena pois päältä (opt-in)
Sisäisten viittausten käyttöönotto xAI SDK:lla
response = client.responses.create(
model="grok-4.5",
input="Current status of the European AI Act",
tools=[{"type": "web_search"}],
include=["inline_citations"]
)
Sisäisten viittausten poistaminen käytöstä Responses API:ssa
response = client.responses.create(
model="grok-4.5",
input="Current status of the European AI Act",
tools=[{"type": "web_search"}],
include=["no_inline_citations"]
)
Jäsennelty annotaatiokaavio
Jokainen sisäinen viittaus tuottaa annotaatio-objektin, jossa on tarkat metatiedot. Tämä rakenne mahdollistaa edistyneen ohjelmallisen käsittelyn:
{
"type": "url_citation",
"url": "https://eur-lex.europa.eu/eli/reg/2024/1689",
"start_index": 145,
"end_index": 178,
"title": "1"
}
Kentät start_index ja end_index noudattavat Pythonin slice-käytäntöä. Voit käyttää niitä tarkasti siteeratun tekstin erottamiseen tai mukautetun HTML-esityksen luomiseen:
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}")
Streamauskäyttäytyminen
Streamausta käytettäessä sisäiset viittaukset ilmestyvät tekstikappaleisiin vähitellen. Täydelliset annotaatiot ovat kuitenkin saatavilla vasta lopullisessa vastauksessa. Suunnittele kaksivaiheinen käsittely, jos käyttöliittymäsi näyttää lähteet reaaliajassa.
Lähteillä varustetun käyttöliittymän rakentaminen
Tässä on esimerkki viittausten muuntamisesta jäsennellyksi HTML-koodiksi:
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
Kokoelmaviittaukset
Jos käytät collections_search-työkalua web_search-työkalun rinnalla, ladattuihin dokumentteihisi viittaavat viittaukset käyttävät erityistä URI-muotoa: collections://collection_id/files/file_id. Erota nämä tavallisista verkkoviittauksista mukauttaaksesi front-end-esitystä.
Käytännön harjoitus
Luo sovellus, joka näyttää Grok-hakutulokset alaviitejärjestelmällä. Jokaisen faktan tulee linkittyä takaisin alkuperäiseen lähteeseensä. Testaa sovellusta ajankohtaisilla kysymyksillä ja varmista manuaalisesti, että linkit ovat toimivia ja asiaankuuluvia.
Keskeiset asiat
- Globaalit viittaukset (URL-luettelo) palautetaan oletuksena ilman erillisiä asetuksia
- Sisäiset viittaukset (linkit tekstissä) otetaan käyttöön
include-parametrilla - Sisäisten viittausten oletustoiminta vaihtelee SDK:n mukaan
- Jokainen annotaatio sisältää URL-osoitteen, sijainti-indeksit ja viittausnumeron
- Streamauksessa täydelliset annotaatiot ovat saatavilla vasta lopullisessa vastauksessa
- Kokoelmaviittaukset käyttävät erilaista URI-muotoa (
collections://)