Przejdź do głównej treści
Polski— Wybierz język
Menu

API moderacji Mistral

Lekcja 5 z 12 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Klasyfikuj treści po wygenerowaniu
  2. Model Mistral Moderation 2
  3. Punkt końcowy /v1/moderations
  4. Struktura odpowiedzi
  5. Moderuj wiele tekstów wsadowo
  6. Guardraile kontra API moderacji: kiedy czego użyć
  7. Przykład: kompletny potok
  8. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. Przykład odpowiedzi zawierał wcześniej nieistniejące klucze (hate, violence, unpredictable); obecnie odzwierciedla jedenaście kategorii z modelu mistral-moderation-2603. Końcowy potok używał wcześniej wymyślonego formatu guardraili (enabled) i wykrywał blokady, szukając „403“ w komunikacie o błędzie: teraz stosuje oficjalny format i sprawdza e.status_code. Prezentacja modelu jest zgodna z jego oficjalną kartą danych, a lekcja wprowadza Shieldstral 1.0, model moderacji będący od sierpnia 2026 r. w wersji publicznej zapowiedzi (public preview). Kod zweryfikowany pod kątem typów SDK mistralai w wersji 3.7.0. Źródła: Moderation & Guardrailing · Mistral Moderation 2 · Shieldstral 1.0.

Klasyfikuj treści po wygenerowaniu

Guardraile filtrują prompty wejściowe. A co z treściami wygenerowanymi przez model? Niewinne pytanie może skutkować problematyczną odpowiedzią: zapytanie ucznia szkoły podstawowej o II wojnę światową może wywołać opis, którego nie chcesz wyświetlać bez zastrzeżeń. Tu właśnie wkracza API moderacji: analizuje treść post factum i przypisuje wyniki ryzyka w podziale na kategorie.

API moderacji to twoja druga linia obrony – uzupełnia guardraile, tworząc kompletną architekturę bezpieczeństwa, z jedną istotną różnicą: samo w sobie niczego nie blokuje, lecz cię informuje.

Model Mistral Moderation 2

Dedykowany model moderacji to mistral-moderation-2603 (Mistral Moderation 2, wersja z marca 2026 r.). Jest to wyspecjalizowany klasyfikator, odrębny od modeli generatywnych: nie pisze tekstu, lecz przypisuje wyniki. Jego oficjalna karta danych podkreśla okno kontekstowe o wielkości 128 000 tokenów, wykrywanie prób ominięcia zabezpieczeń (jailbreak) oraz wysoką skuteczność w przypadku złożonych treści wielojęzycznych, w tym długich rozmów. Zastępuje on model mistral-moderation-2411, który został wycofany 31 marca 2026 r.

Ocenia każdy tekst w 11 kategoriach, przyznając wynik od 0,0 do 1,0 dla każdej z nich. Akceptuje dwa tryby wejścia: zwykły tekst lub konwersacyjny, a wybór między nimi wpływa na jakość wyników bardziej, niż mogłoby się wydawać.

Od 4 sierpnia 2026 r. istnieje drugi model moderacji w wersji publicznej zapowiedzi (public preview): Shieldstral 1.0. Działa inaczej: jest kompaktowy (3,8 miliarda parametrów) i multimodalny; klasyfikuje teksty i obrazy na podstawie pytań dotyczących polityki sformułowanych w języku naturalnym, odpowiadając „tak“ lub „nie“. Jego wagi są publikowane na licencji Apache 2.0, co umożliwia samodzielny hosting. Dopóki pozostaje w fazie zapowiedzi, mistral-moderation-2603 pozostaje modelem produkcyjnym i to jego używa się do guardraili.

Punkt końcowy /v1/moderations

Tryb zwykłego tekstu jest najprostszy: wysyłasz jeden lub więcej tekstów do klasyfikacji, bez dodatkowego kontekstu.

from mistralai.client import Mistral
import os

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

# Moderuj prosty tekst
response = client.classifiers.moderate(
    model="mistral-moderation-2603",
    inputs=["Tekst do analizy pod kątem moderacji"]
)

# Dostęp do wyników
for result in response.results:
    print(f"Kategorie: {result.categories}")
    print(f"Wyniki: {result.category_scores}")

Aby moderować pełne wymiany zdań – prompt i odpowiedź razem – tryb konwersacyjny dostarcza klasyfikatorowi tego, czego mu brakowało: wątku dyskusji.

# Moderuj pełną rozmowę
response = client.classifiers.moderate_chat(
    model="mistral-moderation-2603",
    inputs=[
        [
            {"role": "user", "content": "Jak leczyć ból głowy?"},
            {"role": "assistant", "content": "Weź 1 g paracetamolu..."}
        ]
    ]
)

