Implementacja cytowań w Pythonie
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie przewodnika Mistral Citations & References: wynik działania narzędzia遵循 udokumentowany format – jest to obiekt indeksowany numerem źródła, bez pól
typeanireference_id– a polareference_idsw odpowiedzi są rozwiązywane poprzezstr(ref_id)wewnątrz tego obiektu. Źródło: Citations & References.
Kompleksowy proces cytowania
Złożysz teraz potok RAG, który cytuje swoje źródła – od pierwszego wywołania API aż po strukturę danych zużywaną przez Twój interfejs. Zapamiętaj tę zasadę: model nigdy sam nie pobiera dokumentów. Sygnalizuje, że potrzebuje wyszukiwania, Ty wykonujesz to wyszukiwanie we własnej bazie danych, a następnie zwracasz fragmenty wraz z ich identyfikatorami. Ta wymiana generuje odpowiedź, w której każde twierdzenie pozostaje powiązane z rzeczywistym dokumentem.
Konkretnie, pełny cykl wymaga dwóch wywołań chat.complete. Pierwsze inicjuje wywołanie narzędzia; drugie generuje odpowiedź z cytowaniami, gdy źródła zostaną wstrzyknięte do historii. Przejdziemy przez ten cykl na prostym przykładzie: asystent wewnętrznej dokumentacji pytany o najlepsze praktyki wdrażania LLM.
Zdefiniuj kontrakt modelu w wiadomości systemowej
Wiadomość systemowa ustala kontrakt: odpowiadaj na podstawie dostarczonych źródeł, systematycznie cytuj i przede wszystkim przyznawaj się do braku informacji, zamiast wypełniać luki domysłami. Ta ostatnia instrukcja robi różnicę w środowisku produkcyjnym, ponieważ odpowiedzi mają tendencję do dryfowania przy pytaniach słabo pokrytych przez bazę dokumentacji.
from mistralai.client import Mistral
import json
client = Mistral(api_key="your-api-key")
# Wiadomość systemowa zachęcająca do cytowania
system_message = {
"role": "system",
"content": (
"Jesteś asystentem dokumentacji. "
"Odpowiadaj na pytania, korzystając z dostarczonych źródeł. "
"Systematycznie cytuj swoje źródła. "
"Jeśli informacji nie ma w żadnym źródle, wyraźnie to zaznacz."
)
}
user_message = {
"role": "user",
"content": "Jakie są najlepsze praktyki wdrażania LLM w środowisku produkcyjnym?"
}
messages = [system_message, user_message]
Zadeklaruj narzędzie wyszukiwania
Narzędzie opisuje, jak wygląda wyszukiwanie dokumentów w Twoim systemie: tutaj jest to prosta funkcja search_documentation przyjmująca zapytanie tekstowe. Pierwsze wywołanie nie oczekuje pisemnej odpowiedzi; oczekuje, że model sformułuje zapytanie, które uzna za stosowne, co избавia Cię od pisania warstwy przeformułowywania.
reference_tool = {
"type": "function",
"function": {
"name": "search_documentation",
"description": "Przeszukuje bazę danych dokumentacji",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Zapytanie wyszukiwania"
}
},
"required": ["query"]
}
}
}
# Pierwsze wywołanie: model prosi o użycie narzędzia
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=[reference_tool]
)
Zwróć wyniki w formacie odniesień
To jest krok strukturalny. Wyniki Twojego silnika wyszukiwania wracają w ToolMessage, którego zawartością jest obiekt odniesienia z poprzedniej lekcji: każde źródło ma numer ("0", "1"…), adres URL, tytuł i wybrane fragmenty. To są numery, których model używa do oznaczania swoich cytowań, a które Twój frontend później rozwiąże w linki.
from mistralai.client.models import ToolMessage
# Wyniki wyszukiwania dokumentacji w formacie odniesień Mistral
references = {
"0": {
"url": "https://docs.example.com/deployment-guide",
"title": "Przewodnik po wdrażaniu LLM",
"snippets": [[
"Zawsze konfiguruj limity szybkości, aby chronić usługę.",
"Ciągle monitoruj opóźnienie P99 i wskaźniki błędów."
]],
"description": None,
"date": "2026-09-01",
"source": "docs"
},
"1": {
"url": "https://docs.example.com/security",
"title": "Bezpieczeństwo aplikacji AI",
"snippets": [[
"Filtruj dane wejściowe użytkowników, aby zapobiec iniekcjom.",
"Nigdy nie udostępniaj kluczy API po stronie klienta."
]],
"description": None,
"date": "2026-08-15",
"source": "docs"
},
"2": {
"url": "https://docs.example.com/scaling",
"title": "Skalowalność i wydajność",
"snippets": [[
"Używaj pamięci podręcznej semantycznej, aby zmniejszyć liczbę wywołań API.",
"Dobieraj rozmiar instancji w oparciu o szczytowy ruch."
]],
"description": None,
"date": "2026-07-20",
"source": "docs"
}
}
# Dodaj wywołanie narzędzia i odpowiedź do historii
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)
)
)
Zauważ, że oryginalna wiadomość modelu jest ponownie wstrzykiwana do historii przed ToolMessage: bez tej pary wywołanie narzędzia / wynik narzędzia, API odmówi kontynuacji. Drugie wywołanie nie potrzebuje już definicji narzędzi, ponieważ wyszukiwanie już miało miejsce.
# Drugie wywołanie: model generuje odpowiedź z cytowaniami
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
Oddziel tekst od odniesień
Odpowiedź z cytowaniami nie jest już prostym ciągiem znaków, lecz sekwencją fragmentów przeplatających prozę i znaczniki cytowań. Parsowanie polega na przejściu przez tę sekwencję i sortowaniu: obiekty TextChunk rekonstruują czytelny tekst, podczas gdy obiekty ReferenceChunk dostarczają faktycznie użyte reference_ids. To rozróżnienie daje Ci cenne informacje: dokładnie które źródła model wykorzystał spośród tych, które dostarczyłeś.
from mistralai.client.models import TextChunk, ReferenceChunk
def parse_cited_response(response):
"""Wyodrębnia tekst i odniesienia z odpowiedzi zawierającej cytowania."""
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("=== Odpowiedź ===")
print(result["text"])
print("\n=== Cytowane źródła ===")
for ref_id in result["references_used"]:
source = references[str(ref_id)]
print(f" - {source['title']} : {source['url']}")
Przygotuj wyświetlanie w frontendzie
Spłaszczenie odpowiedzi do zwykłego tekstu spowodowałoby utratę pozycji cytowań, a tym samym ich wartości. Lepiej jest zachować sekwencję i ją wzbogacić: rozwiąż każdy ReferenceChunk względem tabeli odniesień, aby przenieść tytuł i URL każdego źródła. Twój interfejs otrzymuje w ten sposób uporządkowaną listę bloków, które może renderować jako klikalne linki, dymki lub interaktywne numery cytowań, bez konieczności reinterpretowania tekstu.
def format_for_frontend(response, reference_map):
"""Formatuje odpowiedź z cytowaniami dla frontendu."""
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
Zanim udostępnisz ten potok całej swojej bazie dokumentacji, uruchom go zaledwie z trzema do pięciu źródłami, jak w powyższym przykładzie. Natychmiast zobaczysz, czy model cytuje we właściwym miejscu, czy wykorzystuje wiele dokumentów, czy też systematycznie kurczowo trzyma się pierwszego z nich, co pozwoli Ci skorygować wiadomość systemową, zanim zachowanie to zaginie w gąszczu danych.
Kluczowe wnioski
- Potok realizuje przepływ dwuetapowy: wywołanie narzędzia, a następnie odpowiedź z cytowaniami
- Odniesienia są przekazywane przez
ToolMessage, w obiekcie indeksowanym numerem źródła ("0","1"…) - Odpowiedź zawiera mieszankę
TextChunkiReferenceChunkdo sparsowania - Ustrukturyzuj dane wyjściowe tak, aby Twój frontend mógł wyświetlać interaktywne cytowania
- Przetestuj działanie na 3–5 źródłach przed przejściem do środowiska produkcyjnego