Διαμόρφωση δικλίδων ασφαλείας σε Python
Σε αυτήν τη σελίδα
Μάθημα ξαναγράφηκε στις 3 Νοεμβρίου 2026. Η προηγούμενη έκδοση διαμόρφωνε τις δικλίδες ασφαλείας χρησιμοποιώντας ένα πλασματικό λεξικό (
enabled), ανύπαρκτες κατηγορίες (hate,violence,unpredictable), ισχυριζόταν ότι οι μη αναφερόμενες κατηγορίες διατηρούσαν «προεπιλεγμένα όρια», και δοκίμαζεe.status_code == 3201, παρόλο που το3201είναι κωδικός σφάλματος στο σώμα της απάντησης και όχι κωδικός κατάστασης HTTP. Η διαμόρφωση ακολουθεί πλέον την επίσημη μορφή και ο κώδικας έχει επαληθευτεί έναντι των τύπων του SDKmistralai3.7.0. Πηγές: Moderation & Guardrailing · mistralai Python SDK.
Από τη θεωρία στον κώδικα
Κατανοείτε πλέον πώς λειτουργούν οι δικλίδες ασφαλείας. Σε αυτό το μάθημα, θα τις διαμορφώσετε με ακρίβεια: θα επιλέξετε τις κατηγορίες σας, θα ορίσετε τα όριά σας και θα διαχειριστείτε τους αποκλεισμούς στον κώδικα Python.
Ξεκινήστε με το SDK της Mistral εγκατεστημένο (οι δικλίδες ασφαλείας απαιτούν έκδοση 2 ή νεότερη) και ένα κλειδί API φορτωμένο από το περιβάλλον και όχι σκληροκωδικοποιημένο.
pip install "mistralai>=2"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Η παράμετρος guardrails αναλυτικά
Η παράμετρος guardrails είναι μια λίστα. Κάθε στοιχείο συνδυάζει την επιλογή block_on_error με μια διαμόρφωση moderation_llm_v2, η οποία περιέχει τα όρια, την επιλογή ignore_other_categories και την ενέργεια:
from mistralai.client.models import GuardrailConfigTypedDict
GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
# Αποκλεισμός σε περίπτωση αποτυχίας της ίδιας της αξιολόγησης
"block_on_error": True,
"moderation_llm_v2": {
# Όρια ανά κατηγορία, από 0 έως 1 (το 1 απενεργοποιεί την κατηγορία)
"custom_category_thresholds": {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"dangerous": 0.2,
"criminal": 0.1,
"selfharm": 0.1,
"health": 0.5,
"financial": 0.5,
"law": 0.5,
"pii": 0.2,
"jailbreaking": 0.1,
},
"ignore_other_categories": False,
# Ενέργεια σε περίπτωση υπέρβασης ορίου
"action": "block",
},
}
]
Το προεπιλεγμένο μοντέλο moderation είναι το mistral-moderation-2603· το προαιρετικό κλειδί model_name σάς επιτρέπει να ορίσετε ένα διαφορετικό.
Ο χαρακτηρισμός τύπου list[GuardrailConfigTypedDict] δεν είναι υποχρεωτικός, αλλά αξίζει να τον χρησιμοποιήσετε: το SDK περιγράφει κάθε επιτρεπόμενο κλειδί, οπότε ένας έλεγχος τύπων όπως το pyright ή το mypy θα επισημάνει μια κατηγορία με λάθος ορθογραφία (violence αντί για violence_and_threats) που το ίδιο το API δεν θα εντόπιζε.
custom_category_thresholds
Αυτή είναι η καρδιά της διαμόρφωσης. Κάθε κατηγορία λαμβάνει ένα όριο μεταξύ 0 και 1, το οποίο συγκρίνεται με τη βαθμολογία που αποδίδει ο ταξινομητής στο prompt. Όσο χαμηλότερο είναι το όριο, τόσο περισσότερο μπλοκάρει το φίλτρο, με τον κίνδυνο να απορρίπτει νόμιμα αιτήματα. Ένα όριο ίσο με 1 απενεργοποιεί ρητά την κατηγορία. Η Mistral δεν δημοσιεύει έναν προτεινόμενο πίνακα τιμών: πρέπει να βαθμονομήσετε αυτές τις τιμές στα δικά σας παραδείγματα (μάθημα 7).
Οι τιμές έχουν νόημα μόνο στο πλαίσιο της εφαρμογής σας. Ένα chatbot ανοιχτό στο κοινό κλειδώνει τις ευαίσθητες κατηγορίες στις χαμηλότερες ρυθμίσεις, ενώ ένα εσωτερικό εργαλείο για επαγγελματίες υγείας πρέπει να επιτρέπει ιατρικές ερωτήσεις παραμένοντας αυστηρό στα προσωπικά δεδομένα.
# Δημόσιο chatbot: πολύ χαμηλά όρια
public_thresholds = {
"sexual": 0.1,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.1,
"criminal": 0.1,
"selfharm": 0.1,
}
# Εσωτερικό ιατρικό εργαλείο: health απενεργοποιημένο, PII υπό παρακολούθηση
medical_thresholds = {
"sexual": 0.2,
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.3,
"health": 1, # απενεργοποιεί την κατηγορία: οι ιατρικές ερωτήσεις είναι ο βασικός σκοπός του εργαλείου
"pii": 0.1,
}
Κατηγορίες που δεν αναφέρετε
Τι συμβαίνει με τις κατηγορίες που λείπουν από το custom_category_thresholds; Η τεκμηρίωση δεν το αναφέρει ρητά, αλλά το παράδειγμα αποκλεισμού είναι αποκαλυπτικό: οι μη αναφερόμενες κατηγορίες εμφανίζονται εκεί με όριο 1.0, σημειωμένες αλλά ανενεργές. Μην βασίζεστε σε ένα προεπιλεγμένο όριο: αναφέρετε κάθε κατηγορία που πρέπει να μπορεί να προκαλέσει αποκλεισμό.
Η επιλογή ignore_other_categories ελέγχει μόνο τι αξιολογείται και επιστρέφεται. Όταν ορίζεται σε False, όλες οι αξιολογημένες κατηγορίες εμφανίζονται στο αποτέλεσμα· όταν είναι True, αξιολογούνται μόνο αυτές που αναφέρατε.
TARGETED_GUARDRAILS: list[GuardrailConfigTypedDict] = [
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {
"hate_and_discrimination": 0.1,
"violence_and_threats": 0.2,
},
"ignore_other_categories": True, # αξιολογεί μόνο αυτές τις δύο κατηγορίες
"action": "block",
},
}
]
Προειδοποίηση: με αυτή τη διαμόρφωση, μια απόπειρα jailbreak ή ένα αίτημα για προσωπικά δεδομένα θα περνούσαν χωρίς έλεγχο. Περιορίστε τη λίστα μόνο για συγκεκριμένο λόγο.
Πλήρες παράδειγμα: chatbot με δικλίδες ασφαλείας
Ακολουθεί μια ελάχιστη συνάρτηση: στέλνει το μήνυμα με την πλήρη διαμόρφωση και μετατρέπει έναν αποκλεισμό σε μια αναγνώσιμη απάντηση για τον χρήστη.
from mistralai.client import errors
def chat_securise(message_utilisateur: str) -> str:
"""Στέλνει ένα μήνυμα προστατευμένο από δικλίδες ασφαλείας."""
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "You are a professional assistant."},
{"role": "user", "content": message_utilisateur},
],
guardrails=GUARDRAILS,
)
except errors.SDKError as e:
if e.status_code == 403:
return "Sorry, this request cannot be processed."
raise
contenu = response.choices[0].message.content
return contenu if isinstance(contenu, str) else ""
print(chat_securise("Explain machine learning to me"))
Δύο παρατηρήσεις. Το message.content μπορεί να είναι συμβολοσειρά ή λίστα μερών ανάλογα με το μοντέλο, εξ ου και ο έλεγχος isinstance. Και η απάντηση από το chat.complete() δεν εκθέτει βαθμολογίες δικλίδων ασφαλείας στο SDK 3.7.0: για να τις καταγράψετε, χρησιμοποιήστε το Conversations API, του οποίου η απάντηση τις μεταφέρει στο πεδίο guardrails.
Καθαρός χειρισμός σφαλμάτων αποκλεισμού
Πρέπει να διακρίνετε δύο αποτυχίες που απαιτούν διαφορετικό μήνυμα και διαφορετική ειδοποίηση: έναν αποκλεισμό πολιτικής περιεχομένου, που επιστρέφει κωδικό κατάστασης HTTP 403, και μια αποτυχία αξιολόγησης moderation με ενεργοποιημένο το block_on_error, την οποία το σώμα της απάντησης σηματοδοτεί με κωδικό 3201. Και τα δύο φτάνουν ως errors.SDKError, των οποίων το body περιέχει το JSON που επιστρέφει το API:
import json
from typing import Any
from mistralai.client import errors
def chat_avec_gestion_erreurs(message_utilisateur: str) -> dict[str, Any]:
"""Chat που διακρίνει τους αποκλεισμούς πολιτικής από τις αποτυχίες moderation."""
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": message_utilisateur}],
guardrails=GUARDRAILS,
)
except errors.SDKError as e:
try:
corps = json.loads(e.body)
except json.JSONDecodeError:
raise e
if corps.get("code") == 3201:
return {
"status": "error",
"content": "Moderation service unavailable. Request blocked as a precaution.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Your message was blocked by our security policy.",
"categories": [nom for nom, d in decisions.items() if d["violated"]],
}
raise
return {"status": "ok", "content": response.choices[0].message.content}
Ελέγξτε πρώτα τον κωδικό 3201, καθώς η τεκμηρίωση δεν καθορίζει την κατάσταση HTTP για αυτό το σφάλμα. Οι παραβιασμένες κατηγορίες προέρχονται από το decisions, όπου κάθε εγγραφή δίνει threshold, score και violated: αυτό είναι που θα καταγράψετε για να εξηγήσετε έναν αποκλεισμό.
Βέλτιστες πρακτικές διαμόρφωσης
Ξεκινήστε αυστηρά και στη συνέχεια χαλαρώστε. Τα χαμηλά όρια κατά την εκκίνηση σάς βοηθούν να εντοπίσετε ψευδώς θετικά αποτελέσματα ενώ ο όγκος είναι ακόμη διαχειρίσιμος, και κάθε αύξηση αποφασίζεται με βάση παρατηρούμενες περιπτώσεις και όχι τη διαίσθηση:
# Φάση 1: εκκίνηση (πολύ αυστηρή)
phase1 = {"hate_and_discrimination": 0.1, "violence_and_threats": 0.1, "criminal": 0.1}
# Φάση 2: μετά την ανάλυση ψευδώς θετικών
phase2 = {"hate_and_discrimination": 0.15, "violence_and_threats": 0.25, "criminal": 0.1}
# Φάση 3: σταθερή παραγωγή
phase3 = {"hate_and_discrimination": 0.2, "violence_and_threats": 0.3, "criminal": 0.15}
Αυτές οι τιμές απεικονίζουν την προσέγγιση· οι δικές σας θα προκύψουν από τις δικές σας μετρήσεις. Διατηρήστε το block_on_error ορισμένο σε True στην παραγωγή: η προεπιλεγμένη τιμή του στο SDK είναι False, και μια αποτυχία moderation θα άφηνε τότε μη επαληθευμένο περιεχόμενο να περάσει. Τέλος, η τεκμηρίωση προειδοποιεί ότι το μοντέλο moderation εξελίσσεται: οι πολιτικές που βασίζονται σε βαθμολογίες ενδέχεται να απαιτούν επαναβαθμονόμηση.
Βασικά σημεία
- Το
guardrailsείναι μια λίστα αντικειμένων{"block_on_error": ..., "moderation_llm_v2": {...}} - Μέσα στο
moderation_llm_v2:custom_category_thresholds,ignore_other_categories,actionκαι προαιρετικάmodel_name - Όρια από
0έως1· το χαμηλότερο είναι αυστηρότερο· το1απενεργοποιεί μια κατηγορία. Αναφέρετε κάθε κατηγορία που πρέπει να μπλοκάρει - Ένας αποκλεισμός προκαλεί
errors.SDKErrorμεstatus_code == 403· μια αποτυχία μεblock_on_errorφέρει κωδικό3201στο σώμα - Διατηρήστε
block_on_error=Trueστην παραγωγή, καθώς η προεπιλογή είναιFalse