Конфигуриране на предпазни механизми в Python
На тази страница
Урокът е пренаписан на 3 ноември 2026 г. Предишната версия конфигурираше предпазните механизми чрез измислен речник (
enabled), несъществуващи категории (hate,violence,unpredictable), твърдеше, че неизброените категории запазват „прагове по подразбиране“, и тествашеe.status_code == 3201, въпреки че3201е код за грешка в тялото на отговора, а не HTTP статус. Конфигурацията сега следва официалния формат, а кодът е проверен спрямо типовете наmistralaiSDK 3.7.0. Източници: Moderation & Guardrailing · mistralai Python SDK.
От теория към код
Сега разбирате как работят предпазните механизми. В този урок ще ги конфигурирате прецизно: ще изберете категориите си, ще дефинирате праговете и ще обработвате блокиранията във вашия Python код.
Започнете с инсталиран Mistral SDK (предпазните механизми изискват версия 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",
},
}
]
Моделът за модериране по подразбиране е mistral-moderation-2603; незадължителният ключ model_name Ви позволява да посочите различен.
Анотацията list[GuardrailConfigTypedDict] не е задължителна, но си струва да я използвате: SDK описва всеки позволен ключ, така че проверка на типовете като pyright или mypy ще сигнализира за правописна грешка в категорията (violence вместо violence_and_threats), която самото API не би уловило.
custom_category_thresholds
Това е сърцето на конфигурацията. Всяка категория получава праг между 0 и 1, който се сравнява с резултата, присвоен от класификатора на подкана. Колкото по-нисък е прагът, толкова повече филтърът блокира, с риска да отхвърли легитимни заявки. Праг от 1 изрично деактивира категорията. Mistral не публикува препоръчителна мрежа от стойности: трябва да калибрирате тези стойности върху собствените си примери (урок 7).
Стойностите имат смисъл само в контекста на Вашето приложение. Чатбот, насочен към широката публика, заключва чувствителните категории при най-ниските настройки, докато вътрешен инструмент за здравни специалисти трябва да позволява медицински въпроси, оставайки строг относно личните данни.
# Публичен чатбот: много ниски прагове
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) или заявка за лични данни биха преминали непроверени. Ограничете списъка само по конкретна причина.
Пълен пример: чатбот с предпазни механизми
Ето една минимална функция: тя изпраща съобщението с пълната конфигурация и превръща блокирането в четим отговор за потребителя.
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 "Съжаляваме, тази заявка не може да бъде обработена."
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, и неуспех при оценката на модерирането с активиран 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]:
"""Чат, който разграничава блокиранията по политика от неуспехите при модериране."""
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": "Услугата за модериране е недостъпна. Заявката е блокирана като предпазна мярка.",
}
if e.status_code == 403:
decisions = corps["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Съобщението Ви беше блокирано от нашата политика за сигурност.",
"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, и тогава неуспех при модерирането би пропуснал непроверено съдържание. Накрая, документацията предупреждава, че моделът за модериране еволюира: политиките, базирани на резултати, може да изискват прекалибриране.
Ключови изводи
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