Προσαρμοσμένα Guardrails: Αποκλεισμός πριν το Μοντέλο
Σε αυτήν τη σελίδα
Μάθημα ξαναγράφηκε στις 3 Νοεμβρίου 2026. Η προηγούμενη έκδοση περιέγραφε μια ανύπαρκτη παράμετρο
guardrails(ένα λεξικό μεenabled), ανύπαρκτες κατηγορίες (hate,violence), μια missing μέθοδοconversation.send()στο SDK και φανταστικές αποκρίσεις JSON. Η επίσημη μορφή είναι μια λίστα διαμορφώσεωνmoderation_llm_v2, και οι αποκρίσεις παρακάτω ταιριάζουν με την τεκμηρίωση. Ο κώδικας έχει επαληθευτεί έναντι των τύπων SDKmistralaiέκδοσης 3.7.0. Πηγές: Moderation & Guardrailing · mistralai Python SDK.
Η Αρχή των Προσαρμοσμένων Guardrails
Τα Προσαρμοσμένα Guardrails της Mistral λειτουργούν ως φίλτρο εισόδου: αναλύουν το prompt του χρήστη πριν αυτό φτάσει στο μοντέλο παραγωγής. Εάν το περιεχόμενο υπερβεί οποιοδήποτε όριο έχετε ορίσει, το αίτημα αποκλείεται με σφάλμα HTTP 403. Το μοντέλο δεν βλέπει ποτέ το προβληματικό prompt.
Κρατήστε στο μυαλό σας δύο περιορισμούς από την αρχή. Πρώτον, τα guardrails κάνουν moderation μόνο στην είσοδο· δεν ελέγχουν τι παράγει το μοντέλο. Αυτός είναι ο ρόλος του Moderation API (Μάθημα 5). Δεύτερον, αντικαθιστούν εργασία που διαφορετικά θα έπρεπε να κωδικοποιήσετε εσείς: κλήση του Moderation API, σύγκριση βαθμολογιών με τα κατώφλια σας και απόρριψη του αιτήματος.
Πώς Λειτουργεί
Όταν προσθέτετε guardrails σε ένα αίτημα, η ροή στην πλευρά της Mistral είναι η εξής:
- Η εφαρμογή σας στέλνει το αίτημα με την παράμετρο
guardrails. - Ο ταξινομητής
mistral-moderation-2603βαθμολογεί το prompt σε κάθε κατηγορία. - Εάν μια βαθμολογία υπερβεί το κατώφλι της, το API επιστρέφει σφάλμα
403και το μοντέλο δεν καλείται. - Διαφορετικά, το μοντέλο επεξεργάζεται το αίτημα κανονικά.
- Η απόκριση περιλαμβάνει ένα πεδίο
guardrailsπου περιέχει τις αξιολογημένες βαθμολογίες.
Flow: prompt → [mistral-moderation-2603] → score > threshold? → 403 (blocked)
→ else → [LLM] → response + scores
Η απόφαση βασίζεται σε μια βαθμολογία που συγκρίνεται με ένα κατώφλι που ορίζετε εσείς, κατηγορία προς κατηγορία, μεταξύ 0 και 1. Ένα χαμηλό κατώφλι αποκλείει περισσότερο περιεχόμενο· ένα κατώφλι 1 απενεργοποιεί ρητά την κατηγορία.
Η Μορφή της Παραμέτρου guardrails
Η παράμετρος είναι μια λίστα. Κάθε στοιχείο είναι ένα αντικείμενο που περιέχει μια διαμόρφωση moderation_llm_v2 και, δίπλα της, την επιλογή block_on_error:
guardrails = [
{
"block_on_error": True, # block if moderation itself fails
"moderation_llm_v2": {
"custom_category_thresholds": {
"jailbreaking": 0.3,
"criminal": 0.2,
},
"ignore_other_categories": False,
"action": "block",
},
}
]
| Κλειδί | Τοποθεσία | Ρόλος |
|---|---|---|
custom_category_thresholds | μέσα στο moderation_llm_v2 | Κατώφλι από 0 έως 1 ανά κατηγορία· το 1 απενεργοποιεί την κατηγορία |
ignore_other_categories | μέσα στο moderation_llm_v2 | True: αξιολογούνται μόνο οι αναφερόμενες κατηγορίες |
action | μέσα στο moderation_llm_v2 | "block" για απόρριψη του αιτήματος εάν υπερβεί ένα κατώφλι |
model_name | μέσα στο moderation_llm_v2, προαιρετικό | Μοντέλο moderation διαφορετικό από το προεπιλεγμένο mistral-moderation-2603 |
block_on_error | δίπλα στο moderation_llm_v2 | True: το αίτημα αποκλείεται εάν αποτύχει η αξιολόγηση |
Μπορείτε να τοποθετήσετε πολλαπλά αντικείμενα στη λίστα: το αίτημα αποκλείεται μόλις ενεργοποιηθεί έστω και ένα από αυτά. Κάθε αντικείμενο περιέχει μόνο μία διαμόρφωση moderation_llm_v2. Μια παλαιότερη διαμόρφωση, η moderation_llm_v1, υπάρχει ακόμα στο SDK με κατηγορίες από το deprecated μοντέλο mistral-moderation-2411 (deprecated στις 31 Μαρτίου 2026): μην τη χρησιμοποιείτε για νέα έργα.
Οι Έντεκα Κατηγορίες
Τα κλειδιά στο custom_category_thresholds είναι σταθερά· ένα άλλο κλειδί, όπως το violence ή το hate, δεν αντιστοιχεί σε τίποτα:
| Κλειδί | Τι εντοπίζει |
|---|---|
sexual | Ρητό σεξουαλικό περιεχόμενο |
hate_and_discrimination | Μίσος ή διακρίσεις βάσει προστατευόμενων χαρακτηριστικών |
violence_and_threats | Περιγραφόμενη, εξυμνημένη ή απειλούμενη σωματική βία |
dangerous | Εξαιρετικά επικίνδυνες συμπεριφορές |
criminal | Παράνομες δραστηριότητες |
selfharm | Αυτοτραυματισμός, αυτοκτονία, διατροφικές διαταραχές |
health | Αιτήματα για λεπτομερείς ή εξατομικευμένες ιατρικές συμβουλές |
financial | Αιτήματα για λεπτομερείς ή εξατομικευμένες οικονομικές συμβουλές |
law | Αιτήματα για λεπτομερείς ή εξατομικευμένες νομικές συμβουλές |
pii | Ζητούμενα ή κοινοποιημένα προσωπικά δεδομένα |
jailbreaking | Απόπειρες παράκαμψης των κανόνων του μοντέλου |
Το Μάθημα 6 επανεξετάζει καθεμία από αυτές και συζητά την επιλογή κατωφλίων.
Τα Τρία Επίπεδα Εφαρμογής
Η ίδια παράμετρος γίνεται δεκτή σε τρία σημεία. Η επιλογή σας καθορίζει πού ζει η πολιτική ασφαλείας σας και ποιος θα μπορούσε να ξεχάσει να την εφαρμόσει.
Επίπεδο 1: Ένα Αίτημα Chat Completions
Περνάτε το guardrails στην κλήση chat.complete(). Κάθε αίτημα κουβαλά τους δικούς του κανόνες: πρακτικό για εξερεύνηση, αλλά ριψοκίνδυνο σε μεγάλη κλίμακα, καθώς μια μεμονωμένη κλήση χωρίς την παράμετρο περνάει ανεξέλεγκτη.
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)
Χρήση: Πρωτοτυποποίηση, μεμονωμένες κλήσεις, ρύθμιση κατωφλίων.
Επίπεδο 2: Μια Συνομιλία
Με το Conversations API, περνάτε το guardrails κατά την εκκίνηση, στο 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)
Τα επόμενα μηνύματα στέλνονται με client.beta.conversations.append(conversation_id=conversation.conversation_id, inputs=...). Αυτή η μέθοδος δεν δέχεται παράμετρο guardrails στο SDK 3.7.0 και η τεκμηρίωση δεν διευκρινίζει εάν τα guardrails εκκίνησης ισχύουν για τους επόμενους γύρους. Για εγγυημένη προστασία σε κάθε γύρο, επισυνάψτε guardrails σε έναν πράκτορα.
Χρήση: Μεμονωμένη συνομιλία χωρίς πράκτορα, ή παράκαμψη των guardrails ενός πράκτορα για ένα συγκεκριμένο αίτημα.
Επίπεδο 3: Ένας Πράκτορας
Τα guardrails που περνιούνται στο client.beta.agents.create() γίνονται μέρος του ορισμού του πράκτορα. Σύμφωνα με την τεκμηρίωση, όλες οι συνομιλίες που χρησιμοποιούν αυτόν τον πράκτορα τα κληρονομούν χωρίς ανάγκη επανάληψής τους. Ωστόσο, ένα αίτημα συνομιλίας μπορεί να τα παρακάμψει περνώντας τα δικά του 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!")
Χρήση: Παραγωγή, όταν πολλαπλές ομάδες ή υπηρεσίες καλούν τον ίδιο βοηθό.
Τι Επιστρέφουν τα Guardrails
Όταν το αίτημα περάσει, η απόκριση του API περιλαμβάνει, δίπλα στα τυπικά πεδία, ένα πεδίο guardrails: μια λίστα με ένα αποτέλεσμα ανά guardrail. Ορίστε αυτό το πεδίο από το παράδειγμα της τεκμηρίωσης:
{
"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 }
}
}
}
]
}
Με το ignore_other_categories ορισμένο σε True, μόνο οι κατηγορίες που αναφέρονται στα κατώφλιά σας εμφανίζονται σε αυτό το αποτέλεσμα. Στο Python SDK, μια απόκριση συνομιλίας εκθέτει αυτό το πεδίο (conversation.guardrails). Η απόκριση chat.complete(), ωστόσο, δεν έχει καθορισμένο πεδίο γι’ αυτό στο SDK 3.7.0: χάνεται εκεί. Εάν θέλετε να καταγράφετε βαθμολογίες—και είναι χρήσιμο να γνωρίζετε αργότερα εάν τα κατώφλιά σας είναι πολύ χαλαρά ή πολύ αυστηρά—χρησιμοποιήστε συνομιλίες ή διαβάστε την ακατέργαστη απόκριση HTTP.
Όταν ένα κατώφλι υπερβεί, το API επιστρέφει ένα σφάλμα 403 του οποίου το σώμα λεπτομερεί την απόφαση, κατηγορία προς κατηγορία:
{
"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 τότε εγείρει errors.SDKError, όπου το status_code είναι 403 και το body περιέχει αυτό το JSON:
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}")
Αυτό το φορτίο σας επιτρέπει να εξηγήσετε έναν αποκλεισμό κατά τη διάρκεια μιας έφεσης: ποια κατηγορία, ποια βαθμολογία, ποιο κατώφλι.
Τέλος, υπάρχει η υποβαθμισμένη περίπτωση. Εάν η ίδια η αξιολόγηση αποτύχει και το block_on_error είναι True, το αίτημα απορρίπτεται με κωδικό σφάλματος 3201 και το μήνυμα Request blocked due to error in guardrail evaluation and block_on_error is set to True. Αυτή είναι η λειτουργία fail-safe: σε περίπτωση αμφιβολίας, αποκλεισμός. Με το block_on_error ορισμένο σε False (η προεπιλεγμένη τιμή του στο SDK), το αίτημα θα περνούσε ανεξέλεγκτο.
Επιλογή του Σωστού Επιπέδου
| Κριτήριο | Chat Completions | Συνομιλία | Πράκτορας |
|---|---|---|---|
| Πού δηλώνονται τα guardrails | Σε κάθε κλήση | Κατά την εκκίνηση (start) | Κατά τη δημιουργία του πράκτορα |
| Κληρονομικότητα | Καμία | Μη τεκμηριωμένη για επόμενους γύρους | Όλες οι συνομιλίες του πράκτορα |
| Μπορεί να παρακαμφθεί | — | — | Ναι, από ένα αίτημα συνομιλίας |
| Χρήση | Δοκιμές, ρύθμιση κατωφλίων | Μεμονωμένη συνομιλία | Παραγωγή |
Στην πράξη, ρυθμίστε τα κατώφλιά σας σε αιτήματα Chat Completions χρησιμοποιώντας πραγματικές περιπτώσεις και, στη συνέχεια, μεταφέρετε την πολιτική σε έναν πράκτορα μόλις ο κώδικας βγει από το μηχάνημά σας: δεν θα υπάρχουν πλέον ξεχασμένες κλήσεις.
Βασικά σημεία
- Τα Guardrails αποκλείουν τα prompts πριν το μοντέλο μέσω σφάλματος
403· δεν ελέγχουν την έξοδο - Η παράμετρος είναι μια λίστα αντικειμένων
{"block_on_error": ..., "moderation_llm_v2": {...}}, όχι ένα λεξικό μεenabled - Έντεκα κατηγορίες με σταθερά ονόματα (
hate_and_discrimination,violence_and_threats, …), καθεμία με κατώφλι από 0 έως 1· το1απενεργοποιεί - Τρία επίπεδα:
chat.complete(),conversations.start(),agents.create()· οι πράκτορες περνούν τα guardrails τους σε όλες τις συνομιλίες τους block_on_error=Trueεξασφαλίζει συμπεριφορά fail-safe (σφάλμα3201)