API moderacji Mistral
Na tej stronie
Zaktualizowano 3 listopada 2026 r. Przykład odpowiedzi zawierał wcześniej nieistniejące klucze (
hate,violence,unpredictable); obecnie odzwierciedla jedenaście kategorii z modelumistral-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 sprawdzae.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 SDKmistralaiw 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ć
| Aspekt | Niestandardowe guardraile | API moderacji |
|---|---|---|
| Czas | PRZED generowaniem | PO generowaniu |
| Działanie | Blokuje automatycznie (403) | Zwraca wyniki (ty decydujesz) |
| Kontrola | Twoje progi na kategorię, stosowane przez Mistral | Surowe wyniki, dowolna logika |
| Wywołanie | Parametr żądania generowania | Oddzielne wywołanie /v1/moderations |
| Przypadek użycia | Filtruj niebezpieczne prompty | Klasyfikuj 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-2603do 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ą