Премини към основното съдържание
Български— Изберете език
Меню

Конфигуриране на предпазни механизми в Python

Урок 3 от 12 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. От теория към код
  2. Параметърът guardrails в детайли
  3. Пълен пример: чатбот с предпазни механизми
  4. Чисто обработване на грешки при блокиране
  5. Най-добри практики за конфигуриране
  6. Ключови изводи

Урокът е пренаписан на 3 ноември 2026 г. Предишната версия конфигурираше предпазните механизми чрез измислен речник (enabled), несъществуващи категории (hate, violence, unpredictable), твърдеше, че неизброените категории запазват „прагове по подразбиране“, и тестваше e.status_code == 3201, въпреки че 3201 е код за грешка в тялото на отговора, а не HTTP статус. Конфигурацията сега следва официалния формат, а кодът е проверен спрямо типовете на mistralai SDK 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