Персонализирани предпазни механизми: Блокиране преди модела
На тази страница
Урокът е пренаписан на 3 ноември 2026 г. Предишната версия описваше фиктивен параметър
guardrails(речник сenabled'), несъществуващи категории (hate,violence), липсващ методconversation.send()в SDK и въображаеми JSON отговори. Официалният формат е **списък** от конфигурацииmoderation_llm_v2, а отговорите по-долу съответстват на документацията. Кодът е верифициран спрямо типовете наmistralai` SDK версия 3.7.0. Източници: Moderation & Guardrailing · mistralai Python SDK.
Принципът на персонализираните предпазни механизми
Персонализираните предпазни механизми (Custom Guardrails) на Mistral действат като филтър за входящи данни: те анализират подканата (prompt) на потребителя преди тя да достигне до генериращия модел. Ако съдържанието надвиши някой от зададените от Вас прагове, заявката се блокира с HTTP грешка 403. Моделът никога не вижда проблемната подкана.
Имайте предвид две ограничения от самото начало. Първо, предпазните механизми модерират само входните данни; те не проверяват какво генерира моделът. Това е ролята на API за модерация (Урок 5). Второ, те заместват работа, която иначе бихте трябвало да кодирате сами: извикване на API за модерация, сравняване на резултатите с Вашите прагове и отхвърляне на заявката.
Как работи
Когато добавите предпазни механизми към заявка, потокът от страна на Mistral е следният:
- Вашето приложение изпраща заявката с параметъра
guardrails. - Класификаторът
mistral-moderation-2603оценява подканата във всяка категория. - Ако резултатът надвиши прага, 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, # блокиране, ако самата модерация се провали
"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, по избор | Модел за модерация, различен от стандартния mistral-moderation-2603 |
block_on_error | наред с moderation_llm_v2 | True: заявката се блокира, ако оценяването се провали |
Можете да поставите множество обекти в списъка: заявката се блокира веднага щом някой от тях се активира. Всеки обект съдържа само една конфигурация moderation_llm_v2. По-стара конфигурация, moderation_llm_v1, все още съществува в SDK с категории от остарелия модел mistral-moderation-2411 (депрекиран на 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: Разговор (Conversation)
С 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 и документацията не уточнява дали предпазните механизми при стартиране се прилагат към последващи обороти. За гарантирана защита във всеки оборот, прикрепете предпазни механизми към агент.
Случай на употреба: Еднократен разговор без агент или заместване на предпазните механизми на агент за конкретна заявка.
Ниво 3: Агент
Предпазните механизми, предадени на 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!")
Случай на употреба: Продукционна среда, когато множество екипи или услуги извикват един и същ асистент.
Какво връщат предпазните механизми
Когато заявката премине успешно, отговорът на API включва, наред със стандартните полета, поле guardrails: списък с един резултат за всеки предпазен механизъм. Ето това поле от примера в документацията:
{
"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 | Conversation | Agent |
|---|---|---|---|
| Къде се декларират предпазните механизми | Във всяко извикване | При стартиране (start) | При създаване на агент |
| Наследяване | Няма | Недокументирано за последващи обороти | Всички разговори на агента |
| Може ли да се замени | — | — | Да, чрез заявка за разговор |
| Случай на употреба | Тестове, настройка на прагове | Еднократен разговор | Продукционна среда |
На практика, настройте праговете си върху заявки за Chat Completions, използвайки реални случаи, след което преместете политиката към агент веднага щом кодът напусне Вашата машина: няма да има повече забравени извиквания.
Ключови изводи
- Предпазните механизми блокират подканите преди модела чрез грешка
403; те не проверяват изхода - Параметърът е списък от обекти
{"block_on_error": ..., "moderation_llm_v2": {...}}, а не речник сenabled - Единадесет категории с фиксирани имена (
hate_and_discrimination,violence_and_threats, …), всяка с праг от 0 до 1;1деактивира - Три нива:
chat.complete(),conversations.start(),agents.create(); агентите предават своите предпазни механизми на всички свои разговори block_on_error=Trueосигурява поведение fail-safe (грешка3201)