Lähe põhisisu juurde
Eesti— Vali keel
Menüü

XML ja Markdown API-s

Õppetund 11 / 16 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Juhiste struktureerimine mudelile
  2. XML-sildid sektsioonide eraldamiseks
  3. Markdown loetavate juhiste jaoks
  4. Mõlema formaadi kombineerimine
  5. Taaskasutatav vihjemall
  6. Peamised punktid

Juhiste struktureerimine mudelile

Niikaua kui vihje mahub kolme lausesse, sobib tavaline tekst suurepäraselt. Probleemid tekivad siis, kui see kasvab: mitu kontekstiplokki, tingimuslikud reeglid, töödeldavad kasutajaandmed, väljundiskeem. Kõik sulandub omavahel, mudel ajab segamini, mida lugeda ja mida rakendada, ning teie meeskond kaotab ülevaate, millist rida muuta. XML-sildid ja Markdowni süntaks lahendavad selle kahekordse vajaduse: need on mudelile loetavad ja inimestele hooldatavad. Mistral soovitab nende kasutamist tootmiskeskkonna vihjetes sõnaselgelt.

Nende tõhusus taandub lihtsale põhjusele. Keelemudeleid on treenitud miljarditel dokumentidel, mis sisaldavad HTML-i, XML-i ja Markdowni; need formaadid on tuttavad, kuna need esinevad treeningandmestikus massiivselt. Mudel tuvastab selgelt sektsioonid ja nende rollid, samas kui sina saad vihje, mida kolleeg saab pilguheituga auditeerida.

XML-sildid sektsioonide eraldamiseks

XML-siltide kõige kulutõhusam kasutusviis on andmete eraldamine juhisteest. Järgmises näites sisaldab süsteemne vihje reegleid ja oodatavat skeemi; kasutaja sõnum pakib dokumendi sildi <document> sisse, takistades mudelil aru saamast, et aruande sisu on juhised.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

system_prompt = """You are a document analysis assistant.

<instructions>
Analyze the provided document and extract the requested information.
Respond only in JSON.
If information is missing, use null.
</instructions>

<output_schema>
{
  "title": "string",
  "author": "string",
  "date": "string (YYYY-MM-DD)",
  "summary": "string (max 100 words)",
  "keywords": ["string"]
}
</output_schema>"""

user_prompt = """<document>
Q1 2026 Quarterly Report — Mistral AI
Written by Arthur Mensch, CEO
Publication date: April 1, 2026

This report presents the results for the first quarter of 2026. The company experienced significant growth in its API business with a 300% increase in daily requests.
</document>

Extract the metadata from this document."""

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_prompt}
    ],
    temperature=0.0
)

print(response.choices[0].message.content)

Tootmiskeskkonnas kordub väike siltide sõnavara pidevalt ja see võidab standardiseerimisest kogu teie vihjete baasis:

<instructions>...</instructions>   <!-- Reeglid mudelile -->
<context>...</context>             <!-- Taustateave -->
<document>...</document>           <!-- Analüüsitav tekst -->
<examples>...</examples>           <!-- Näited (few-shot) -->
<constraints>...</constraints>     <!-- Piirangud ja keelud -->
<output_format>...</output_format> <!-- Oodatav väljundiformaat -->
<user_data>...</user_data>         <!-- Kasutajaandmed -->

Markdown loetavate juhiste jaoks

Markdown lahendab teise vajaduse: reeglite hierarhiseerimise. Kui XML lõikab vihje tsoonideks, siis Markdowni pealkirjad, loendid ja rasvane tekst korrastavad sisu iga tsooni sees. See tehnilise kirjutamise vihje paigutab seega rolli, kirjutamisreeglid, kohustusliku nummerdatud struktuuri ja keelude loendi samale visuaalsele tasandile – inimkirjutaja saaks sellega töötada, mis on õige test.

system_prompt = """# Technical Writing Assistant

## Your role
You write technical documentation for REST APIs.

## Writing rules
- **Use "you"** throughout the text
- Short sentences (max 25 words)
- One concept per paragraph
- Inline code in backticks: `GET /api/v1/users`

## Mandatory structure
1. **Introduction** — Context and objective of the endpoint
2. **Request** — Method, URL, headers, parameters
3. **Response** — HTTP codes, JSON body, examples
4. **Errors** — Possible error codes and resolution

## Prohibitions
- No undefined jargon
- No "simply" or "easily"
- No examples with unrealistic fictional data"""

