Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Προσαρμοσμένα Guardrails: Αποκλεισμός πριν το Μοντέλο

Μάθημα 2 / 12 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Η Αρχή των Προσαρμοσμένων Guardrails
  2. Πώς Λειτουργεί
  3. Η Μορφή της Παραμέτρου guardrails
  4. Οι Έντεκα Κατηγορίες
  5. Τα Τρία Επίπεδα Εφαρμογής
  6. Τι Επιστρέφουν τα Guardrails
  7. Επιλογή του Σωστού Επιπέδου
  8. Βασικά σημεία

Μάθημα ξαναγράφηκε στις 3 Νοεμβρίου 2026. Η προηγούμενη έκδοση περιέγραφε μια ανύπαρκτη παράμετρο guardrails (ένα λεξικό με enabled), ανύπαρκτες κατηγορίες (hate, violence), μια missing μέθοδο conversation.send() στο SDK και φανταστικές αποκρίσεις JSON. Η επίσημη μορφή είναι μια λίστα διαμορφώσεων moderation_llm_v2, και οι αποκρίσεις παρακάτω ταιριάζουν με την τεκμηρίωση. Ο κώδικας έχει επαληθευτεί έναντι των τύπων SDK mistralai έκδοσης 3.7.0. Πηγές: Moderation & Guardrailing · mistralai Python SDK.

Η Αρχή των Προσαρμοσμένων Guardrails

Τα Προσαρμοσμένα Guardrails της Mistral λειτουργούν ως φίλτρο εισόδου: αναλύουν το prompt του χρήστη πριν αυτό φτάσει στο μοντέλο παραγωγής. Εάν το περιεχόμενο υπερβεί οποιοδήποτε όριο έχετε ορίσει, το αίτημα αποκλείεται με σφάλμα HTTP 403. Το μοντέλο δεν βλέπει ποτέ το προβληματικό prompt.

Κρατήστε στο μυαλό σας δύο περιορισμούς από την αρχή. Πρώτον, τα guardrails κάνουν moderation μόνο στην είσοδο· δεν ελέγχουν τι παράγει το μοντέλο. Αυτός είναι ο ρόλος του Moderation API (Μάθημα 5). Δεύτερον, αντικαθιστούν εργασία που διαφορετικά θα έπρεπε να κωδικοποιήσετε εσείς: κλήση του Moderation API, σύγκριση βαθμολογιών με τα κατώφλια σας και απόρριψη του αιτήματος.

Πώς Λειτουργεί

Όταν προσθέτετε guardrails σε ένα αίτημα, η ροή στην πλευρά της Mistral είναι η εξής:

  1. Η εφαρμογή σας στέλνει το αίτημα με την παράμετρο guardrails.
  2. Ο ταξινομητής mistral-moderation-2603 βαθμολογεί το prompt σε κάθε κατηγορία.
  3. Εάν μια βαθμολογία υπερβεί το κατώφλι της, το API επιστρέφει σφάλμα 403 και το μοντέλο δεν καλείται.
  4. Διαφορετικά, το μοντέλο επεξεργάζεται το αίτημα κανονικά.
  5. Η απόκριση περιλαμβάνει ένα πεδίο 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_v2True: αξιολογούνται μόνο οι αναφερόμενες κατηγορίες
actionμέσα στο moderation_llm_v2"block" για απόρριψη του αιτήματος εάν υπερβεί ένα κατώφλι
model_nameμέσα στο moderation_llm_v2, προαιρετικόΜοντέλο moderation διαφορετικό από το προεπιλεγμένο mistral-moderation-2603
block_on_errorδίπλα στο moderation_llm_v2True: το αίτημα αποκλείεται εάν αποτύχει η αξιολόγηση

Μπορείτε να τοποθετήσετε πολλαπλά αντικείμενα στη λίστα: το αίτημα αποκλείεται μόλις ενεργοποιηθεί έστω και ένα από αυτά. Κάθε αντικείμενο περιέχει μόνο μία διαμόρφωση 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)