Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Rozhraní API pro moderování od Mistralu

Lekce 5 z 12 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Klasifikace obsahu po vygenerování
  2. Model Mistral Moderation 2
  3. Koncový bod /v1/moderations
  4. Struktura odpovědi
  5. Moderování více textů v dávce
  6. Ochranné zábrany vs. rozhraní API pro moderování: kdy co použít
  7. Příklad: kompletní potrubí
  8. Klíčové poznatky

Aktualizováno 3. listopadu 2026. Příklad odpovědi dříve obsahoval neexistující klíče (hate, violence, unpredictable); nyní odráží jedenáct kategorií z modelu mistral-moderation-2603. Konečné potrubí dříve používalo vymyšlený formát ochranných zábran (enabled) a detekovalo blokování hledáním řetězce „403“ v chybové zprávě: nyní dodržuje oficiální formát a kontroluje e.status_code. Prezentace modelu se řídí jeho oficiálním datovým listem a lekce představuje Shieldstral 1.0, model pro moderování ve veřejné verzi preview od srpna 2026. Kód ověřen proti typům SDK mistralai verze 3.7.0. Zdroje: Moderation & Guardrailing · Mistral Moderation 2 · Shieldstral 1.0.

Klasifikace obsahu po vygenerování

Ochranné zábrany filtrují vstupní prompty. Co ale obsah vygenerovaný modelem? I nevinný prompt může vést k problematické odpovědi: otázka středoškoláka o druhé světové válce může vyústit v popis, který nechceš zobrazit bez varování. Zde přichází na řadu rozhraní API pro moderování: analyzuje obsah dodatečně a přiřazuje riziková skóre podle kategorií.

Rozhraní API pro moderování je tvou druhou linií obrany – doplňuje ochranné zábrany a vytváří tak kompletní bezpečnostní architekturu, s jedním zásadním rozdílem: samo nic neblokuje, pouze tě informuje.

Model Mistral Moderation 2

Specializovaný model pro moderování se jmenuje mistral-moderation-2603 (Mistral Moderation 2, verze z března 2026). Je to specializovaný klasifikátor, odlišný od generativních modelů: nepíše text, ale přiřazuje skóre. Jeho oficiální datový list zdůrazňuje kontextové okno o velikosti 128 000 tokenů, detekci jailbreaku a vysoký výkon u komplexního vícejazyčného obsahu, včetně dlouhých konverzací. Nahrazuje model mistral-moderation-2411, který byl vyřazen 31. března 2026.

Hodnotí každý text v 11 kategoriích, přičemž každá kategorie získá skóre od 0,0 do 1,0. Přijímá dva režimy vstupu: prostý text nebo konverzační, a volba mezi nimi ovlivňuje kvalitu výsledků více, než bys možná čekal.

Od 4. srpna 2026 existuje ve veřejné verzi preview druhý model pro moderování: Shieldstral 1.0. Funguje jinak: je kompaktní (3,8 miliardy parametrů) a multimodální, klasifikuje text i obrázky na základě otázek týkajících se zásad formulovaných v přirozeném jazyce, přičemž odpovídá ano či ne. Jeho váhy jsou publikovány pod licencí Apache 2.0, což umožňuje vlastní hostování. Dokud je ve fázi preview, zůstává mistral-moderation-2603 produkčním modelem a právě ten se používá pro ochranné zábrany.

Koncový bod /v1/moderations

Režim prostého textu je nejjednodušší: odešleš jeden nebo více textů ke klasifikaci bez dalšího kontextu.

from mistralai.client import Mistral
import os

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

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

# Přístup k výsledkům
for result in response.results:
    print(f"Categories: {result.categories}")
    print(f"Scores: {result.category_scores}")

Pro moderování celých výměn, promptu i odpovědi dohromady, poskytuje konverzační režim klasifikátoru to, co mu chybělo: vlákno diskuse.

# Moderování celé konverzace
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 vyhodnocuje celý kontext
for result in response.results:
    print(f"Health score: {(result.category_scores or {}).get('health', 0)}")

Konverzační režim, který volá koncový bod /v1/chat/moderations, je to, co Mistral doporučuje pro výměnu názorů: model je vycvičen tak, aby klasifikoval poslední obrat konverzace s ohledem na ty předchozí. Pokud chceš zmoderovat odpověď svého asistenta, umísti ji jako poslední. Seznam seznamů v příkladu umožňuje odeslat najednou více konverzací; pro jednu konverzaci stačí jednoduchý seznam zpráv. Stejný text tak může získat jiné skóre v závislosti na tom, zda odpovídá na legitimní nebo škodlivou otázku – dávkování uvedené v odpovědi na žádost o informace nemá stejný status jako stejné dávkování proklouzlé do výměny o rizikovém samoléčení.

Struktura odpovědi

Pro každý analyzovaný text obsahuje odpověď dva paralelní bloky: categories, booleany vypočítané s prahovými hodnotami stanovenými Mistralem na základě jeho interní testovací sady, a category_scores, surová skóre od 0,0 do 1,0. Níže uvedený příklad je ilustrativní se zaokrouhlenými hodnotami; některé příklady v dokumentaci stále zobrazují devět kategorií starého modelu, kde dangerous_and_criminal_content kombinovalo dangerous a criminal. Použiješ ty druhé, protože ti umožní nastavit 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 příkladu je jako true označena pouze kategorie health se skóre 0,72. Asistent orientovaný na spotřebitele by to považoval za signál k blokování; nástroj určený pro farmaceuty by ho bez váhání propustil. Stejné skóre, dvě opačná rozhodnutí, a přesně proto pracuješ se skóremi místo s booleany.

Moderování více textů v dávce

API přijímá více textů v jedné žádosti, což mění vše pro dávkové zpracování: retroaktivní analýza historie konverzace nebo databáze komentářů se stává operací s rozumným počtem volání.

# Moderování více textů v jedné žádosti
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á svůj vlastní výsledek
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. rozhraní API pro moderování: kdy co použít

AspektVlastní ochranné zábranyRozhraní API pro moderování
ČasováníPŘED generovánímPO generování
AkceAutomaticky blokuje (403)Vrací skóre (rozhoduješ ty)
KontrolaTvé prahové hodnoty na kategorii, aplikované MistralemSurová skóre, volná logika
VoláníParametr žádosti o generováníSamostatné volání na /v1/moderations
Případ použitíFiltrace nebezpečních promptůKlasifikace odpovědí

Příklad: kompletní potrubí

Následující potrubí ukazuje sekvenování obou mechanismů. Generování je chráněno ochrannou zábranou zaměřenou na jailbreaking; odpověď je následně klasifikována společně s otázkou, která ji vyprodukovala, a vlastní rozhodnutí zasáhne, jakmile některé skóre překročí 0,5. Všimni si, že dva kroky vracejí odlišné stavy – blocked_input a blocked_output – takže tvé logy jasně ukazují, kde žádost skončila.

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:
    """Potrubí s ochrannými zábranami (vstup) a moderováním (výstup)."""
    # Krok 1: generování 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: moderování výstupu v kontextu 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}

Klíčové poznatky

  • Rozhraní API pro moderování používá model mistral-moderation-2603 ke klasifikaci obsahu
  • K dispozici jsou dva režimy: prostý text a konverzační
  • Skóre se pohybují od 0,0 do 1,0 – ty definuješ vlastní rozhodovací prahy
  • Konverzační režim je přesnější, protože zohledňuje kontext
  • Kombinuj ochranné zábrany (vstup) + moderování (výstup) pro hloubkovou obranu