Salt la conținutul principal
Română— Alege o limbă
Meniu

API-ul de moderare Mistral

Lecția 5 din 12 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Clasificarea conținutului după generare
  2. Modelul Mistral Moderation 2
  3. Endpoint-ul /v1/moderations
  4. Structura răspunsului
  5. Moderarea mai multor texte în lot (batch)
  6. Guardrails vs API de Moderare: când să le folosiți
  7. Exemplu: pipeline complet
  8. Puncte cheie

Actualizat la 3 noiembrie 2026. Exemplul de răspuns includea anterior chei inexistente (hate, violence, unpredictable); acum reflectă cele unsprezece categorii din mistral-moderation-2603. Pipeline-ul final folosea anterior un format inventat de guardrail (enabled) și detecta blocările căutând „403“ în mesajul de eroare: acum respectă formatul oficial și verifică e.status_code. Prezentarea modelului aderă la fișa sa tehnică oficială, iar lecția introduce Shieldstral 1.0, modelul de moderare aflat în previzualizare publică din august 2026. Cod verificat față de tipurile SDK mistralai versiunea 3.7.0. Surse: Moderare și Guardrailing · Mistral Moderation 2 · Shieldstral 1.0.

Clasificarea conținutului după generare

Guardrail-urile filtrează prompt-urile de intrare. Dar ce se întâmplă cu conținutul generat de model? Un prompt inocent poate produce un răspuns problematic: o întrebare de gimnaziu despre Al Doilea Război Mondial ar putea genera o descriere pe care nu doriți să o afișați fără avertismente. Acesta este rolul API-ului de Moderare: să analizeze conținutul post-factum și să atribuie scoruri de risc pe categorii.

API-ul de Moderare este a doua linie de apărare – completează guardrail-urile pentru a crea o arhitectură de securitate completă, cu o diferență majoră: nu blochează nimic de unul singur; vă informează.

Modelul Mistral Moderation 2

Modelul dedicat de moderare se numește mistral-moderation-2603 (Mistral Moderation 2, versiunea din martie 2026). Este un clasificator specializat, distinct de modelele de generare: nu scrie text, ci atribuie scoruri. Fișa sa tehnică oficială evidențiază o fereastră de context de 128.000 de tokeni, detectarea jailbreak-urilor și performanțe ridicate pe conținut multilingv complex, inclusiv conversații lungi. Înlocuiește mistral-moderation-2411, care a fost depreciat la 31 martie 2026.

Acesta evaluează fiecare text pe 11 categorii, cu un scor de la 0.0 la 1.0 per categorie. Acceptă două moduri de intrare, text simplu sau conversațional, iar alegerea dintre ele afectează calitatea rezultatelor mai mult decât v-ați aștepta.

Un al doilea model de moderare există din 4 august 2026, în previzualizare publică: Shieldstral 1.0. Funcționează diferit: compact (3,8 miliarde de parametri) și multimodal, clasifică texte și imagini pe baza unor întrebări de politică formulate în limbaj natural, răspunzând cu da sau nu. Ponderile sale sunt publicate sub licența Apache 2.0, permițând găzduirea proprie (self-hosting). Atâta timp cât rămâne în previzualizare, mistral-moderation-2603 rămâne modelul de producție și este cel utilizat pentru guardrails.

Endpoint-ul /v1/moderations

Modul text simplu este cel mai simplu: trimiteți unul sau mai multe texte de clasificat, fără context suplimentar.

from mistralai.client import Mistral
import os

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

# Moderare text simplu
response = client.classifiers.moderate(
    model="mistral-moderation-2603",
    inputs=["Text de analizat pentru moderare"]
)

# Accesarea rezultatelor
for result in response.results:
    print(f"Categorii: {result.categories}")
    print(f"Scoruri: {result.category_scores}")

Pentru a modera schimburi complete, prompt-ul și răspunsul împreună, modul conversațional oferă clasificatorului ceea ce îi lipsea: firul discuției.

# Moderarea unei conversații complete
response = client.classifiers.moderate_chat(
    model="mistral-moderation-2603",
    inputs=[
        [
            {"role": "user", "content": "Cum tratez o durere de cap?"},
            {"role": "assistant", "content": "Luați 1g de paracetamol..."}
        ]
    ]
)

