Idézetek implementálása Pythonban
Ezen az oldalon
Frissítve: 2026. november 3. a Mistral Idézetek és hivatkozások útmutatója alapján: az eszköz válasza a dokumentált formátumot követi – egy forrásszámmal indexelt objektum,
typevagyreference_idmezők nélkül –, és a válaszban szereplőreference_idsértékek astr(ref_id)segítségével oldódnak fel ebben az objektumban. Forrás: Idézetek és hivatkozások.
A teljes idézési folyamat
Most összeállítasz egy RAG folyamatot, amely idézi a forrásait, az első API-hívástól kezdve egészen addig az adatszerkezetig, amelyet a felületed fogyaszt. Tartsd észben ezt az alapelvet: a modell soha nem fetcheli le maga a dokumentumokat. Jelzi, hogy keresésre van szüksége, te végrehajtod ezt a keresést a saját adatbázisodban, majd visszaadod a részleteket az azonosítóikkal együtt. Ez az oda-vissza kommunikáció olyan választ eredményez, ahol minden állítás egy valódi dokumentumhoz marad kötve.
Konkrétabban, egy teljes ciklus két chat.complete hívást igényel. Az első váltja ki az eszköz hívását; a második generálja az idézett választ, miután a forrásokat beillesztetted a történetbe (history). Végigvezetünk ezen a cikluson egy egyszerű eset segítségével: egy belső dokumentációs asszisztens, akit az LLM éles környezetbe történő telepítésének legjobb gyakorlatairól kérdeznek.
A modellszerződés meghatározása a rendszerüzenetben
A rendszerüzenet határozza meg a szerződést: a megadott források alapján válaszolj, szisztematikusan idézz, és mindenekelőtt valljad be, ha hiányzik az információ, ahelyett, hogy kitöltenéd a hézagot. Ez az utolsó utasítás teszi a különbséget éles környezetben, mert a válaszok hajlamosak eltérni olyan kérdéseknél, amelyeket a dokumentációs bázis gyengén fed le.
from mistralai.client import Mistral
import json
client = Mistral(api_key="your-api-key")
# Rendszerüzenet, amely bátorítja az idézést
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]
A keresési eszköz deklarálása
Az eszköz leírja, hogyan néz ki egy dokumentumkeresés a te rendszeredben: itt egy egyszerű search_documentation függvényről van szó, amely egy szöveges lekérdezést fogad el. Az első hívás nem vár írásbeli választ; arra számít, hogy a modell megfogalmazza a számára releváns lekérdezést, így megspórolod neked egy újraformuláló réteg megírását.
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"]
}
}
}
# Első hívás: a modell kéri az eszköz használatát
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=[reference_tool]
)
Az eredmények visszaadása hivatkozási formátumban
Ez a strukturális lépés. A keresőmotorod eredményei egy ToolMessage-ben érkeznek vissza, amelynek tartalma az előző leckéből származó hivatkozási objektum: minden forrásnak van egy száma ("0", "1"…), egy URL-je, egy címe és a kiválasztott részletei. Ezeket a számokat használja fel a modell az idézeteinek megjelölésére, és amelyeket a frontended később linkekké alakít át.
from mistralai.client.models import ToolMessage
# Dokumentumkeresési eredmények Mistral hivatkozási formátumban
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"
}
}
# Az eszköz hívásának és válaszának hozzáadása a történethez
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)
)
)
Vedd észre, hogy a modell eredeti üzenetét újra beillesztjük a történetbe a ToolMessage előtt: ebből az eszköz hívás / eszköz válasz páros nélkül az API elutasítja a folytatást. A második híváshoz már nincs szükség az eszközdefiníciókra, mivel a keresés már megtörtént.
# Második hívás: a modell választ generál idézetekkel
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
A szöveg és a hivatkozások szétválasztása
Az idézett válasz már nem egy egyszerű sztring, hanem töredékek (chunkok) sorozata, amelyek váltakozva tartalmaznak prózát és idézőjeleket. A feldolgozás ennek a sorozatnak a bejárását és rendezését jelenti: a TextChunk objektumok rekonstruálják az olvasható szöveget, míg a ReferenceChunk objektumok a ténylegesen használt reference_ids értékeket szolgáltatják. Ez a megkülönböztetés értékes információt ad: pontosan megmutatja, mely forrásokat használta fel a modell az általad biztosítottak közül.
from mistralai.client.models import TextChunk, ReferenceChunk
def parse_cited_response(response):
"""Kiszűri a szöveget és a hivatkozásokat egy idézett válaszból."""
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("=== Response ===")
print(result["text"])
print("\n=== Cited Sources ===")
for ref_id in result["references_used"]:
source = references[str(ref_id)]
print(f" - {source['title']} : {source['url']}")
A frontend megjelenítés előkészítése
Ha egyszerű szöveggé lapítod össze a választ, elveszíted az idézetek pozícióját, és ezzel az értéküket is. Jobb, ha megtartod a sorrendet, és dúsítod azt: oldd fel minden ReferenceChunk értékét egy hivatkozási tábla alapján, hogy magaddal vidd az egyes források címét és URL-jét. Így a felületed egy rendezett blokklistát kap, amelyet kattintható linkekként, eszköztippekként vagy interaktív idézőszámokként jeleníthet meg anélkül, hogy újraértelmezné a szöveget.
def format_for_frontend(response, reference_map):
"""Formázza a választ idézetekkel a frontend számára."""
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
Mielőtt ezt a folyamatot megnyitnád a teljes dokumentációs bázisod előtt, futtasd le mindössze három-öt forrással, ahogy a fenti példában is láttad. Azonnal látni fogod, hogy a modell a megfelelő helyen idéz-e, kihasznál-e több dokumentumot, vagy szisztematikusan ragaszkodik-e az elsőhöz, így még időben korrigálhatod a rendszerüzenetet, mielőtt a viselkedés elveszne a nagy volumenben.
Főbb megállapítások
- A folyamat két hívásból áll: először az eszköz hívása, majd az idézett válasz.
- A hivatkozások egy
ToolMessageútján kerülnek átadásra, egy forrásszámmal indexelt objektumban ("0","1"…). - A válasz
TextChunkésReferenceChunkkeverékét tartalmazza, amelyet elemezni kell. - Strukturáld a kimenetet úgy, hogy a frontended képes legyen interaktív idézeteket megjeleníteni.
- Tesztelj 3–5 forrással a viselkedés ellenőrzéséhez, mielőtt éles környezetbe helyeznéd.