Salt la conținutul principal
Română— Alege o limbă
Meniu

XML și Markdown în API

Lecția 11 din 16 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Structurarea instrucțiunilor pentru model
  2. Etichete XML pentru delimitarea secțiunilor
  3. Markdown pentru instrucțiuni lizibile
  4. Combinarea ambelor formate
  5. Un șablon de prompt reutilizabil
  6. Puncte cheie

Structurarea instrucțiunilor pentru model

Atâta timp cât un prompt încap în trei propoziții, textul simplu funcționează perfect. Problemele apar când acesta crește: multiple blocuri de context, reguli condiționale, date de utilizator de procesat, o schemă de ieșire. Totul se amestecă, modelul confundă ce trebuie citit cu ce trebuie aplicat, iar echipa dumneavoastră pierde șirul liniei de modificat. Etichetele XML și sintaxa Markdown răspund acestei duble nevoi: lizibile pentru model, ușor de întreținut pentru oameni. Mistral recomandă în mod explicit utilizarea lor în prompturile de producție.

Eficacitatea lor se reduce la un motiv simplu. Modelele lingvistice au fost antrenate pe miliarde de documente conținând HTML, XML și Markdown; aceste formate le sunt familiare deoarece apar masiv în datele de antrenament. Modelul identifică clar secțiunile și rolurile lor, în timp ce dumneavoastră obțineți un prompt pe care un coleg îl poate audita dintr-o privire.

Etichete XML pentru delimitarea secțiunilor

Cea mai eficientă utilizare a etichetelor XML este izolarea datelor de instrucțiuni. În exemplul următor, promptul de sistem conține regulile și schema așteptată; mesajul utilizatorului încadrează documentul într-o etichetă <document>, împiedicând modelul să confunde conținutul raportului cu o instrucțiune.

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)

În producție, un mic vocabular de etichete revine constant și beneficiază de standardizare în baza dumneavoastră de prompturi:

<instructions>...</instructions>   <!-- Reguli pentru model -->
<context>...</context>             <!-- Informații de context -->
<document>...</document>           <!-- Text de analizat -->
<examples>...</examples>           <!-- Exemple few-shot -->
<constraints>...</constraints>     <!-- Limite și interdicții -->
<output_format>...</output_format> <!-- Format de ieșire așteptat -->
<user_data>...</user_data>         <!-- Datele utilizatorului -->

Markdown pentru instrucțiuni lizibile

Markdown răspunde unei alte nevoi: ierarhizarea regulilor. Unde XML taie promptul în zone, titlurile, listele și textul îngroșat din Markdown organizează conținutul în interiorul unei zone. Acest prompt de redactare tehnică plasează astfel un rol, reguli de scriere, o structură numerotată obligatorie și o listă de interdicții pe același plan vizual – un scriitor uman ar putea lucra cu acesta, ceea ce constituie testul corect.

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"""

Combinarea ambelor formate

Pentru prompturi complexe, cea mai eficientă practică este imbricarea celor două: XML delimitează zonele majore, în timp ce Markdown structurează interiorul fiecăreia. Agentul de suport multilingv de mai jos folosește <persona> pentru identitate și <rules> pentru comportament – cu două subsecțiuni Markdown în interior, inclusiv o regulă de escaladare condiționată – și <knowledge_base> pentru fapte perisabile, care devin singura parte de actualizat atunci când se schimbă versiunea software-ului.

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>"""

Un șablon de prompt reutilizabil

Următorul pas este oprirea scrierii manuale a prompturilor și începerea construirii lor. Funcția de mai jos preia un document și o listă de întrebări, apoi produce mesajele complete. Două detalii merită atenția dumneavoastră: instrucțiunile cer o citare justificativă pentru fiecare răspuns și o frază explicită de rezervă atunci când informația lipsește, ceea ce reduce drastic halucinațiile asupra documentelor contractuale; iar temperature la 0.1 lasă doar suficientă flexibilitate pentru formulare fără a permite interpretarea.

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
)

Câteva obiceiuri fac aceste prompturi durabile. Denumiți etichetele descriptiv – <document> spune ce conține, <data> nu spune nimic și veți pierde cinci minute la fiecare revizuire. Închideți-le sistematic: o etichetă de deschidere fără una de închidere estompează granița dintre două secțiuni, iar modelul ar putea apoi să citească instrucțiunile dumneavoastră ca fiind conținut de analizat. În final, folosiți indentarea pentru lizibilitatea umană; modelul se descurcă și fără ea, dar persoana care va prelua promptul peste șase luni nu o va face.

Puncte cheie

  • Etichetele XML izolează datele de instrucțiuni în prompt
  • Markdown structurează regulile și listele pentru lizibilitate
  • Combinați ambele formate pentru prompturi complexe de producție
  • Denumiți etichetele descriptiv și închideți-le sistematic
  • Prompturile structurate sunt mai ușor de întreținut, testat și versionat