Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

XML agus Markdown san API

Ceacht 11 as 16 Nuashonraithe 2 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Do chuid treoracha a struchtúrú don mhúnla
  2. Clibeanna XML chun rannáin a theorannú
  3. Markdown le haghaidh treoracha inléite
  4. An dá fhormáid a chomhcheangal
  5. Teimpléad leide in-athúsáidte
  6. Príomhphointí

Do chuid treoracha a struchtúrú don mhúnla

Fad is a fheileann leid i dtrí abairt, oibreoidh gnáth-théacs go maith. Tagann fadhbanna chun cinn nuair a fhásann sé: blocanna comhthéacs iolracha, rialacha coinníollacha, sonraí úsáideora le próiseáil, scéama aschuir. Meascann gach rud le chéile, déanann an múnla botún idir an méid atá le léamh agus an méid atá le cur i bhfeidhm, agus cailleann do fhoireann an t-rian ar an líne atá le hathrú. Freagraíonn clibeanna XML agus comhréir Markdown don ghá dhúbailte seo: inléite don mhúnla, inchothabhála do dhaoine. Molann Mistral go sonrach a n-úsáid i leideanna táirgeachta.

Tagann a n-éifeachtacht anuas ar chúis shimplí. Oileadh samhlacha teanga ar bhilliúin doiciméad ina raibh HTML, XML, agus Markdown; tá na formáidí seo eolach toisc go bhfuil siad le feiceáil go forleathan i sonraí oiliúna. Aithníonn an múnla go soiléir na rannáin agus a ról, agus faigheann tusa leid is féidir le comhghleacaí a iniúchadh ag amharc amháin.

Clibeanna XML chun rannáin a theorannú

Is é an úsáid is cost-éifeachtaí a bhaintear as clibeanna XML ná sonraí a scaradh ó threoracha. Sa sampla seo a leanas, iompraíonn an leid córais na rialacha agus an scéama a bhfuiltear ag súil leis; cuimsíonn teachtaireacht an úsáideora an doiciméad i gclib <document>, rud a choscann ar an múnla ábhar na tuairisce a mheascadh suas le treoir.

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)

I dtáirgeadh, filltear ar stór focal beag clibeanna go minic agus baineann sé tairbhe as caighdeánú ar fud do bhunáit leideanna:

<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 le haghaidh treoracha inléite

Freagraíonn Markdown ar ghá eile: rialacha a chéimniú. Áit a ndéanann XML gearradh ar an leid ina chriosanna, eagraíonn ceanntásca, liostaí, agus téacs trom Markdown an t-ábhar laistigh de chrios. Cuirtear ról, rialacha scríbhneoireachta, struchtúr uimhrithe éigeantach, agus liosta toirmeasc ar an bplána amhairc céanna sa leid scríbhneoireachta teicniúla seo—d’fhéadfadh scríbhneoir daonna oibriú leis seo, agus sin an tástáil cheart.

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

An dá fhormáid a chomhcheangal

I gcás leideanna casta, is é an cleachtas is éifeachtaí ná an dá cheann a neadú: teorannaíonn XML na príomhchriosanna, agus struchtúraíonn Markdown inmheánach gach ceann acu. Úsáideann an gníomhaire tacaíochta ilteangach thíos <persona> don aitheantas agus <rules> don iompar—le dhá fho-rannán Markdown laistigh, lena n-áirítear riail éalaithe coinníollaí—agus <knowledge_base> do fhíricí tréimhsiúla, a éiríonn mar an t-aon chuid atá le nuashonrú nuair a athraíonn leagan an bhogearra.

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

Teimpléad leide in-athúsáidte

Is é an chéad chéim eile ná stop a chur le scríobh láimhe leideanna agus tosú á dtógáil. Glacann an fheidhm thíos le doiciméad agus liosta ceisteanna, agus déanann sí na teachtaireachtaí iomlána a tháirgeadh. Tá dhá shonraí ar fiú d’aird a thabhairt orthu: éilíonn na treoracha luachan údaraithe do gach freagra agus frása cúltaca sainráite nuair nach bhfuil eolas ann, rud a laghdaíonn go géar hallúicináisiúin ar dhoiciméid chonarthacha; agus fágann an temperature ag 0.1 díreach dóthain solúbthachta don fhráseáil gan léirmhíniú a cheadú.

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
)

Déanann roinnt nósanna na leideanna seo marthanach. Ainmnigh do chlibeanna go cur síosach—deir <document> cad atá ann, ní deir <data> tada agus caillfidh tú cúig nóiméad ar gach athbhreithniú. Dún iad go córasach: doiléiríonn clib oscailte gan clib dhúnta an teorainn idir dhá rannán, agus d’fhéadfadh an múnla do chuid treoracha a léamh mar ábhar le hanailísiú ansin. Ar deireadh, déan eangú d’inléiteacht dhaonna; déanann an múnla go maith gan é, ach ní dhéanfaidh an duine a ghlacfaidh leis an leid i gceann sé mhí.

Príomhphointí

  • Scarann clibeanna XML sonraí ó threoracha sa leid
  • Struchtúraíonn Markdown rialacha agus liostaí d’inléiteacht
  • Comhcheangail an dá cheann le haghaidh leideanna casta táirgeachta
  • Ainmnigh do chlibeanna go cur síosach agus dún iad go córasach
  • Tá leideanna struchtúrtha níos fusa a chothabháil, a thástáil, agus a leaganú