Salt la conținutul principal
Română— Alege o limbă
Meniu

Implementarea citărilor în Python

Lecția 9 din 16 Actualizată 3 noiembrie 2026 Avansat
Pe această pagină
  1. Fluxul complet de citare
  2. Definirea contractului modelului în mesajul de sistem
  3. Declararea instrumentului de căutare
  4. Returnarea rezultatelor în format de referință
  5. Separarea textului de referințe
  6. Pregătirea afișării în frontend
  7. Puncte cheie

Actualizat la 3 noiembrie 2026 pe baza ghidului Mistral Citations & References: rezultatul instrumentului respectă formatul documentat—un obiect indexat după numărul sursei, fără câmpurile type sau reference_id—iar reference_ids din răspuns se rezolvă prin str(ref_id) în cadrul acelui obiect. Sursă: Citations & References.

Fluxul complet de citare

Veți asambla acum un pipeline RAG care își citează sursele, de la primul apel API până la structura de date consumată de interfața dumneavoastră. Rețineți acest principiu fundamental: modelul nu preia niciodată documente direct. El semnalează că are nevoie de o căutare, dumneavoastră executați acea căutare în propria bază de date, iar apoi returnați extrasele împreună cu identificatorii lor. Acest schimb produce un răspuns în care fiecare afirmație rămâne legată de un document real.

Mai exact, un ciclu complet necesită două apeluri către chat.complete. Primul declanșează apelul instrumentului; al doilea generează răspunsul citat odată ce sursele sunt injectate în istoric. Vom parcurge acest ciclu folosind un caz simplu: un asistent de documentație internă întrebat despre cele mai bune practici pentru implementarea unui LLM.

Definirea contractului modelului în mesajul de sistem

Mesajul de sistem stabilește contractul: răspundeți pe baza surselor furnizate, citați sistematic și, mai presus de toate, admiteți când informațiile lipsesc, în loc să completați golurile. Această ultimă instrucțiune face diferența în producție, deoarece răspunsurile tind să devieze la întrebările acoperite insuficient de baza de documentație.

from mistralai.client import Mistral
import json

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

# Mesaj de sistem care încurajează citările
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]

Declararea instrumentului de căutare

Instrumentul descrie cum arată o căutare de documente în sistemul dumneavoastră: aici, o funcție simplă search_documentation care primește o interogare text. Primul apel nu se așteaptă la un răspuns scris; se așteaptă ca modelul să formuleze interogarea pe care o consideră relevantă, scutindu-vă de scrierea unui strat de reformulare.

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

# Primul apel: modelul solicită utilizarea instrumentului
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=[reference_tool]
)

Returnarea rezultatelor în format de referință

Acesta este pasul structural. Rezultatele motorului de căutare revin într-un ToolMessage al cărui conținut este obiectul de referință din lecția anterioară: fiecare sursă are un număr ("0", "1"…), un URL, un titlu și extrasele selectate. Acestea sunt numerele pe care modelul le reutilizează pentru a-și marca citările și pe care frontend-ul dumneavoastră le va rezolva ulterior în link-uri.

from mistralai.client.models import ToolMessage

# Rezultatele căutării în documentație, în formatul de referință 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"
    }
}

# Adăugarea apelului instrumentului și a răspunsului în istoric
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)
    )
)

Rețineți că mesajul original al modelului este reinjectat în istoric înainte de ToolMessage: fără această pereche apel instrument / rezultat instrument, API-ul refuză continuarea. Al doilea apel nu mai are nevoie de definițiile instrumentelor, deoarece căutarea a avut deja loc.

# Al doilea apel: modelul generează un răspuns cu citări
final_response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)

Separarea textului de referințe

Răspunsul citat nu mai este un simplu șir de caractere, ci o secvență de fragmente alternând proza și marcatorii de citare. Analiza implică parcurgerea acestei secvențe și sortarea: obiectele TextChunk reconstruiesc textul lizibil, în timp ce obiectele ReferenceChunk livrează reference_ids utilizați efectiv. Această distincție vă oferă informații valoroase: exact sursele pe care modelul le-a utilizat dintre cele furnizate de dumneavoastră.

from mistralai.client.models import TextChunk, ReferenceChunk

def parse_cited_response(response):
    """Extrage textul și referințele dintr-un răspuns citat."""
    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("=== Răspuns ===")
print(result["text"])
print("\n=== Surse citate ===")
for ref_id in result["references_used"]:
    source = references[str(ref_id)]
    print(f"  - {source['title']} : {source['url']}")

Pregătirea afișării în frontend

Aplatizarea răspunsului în text simplu ar duce la pierderea poziției citărilor și, prin urmare, a valorii lor. Este mai bine să păstrați secvența și să o îmbogățiți: rezolvați fiecare ReferenceChunk față de un tabel de referințe pentru a transporta titlul și URL-ul fiecărei surse. Interfața dumneavoastră primește astfel o listă ordonată de blocuri pe care le poate reda ca link-uri clicabile, tooltip-uri sau numere de citare interactive, fără a fi nevoită să reinterpreteze vreodată textul.

def format_for_frontend(response, reference_map):
    """Formatează răspunsul cu citări pentru frontend."""
    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

Înainte de a deschide acest pipeline către întreaga bază de documentație, rulați-l cu doar trei până la cinci surse, ca în exemplul de mai sus. Veți vedea imediat dacă modelul citează la locul potrivit, dacă valorifică mai multe documente sau dacă se agață sistematic de prima, permițându-vă să corectați mesajul de sistem înainte ca comportamentul să se piardă în volum.

Puncte cheie

  • Pipeline-ul urmează un flux cu două apeluri: apelul instrumentului, apoi răspunsul citat
  • Referințele sunt transmise prin ToolMessage, într-un obiect indexat după numărul sursei ("0", "1"…)
  • Răspunsul conține un amestec de TextChunk și ReferenceChunk de analizat
  • Structurați ieșirea astfel încât frontend-ul să poată afișa citări interactive
  • Testați cu 3–5 surse pentru a valida comportamentul înainte de a trece la producție