Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Rozhranie API pre moderovanie od Mistral

Lekcia 5 z 12 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Klasifikácia obsahu po generovaní
  2. Model Mistral Moderation 2
  3. Koncový bod /v1/moderations
  4. Štruktúra odpovede
  5. Moderovanie viacerých textov v dávke
  6. Ochranné zábrany vs. API pre moderovanie: kedy čo použiť
  7. Príklad: kompletný pipeline
  8. Kľúčové poznatky

Aktualizované 3. novembra 2026. Príklad odpovede predtým obsahoval neexistujúce kľúče (hate, violence, unpredictable); teraz odráža jedenásť kategórií z modelu mistral-moderation-2603. Pôvodný finálny pipeline používal vymyslený formát ochranných zábran (enabled) a blokovania detekoval hľadaním reťazca “403” v chybovej správe: teraz nasleduje oficiálny formát a kontroluje e.status_code. Prezentácia modelu sa riadi jeho oficiálnym technickým listom a lekcia predstavuje Shieldstral 1.0, model na moderovanie vo verejnej preview verzii od augusta 2026. Kód overený podľa typov SDK mistralai verzie 3.7.0. Zdroje: Moderation & Guardrailing · Mistral Moderation 2 · Shieldstral 1.0.

Klasifikácia obsahu po generovaní

Ochranné zábrany filtrujú vstupné prompty. Ale čo s obsahom, ktorý model vygeneroval? Neškodný prompt môže viesť k problematickej odpovedi: otázka stredoškoláka o druhej svetovej vojne môže vyústiť do popisu, ktorý nechceš zobrazovať bez varovaní. Presne tu nastupuje rozhranie API pre moderovanie: analyzuje obsah dodatočne a priraďuje rizikové skóre podľa kategórií.

Rozhranie API pre moderovanie je tvoja druhá línia obrany – dopĺňa ochranné zábrany a vytvára tak kompletnú bezpečnostnú architektúru, s jedným zásadným rozdielom: samo nič neblokuje, iba ťa informuje.

Model Mistral Moderation 2

Špecializovaný model na moderovanie sa nazýva mistral-moderation-2603 (Mistral Moderation 2, verzia z marca 2026). Ide o špecializovaný klasifikátor, ktorý sa líši od generatívnych modelov: nepíše text, ale priraďuje skóre. Jeho oficiálny technický list zdôrazňuje kontextové okno s veľkosťou 128 000 tokenov, detekciu prelomenia ochrany (jailbreak) a vysoký výkon pri komplexnom viacjazyčnom obsahu, vrátane dlhých konverzácií. Nahradil model mistral-moderation-2411, ktorý bol vyradený 31. marca 2026.

Hodnotí každý text v 11 kategóriách, pričom každej priraďuje skóre od 0,0 do 1,0. Akceptuje dva režimy vstupu: prostý text alebo konverzačný režim, pričom výber medzi nimi ovplyvňuje kvalitu výsledkov viac, než by si čakal.

Od 4. augusta 2026 existuje v rámci verejnej preview aj druhý model na moderovanie: Shieldstral 1.0. Funguje inak: je kompaktný (3,8 miliardy parametrov) a multimodálny, klasifikuje text a obrázky na základe otázok týkajúcich sa pravidiel formulovaných v prirodzenom jazyku, pričom odpovedá áno alebo nie. Jeho váhy sú zverejnené pod licenciou Apache 2.0, čo umožňuje vlastné hostovanie. Pokiaľ zostáva vo fáze preview, model mistral-moderation-2603 zostáva produkčným modelom a práve ten sa používa pre ochranné zábrany.

Koncový bod /v1/moderations

Režim prostého textu je najjednoduchší: odošleš jeden alebo viacero textov na klasifikáciu bez ďalšieho kontextu.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Moderovanie jednoduchého textu
response = client.classifiers.moderate(
    model="mistral-moderation-2603",
    inputs=["Text to analyze for moderation"]
)

# Prístup k výsledkom
for result in response.results:
    print(f"Categories: {result.categories}")
    print(f"Scores: {result.category_scores}")

Na moderovanie celých výmen, promptu aj odpovede spoločne, poskytuje konverzačný režim klasifikátoru to, čo mu chýbalo: kontext diskusie.

# Moderovanie celej konverzácie
response = client.classifiers.moderate_chat(
    model="mistral-moderation-2603",
    inputs=[
        [
            {"role": "user", "content": "How do I treat a headache?"},
            {"role": "assistant", "content": "Take 1g of paracetamol..."}
        ]
    ]
)

# Klasifikátor vyhodnotí celý kontext
for result in response.results:
    print(f"Health score: {(result.category_scores or {}).get('health', 0)}")

Konverzačný režim, ktorý volá koncový bod /v1/chat/moderations, je to, čo Mistral odporúča pre výmenu názorov: model je trénovaný na klasifikáciu posledného kroku konverzácie s prihliadnutím na tie predchádzajúce. Ak chceš zmoderovať odpoveď svojho asistenta, umiestni ju ako poslednú. Zoznam zoznamov v príklade umožňuje odoslať naraz viacero konverzácií; pre jednu konverzáciu stačí jednoduchý zoznam správ. Ten istý text tak môže dostať odlišné skóre v závislosti od toho, či odpovedá na legitímnu alebo škodlivú otázku – dávkovanie uvedené ako odpoveď na žiadosť o informácie nemá rovnaký status ako rovnaké dávkovanie prepašované do výmeny o rizikovom samoliečení.

Štruktúra odpovede

