Vai al contenuto principale
Italiano— Scegli una lingua
Menu

XML e Markdown nelle API

Lezione 11 di 16 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Strutturare le istruzioni per il modello
  2. Tag XML per delimitare le sezioni
  3. Markdown per istruzioni leggibili
  4. Combinare entrambi i formati
  5. Un modello di prompt riutilizzabile
  6. Punti chiave

Strutturare le istruzioni per il modello

Finché un prompt sta in tre frasi, il testo semplice funziona bene. I problemi sorgono quando cresce: blocchi di contesto multipli, regole condizionali, dati utente da elaborare, uno schema di output. Tutto si mescola, il modello confonde ciò che deve leggere con ciò che deve applicare e il tuo team perde il filo su quale riga modificare. I tag XML e la sintassi Markdown rispondono a questa doppia esigenza: leggibili per il modello, manutenibili per gli umani. Mistral ne raccomanda esplicitamente l’uso nei prompt di produzione.

La loro efficacia si riduce a una ragione semplice. I modelli linguistici sono stati addestrati su miliardi di documenti contenenti HTML, XML e Markdown; questi formati sono familiari perché compaiono massicciamente nei dati di addestramento. Il modello identifica chiaramente le sezioni e i loro ruoli, mentre tu ottieni un prompt che un collega può verificare a colpo d’occhio.

Tag XML per delimitare le sezioni

L’uso più efficiente dei tag XML consiste nell’isolare i dati dalle istruzioni. Nell’esempio seguente, il prompt di sistema contiene le regole e lo schema atteso; il messaggio dell’utente avvolge il documento in un tag <document>, impedendo al modello di scambiare il contenuto del report per un’istruzione.

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)

In produzione, un piccolo vocabolario di tag ricorre costantemente e trae vantaggio dalla standardizzazione nella tua base di prompt:

<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 per istruzioni leggibili

Il Markdown risponde a un’altra esigenza: gerarchizzare le regole. Mentre l’XML suddivide il prompt in zone, i titoli, le liste e il grassetto del Markdown organizzano il contenuto all’interno di ciascuna zona. Questo prompt di scrittura tecnica colloca così un ruolo, regole di scrittura, una struttura numerata obbligatoria e un elenco di divieti sullo stesso piano visivo: uno scrittore umano potrebbe lavorarci, ed è proprio il test giusto.

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

Combinare entrambi i formati

Per prompt complessi, la pratica più efficace consiste nell’annidare i due formati: l’XML delimita le zone principali, mentre il Markdown struttura l’interno di ciascuna. L’agente di supporto multilingue qui sotto usa <persona> per l’identità e <rules> per il comportamento — con due sottosezioni Markdown all’interno, inclusa una regola di escalation condizionale — e <knowledge_base> per i fatti deperibili, che diventano l’unica parte da aggiornare quando cambia la versione del software.

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 modello di prompt riutilizzabile

Il passo successivo è smettere di scrivere i prompt a mano e iniziare a costruirli. La funzione seguente prende un documento e un elenco di domande, quindi produce i messaggi completi. Due dettagli meritano la tua attenzione: le istruzioni richiedono una citazione giustificativa per ogni risposta e una frase di ripiego esplicita quando l’informazione manca, il che riduce drasticamente le allucinazioni sui documenti contrattuali; e la temperature a 0,1 lascia giusto la flessibilità necessaria per la formulazione senza permettere interpretazioni.

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
)

Alcune abitudini rendono questi prompt durevoli. Dai nomi descrittivi ai tuoi tag: <document> dice cosa contiene, <data> non dice nulla e perderai cinque minuti a ogni revisione. Chiudili sistematicamente: un tag di apertura senza tag di chiusura offusca il confine tra due sezioni e il modello potrebbe poi leggere le tue istruzioni come contenuto da analizzare. Infine, usa l’indentazione per la leggibilità umana; il modello se la cava senza, ma chi riprenderà il prompt tra sei mesi no.

Punti chiave

  • I tag XML isolano i dati dalle istruzioni nel prompt
  • Il Markdown struttura regole ed elenchi per la leggibilità
  • Combina entrambi per prompt complessi in produzione
  • Assegna nomi descrittivi ai tag e chiudili sistematicamente
  • I prompt strutturati sono più facili da mantenere, testare e versionare