Rozhranie API pre moderovanie od Mistral
Na tejto strane
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 modelumistral-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 kontrolujee.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 SDKmistralaiverzie 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ť
| Aspekt | Vlastné ochranné zábrany | API pre moderovanie |
|---|---|---|
| Časovanie | PRED generovaním | PO generovaní |
| Akcia | Automaticky blokuje (403) | Vracia skóre (rozhoduješ ty) |
| Kontrola | Tvoje prahy na kategóriu, aplikuje Mistral | Surové skóre, voľná logika |
| Volanie | Parameter požiadavky na generovanie | Samostatné volanie na /v1/moderations |
| Prípad použitia | Filter nebezpečných promptov | Klasifiká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-2603na 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