Ir para o conteúdo principal
Português— Escolher um idioma
Menu

XML e Markdown na API

Aula 11 de 16 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Estruturação das suas instruções para o modelo
  2. Etiquetas XML para delimitar secções
  3. Markdown para instruções legíveis
  4. Combinação de ambos os formatos
  5. Um modelo de prompt reutilizável
  6. Pontos-chave

Estruturação das suas instruções para o modelo

Enquanto um prompt couber em três frases, o texto simples funciona bem. Os problemas surgem quando ele cresce: múltiplos blocos de contexto, regras condicionais, dados de utilizador para processar, um esquema de saída. Tudo se mistura, o modelo confunde o que deve ler com o que deve aplicar, e a sua equipa perde a noção de qual linha modificar. As etiquetas XML e a sintaxe Markdown respondem a esta necessidade dupla: legíveis para o modelo, sustentáveis para os humanos. A Mistral recomenda explicitamente a sua utilização em prompts de produção.

A sua eficácia resume-se a uma razão simples. Os modelos de linguagem foram treinados em milhares de milhões de documentos contendo HTML, XML e Markdown; estes formatos são familiares porque aparecem massivamente nos dados de treino. O modelo identifica claramente as secções e as suas funções, enquanto você obtém um prompt que um colega pode auditar num relance.

Etiquetas XML para delimitar secções

A utilização mais rentável das etiquetas XML é isolar os dados das instruções. No exemplo seguinte, o prompt do sistema contém as regras e o esquema esperado; a mensagem do utilizador envolve o documento numa etiqueta <document>, impedindo o modelo de confundir o conteúdo do relatório com uma instrução.

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)

Em produção, um pequeno vocabulário de etiquetas repete-se constantemente e beneficia de uma padronização na sua base de prompts:

<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 para instruções legíveis

O Markdown responde a outra necessidade: hierarquizar regras. Onde o XML divide o prompt em zonas, os títulos, listas e texto a negrito do Markdown organizam o conteúdo dentro de uma zona. Este prompt de escrita técnica coloca assim um papel, regras de escrita, uma estrutura numerada obrigatória e uma lista de proibições no mesmo plano visual — um escritor humano poderia trabalhar com isto, que é o teste correto.

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

Combinação de ambos os formatos

Para prompts complexos, a prática mais eficaz é aninhar os dois: o XML delimita as grandes zonas, enquanto o Markdown estrutura o interior de cada uma. O agente de suporte multilingue abaixo utiliza <persona> para a identidade e <rules> para o comportamento — com duas subsecções Markdown no interior, incluindo uma regra de escalonamento condicional — e <knowledge_base> para factos perecíveis, que se tornam a única parte a atualizar quando a versão do software muda.

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

Um modelo de prompt reutilizável

O próximo passo é deixar de escrever prompts manualmente e começar a construí-los. A função abaixo recebe um documento e uma lista de perguntas, produzindo depois as mensagens completas. Dois detalhes merecem a sua atenção: as instruções exigem uma citação justificativa para cada resposta e uma frase de fallback explícita quando a informação está ausente, o que reduz drasticamente as alucinações em documentos contratuais; e a temperature em 0,1 deixa flexibilidade suficiente para a formulação sem permitir interpretação.

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
)

Alguns hábitos tornam estes prompts duradouros. Nomeie as suas etiquetas de forma descritiva — <document> diz o que contém, <data> não diz nada e você perderá cinco minutos em cada revisão. Feche-as sistematicamente: uma etiqueta de abertura sem uma de fecho desfoca a fronteira entre duas secções, e o modelo pode então ler as suas instruções como conteúdo a analisar. Por fim, utilize a indentação para legibilidade humana; o modelo desenrasca-se sem ela, mas a pessoa que retomar o prompt daqui a seis meses não conseguirá.

Pontos-chave

  • As etiquetas XML isolam os dados das instruções no prompt
  • O Markdown estrutura regras e listas para legibilidade
  • Combine ambos para prompts complexos de produção
  • Nomeie as suas etiquetas de forma descritiva e feche-as sistematicamente
  • Prompts estruturados são mais fáceis de manter, testar e versionar