Имплементиране на цитати в Python
На тази страница
Обновено на 3 ноември 2026 г. въз основа на ръководството на Mistral Citations & References: резултатът от инструмента следва документирания формат – обект, индексиран по номер на източника, без полета
typeилиreference_id– аreference_idsв отговора се разрешават чрезstr(ref_id)в рамките на този обект. Източник: Citations & References.
Пълният конвейер за цитиране
Сега ще сглобите RAG конвейер, който цитира своите източници – от първото API обаждане до структурата от данни, която вашият интерфейс използва. Имайте предвид следния принцип: моделът никога не извлича документи сам. Той сигнализира, че има нужда от търсене; Вие изпълнявате това търсене във вашата собствена база данни и след това връщате откъсите заедно с техните идентификатори. Този обмен води до отговор, в който всяко твърдение остава свързано с реален документ.
По-конкретно, един пълен цикъл изисква две обаждания към chat.complete. Първото задейства извикването на инструмента; второто генерира цитирания отговор, след като източниците бъдат инжектирани в историята. Ще разгледаме този цикъл чрез прост случай: вътрешен асистент за документация, запитан за най-добрите практики за внедряване на LLM.
Дефиниране на договора с модела в системното съобщение
Системното съобщение задава договора: отговаряйте въз основа на предоставените източници, цитирайте систематично и преди всичко признавайте, когато липсва информация, вместо да попълвате празнотата. Тази последна инструкция прави разликата в производствена среда, защото отговорите имат тенденция да се отклоняват при въпроси, които са слабо покрити от базата с документация.
from mistralai.client import Mistral
import json
client = Mistral(api_key="your-api-key")
# Системно съобщение, насърчаващо цитирането
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]
Деклариране на инструмента за търсене
Инструментът описва как изглежда търсенето на документи във вашата система: тук става въпрос за проста функция search_documentation, приемаща текстова заявка. Първото обаждане не очаква написан отговор; то очаква моделът да формулира заявката, която счита за релевантна, като Ви спестява необходимостта от писане на слой за преформулиране.
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"]
}
}
}
# Първо обаждане: моделът иска да използва инструмента
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=[reference_tool]
)
Връщане на резултатите във формат за препратки
Това е структурната стъпка. Резултатите от вашия търсач се връщат в ToolMessage, чието съдържание е обектът за препратки от предишния урок: всеки източник има номер ("0", "1"…), URL адрес, заглавие и избраните откъси. Това са номерата, които моделът използва повторно, за да маркира своите цитати, и които вашият фронтенд впоследствие ще превърне във връзки.
from mistralai.client.models import ToolMessage
# Резултати от търсенето в документацията, във формат за препратки на Mistral
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"
}
}
# Добавяне на извикването на инструмента и отговора към историята
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)
)
)
Обърнете внимание, че оригиналното съобщение на модела се инжектира отново в историята преди ToolMessage: без тази двойка извикване на инструмент / резултат от инструмент, API отказва продължението. Второто обаждане вече не нуждае от дефинициите на инструментите, тъй като търсенето вече е извършено.
# Второ обаждане: моделът генерира отговор с цитати
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
Разделяне на текста от препратките
Цитираният отговор вече не е просто низ, а последователност от части, редуващи проза и маркировки за цитати. Парсирането включва обхождане на тази последователност и сортиране: обектите TextChunk възстановяват четимия текст, докато обектите ReferenceChunk доставят действително използваните reference_ids. Това разграничение Ви предоставя ценна информация: точно кои източници е използвал моделът сред предоставените от Вас.
from mistralai.client.models import TextChunk, ReferenceChunk
def parse_cited_response(response):
"""Извлича текста и препратките от цитиран отговор."""
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("=== Отговор ===")
print(result["text"])
print("\n=== Цитирани източници ===")
for ref_id in result["references_used"]:
source = references[str(ref_id)]
print(f" - {source['title']} : {source['url']}")
Подготовка за показване във фронтенда
Изравняването на отговора в обикновен текст би загубило позицията на цитатите, а следователно и тяхната стойност. По-добре е да запазите последователността и да я обогатите: разрешете всеки ReferenceChunk спрямо таблица с препратки, за да пренесете заглавието и URL адреса на всеки източник. По този начин Вашият интерфейс получава подреден списък от блокове, които може да визуализира като кликабельни връзки, подсказки или интерактивни номера на цитати, без никога да се налага да преинтерпретира текста.
def format_for_frontend(response, reference_map):
"""Форматира отговора с цитати за фронтенда."""
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
Преди да отворите този конвейер към цялата си база с документация, стартирайте го само с три до пет източника, както в примера по-горе. Веднага ще видите дали моделът цитира на правилното място, дали използва множество документи или дали систематично се придържа към първия, което Ви позволява да коригирате системното съобщение, преди поведението да се загуби в обема.
Ключови изводи
- Конвейерът следва поток от две обаждания: извикване на инструмент, следвано от цитиран отговор
- Препратките се предават чрез
ToolMessage, в обект, индексиран по номер на източника ("0","1"…) - Отговорът съдържа смес от
TextChunkиReferenceChunkза парсиране - Структурирайте изхода така, че Вашият фронтенд да може да показва интерактивни цитати
- Тествайте с 3–5 източника, за да валидирате поведението, преди да преминете към производствена среда