# Klasyfikator ocenia pełny kontekst
for result in response.results:
    print(f"Wynik zdrowotny: {(result.category_scores or {}).get('health', 0)}")

Tryb konwersacyjny, który wywołuje punkt końcowy /v1/chat/moderations, jest tym, co Mistral zaleca w przypadku wymiany zdań: model został wytrenowany do klasyfikowania ostatniego zwrotu rozmowy w świetle poprzednich. Aby moderować odpowiedź swojego asystenta, umieść ją na końcu. Lista list w przykładzie pozwala wysłać wiele rozmów naraz; do pojedynczej rozmowy wystarczy prosta lista wiadomości. Ten sam tekst może więc otrzymać inny wynik w zależności od tego, czy odpowiada na legitimate pytanie, czy na złośliwe – dawka podana w odpowiedzi na zapytanie informacyjne nie ma tego samego statusu co ta sama dawka przemycana w wymianie dotyczącej ryzykownego samoleczenia.

Struktura odpowiedzi

Dla każdego analizowanego tekstu odpowiedź zawiera dwa równoległe bloki: categories – wartości logiczne obliczane z progami ustalonymi przez Mistral na podstawie jego wewnętrznego zestawu testowego, oraz category_scores – surowe wyniki od 0,0 do 1,0. Poniższy przykład ma charakter poglądowy, z zaokrąglonymi wartościami; niektóre przykłady w dokumentacji nadal pokazują dziewięć kategorii starego modelu, gdzie dangerous_and_criminal_content łączyło dangerous i criminal. Będziesz używać tych drugich, ponieważ pozwalają ci ustalić własne granice.

{
  "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
      }
    }
  ]
}

W tym przykładzie tylko health jest oznaczone jako true, z wynikiem 0,72. Asystent skierowany do konsumenta potraktowałby to jako sygnał do blokady; narzędzie przeznaczone dla farmaceutów przepuściłoby je bez wahania. Ten sam wynik, dwie przeciwstawne decyzje – i właśnie dlatego pracujesz na wynikach, a nie na wartościach logicznych.

Moderuj wiele tekstów wsadowo

API akceptuje wiele tekstów w jednym żądaniu, co zmienia wszystko w przypadku przetwarzania wsadowego: retrospektywna analiza historii rozmów lub bazy komentarzy staje się operacją rozsądną pod względem liczby wywołań.

# Moderuj wiele tekstów w jednym żądaniu
texts = [
    "Pierwszy tekst do analizy",
    "Drugi tekst do analizy",
    "Trzeci tekst do analizy"
]

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

# Każdy tekst ma własny wynik
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"Tekst {i+1}: maks. wynik = {max_score:.2f} ({max_cat})")

Guardraile kontra API moderacji: kiedy czego użyć

AspektNiestandardowe guardraileAPI moderacji
CzasPRZED generowaniemPO generowaniu
DziałanieBlokuje automatycznie (403)Zwraca wyniki (ty decydujesz)
KontrolaTwoje progi na kategorię, stosowane przez MistralSurowe wyniki, dowolna logika
WywołanieParametr żądania generowaniaOddzielne wywołanie /v1/moderations
Przypadek użyciaFiltruj niebezpieczne promptyKlasyfikuj odpowiedzi

Przykład: kompletny potok

Poniższy potok pokazuje sekwencjonowanie obu mechanizmów. Generowanie jest chronione guardrailem skupionym na wykrywaniu prób ominięcia zabezpieczeń (jailbreaking); odpowiedź jest następnie klasyfikowana wraz z pytaniem, które ją wywołało, a niestandardowa decyzja zapada, gdy tylko wynik przekroczy 0,5. Zauważ, że dwa kroki zwracają odrębne statusy – blocked_input i blocked_output – dzięki czemu twoje logi jasno wskazują, gdzie żądanie zostało zatrzymane.

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:
    """Potok z guardrailami (wejście) i moderacją (wyjście)."""
    # Krok 1: generowanie z guardrailami
    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: moderuj wyjście w kontekście pytania
    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}

Kluczowe wnioski

  • API moderacji używa modelu mistral-moderation-2603 do klasyfikowania treści
  • Dostępne są dwa tryby: zwykły tekst i konwersacyjny
  • Wyniki mieszczą się w zakresie od 0,0 do 1,0 – ty definiujesz własne progi decyzyjne
  • Tryb konwersacyjny jest dokładniejszy, ponieważ uwzględnia kontekst
  • Łącz guardraile (wejście) z moderacją (wyjście), aby uzyskać obronę wielowarstwową