Pre každý analyzovaný text obsahuje odpoveď dva paralelné bloky: categories, booleovské hodnoty vypočítané s prahmi stanovenými spoločnosťou Mistral na základe jej interného testovacieho súboru, a category_scores, surové skóre od 0,0 do 1,0. Nižšie uvedený príklad je ilustračný so zaokrúhlenými hodnotami; niektoré príklady v dokumentácii stále zobrazujú deväť kategórií starého modelu, kde dangerous_and_criminal_content kombinovalo dangerous a criminal. Použiješ tie druhé, pretože ti umožňujú nastaviť si vlastné hranice.

{
  "id": "mod-abc123",
  "model": "mistral-moderation-2603",
  "results": [
    {
      "categories": {
        "sexual": false,
        "hate_and_discrimination": false,
        "violence_and_threats": false,
        "dangerous": false,
        "criminal": false,
        "selfharm": false,
        "health": true,
        "financial": false,
        "law": false,
        "pii": false,
        "jailbreaking": false
      },
      "category_scores": {
        "sexual": 0.01,
        "hate_and_discrimination": 0.02,
        "violence_and_threats": 0.03,
        "dangerous": 0.02,
        "criminal": 0.01,
        "selfharm": 0.01,
        "health": 0.72,
        "financial": 0.05,
        "law": 0.08,
        "pii": 0.02,
        "jailbreaking": 0.01
      }
    }
  ]
}

V tomto príklade je ako true označená iba kategória health so skóre 0,72. Asistent orientovaný na spotrebiteľa by to vnímal ako signál na blokovanie; nástroj určený pre lekárnikov by ho bez váhania prepustil. To isté skóre, dve opačné rozhodnutia, a presne preto pracuješ so skóre namiesto booleovských hodnôt.

Moderovanie viacerých textov v dávke

API akceptuje viacero textov v jednej požiadavke, čo mení všetko pri dávkovom spracovaní: spätná analýza histórie konverzácie alebo databázy komentárov sa stáva operáciou s prijateľným počtom volaní.

# Moderovanie viacerých textov v jednej požiadavke
texts = [
    "First text to analyze",
    "Second text to analyze",
    "Third text to analyze"
]

response = client.classifiers.moderate(
    model="mistral-moderation-2603",
    inputs=texts
)

# Každý text má svoj vlastný výsledok
for i, result in enumerate(response.results):
    scores = result.category_scores or {}
    max_cat = max(scores, key=lambda c: scores[c])
    max_score = scores[max_cat]
    print(f"Text {i+1}: max score = {max_score:.2f} ({max_cat})")

Ochranné zábrany vs. API pre moderovanie: kedy čo použiť

AspektVlastné ochranné zábranyAPI pre moderovanie
ČasovaniePRED generovanímPO generovaní
AkciaAutomaticky blokuje (403)Vracia skóre (rozhoduješ ty)
KontrolaTvoje prahy na kategóriu, aplikuje MistralSurové skóre, voľná logika
VolanieParameter požiadavky na generovanieSamostatné volanie na /v1/moderations
Prípad použitiaFilter nebezpečných promptovKlasifikácia odpovedí

Príklad: kompletný pipeline

Nižšie uvedený pipeline ukazuje postupnosť oboch mechanizmov. Generovanie je chránené ochrannou zábranou zameranou na prelomenie ochrany (jailbreaking); odpoveď je následne klasifikovaná spolu s otázkou, ktorá ju vyprodukovala, a vlastné rozhodnutie zasahuje hneď, ako skóre presiahne 0,5. Všimni si, že dva kroky vracajú odlišné stavy – blocked_input a blocked_output – takže tvoje logy jasne ukazujú, kde sa požiadavka zastavila.

from mistralai.client import errors
from mistralai.client.models import GuardrailConfigTypedDict

GUARDRAIL_JAILBREAK: list[GuardrailConfigTypedDict] = [
    {
        "block_on_error": True,
        "moderation_llm_v2": {
            "custom_category_thresholds": {"jailbreaking": 0.1},
            "action": "block",
        },
    }
]


def secure_pipeline(user_message: str) -> dict:
    """Pipeline s ochrannými zábranami (vstup) a moderovaním (výstup)."""
    # Krok 1: generovanie s ochrannými zábranami
    try:
        response = client.chat.complete(
            model="mistral-large-latest",
            messages=[{"role": "user", "content": user_message}],
            guardrails=GUARDRAIL_JAILBREAK,
        )
    except errors.SDKError as e:
        if e.status_code == 403:
            return {"status": "blocked_input", "content": None}
        raise

    generated = response.choices[0].message.content
    if not isinstance(generated, str):
        return {"status": "error", "content": None}

    # Krok 2: moderovanie výstupu v kontexte otázky
    moderation = client.classifiers.moderate_chat(
        model="mistral-moderation-2603",
        inputs=[
            {"role": "user", "content": user_message},
            {"role": "assistant", "content": generated},
        ],
    )

    scores = moderation.results[0].category_scores or {}
    if max(scores.values(), default=0.0) > 0.5:
        return {"status": "blocked_output", "scores": scores}

    return {"status": "ok", "content": generated, "scores": scores}

Kľúčové poznatky

  • API pre moderovanie používa model mistral-moderation-2603 na klasifikáciu obsahu
  • Dostupné sú dva režimy: prostý text a konverzačný
  • Skóre sa pohybujú od 0,0 do 1,0 – ty si definuješ vlastné rozhodovacie prahy
  • Konverzačný režim je presnejší, pretože zohľadňuje kontext
  • Kombinuj ochranné zábrany (vstup) + moderovanie (výstup) pre hĺbkovú obranu