Przejdź do głównej treści
Polski— Wybierz język
Menu

Implementacja cytowań w Pythonie

Lekcja 9 z 16 Zaktualizowano 3 listopada 2026 Zaawansowany
Na tej stronie
  1. Kompleksowy proces cytowania
  2. Zdefiniuj kontrakt modelu w wiadomości systemowej
  3. Zadeklaruj narzędzie wyszukiwania
  4. Zwróć wyniki w formacie odniesień
  5. Oddziel tekst od odniesień
  6. Przygotuj wyświetlanie w frontendzie
  7. Kluczowe wnioski

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 type ani reference_id – a pola reference_ids w odpowiedzi są rozwiązywane poprzez str(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ę TextChunk i ReferenceChunk do 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