Przejdź do głównej treści
Polski— Wybierz język
Menu

XML i Markdown w API

Lekcja 11 z 16 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Strukturyzowanie instrukcji dla modelu
  2. Tagi XML do wydzielania sekcji
  3. Markdown dla czytelnych instrukcji
  4. Łączenie obu formatów
  5. Wielokrotnego użytku szablon promptu
  6. Kluczowe wnioski

Strukturyzowanie instrukcji dla modelu

Dopóki prompt mieści się w trzech zdaniach, zwykły tekst sprawdza się doskonale. Problemy zaczynają się, gdy urasta: wiele bloków kontekstu, reguły warunkowe, dane użytkowe do przetworzenia, schemat wyjścia. Wszystko zlewa się w całość, model myli to, co ma przeczytać, z tym, co ma zastosować, a Twój zespół gubi się, którą linię zmodyfikować. Tagi XML i składnia Markdown odpowiadają na tę podwójną potrzebę: są czytelne dla modelu i łatwe w utrzymaniu dla ludzi. Mistral wyraźnie zaleca ich stosowanie w promptach produkcyjnych.

Ich skuteczność sprowadza się do prostej przyczyny. Modele językowe były trenowane na miliardach dokumentów zawierających HTML, XML i Markdown; formaty te są im znajome, ponieważ występują masowo w danych treningowych. Model wyraźnie identyfikuje sekcje i ich role, podczas gdy Ty otrzymujesz prompt, który kolega może zweryfikować jednym rzutem oka.

Tagi XML do wydzielania sekcji

Najbardziej opłacalnym zastosowaniem tagów XML jest oddzielenie danych od instrukcji. W poniższym przykładzie prompt systemowy zawiera reguły i oczekiwany schemat; wiadomość użytkownika otacza dokument tagiem <document>, zapobiegając pomyłce modelu, który mógłby potraktować treść raportu jako instrukcję.

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)

W środowisku produkcyjnym niewielki słownik tagów powtarza się nieustannie i warto go ustandaryzować w całej bazie promptów:

<instructions>...</instructions>   <!-- Reguły dla modelu -->
<context>...</context>             <!-- Informacje tła -->
<document>...</document>           <!-- Tekst do analizy -->
<examples>...</examples>           <!-- Przykłady few-shot -->
<constraints>...</constraints>     <!-- Ograniczenia i zakazy -->
<output_format>...</output_format> <!-- Oczekiwany format wyjścia -->
<user_data>...</user_data>         <!-- Dane użytkownika -->

Markdown dla czytelnych instrukcji

Markdown odpowiada na inną potrzebę: hierarchizację reguł. Tam gdzie XML dzieli prompt na strefy, nagłówki, listy i pogrubienia w Markdown organizują treść wewnątrz danej strefy. Ten prompt do pisania technicznego umieszcza więc rolę, zasady pisania, obowiązkową strukturę numerowaną i listę zakazów na tej samej płaszczyźnie wizualnej – ludzki pisarz mógłby z tym pracować, a to jest właściwy 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"""

Łączenie obu formatów

W przypadku złożonych promptów najskuteczniejszą praktyką jest zagnieżdżenie obu formatów: XML wyznacza główne strefy, podczas gdy Markdown strukturyzuje wnętrze każdej z nich. Poniższy wielojęzyczny agent wsparcia używa <persona> do tożsamości i <rules> do zachowania – z dwiema podsekcjami Markdown wewnątrz, w tym warunkową regułą eskalacji – oraz <knowledge_base> dla faktów ulotnych, które stają się jedyną częścią wymagającą aktualizacji przy zmianie wersji oprogramowania.

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

Wielokrotnego użytku szablon promptu

Kolejnym krokiem jest zaprzestanie ręcznego pisania promptów i rozpoczęcie ich budowania. Poniższa funkcja przyjmuje dokument i listę pytań, a następnie generuje kompletne wiadomości. Dwa szczegóły zasługują na Twoją uwagę: instrukcje wymagają uzasadniającego cytatu dla każdej odpowiedzi oraz wyraźnej frazy zastępczej, gdy informacje są nieobecne, co drastycznie redukuje halucynacje w dokumentach kontraktowych; natomiast temperature ustawione na 0.1 pozostawia wystarczająco dużo elastyczności dla sformułowań, nie pozwalając jednocześnie na interpretację.

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
)

Kilka nawyków sprawia, że te prompty są trwałe. Nazywaj swoje tagi opisowo – <document> mówi, co zawiera, <data> nie mówi nic i stracisz pięć minut przy każdej recenzji. Zamykaj je systematycznie: otwarty tag bez tagu zamykającego zaciera granicę między dwiema sekcjami, przez co model może potraktować Twoje instrukcje jako treść do analizy. Na koniec stosuj wcięcia dla czytelności ludzkiej; model poradzi sobie bez nich, ale osoba, która przejmie prompt za sześć miesięcy, już nie.

Kluczowe wnioski

  • Tagi XML oddzielają dane od instrukcji w prompcie
  • Markdown strukturyzuje reguły i listy dla lepszej czytelności
  • Łącz oba formaty w złożonych promptach produkcyjnych
  • Nazywaj tagi opisowo i zamykaj je systematycznie
  • Ustrukturyzowane prompty są łatwiejsze w utrzymaniu, testowaniu i wersjonowaniu