XML ja Markdown API:ssa
Tällä sivulla
Ohjeiden jäsentäminen mallille
Niin kauan kuin kehotus mahtuu kolmeen lauseeseen, pelkkä teksti toimii hyvin. Ongelmat alkavat, kun kehotus kasvaa: useita kontekstilohkoja, ehdollisia sääntöjä, käsiteltävää käyttäjädataa ja tulosskeema. Kaikki sekoittuu keskenään, malli sekoittaa sen, mitä sen tulee lukea, siihen, mitä sen tulee soveltaa, ja tiimisi menettää käsityksen siitä, mitä riviä pitäisi muokata. XML-tunnisteet ja Markdown-syntaksi ratkaisevat tämän kaksoistarpeen: ne ovat luettavia mallille ja ylläpidettäviä ihmisille. Mistral suosittelee niiden käyttöä nimenomaan tuotantokehotuksissa.
Niiden tehokkuus perustuu yksinkertaiseen syyhyn. Kielimallit on koulutettu miljardeilla dokumenteilla, jotka sisältävät HTML:ää, XML:ää ja Markdownia; nämä formaatit ovat niille tuttuja, koska niitä esiintyy valtavasti koulutusdatassa. Malli tunnistaa selkeästi osiot ja niiden roolit, kun taas sinä saat kehotuksen, jonka kollegasi voi tarkistaa silmäyksellä.
XML-tunnisteet osioiden rajaamiseen
XML-tunnisteiden kustannustehokkain käyttötapa on datan erottaminen ohjeista. Seuraavassa esimerkissä järjestelmäkehotus sisältää säännöt ja odotetun skeeman; käyttäjäviesti käärii dokumentin <document>-tunnisteeseen, mikä estää mallia sekoittamasta raportin sisältöä ohjeistukseen.
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)
Tuotannossa pieni joukko tunnisteita toistuu jatkuvasti, ja niiden standardointi koko kehotuskannassa kannattaa:
<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 selkeiden ohjeiden laatimiseen
Markdown ratkaisee toisen tarpeen: sääntöjen hierarkisoimisen. Siinä missä XML leikkaa kehotuksen vyöhykkeisiin, Markdownin otsikot, listat ja lihavoinnit järjestävät sisällön kunkin vyöhykkeen sisällä. Tämä teknisen kirjoittamisen kehotus asettaa roolin, kirjoitussäännöt, pakollisen numeroidun rakenteen ja kieltolistauksen samalle visuaaliselle tasolle – ihmiskirjoittaja voisi työskennellä tämän pohjalta, mikä on oikea testi.
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"""
Molempien formaattien yhdistäminen
Monimutkaisissa kehotuksissa tehokkain käytäntö on niiden pesittäminen: XML rajaa päävyöhykkeet, kun taas Markdown jäsentelee kunkin vyöhykkeen sisällön. Alla oleva monikielinen tukiasentti käyttää <persona>-tunnistetta identiteetille ja <rules>-tunnistetta käytökselle – sisällä on kaksi Markdown-aliosiota, mukaan lukien ehdollinen eskalointisääntö – sekä <knowledge_base>-tunnistetta vanhentuville faktoille, jotka ovat ainoa osa, jota tulee päivittää ohjelmistoversion muuttuessa.
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>"""
Uudelleenkäytettävä kehotusmalli
Seuraava askel on lopettaa kehotusten manuaalinen kirjoittaminen ja alkaa rakentaa niitä. Alla oleva funktio ottaa vastaan dokumentin ja kysymyslistan ja tuottaa valmiit viestit. Kaksi yksityiskohtaa ansaitsee huomiosi: ohjeet vaativat perustelevaa lainausta jokaiselle vastaukselle ja eksplisiittistä varalausetta, jos tietoa ei ole, mikä vähentää jyrkästi hallusinaatioita sopimusasiakirjoissa; ja temperature-arvo 0,1 jättää juuri tarpeeksi joustavuutta formulointiin sallimatta tulkintaa.
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
)
Muutama tapa tekee näistä kehotuksista kestäviä. Nimeä tunnisteet kuvaavasti – <document> kertoo, mitä se sisältää, <data> ei kerro mitään, ja hukkaat viisi minuuttia jokaiseen katselmukseen. Sulje ne systemaattisesti: avoin tunniste ilman päättävää tunniste hämärtää rajan kahden osion välillä, jolloin malli saattaa lukea ohjeesi analysoitavana sisältönä. Lopuksi, sisennä ihmisten luettavuuden vuoksi; malli pärjää ilman sitä, mutta henkilö, joka ottaa kehotuksen käsiinsä kuuden kuukauden kuluttua, ei pärjää.
Keskeiset asiat
- XML-tunnisteet erottavat datan ohjeista kehotuksessa
- Markdown jäsentelee säännöt ja listat luettavuuden parantamiseksi
- Yhdistä molemmat monimutkaisissa tuotantokehotuksissa
- Nimeä tunnisteet kuvaavasti ja sulje ne systemaattisesti
- Jäsennellyt kehotukset ovat helpompia ylläpitää, testata ja versioida