Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Viittausten hyödyntäminen tuloksissa

Oppitunti 3 / 14 Päivitetty 30. heinäkuuta 2026 Aloittelija
Tällä sivulla
  1. Jäljitettävät vastaukset viittauksilla
  2. Globaalit viittaukset: täydellinen lähdeluettelo
  3. Sisäiset viittaukset: viitteet tekstissä
  4. Jäsennelty annotaatiokaavio
  5. Streamauskäyttäytyminen
  6. Lähteillä varustetun käyttöliittymän rakentaminen
  7. Kokoelmaviittaukset
  8. Käytännön harjoitus
  9. Keskeiset asiat

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.

Viittaukset ja lähteet Grok-vastauksissa

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