Mõlema formaadi kombineerimine

Keerukate vihjete puhul on kõige tõhusam tava kahe vormingu pesastamine: XML määratleb peamised tsoonid, samas kui Markdown struktureerib ühe tsooni sisu. Allpool olev mitmekeelne tugiteenuse agent kasutab identiteedi jaoks silti <persona> ja käitumise jaoks silti <rules> – mille sees on kaks Markdowni alajaotust, sealhulgas tingimuslik eskaleerimisreegel – ning silti <knowledge_base> muutuvate faktide jaoks, millest saab ainus osa, mida tarkvara versiooni muutumisel uuendada tuleb.

system_prompt = """# Multilingual Support Agent

<persona>
You are the assistant for DataFlow, an ETL software publisher.
You speak French, English, and Spanish.
</persona>

<rules>
## Behavior rules
- Respond in the user's language
- Identify the problem category: **bug**, **question**, **feature request**
- For bugs: collect software version, OS, exact error message

## Escalation
- If the problem persists after 3 exchanges → propose a support ticket
- If the client mentions data loss → immediate escalation (high priority)
</rules>

<knowledge_base>
- Current version: DataFlow 4.2.1 (April 2026)
- Supported OS: Windows 11, Ubuntu 22.04+, macOS 14+
- Documentation: docs.dataflow.io
</knowledge_base>"""

Taaskasutatav vihjemall

Järgmine samm on käsitsi vihjete kirjutamise lõpetamine ja nende loomise alustamine. Allpool olev funktsioon võtab dokumendi ja küsimuste loendi ning loob seejärel täielikud sõnumid. Kaks detaili väärivad tähelepanu: juhised nõuavad iga vastuse jaoks põhjendavat tsitaati ja selget varulauset juhuks, kui teave puudub, mis vähendab järsult hallutsinatsioone lepingudokumentidel; ja temperature väärtusega 0,1 jätab sõnastamiseks just piisavalt paindlikkust, lubamata tõlgendamist.

def build_analysis_prompt(document: str, questions: list[str]) -> list:
    """Builds a structured analysis prompt using XML."""
    system = """# Document Analyst

<instructions>
Read the provided document and answer the questions asked.
Every answer must cite the part of the document that justifies it.
If the answer is not in the document, reply "Not mentioned in the document."
</instructions>

<output_format>
For each question, respond in this format:
**Q{n}**: [your answer]
> Citation: "[excerpt from document]"
</output_format>"""

    questions_formatted = "\n".join(
        f"{i+1}. {q}" for i, q in enumerate(questions)
    )

    user = f"""<document>
{document}
</document>

<questions>
{questions_formatted}
</questions>"""

    return [
        {"role": "system", "content": system},
        {"role": "user", "content": user}
    ]

# Usage
messages = build_analysis_prompt(
    document="Service agreement contract between...",
    questions=[
        "What is the contract duration?",
        "What are the late payment penalties?",
        "Is there a non-compete clause?"
    ]
)

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    temperature=0.1
)

Mõned harjumused muudavad need vihjed kestvaks. Nimeta oma sildid kirjeldavalt – <document> ütleb, mida see sisaldab, <data> ei ütle midagi ja sa kaotad iga ülevaatuse peale viis minutit. Sulge need süstemaatiliselt: avatud silt ilma sulgeva sildita hägustab kahe sektsiooni vahelist piiri ja mudel võib seejärel lugeda teie juhiseid analüüsitava sisuna. Lõpuks, kasuta taanet inimestele loetavuse huvides; mudel saab selleta hakkama, kuid inimene, kes võtab vihje kuue kuu pärast ette, ei saa.

Peamised punktid

  • XML-sildid eraldavad vihjes andmed juhisteest
  • Markdown struktureerib loetavuse huvides reegleid ja loendeid
  • Kombineeri mõlemat keerukates tootmiskeskkonna vihjetes
  • Nimeta sildid kirjeldavalt ja sulge need süstemaatiliselt
  • Struktureeritud vihjeid on lihtsam hooldada, testida ja versioonida