Премини към основното съдържание
Български— Изберете език
Меню

XML и Markdown в API

Урок 11 от 16 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Структуриране на инструкциите за модела
  2. XML тагове за разграничаване на секции
  3. Markdown за четими инструкции
  4. Комбиниране на двата формата
  5. Многоразова шаблонна подсказка
  6. Ключови изводи

Структуриране на инструкциите за модела

Докато подсказката се събира в три изречения, обикновеният текст работи отлично. Проблемите възникват, когато тя нарасне: множество блокове с контекст, условни правила, потребителски данни за обработка, схема на изхода. Всичко се слива, моделът обърква какво да прочете с какво да приложи, а екипът Ви губи представа кой ред да промени. XML тагове и синтаксисът на Markdown решават тази двойна нужда: четими за модела, поддържаеми за хората. Mistral изрично препоръчва използването им в производствени подсказки.

Ефективността им се свежда до една проста причина. Езиковите модели са обучени върху милиарди документи, съдържащи HTML, XML и Markdown; тези формати са познати, защото се срещат масово в обучаващите данни. Моделът ясно идентифицира секциите и техните роли, докато Вие получавате подсказка, която колега може да одитира с един поглед.

XML тагове за разграничаване на секции

Най-рентабилното използване на XML тагове е изолирането на данни от инструкции. В следващия пример системната подсказка носи правилата и очакваната схема; съобщението на потребителя обгръща документа в таг <document>, предотвратявайки объркването на съдържанието на доклада с инструкция от страна на модела.

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)

В производствена среда малък речник от тагове се повтаря постоянно и се възползва от стандартизация във Вашата база с подсказки:

<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 за четими инструкции

Markdown отговаря на друга нужда: йерархизиране на правилата. Докато XML разделя подсказката на зони, заглавията, списъците и удебеленият текст в Markdown организират съдържанието вътре в зоната. Тази подсказка за техническо писане поставя роля, правила за писане, задължителна номерирана структура и списък със забрани на една и съща визуална равнина – човешки писател би могъл да работи с това, което е правилният тест.

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

Комбиниране на двата формата

За сложни подсказки най-ефективната практика е влагането на двете: XML разграничава основните зони, докато Markdown структурира вътрешността на всяка от тях. Агентът за многоезична поддръжка по-долу използва <persona> за идентичност и <rules> за поведение – с две Markdown подсекции вътре, включително правило за условно ескалиране – и <knowledge_base> за преходни факти, които стават единствената част за актуализиране при промяна на версията на софтуера.

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

Многоразова шаблонна подсказка

Следващата стъпка е да спрете ръчното писане на подсказки и да започнете да ги изграждате. Функцията по-долу приема документ и списък с въпроси, след което генерира пълните съобщения. Два детайла заслужават вниманието Ви: инструкциите изискват обосноваващ цитат за всеки отговор и изрична фраза за резервен вариант, когато информация липсва, което рязко намалява халюцинациите при договорни документи; а temperature стойност 0.1 оставя точно достатъчно гъвкавост за формулировките, без да позволява тълкуване.

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
)

Няколко навика правят тези подсказки дълготрайни. Именувайте таговете си описателно – <document> казва какво съдържа, <data> не казва нищо и ще губите по пет минути при всяка проверка. Затваряйте ги систематично: отворен таг без затварящ размива границата между две секции и моделът може да прочете инструкциите Ви като съдържание за анализ. Накрая, използвайте отстъпи за човешка четимост; моделът се справя добре без тях, но човекът, който ще поеме подсказката след шест месеца, няма да може.

Ключови изводи

  • XML таговете изолират данните от инструкциите в подсказката
  • Markdown структурира правилата и списъците за по-добра четимост
  • Комбинирайте и двете за сложни производствени подсказки
  • Именувайте таговете си описателно и ги затваряйте систематично
  • Структурираните подсказки са по-лесни за поддръжка, тестване и версиониране