Toteuta viittaukset Pythonilla
Tällä sivulla
Päivitetty 3. marraskuuta 2026 Mistralin Citations & References -oppaan perusteella: työkalun tulos noudattaa dokumentoitua muotoa – objekti, joka on indeksoitu lähteen numerolla, ilman
type- taireference_id-kenttiä – ja vastauksenreference_idsratkeavat käyttämällästr(ref_id)kyseisessä objektissa. Lähde: Citations & References.
Koko viittausputki
Nyt koostat RAG-putken, joka viittaa lähteisiinsä ensimmäisestä API-kutsusta aina käyttöliittymäsi kuluttamaan tietorakenteeseen saakka. Pidä mielessäsi tämä periaate: malli ei koskaan nouda dokumentteja itse. Se signaloi tarvitsevansa hakua, sinä suoritat haun omassa tietokannassasi ja palautat sitten otteet niiden tunnisteineen. Tämä vuorovaikutus tuottaa vastauksen, jossa jokainen väittämä pysyy sidottuna todelliseen dokumenttiin.
Tarkemmin sanottuna täysi sykli vaatii kaksi chat.complete-kutsua. Ensimmäinen laukaisee työkalukutsun; toinen generoi viitatun vastauksen, kun lähteet on syötetty historiaan. Käymme läpi tämän syklin yksinkertaisella tapauksella: sisäinen dokumentaatioavustaja, jota kysytään LLM:n tuotantoon käyttöönoton parhaista käytännöistä.
Määritä mallin sopimus järjestelmäviestissä
Järjestelmäviesti asettaa sopimuksen: vastaa annettujen lähteiden perusteella, viittaa systemaattisesti ja ennen kaikkea myönnä, kun tieto puuttuu, sen sijaan että täyttäisit aukon. Tämä viimeinen ohje tekee eron tuotannossa, koska vastaukset pyrkivät harhailemaan kysymyksissä, joita dokumentaatiokanta ei kata kunnolla.
from mistralai.client import Mistral
import json
client = Mistral(api_key="your-api-key")
# Viittauksiin kannustava järjestelmäviesti
system_message = {
"role": "system",
"content": (
"You are a documentation assistant. "
"Answer questions using the provided sources. "
"Cite your sources systematically. "
"If the information is not in any source, state this explicitly."
)
}
user_message = {
"role": "user",
"content": "What are the best practices for deploying an LLM in production?"
}
messages = [system_message, user_message]
Määrittele hakutyökalu
Työkalu kuvaa, miltä dokumenttihaku näyttää järjestelmässäsi: tässä yksinkertainen search_documentation-funktio, joka ottaa tekstikyselyn. Ensimmäinen kutsu ei odota kirjallista vastausta; se odottaa mallin muotoilevan kyselyn, jonka se katsoo relevantiksi, säästäen sinut uudelleenmuotoilukerrokseen kirjoittamiselta.
reference_tool = {
"type": "function",
"function": {
"name": "search_documentation",
"description": "Searches the documentation database",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query"
}
},
"required": ["query"]
}
}
}
# Ensimmäinen kutsu: malli pyytää työkalun käyttöä
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=[reference_tool]
)
Palauta tulokset viitemuodossa
Tämä on rakenteellinen vaihe. Hakukoneesi tulokset palaavat ToolMessage-objektina, jonka sisältö on edellisen oppitunnin mukainen viiteobjekti: jokaisella lähteellä on numero ("0", "1"…), URL-osoite, otsikko ja valitut otteet. Nämä ovat numeroita, joita malli käyttää uudelleen merkitessään viittauksiaan ja jotka frontendisi myöhemmin ratkaisee linkeiksi.
from mistralai.client.models import ToolMessage
# Dokumenttihausta saadut tulokset Mistralin viitemuodossa
references = {
"0": {
"url": "https://docs.example.com/deployment-guide",
"title": "LLM Deployment Guide",
"snippets": [[
"Always configure rate limits to protect the service.",
"Monitor P99 latency and error rates continuously."
]],
"description": None,
"date": "2026-09-01",
"source": "docs"
},
"1": {
"url": "https://docs.example.com/security",
"title": "AI Application Security",
"snippets": [[
"Filter user inputs to prevent injections.",
"Never expose API keys on the client side."
]],
"description": None,
"date": "2026-08-15",
"source": "docs"
},
"2": {
"url": "https://docs.example.com/scaling",
"title": "Scalability and Performance",
"snippets": [[
"Use semantic caching to reduce API calls.",
"Size instances based on peak traffic."
]],
"description": None,
"date": "2026-07-20",
"source": "docs"
}
}
# Lisää työkalukutsu ja vastaus historiaan
tool_call = response.choices[0].message.tool_calls[0]
messages.append(response.choices[0].message)
messages.append(
ToolMessage(
tool_call_id=tool_call.id,
name="search_documentation",
content=json.dumps(references, ensure_ascii=False)
)
)
Huomaa, että mallin alkuperäinen viesti syötetään uudelleen historiaan ennen ToolMessage-objektia: ilman tätä työkalukutsu/työkalutulos-paria API kieltää jatkamisen. Toinen kutsu ei enää tarvitse työkalumääritelmiä, sillä haku on jo suoritettu.
# Toinen kutsu: malli generoi vastauksen viittauksineen
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
Erota teksti viitteistä
Viitattu vastaus ei ole enää pelkkä merkkijono, vaan sekvenssi osia, joissa proosa ja viitemerkinnät vuorottelevat. Jäsennys tarkoittaa tämän sekvenssin läpikäyntiä ja lajittelua: TextChunk-objektit rekonstruoivat luettavan tekstin, kun taas ReferenceChunk-objektit toimittavat todella käytetyt reference_ids. Tämä ero antaa arvokasta tietoa: tarkalleen ottaen, mitkä lähteet malli käytti tarjoamistasi lähteistä.
from mistralai.client.models import TextChunk, ReferenceChunk
def parse_cited_response(response):
"""Pura teksti ja viitteet viitatusta vastauksesta."""
content_parts = response.choices[0].message.content
text_parts = []
cited_refs = set()
for chunk in content_parts:
if isinstance(chunk, TextChunk):
text_parts.append(chunk.text)
elif isinstance(chunk, ReferenceChunk):
for ref_id in chunk.reference_ids:
cited_refs.add(ref_id)
return {
"text": "".join(text_parts),
"references_used": list(cited_refs)
}
result = parse_cited_response(final_response)
print("=== Vastaus ===")
print(result["text"])
print("\n=== Viitatut lähteet ===")
for ref_id in result["references_used"]:
source = references[str(ref_id)]
print(f" - {source['title']} : {source['url']}")
Valmistele näyttäminen frontendissä
Vastauksen litistäminen pelkäksi tekstiksi hukkaa viittausten sijainnin ja siten niiden arvon. On parempi säilyttää sekvenssi ja rikastaa sitä: ratkaise jokainen ReferenceChunk viitetaulukkoa vasten kuljettaaksesi mukana kunkin lähteen otsikon ja URL-osoitteen. Käyttöliittymäsi saa näin järjestetyn listan lohkoja, jotka se voi renderöidä klikattaviksi linkeiksi, työkaluvihjeiksi tai interaktiivisiksi viitenumeroiksi joutumatta koskaan tulkitsemaan tekstiä uudelleen.
def format_for_frontend(response, reference_map):
"""Muotoilee vastauksen viittauksineen frontendille."""
content_parts = response.choices[0].message.content
formatted = []
for chunk in content_parts:
if isinstance(chunk, TextChunk):
formatted.append({
"type": "text",
"content": chunk.text
})
elif isinstance(chunk, ReferenceChunk):
refs = []
for ref_id in chunk.reference_ids:
source = reference_map.get(str(ref_id))
if source:
refs.append({
"id": ref_id,
"title": source["title"],
"url": source["url"]
})
formatted.append({
"type": "citation",
"references": refs
})
return formatted
Ennen kuin avaat tämän putken koko dokumentaatiokannallesi, suorita se vain kolmella–viidellä lähteellä, kuten yllä olevassa esimerkissä. Näet heti, viittaako malli oikeaan paikkaan, hyödyntääkö se useita dokumentteja vai takertuuko se systemaattisesti ensimmäiseen, jolloin voit korjata järjestelmäviestin ennen kuin käyttäytyminen hukkuu volyymiin.
Keskeiset asiat
- Putki noudattaa kahden kutsun virtaa: työkalukutsu ja sen jälkeen viitattu vastaus
- Viitteet välitetään
ToolMessage-objektin kautta objektina, joka on indeksoitu lähteen numerolla ("0","1"…) - Vastaus sisältää sekoituksen
TextChunk- jaReferenceChunk-objekteja jäsennettäväksi - Rakenna tuloste niin, että frontendisi voi näyttää interaktiiviset viittaukset
- Testaa 3–5 lähteellä validoidaksesi käyttäytymisen ennen siirtymistä tuotantoon