XML un Markdown API
Šajā lapā
Instrukciju strukturēšana modelim
Kamēr pieprasījums ietilpst trīs teikumos, parasts teksts darbojas lieliski. Problēmas rodas, kad tas aug: vairāki konteksta bloki, nosacīti noteikumi, apstrādājami lietotāja dati, izvades shēma. Viss sajaucas kopā, models nesaprot, kas ir jālasa un kas jāpiemēro, un tava komanda zaudē pavedienu, kuru rindu mainīt. XML tagi un Markdown sintakse risina šo divkāršo vajadzību: lasāmi modelim un uzturami cilvēkiem. Mistral tieši iesaka to izmantošanu ražošanas pieprasījumos.
To efektivitāte slēpjas vienkāršā iemeslā. Valodu modeļi tika apmācīti uz miljardiem dokumentu, kas satur HTML, XML un Markdown; šie formāti tiem ir pazīstami, jo masveidā parādās apmācības datos. Models skaidri identificē sadaļas un to lomas, savukārt tu iegūsti pieprasījumu, ko kolēģis var pārbaudīt acumirklī.
XML tagi sadaļu norobežošanai
Efektīvākais XML tagu pielietojums ir datu atdalīšana no instrukcijām. Tālāk redzamajā piemērā sistēmas pieprasījums satur noteikumus un paredzēto shēmu; lietotāja ziņojums ietver dokumentu <document> tagā, novēršot modeļa kļūdu, kurā tas ziņojuma saturu sajauktu ar instrukciju.
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)
Ražošanas vidē neliels tagu vārdu krājums atkārtojas nepārtraukti, un to standartizēšana visā pieprasījumu bāzē ir izdevīga:
<instructions>...</instructions> <!-- Noteikumi modelim -->
<context>...</context> <!-- Fona informācija -->
<document>...</document> <!-- Analizējamais teksts -->
<examples>...</examples> <!-- Dažu piemēru (few-shot) paraugi -->
<constraints>...</constraints> <!-- Ierobežojumi un aizliegumi -->
<output_format>...</output_format> <!-- Paredzētais izvades formāts -->
<user_data>...</user_data> <!-- Lietotāja dati -->
Markdown lasāmām instrukcijām
Markdown risina citu vajadzību: noteikumu hierarhizēšanu. Ja XML sadala pieprasījumu zonās, tad Markdown virsraksti, saraksti un treknraksts organizē saturu katras zonas iekšienē. Šis tehniskās rakstīšanas pieprasījums tādējādi izvieto lomu, rakstīšanas noteikumus, obligātu numurētu struktūru un aizliegumu sarakstu vienā vizuālajā plaknē — ar to varētu strādāt cilvēks-rakstnieks, un tas ir īstais pārbaudījums.
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"""
Abu formātu kombinēšana
Sarežģītiem pieprasījumiem visefektīvākā prakse ir abu ligzdošana: XML norobežo galvenās zonas, bet Markdown strukturē katras zonas iekšieni. Tālāk redzamais daudzvalodu atbalsta aģents izmanto <persona> identitātei un <rules> uzvedībai — ar divām Markdown apakšnodaļām iekšpusē, tostarp nosacītu eskalācijas noteikumu — un <knowledge_base> pārejošiem faktiem, kas kļūst par vienīgo daļu, kas jāatjaunina, mainoties programmatūras versijai.
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>"""
Atkārtoti izmantojama pieprasījuma veidne
Nākamais solis ir pārtraukt pieprasījumu rakstīšanu ar roku un sākt tos būvēt. Tālāk redzamā funkcija paņem dokumentu un jautājumu sarakstu, pēc tam ģenerē pilnus ziņojumus. Divas detaļas ir pelnījušas tavu uzmanību: instrukcijas pieprasa pamatojošu citātu katrai atbildei un skaidru rezerves frāzi, ja informācijas nav, kas krasi samazina halucinācijas līgumdokumentos; un temperature iestatījums 0.1 līmenī nodrošina tieši pietiekamu elastību formulējumam, neļaujot interpretācijām novirzīties.
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
)
Daži ieradumi padara šos pieprasījumus ilgtspējīgus. Nosauc savus tagus aprakstoši — <document> norāda, ko tas satur, <data> nepasaka neko, un tu zaudēsi piecas minūtes katrā pārskatīšanā. Aizver tos sistemātiski: atvērts tags bez aizveroša taga izpludina robežu starp divām sadaļām, un models tad var nolasīt tavas instrukcijas kā saturu, kas jāanalizē. Visbeidzot, izmanto atkāpes cilvēka lasāmībai; models tiek galā arī bez tām, bet cilvēks, kurš paņems šo pieprasījumu pēc sešiem mēnešiem, vairs netiks galā.
Galvenās atziņas
- XML tagi pieprasījumā atdala datus no instrukcijām
- Markdown strukturē noteikumus un sarakstus lasāmībai
- Kombinē abus formātus sarežģītiem ražošanas pieprasījumiem
- Nosauc savus tagus aprakstoši un aizver tos sistemātiski
- Strukturēti pieprasījumi ir vieglāk uzturami, testējami un versionējami