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

Персонализирани предпазни механизми: Блокиране преди модела

Урок 2 от 12 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Принципът на персонализираните предпазни механизми
  2. Как работи
  3. Формат на параметъра guardrails
  4. Единадесетте категории
  5. Трите нива на приложение
  6. Какво връщат предпазните механизми
  7. Избор на правилното ниво
  8. Ключови изводи

Урокът е пренаписан на 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 е следният:

  1. Вашето приложение изпраща заявката с параметъра guardrails.
  2. Класификаторът mistral-moderation-2603 оценява подканата във всяка категория.
  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,          # блокиране, ако самата модерация се провали
        "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, по изборМодел за модерация, различен от стандартния mistral-moderation-2603
block_on_errorнаред с moderation_llm_v2True: заявката се блокира, ако оценяването се провали

Можете да поставите множество обекти в списъка: заявката се блокира веднага щом някой от тях се активира. Всеки обект съдържа само една конфигурация 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 CompletionsConversationAgent
Къде се декларират предпазните механизмиВъв всяко извикванеПри стартиране (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)