Kohandatud turvamehhanismid: blokeeri enne mudelit
Sellel lehel
Õppetund kirjutati ümber 3. novembril 2026. Eelmine versioon kirjeldas fiktiivset parameetrit
guardrails(sõnastik võtmegaenabled), olematuid kategooriaid (hate,violence), puuduvat meetoditconversation.send()SDK-s ja väljamõeldud JSON-vastuseid. Ametlik vorming on loend konfiguratsioonidestmoderation_llm_v2ja allpool toodud vastused vastavad dokumentatsioonile. Kood on kontrollitudmistralaiSDK tüüpide versiooni 3.7.0 vastu. Allikad: Moderation & Guardrailing · mistralai Python SDK.
Kohandatud turvamehhanismide põhimõte
Mistrali kohandatud turvamehhanismid toimivad sisendfiltrina: need analüüsivad kasutaja sisestust enne, kui see jõuab genereerimismudelini. Kui sisu ületab mõnda sinu määratud lävendit, blokeeritakse päring HTTP veakoodiga 403. Mudel ei näe probleemset sisestust kunagi.
Pea algusest peale meeles kahte piirangut. Esiteks, turvamehhanismid modereerivad ainult sisendit; need ei kontrolli seda, mida mudel genereerib. See on Moderatsiooni API ülesanne (õppetund 5). Teiseks asendavad need tööd, mida muidu peaksid ise kodeerima: Moderatsiooni API kutsumine, tulemuste võrdlemine oma lävenditega ja päringu tagasilükkamine.
Kuidas see toimib
Kui lisad päringule turvamehhanismid, kulgeb protsess Mistrali poolt järgmiselt:
- Sinu rakendus saadab päringu parameetriga
guardrails. - Klassifikaator
mistral-moderation-2603hindab sisestust igas kategoorias. - Kui tulemus ületab lävendit, tagastab API vea
403ja mudelit ei kutsuta. - Vastasel juhul töötleb mudel päringut tavapäraselt.
- Vastus sisaldab välja
guardrails, mis sisaldab hinnatud tulemusi.
Voog: sisestus → [mistral-moderation-2603] → tulemus > lävend? → 403 (blokeeritud)
→ muul juhul → [LLM] → vastus + tulemused
Otsus põhineb tulemusel, mida võrreldakse sinu määratud lävendiga kategooria kaupa vahemikus 0 kuni 1. Madal lävend blokeerib rohkem sisu; lävend 1 lülitab kategooria sõnaselgelt välja.
Parameetri guardrails vorming
Parameeter on loend. Iga element on objekt, mis sisaldab konfiguratsiooni moderation_llm_v2 ja selle kõrval valikut block_on_error:
guardrails = [
{
"block_on_error": True, # blokeeri, kui moderatsioon ise ebaõnnestub
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Võti | Asukoht | Roll |
|---|---|---|
custom_category_thresholds | sees moderation_llm_v2 | Lävend 0-st 1-ni kategooria kohta; 1 lülitab kategooria välja |
ignore_other_categories | sees moderation_llm_v2 | True: hinnatakse ainult loetletud kategooriaid |
action | sees moderation_llm_v2 | "block" päringu tagasilükkamiseks, kui lävend ületatakse |
model_name | sees moderation_llm_v2, valikuline | Moderatsioonimudel, erinev vaikimisi mistral-moderation-2603-st |
block_on_error | kõrval moderation_llm_v2 | True: päring blokeeritakse, kui hindamine ebaõnnestub |
Saad loendisse paigutada mitu objekti: päring blokeeritakse niipea, kui ükskõik milline neist käivitub. Iga objekt sisaldab ainult ühte konfiguratsiooni moderation_llm_v2. Vanem konfiguratsioon moderation_llm_v1 on SDK-s endiselt olemas koos aegunud mudeli mistral-moderation-2411 kategooriatega (aegus 31. märtsil 2026): ära kasuta seda uute projektide jaoks.
Üksteist kategooriat
Võtmed custom_category_thresholds sees on fikseeritud; mõni muu võti, nagu violence või hate, ei vasta millelegi:
| Võti | Mida tuvastab |
|---|---|
sexual | Selge seksuaalne sisu |
hate_and_discrimination | Viha või diskrimineerimine kaitstud tunnuste põhjal |
violence_and_threats | Kirjeldatud, ülistatud või ähvardatud füüsiline vägivald |
dangerous | Äärmiselt ohtlik käitumine |
criminal | Ebaseaduslik tegevus |
selfharm | Enesevigastamine, enesetapp, söömishäired |
health | Päringud üksikasjaliku või isikustatud meditsiinilise nõuande järele |
financial | Päringud üksikasjaliku või isikustatud finantsnõuande järele |
law | Päringud üksikasjaliku või isikustatud õigusnõuande järele |
pii | Isikuandmete küsimine või jagamine |
jailbreaking | Katsed mööda hiilida mudeli reeglitest |
Õppetund 6 võtab need kõik uuesti läbi ja arutab lävendite valikut.
Kolm rakendustaset
Sama parameetrit aktsepteeritakse kolmes kohas. Sinu valik määrab, kus sinu turvapoliitika asub ja kes võib selle rakendamise unustada.
Tase 1: Vestluse lõpuleviimise päring (Chat Completions)
Edastad guardrails väljakutses chat.complete(). Iga päring kannab oma reegleid: praktiline uurimistööks, kuid riskantne suuremahulises kasutuses, kuna üksainus väljakutse ilma parameetrita pääseb kontrollimatult läbi.
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "What is the distance from the Earth to the Moon?"}],
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"sexual": 0.1, "selfharm": 0.1},
"ignore_other_categories": False,
"action": "block",
},
}
],
)
print(response.choices[0].message.content)
Kasutusjuhtum: Prototüüpimine, üksikud väljakutsed, lävendite häälestamine.
Tase 2: Vestlus
Conversations API-ga edastad guardrails käivitamisel meetodis client.beta.conversations.start():
conversation = client.beta.conversations.start(
model="mistral-large-latest",
inputs="Hello, can you help me prepare for an interview?",
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"selfharm": 0.1,
},
"action": "block",
},
}
],
)
for entree in conversation.outputs:
if entree.type == "message.output":
print(entree.content)
Järgnevad sõnumid saadetakse meetodiga client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). See meetod ei aktsepteeri SDK versioonis 3.7.0 parameetrit guardrails ja dokumentatsioon ei täpsusta, kas käivitamisel määratud turvamehhanismid kehtivad ka järgnevate voorude jaoks. Garanteeritud kaitseks igas voorus lisa turvamehhanismid agendile.
Kasutusjuhtum: Üksik vestlus ilma agendita või agendi turvamehhanismide tühistamine konkreetse päringu jaoks.
Tase 3: Agent
Parameetrid guardrails, mis edastatakse meetodile client.beta.agents.create(), saavad agendi definitsiooni osaks. Dokumentatsiooni kohaselt pärandavad kõik vestlused, mis seda agenti kasutavad, need ilma kordamata. Vestluse päring saab need siiski tühistada, edastades oma guardrails.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Secure Assistant",
instructions="You are a professional customer service assistant.",
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
"criminal": 0.1,
"selfharm": 0.1,
"jailbreaking": 0.3,
},
"ignore_other_categories": False,
"action": "block",
},
}
],
)
conversation = client.beta.conversations.start(agent_id=agent.id, inputs="Hello!")
Kasutusjuhtum: Tootmine, kui sama assistenti kutsub mitu meeskonda või teenust.
Mida turvamehhanismid tagastavad
Kui päring õnnestub, sisaldab API vastus standardväljade kõrval välja guardrails: loend, millel on üks tulemus iga turvamehhanismi kohta. Siin on see väli dokumentatsiooni näitest:
{
"guardrails": [
{
"moderation_llm_v2": {
"action": "pass",
"categories": {
"sexual": { "score": 0.03, "violated": false },
"selfharm": { "score": 0.05, "violated": false },
"violence_and_threats": { "score": 0.0, "violated": false },
"hate_and_discrimination": { "score": 0.0, "violated": false }
}
}
}
]
}
Kui ignore_other_categories on seatud väärtusele True, ilmuvad sellesse tulemusse ainult need kategooriad, mis on loetletud sinu lävendites. Pythoni SDK-s paljastab vestluse vastus selle välja (conversation.guardrails). Väljakutse chat.complete() vastusel aga puudub SDK versioonis 3.7.0 selle jaoks spetsiaalne väli: see läheb seal kaduma. Kui soovid tulemusi logida – ja on kasulik teada, kas sinu lävendid on liiga lõdvad või liiga ranged –, kasuta vestlusi või loe toorest HTTP-vastust.
Kui lävend ületatakse, tagastab API vea 403, mille keha kirjeldab otsust kategooria kaupa:
{
"error": { "message": "Content blocked by guardrail", "status": 403 },
"guardrails": {
"results": {
"moderation_llm_v2": {
"model_name": "mistral-moderation-2603",
"decisions": {
"sexual": { "threshold": 0.1, "score": 0.3, "violated": true },
"selfharm": { "threshold": 0.1, "score": 0.05, "violated": false }
},
"violated": true,
"action": "block"
}
}
}
}
SDK viskab seejärel errors.SDKError, kus status_code on 403 ja body sisaldab seda JSON-i:
import json
from mistralai.client import errors
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": user_message}],
guardrails=guardrails,
)
except errors.SDKError as e:
if e.status_code != 403:
raise
decisions = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
violated = [name for name, d in decisions.items() if d["violated"]]
print(f"Request blocked: {violated}")
See kasulik koormus võimaldab sul blokeerimist edasikaebamisel selgitada: milline kategooria, milline tulemus, milline lävend.
Lõpuks on olemas degradeerunud juhtum. Kui hindamine ise ebaõnnestub ja block_on_error on True, keeldutakse päringust veakoodiga 3201 ja sõnumiga Request blocked due to error in guardrail evaluation and block_on_error is set to True. See on tõrkekindel režiim: kahtluse korral blokeeri. Kui block_on_error on seatud väärtusele False (selle vaikimisi väärtus SDK-s), läheks päring kontrollimatult edasi.
Õige taseme valimine
| Kriterium | Chat Completions | Vestlus | Agent |
|---|---|---|---|
| Kus turvamehhanismid deklareeritakse | Igas väljakutses | Käivitamisel (start) | Agendi loomisel |
| Pärimine | Puudub | Järgnevate voorude jaoks dokumenteerimata | Kõik agendi vestlused |
| Ülekirjutatav | — | — | Jah, vestluse päringuga |
| Kasutusjuhtum | Testid, lävendite häälestamine | Üksik vestlus | Tootmine |
Praktikas häälesta oma lävendid Chat Completionsi päringutel, kasutades reaalseid juhtumeid, ja vii poliitika agendile niipea, kui kood lahkub sinu masinast: siis ei jää enam väljakutseid unustamata.
Peamised punktid
- Turvamehhanismid blokeerivad sisestused enne mudelit vea
403kaudu; need ei kontrolli väljundit - Parameeter on objektide
{"block_on_error": ..., "moderation_llm_v2": {...}}loend, mitte sõnastik võtmegaenabled - Üksteist fikseeritud nimedega kategooriat (
hate_and_discrimination,violence_and_threats, …), ühel lävend 0-st 1-ni;1lülitab välja - Kolm taset:
chat.complete(),conversations.start(),agents.create(); agendid edastavad oma turvamehhanismid kõigile oma vestlustele block_on_error=Truetagab tõrkekindla käitumise (viga3201)