# Clasificatorul evaluează contextul complet
for result in response.results:
    print(f"Scor sănătate: {(result.category_scores or {}).get('health', 0)}")

Modul conversațional, care apelează endpoint-ul /v1/chat/moderations, este ceea ce Mistral recomandă pentru un schimb: modelul este antrenat să clasifice ultima intervenție a conversației în lumina celor precedente. Pentru a modera răspunsul asistentului dumneavoastră, plasați-l la final. Lista de liste din exemplu permite trimiterea mai multor conversații simultan; o simplă listă de mesaje este suficientă pentru una singură. Astfel, același text poate primi un scor diferit în funcție de faptul dacă răspunde la o întrebare legitimă sau malițioasă – un dozaj citat ca răspuns la o cerere de informații nu are același statut ca același dozaj strecurat într-un schimb despre automedicația riscantă.

Structura răspunsului

Pentru fiecare text analizat, răspunsul conține două blocuri paralele: categories, booleene calculate cu praguri stabilite de Mistral pe baza setului său intern de teste, și category_scores, scorurile brute de la 0.0 la 1.0. Exemplul de mai jos este ilustrativ, cu valori rotunjite; unele exemple din documentație afișează încă cele nouă categorii ale vechiului model, unde dangerous_and_criminal_content combina dangerous și criminal. Le veți folosi pe acestea din urmă deoarece vă permit să stabiliți propriile limite.

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

În acest exemplu, doar health este marcat true, cu 0.72. Un asistent orientat către consumatori ar vedea aici un semnal de blocare; un instrument destinat farmaciștilor l-ar lăsa să treacă fără ezitare. Același scor, două decizii opuse, și tocmai de aceea lucrați cu scoruri mai degrabă decât cu booleene.

Moderarea mai multor texte în lot (batch)

API-ul acceptă mai multe texte într-o singură cerere, ceea ce schimbă totul pentru procesarea în lot: analizarea retroactivă a unui istoric de conversații sau a unei baze de date de comentarii devine o operațiune rezonabilă în ceea ce privește numărul de apeluri.

# Moderarea mai multor texte într-o singură cerere
texts = [
    "Primul text de analizat",
    "Al doilea text de analizat",
    "Al treilea text de analizat"
]

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

# Fiecare text are propriul rezultat
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}: scor maxim = {max_score:.2f} ({max_cat})")

Guardrails vs API de Moderare: când să le folosiți

AspectGuardrails personalizateAPI de Moderare
MomentÎNAINTE de generareDUPĂ generare
AcțiuneBlochează automat (403)Returnează scoruri (dumneavoastră decideți)
ControlPragurile dumneavoastră per categorie, aplicate de MistralScoruri brute, logică liberă
ApelParametru al cererii de generareApel separat către /v1/moderations
Caz de utilizareFiltrarea prompt-urilor periculoaseClasificarea răspunsurilor

Exemplu: pipeline complet

Pipeline-ul de mai jos arată secvențierea celor două mecanisme. Generarea este protejată de un guardrail concentrat pe jailbreaking; răspunsul este apoi clasificat împreună cu întrebarea care l-a produs, iar o decizie personalizată intervine imediat ce un scor depășește 0.5. Rețineți că cei doi pași returnează statusuri distincte – blocked_input și blocked_output – astfel încât jurnalele (logs) dumneavoastră indică clar unde s-a oprit cererea.

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 cu guardrails (intrare) și moderare (ieșire)."""
    # Pasul 1: generare cu guardrails
    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}

    # Pasul 2: moderarea ieșirii, în contextul întrebării
    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}

Puncte cheie

  • API-ul de Moderare utilizează modelul mistral-moderation-2603 pentru a clasifica conținutul
  • Două moduri disponibile: text simplu și conversațional
  • Scorurile variază de la 0.0 la 1.0 – dumneavoastră definiți propriile praguri de decizie
  • Modul conversațional este mai precis deoarece ține cont de context
  • Combinați guardrails (intrare) + moderare (ieșire) pentru o apărare în profunzime