XML i Markdown u API-ju
Na ovoj stranici
Strukturiranje uputa za model
Dokle god prompt stane u tri rečenice, običan tekst sasvim dobro funkcionira. Problemi nastaju kada poraste: više blokova konteksta, uvjetna pravila, korisnički podaci za obradu, shema izlaza. Sve se stapa, model zbuni što treba čitati, a što primijeniti, a tvoj tim gubi pregled koji redak modificirati. XML oznake i sintaksa Markdownda rješavaju tu dvostruku potrebu: čitljive za model, održive za ljude. Mistral izričito preporučuje njihovu uporabu u produkcijskim promptovima.
Njihova učinkovitost svodi se na jednostavan razlog. Jezični modeli trenirani su na milijardama dokumenata koji sadrže HTML, XML i Markdown; ti su formati poznati jer se masovno pojavljuju u podacima za obuku. Model jasno identificira sekcije i njihove uloge, dok ti dobivaš prompt koji kolega može provjeriti jednim pogledom.
XML oznake za razgraničenje sekcija
Najisplativija uporaba XML oznaka jest izolacija podataka od uputa. U sljedećem primjeru, sistemski prompt nosi pravila i očekivanu shemu; korisnička poruka omata dokument u oznaku <document>, sprječavajući model da sadržaj izvještaja zamijeni s uputom.
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)
U produkciji se mali rječnik oznaka stalno ponavlja i koristi od standardizacije u cijeloj tvojoj bazi promptova:
<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 čitljive upute
Markdown rješava drugu potrebu: hijerarhizaciju pravila. Dok XML reže prompt na zone, Markdown naslovi, popisi i podebljani tekst organiziraju sadržaj unutar zone. Ovaj prompt za tehničko pisanje tako stavlja ulogu, pravila pisanja, obaveznu numeriranu strukturu i popis zabrana na istu vizualnu razinu – ljudski pisac mogao bi raditi s ovim, što je ispravan 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"""
Kombiniranje obaju formata
Za složene promptove, najučinkovitija je praksa ugnježđivanje oboje: XML razgraničava glavne zone, dok Markdown strukturira unutrašnjost svake. Donji agent za višejezičnu podršku koristi <persona> za identitet i <rules> za ponašanje – s dvije Markdown podsekcije unutra, uključujući uvjetno pravilo eskalacije – te <knowledge_base> za prolazne činjenice, koje postaju jedini dio za ažuriranje kada se verzija softvera promijeni.
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 upotrebljivi predložak prompta
Sljedeći korak jest prestati ručno pisati promptove i početi ih graditi. Funkcija u nastavku prima dokument i popis pitanja, zatim proizvodi kompletne poruke. Dva detalja zaslužuju tvoju pozornost: upute zahtijevaju opravdavajući citat za svaki odgovor i eksplicitnu frazu za slučaj nužde kada informacija nedostaje, što oštro smanjuje halucinacije na ugovornim dokumentima; a temperature na 0,1 ostavlja tek dovoljno fleksibilnosti za formulaciju, ne dopuštajući interpretaciju.
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
)
Nekoliko navika čini ove promptove trajnima. Nazovi svoje oznake opisno – <document> govori što sadrži, <data> ne govori ništa i gubit ćeš pet minuta na svakoj recenziji. Sustavno ih zatvaraj: otvorena oznaka bez zatvarajuće zamućuje granicu između dviju sekcija, pa model može pročitati tvoje upute kao sadržaj za analizu. Konačno, koristi uvlačenje radi ljudske čitljivosti; modelu to ne treba, ali osobi koja preuzima prompt za šest mjeseci hoće.
Ključne točke
- XML oznake izoliraju podatke od uputa u promptu
- Markdown strukturira pravila i popise radi čitljivosti
- Kombiniraj oboje za složene produkcijske promptove
- Nazovi svoje oznake opisno i sustavno ih zatvaraj
- Strukturirani promptovi lakši su za održavanje, testiranje i verzioniranje