Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Įgyvendinti citatas Python kalba

Paskaita 9 iš 16 Atnaujinta 2026 m. lapkričio 3 d. Pažengusiems
Šiame puslapyje
  1. Pilnas citavimo procesas
  2. Apibrėžk modelio sutartį sistemos žinutėje
  3. Deklaruok paieškos įrankį
  4. Grąžink rezultatus nuorodų formatu
  5. Atskirk tekstą nuo nuorodų
  6. Paruošk rodymą sąsajoje
  7. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 3 d. pagal „Mistral“ Citations & References gairę: įrankio rezultatas atitinka dokumentuotą formatą – tai objektas, indeksuojamas pagal šaltinio numerį, be laukų type arba reference_id, o atsakyme esantys reference_ids išsprendžiami naudojant str(ref_id) tame objekte. Šaltinis: Citations & References.

Pilnas citavimo procesas

Dabar surinksi RAG procesą, kuris cituoja savo šaltinius – nuo pirmojo API užklausos iki duomenų struktūros, kurią naudoja tavo sąsaja. Įsimink šį principą: modelis pats niekada neatgauna dokumentų. Jis signalizuoja, kad reikia atlikti paiešką, tu tą paiešką vykdai savo duomenų bazėje, o tada grąžini ištraukas kartu su jų identifikatoriais. Šis dialogas sukuria atsakymą, kuriame kiekvienas teiginys yra susietas su tikru dokumentu.

Konkrečiai, visas ciklas reikalauja dviejų chat.complete užklausų. Pirmoji inicijuoja įrankio iškvietimą; antroji sugeneruoja cituojamą atsakymą, kai šaltiniai įterpiami į istoriją. Peržvelgsime šį ciklą naudodami paprastą atvejį: vidinės dokumentacijos asistentas, kurio klausiama apie geriausią LLM diegimo praktiką.

Apibrėžk modelio sutartį sistemos žinutėje

Sistemos žinutė nustato sutartį: atsakyk remdamasis pateiktais šaltiniais, sistemingai cituok ir, svarbiausia, pripažink, kai informacijos trūksta, užuot bandęs užpildyti spragas. Ši paskutinė instrukcija lemia sėkmę gamybinėje aplinkoje, nes atsakymai linkę nukrypti, kai klausimai yra prastai aprašyti dokumentacijos bazėje.

from mistralai.client import Mistral
import json

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

# Sistemos žinutė, skatinanti citavimą
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]

Deklaruok paieškos įrankį

Įrankis aprašo, kaip tavo sistemoje atrodo dokumentų paieška: šiuo atveju tai paprasta search_documentation funkcija, priimanti tekstinę užklausą. Pirmasis iškvietimas nesitiki rašytinio atsakymo; jis tikisi, kad modelis suformuluos jam aktualią užklausą, taip sutaupydamas tau poreikį rašyti perkėlimo sluoksnį.

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

# Pirmasis iškvietimas: modelis prašo naudoti įrankį
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=[reference_tool]
)

Grąžink rezultatus nuorodų formatu

Tai struktūrinis žingsnis. Tavo paieškos variklio rezultatai grįžta kaip ToolMessage, kurio turinys yra nuorodų objektas iš ankstesnės pamokos: kiekvienas šaltinis turi numerį ("0", "1"…), URL, pavadinimą ir pasirinktas ištraukas. Tai tie numeriai, kuriuos modelis pakartotinai naudoja savo citatoms žymėti, ir kuriuos tavo sąsaja vėliau išspręs į nuorodas.

from mistralai.client.models import ToolMessage

# Dokumentacijos paieškos rezultatai „Mistral“ nuorodų formatu
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"
    }
}

# Įtrauk įrankio iškvietimą ir atsakymą į istoriją
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)
    )
)

Atkreipk dėmesį, kad originalus modelio pranešimas vėl įterpiamas į istoriją prieš ToolMessage: be šios įrankio iškvietimo ir įrankio rezultato poros, API atsisakys tęsti darbą. Antrajam iškvietimui įrankių apibrėžimų daugiau nereikia, nes paieška jau buvo atlikta.

# Antrasis iškvietimas: modelis sugeneruoja atsakymą su citatomis
final_response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)

Atskirk tekstą nuo nuorodų

Cituojamas atsakymas nebėra paprasta eilutė, o fragmentų seka, kurioje kaitaliojasi proza ir citatų žymės. Analizuojant reikia pereiti per šią seką ir rūšiuoti: TextChunk objektai atkuria skaitomą tekstą, o ReferenceChunk objektai pateikia faktiškai naudotus reference_ids. Šis skirtumas suteikia vertingos informacijos: tiksliai žinai, kuriuos šaltinius modelis panaudojo iš tų, kuriuos pateikei.

from mistralai.client.models import TextChunk, ReferenceChunk

def parse_cited_response(response):
    """Ištraukia tekstą ir nuorodas iš cituojamo atsakymo."""
    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']}")

Paruošk rodymą sąsajoje

Atsakymo suplokštinimas į paprastą tekstą prarastų citatų pozicijas, taigi ir jų vertę. Geriau išlaikyti seką ir ją praturtinti: išspręsk kiekvieną ReferenceChunk pagal nuorodų lentelę, kad gautum kiekvieno šaltinio pavadinimą ir URL. Tavo sąsaja taip gauna tvarkingą blokų sąrašą, kurį gali atvaizduoti kaip paspaudžiamas nuorodas, paaiškinimus arba interaktyvius citatų numerius, niekada iš naujo neinterpretuodama teksto.

def format_for_frontend(response, reference_map):
    """Suformatuoja atsakymą su citatomis sąsajai."""
    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

Prieš atverdama šį procesą visai savo dokumentacijos bazei, paleisk jį tik su trimis–penkiais šaltiniais, kaip parodyta pavyzdyje aukščiau. Iškart pamatysi, ar modelis cituoja tinkamoje vietoje, ar naudoja kelis dokumentus, ar sistemingai laikosi tik pirmojo, ir galėsi pakoreguoti sistemos žinutę, kol elgsena nepaskendo dideliame duomenų tūryje.

Svarbiausi punktai

  • Procesas vyksta dviem žingsniais: įrankio iškvietimas, tada cituojamas atsakymas
  • Nuorodos perduodamos per ToolMessage, kaip objektas, indeksuojamas pagal šaltinio numerį ("0", "1"…)
  • Atsakyme yra TextChunk ir ReferenceChunk mišinys, kurį reikia analizuoti
  • Suformuok išvestį taip, kad tavo sąsaja galėtų rodyti interaktyvias citatas
  • Testuok su 3–5 šaltiniais, kad patvirtintum elgseną prieš pereidamas prie gamybinės aplinkos