Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Teosta tsiteerimine Pythonis

Õppetund 9 / 16 Värskendatud 3. november 2026 Edasijõudnutele
Sellel lehel
  1. Terve tsiteerimise torustik
  2. Määratle mudeli leping süsteemsõnumis
  3. Määratle otsingutööriist
  4. Tagasta tulemused viitevormingus
  5. Eralda tekst viidetest
  6. Valmista ette kasutajaliidese kuva
  7. Peamised punktid

Uuendatud 3. novembril 2026, tuginedes Mistrali Citations & References juhendile: tööriista tulemus järgib dokumenteeritud vormingut – objekt, mis on indekseeritud allika numbri järgi, ilma väljadeta type või reference_id – ning vastuses olevad reference_ids lahendatakse selle objekti sees kasutades str(ref_id). Allikas: Citations & References.

Terve tsiteerimise torustik

Nüüd paned kokku RAG-torustiku, mis tsiteerib oma allikaid, alates esimesest API-kutsust kuni andmestruktuurini, mida sinu liides tarbib. Pidage meeles seda põhimõtet: mudel ise dokumente ei hangita. See annab märku, et vajab otsingut; sina teostad selle otsingu oma andmebaasis ja seejärel tagastad lõigud koos nende identifikaatoritega. See edasi-tagasi suhtlus loob vastuse, kus iga väide jääb seotuks reaalse dokumendiga.

Täpsemalt öeldes nõuab täielik tsükkel kahte chat.complete väljakutset. Esimene käivitab tööriista kutse; teine genereerib tsiteeritud vastuse, kui allikad on ajaloosse sisestatud. Käime selle tsükli läbi lihtsa näite varal: sisene dokumentatsiooniassistent, kellelt küsitakse LLM-i kasutuselevõtu parimaid tavasid.

Määratle mudeli leping süsteemsõnumis

Süsteemsõnum seab lepingu: vasta pakutud allikate põhjal, tsiteeri süstemaatiliselt ja mis kõige tähtsam – tunnistage, kui teave puudub, selle asemel et lünki välja mõelda. See viimane juhiste osa teeb tootmises vahet, sest vastused kipuvad kalduma kõrvale küsimustes, mida dokumentatsiooni baas halvasti kajastab.

from mistralai.client import Mistral
import json

client = Mistral(api_key="your-api-key")

# Tsiteerimist soodustav süsteemsõnum
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ääratle otsingutööriist

Tööriist kirjeldab, kuidas dokumentide otsing sinu süsteemis välja näeb: siin lihtne funktsioon search_documentation, mis võtab vastu tekstipäringu. Esimene väljakutse ei oota kirjalikku vastust; see ootab, et mudel formuleeriks päringu, mida ta peab asjakohaseks, säästes sind ümberformuleerimise kihi kirjutamisest.

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"]
        }
    }
}

# Esimene väljakutse: mudel taotleb tööriista kasutamist
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=[reference_tool]
)

Tagasta tulemused viitevormingus

See on struktuurne samm. Sinu otsingumootori tulemused saabuvad ToolMessage’ina, mille sisuks on eelmises õppetükis käsitletud viiteobjekt: igal allikal on number ("0", "1"…), URL, pealkiri ja valitud lõigud. Need on numbrid, mida mudel kasutab oma tsiteeringute märkimiseks ja mida sinu kasutajaliides hiljem linkideks lahendab.

from mistralai.client.models import ToolMessage

# Dokumentatsiooni otsingutulemused Mistrali viitevormingus
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"
    }
}

# Lisa tööriista kutse ja vastus ajaloosse
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)
    )
)

Pane tähele, et mudeli algne sõnum sisestatakse ajaloossa uuesti enne ToolMessage’i: ilma selle tööriista kutse ja tulemuse paarita keeldub API jätkamisest. Teine väljakutse ei vaja enam tööriista definitsioone, kuna otsing on juba toimunud.

# Teine väljakutse: mudel genereerib tsiteeringutega vastuse
final_response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)

Eralda tekst viidetest

Tsiteeritud vastus ei ole enam lihtne string, vaid jadade jada, kus vahelduvad proosa ja tsiteerimismärgid. Parsimine hõlmab selle jada läbimist ja sorteerimist: TextChunk objektid rekonstrueerivad loetava teksti, samas kui ReferenceChunk objektid edastavad tegelikult kasutatud reference_ids. See eristus annab sulle väärtuslikku teavet: täpselt milliseid allikaid mudel sinu pakututest kasutas.

from mistralai.client.models import TextChunk, ReferenceChunk

def parse_cited_response(response):
    """Eemaldab teksti ja viited tsiteeritud vastusest."""
    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("=== Vastus ===")
print(result["text"])
print("\n=== Tsiteeritud allikad ===")
for ref_id in result["references_used"]:
    source = references[str(ref_id)]
    print(f"  - {source['title']} : {source['url']}")

Valmista ette kasutajaliidese kuva

Vastuse lamestamine lihttekstiks kaotaks tsiteeringute asukoha ja seeläbi ka nende väärtuse. Parem on jada säilitada ja seda rikastada: lahenda iga ReferenceChunk viitetabeli vastu, et kaasata iga allika pealkiri ja URL. Sinu liides saab seega järjestatud plokkide loendi, mida saab renderdada klõpsatavate linkidena, tööriistadena või interaktiivsete tsiteerimisnumbritena, ilma et peaks teksti kunagi uuesti tõlgendama.

def format_for_frontend(response, reference_map):
    """Vormindab vastuse tsiteeringutega kasutajaliidese jaoks."""
    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

Enne kui avad selle torustiku kogu oma dokumentatsiooni baasile, käivita see vaid kolme kuni viie allikaga, nagu ülaltoodud näites. Näed kohe, kas mudel tsiteerib õiges kohas, kas ta kasutab mitut dokumenti või kas ta jääb süstemaatiliselt kinni esimesse, võimaldades sul süsteemsõnumit parandada enne, kui käitumine suure mahuga kaduma läheb.

Peamised punktid

  • Torustik järgib kahe väljakutse voogu: tööriista kutse, seejärel tsiteeritud vastus
  • Viidetakse edasi ToolMessage kaudu objektina, mis on indekseeritud allika numbri järgi ("0", "1"…)
  • Vastus sisaldab segamini TextChunk ja ReferenceChunk objekte, mida tuleb parsida
  • Struktureeri väljund nii, et sinu kasutajaliides saaks kuvada interaktiivseid tsiteeringuid
  • Testi 3–5 allikaga, et käitumist enne tootmisse viimist valideerida