XML in Markdown v API-ju
Na tej strani
Strukturiranje navodil za model
Dokler se poziv ujame v tri stavke, navadno besedilo deluje brez težav. Težave nastopijo, ko se razširi: več blokov konteksta, pogojna pravila, uporabniški podatki za obdelavo, shema izhoda. Vse se zmeša, model zamenja, kaj naj prebere in kaj naj uporabi, tvoja ekipa pa izgubi sled, katero vrstico spremeniti. Oznake XML in skladnja Markdown naslavljata to dvojno potrebo: berljivo za model, vzdrževljivo za ljudi. Mistral izrecno priporoča njuno uporabo v produkcijskih pozivih.
Njuna učinkovitost izhaja iz preprostega razloga. Jezikovni modeli so bili usposobljeni na milijardah dokumentov, ki vsebujejo HTML, XML in Markdown; te oblike so jim znane, ker se v učnih podatkih pojavljajo množično. Model jasno prepozna razdelke in njihove vloge, ti pa dobiš poziv, ki ga lahko kolega pregleda na prvi pogled.
Oznake XML za razmejevanje razdelkov
Najbolj stroškovno učinkovita uporaba oznak XML je izolacija podatkov od navodil. V naslednjem primeru sistemski poziv nosi pravila in pričakovano shemo; uporabniško sporočilo ovije dokument v oznako <document>, s čimer prepreči, da bi model zamenjal vsebino poročila z navodilom.
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)
V produkciji se majhen besednjak oznak nenehno ponavlja in ima korist od standardizacije v tvoji zbirki pozivov:
<instructions>...</instructions> <!-- Rules for the model -->
<context>...</context> <!-- Background information -->
<document>...</document> <!-- Text to analyze -->
<examples>...</examples> <!-- Few-shot examples -->
<constraints>...</constraints> <!-- Limits and prohibitions -->
<output_format>...</output_format> <!-- Expected output format -->
<user_data>...</user_data> <!-- User data -->
Markdown za berljiva navodila
Markdown naslavlja drugo potrebo: hierarhijo pravil. Kjer XML razreže poziv na cone, naslovi, seznami in krepko besedilo v Markdownu organizirajo vsebino znotraj cone. Ta poziv za tehnično pisanje tako postavi vlogo, pravila pisanja, obvezno oštevilčeno strukturo in seznam prepovedi na isto vizualno raven – s tem bi lahko delal človeški pisec, kar je pravi 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"""
Kombinacija obeh formatov
Za kompleksne pozive je najučinkovitejša praksa gnezdenje obeh: XML razmejuje glavne cone, Markdown pa strukturira notranjost vsake. Spodnji večjezični podporni agent uporablja <persona> za identiteto in <rules> za vedenje – z dvema podrazdelkoma Markdown znotraj, vključno s pogojnim pravilom za eskalacijo – ter <knowledge_base> za dejstva s kratko življenjsko dobo, ki postanejo edini del, ki ga je treba posodobiti ob spremembi različice programske opreme.
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>"""
Ponovno uporabna predloga za pozive
Naslednji korak je prenehanje ročnega pisanja pozivov in začetek njihovega gradnje. Spodnja funkcija prejme dokument in seznam vprašanj, nato pa ustvari celotna sporočila. Dve podrobnosti si zaslužita tvojo pozornost: navodila zahtevajo utemeljitveni citat za vsak odgovor in izrecno frazo za nadomestilo, ko informacija manjka, kar ostro zmanjša halucinacije pri pogodbenih dokumentih; temperatura (temperature) nastavljena na 0,1 pa pušča ravno dovolj prožnosti za formulacijo, ne da bi dovoljevala interpretacijo.
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
)
Nekaj navad naredi te pozive trajne. Poimenuj svoje oznake opisno – <document> pove, kaj vsebuje, <data> ne pove nič in ob vsakem pregledu boš zapravil pet minut. Sistematično jih zapiraj: odprta oznaka brez zaključne oznake zabriše mejo med dvema razdelkoma in model lahko nato tvoja navodila prebere kot vsebino za analizo. Nazadnje, uporabi zamike za človeško berljivost; model se brez njih dobro znajde, oseba, ki bo poziv prevzela čez šest mesecev, pa ne.
Ključne ugotovitve
- Oznake XML izolirajo podatke od navodil v pozivu
- Markdown strukturira pravila in sezname za berljivost
- Združi oboje za kompleksne produkcijske pozive
- Poimenuj oznake opisno in jih sistematično zapiraj
- Strukturirani pozivi so lažji za vzdrževanje, testiranje in različičenje