Настройка ограничителей и элементов управления в Microsoft Foundry

Узнайте, как создавать, настраивать и управлять ограничениями для развертываний моделей и агентов в Microsoft Foundry, используя портал Foundry или REST API.

Общие сведения о концепциях, рисках и точках вмешательства для защиты см. в обзоре Guardrails и элементов управления.

Необходимые условия

• Подписка Azure. Создайте его бесплатно.

• Проект Microsoft Foundry.

• В вашем проекте должно быть по крайней мере одно развертывание модели.

• Владелец учетной записи Foundry или роль выше на ресурсе Azure AI.

  Важно

  Недавно были переименованы роли RBAC в Foundry. Foundry User, Foundry Owner, Foundry Account Owner и Foundry Project Manager ранее назывались пользователь Azure AI, владелец Azure AI, владелец учетной записи Azure AI и руководитель проекта Azure AI. Пока новое название внедряется, в некоторых местах вы всё ещё можете видеть прежние названия. Идентификаторы ролей и основные разрешения не меняются из-за переименования.

Доступность

См. сведения о доступности регионов.

Создание ограждения в Foundry

1. Перейдите в Foundry и перейдите к проекту.
2. Выберите Сборка в правом верхнем меню.
3. Выберите страницу Guardrails в левом меню навигации.
4. Выберите Create Guardrail в правом верхнем углу. Откроется мастер ограждений с первым шагом: добавление элементов управления.

Добавьте элементы управления к ограждению

Управляющие элементы по умолчанию отображаются на правой панели при создании нового ограничителя.

1. Выберите риск из раскрывающегося меню.

2. Выберите точки вмешательства и действия: показаны рекомендуемые точки вмешательства и действия для этого риска. Выберите одну или несколько точек вмешательства и одно действие, чтобы настроить элемент управления.

   Примечание

   Некоторые точки вмешательства не будут доступны для риска, если это неприменимо в этой точке вмешательства. Например, по определению атаки на входные данные пользователей — это вредоносное содержимое, добавленное в входные данные пользователя. Таким образом, этот риск может быть сканирован только в этой точке вмешательства.

3. Выберите "Добавить элемент управления". Элемент управления добавляется в таблицу справа.

Удаление элементов управления из сторожевой границы

Удаление элемента управления:

1. Выберите элемент управления, который нужно удалить.
2. Нажмите кнопку "Удалить".

Изменение элементов управления в ограждении

Существует два способа редактирования элемента управления: удаление и добавление нового элемента управления или переопределение существующего элемента управления. Единственный способ изменить элемент управления, который не может быть удален, например, управление элементами, связанными с насилием, ненавистью, сексуальностью и самоповреждением, во входных и выходных данных пользователей.

Чтобы изменить элемент управления, переопределив его:

1. Выберите тот же риск, связанный с элементом управления, который необходимо изменить.
2. Измените конфигурацию элемента управления, точки вмешательства и действие по мере необходимости.
3. Выберите "Добавить элемент управления".
4. Всплывающее окно запрашивает подтверждение, чтобы переопределить существующий элемент управления. Нажмите кнопку "Подтвердить".

Назначить ограничения агентам и моделям

После добавления, редактирования и (или) удаления элементов управления по мере необходимости:

1. Выберите Далее, чтобы перейти к шагу 2: назначение ограничений агентам и/или моделям.
2. Выберите "Добавить агенты " и /или "Добавить модели ", чтобы просмотреть список агентов и моделей в этом проекте.
3. Выберите модели или агенты. Ранее назначенных агентов и модели также можно снять выделение, чтобы удалить это ограничение и повторно назначить настройки Microsoft по умолчанию.
4. Нажмите кнопку "Сохранить", чтобы подтвердить. Появится уведомление об успешном выполнении.

Проверка и защита имен

1. Нажмите кнопку "Далее", чтобы перейти к шагу 3. Проверьте.
2. Просмотрите элементы управления, добавленные в этот guardrail, и модели и (или) агент, которым он назначен.
3. Назовите ограждение или оставьте автоматически присвоенное имя.
4. Нажмите кнопку "Создать". Guardrail отображается в списке на странице Guardrails и применим к выбранным моделям и агентам.

Изменение существующего предохранителя

1. Выберите Сборка в правом верхнем меню.

2. Выберите страницу Guardrails в левом меню навигации.

3. Найдите защитное средство в списке защитных средств. Выберите его имя напрямую или выберите его строку, а затем нажмите Изменить в области сведений.

   Примечание

   Microsoft не позволяет редактировать защитные ограничения по умолчанию, такие как Default.V2.

4. Выполните те же инструкции, что и в разделе "Создание ограждения " для редактирования, добавления или удаления элементов управления; назначение или повторное назначение агентов и (или) моделей; и при необходимости переименуйте guardrail.

Назначить ограничитель

Существует два пути для назначения охранника модели или агента:

Вариант 1. Изменение сторожевой границы

1. Выберите Сборка в правом верхнем меню.
2. Выберите страницу Guardrails в левом меню навигации.
3. Найдите защитное средство в списке защитных средств. Выберите его имя напрямую или выберите его строку, а затем нажмите Изменить в области сведений.
4. Нажмите кнопку "Далее " на шаге 1. Добавьте элементы управления, чтобы перейти к шагу назначения.
5. Выберите «Добавить агентов» или «Добавить модели» и по мере необходимости выберите или снимите выбор с моделей и/или агентов, чтобы обновить назначение ограждения.

Вариант 2. Изменение модели или агента

1. Выберите Сборка в правом верхнем меню.
2. Выберите агенты или модели в области навигации слева.
3. Выберите агента или модель, которую хотите обновить.
4. Раздел для Guardrails отображается на левой панели игровой площадки агента или игровой площадки чата.
5. Выберите "Управление" в нижней части раздела Guardrails.
6. Выберите Назначить новое ограждение.
7. Обзор направляющих, доступных в этом проекте.
8. Выберите нужное ограждение из списка слева от всплывающего интерфейса.
9. Выберите «Назначить», чтобы обновить назначение ограждения для агента или модели. Новое ограждение начинает работать немедленно.

Удаление ограждения

Удалить ограничитель без назначенных моделей или агентов

1. Выберите Сборка в правом верхнем меню.
2. Выберите страницу Guardrails в левом меню навигации.
3. Найдите ограждение в списке ограждений и выберите его строку.
4. Панель отображается справа. Выберите "Удалить" в верхней части панели.

Удаление ограждения с назначенными моделями или агентами

1. Переназначьте модели или агентов на другой ограничитель или удалите их из этого ограничителя, чтобы их переназначить на Основные ограничители Microsoft.
2. Следуйте инструкциям, чтобы удалить ограждение, к которому не прикреплены модели или агенты.

Тестовые ограждения

Чтобы проверить поведение определенного ограждения, выполните следующие действия:

1. Выберите Сборка в правом верхнем меню.

2. Выберите страницу Guardrails в левом меню навигации.

3. Найдите ограждение в списке ограждений и выберите его строку.

4. Панель отображается справа. Выберите Попробовать на площадке в верхней части панели.

   Примечание

   Если эта кнопка не отображается, сначала назначьте это ограждение модели или агенту. Назначение ограничителя немедленно изменяет поведение системы безопасности, поэтому используйте непромышленную модель или агент для тестирования.

5. На песочнице отправьте запросы к модели или агенту.

6. Если контрол с действием «Annotate and block» был активирован, в чате появляется сообщение с подробными сведениями о том, какой риск был обнаружен и в какой точке вмешательства.

Настройка ограничений через REST API

В REST API служб ИИ Azure защита представлена как политика RAI — объект уровня ресурсов в Azure Resource Manager.

Создание или обновление ограждения

Используйте операцию RAI Policies - Create Or Update для создания или обновления ограничения. Укажите элементы управления (правила фильтрации содержимого) в тексте запроса, включая категорию риска, уровень серьезности и блокировку или аннотацию.

Назначить ограничение к развертыванию модели

Установите свойство raiPolicyName в развертывании, чтобы назначить ограничение. Используйте функцию "Deployments - Create Or Update" и добавьте название guardrail в свойства развертывания.

Работа с заметками

Foundry предоставляет аннотации, помогающие понять результаты «guardrail» для ваших запросов. Заметки можно включить даже для фильтров и уровней серьезности, которые были отключены для блокировки содержимого.

Стандартные заметки ограждения

Если заметки включены, следующие сведения возвращаются через API для категорий ненависти, сексуального контента, насилия и вреда самому себе:

• Категория риска (ненависть, сексуальное насилие, self_harm)
• Уровень серьезности (безопасный, низкий, средний или высокий) в каждой категории содержимого
• Состояние фильтрации (true или false)

Необязательные аннотации модели

Необязательные заметки модели можно задать для режима анотации (возвращает сведения, когда содержимое помечается, но не фильтруется) или режим фильтра (возвращает сведения, когда содержимое помечается и фильтруется).

Совместимость версий API

В следующей таблице показана доступность режима заметки в каждой версии API:

¹ Недоступен в сценариях, отличных от потоковой передачи; доступно только для сценариев потоковой передачи.

Выбор версии API

• Для рабочих развертываний: используйте последнюю версию общедоступной версии (2024-02-01) для обеспечения стабильности и поддержки.
• Для обнаружения персональных идентификационных данных (PII): используйте 2025-01-01-preview или более позднюю версию.
• Для обнаружения заземления: используйте 2025-01-01-preview или более поздней версии.
• Для обнаружения косвенных атак: используйте 2024-04-01-preview или более поздней версии.

Предварительные версии API включают последние функции, но могут иметь критические изменения. Перед развертыванием всегда тестируйте предварительные версии функций в непроизводственных средах.

Примеры кода

В следующих фрагментах кода показано, как просматривать заметки guardrail на разных языках программирования.

Установка зависимостей

Перед выполнением примеров кода установите необходимые библиотеки:

pip install openai>=1.0.0

npm install openai@^4.0.0

Просмотр заметок

# os.getenv() for the endpoint and key assumes that you are using environment variables.

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-03-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT") 
)

response = client.completions.create(
    model="gpt-35-turbo-instruct", # model = "deployment_name".
    prompt="{Example prompt where a severity level of low is detected}" 
    # Content that is detected at severity level medium or high is filtered, 
    # while content detected at severity level low isn't filtered by the content filters.
)

print(response.model_dump_json(indent=2))

const { OpenAI } = require('openai');

const client = new OpenAI({
  apiKey: process.env.AZURE_OPENAI_API_KEY,
  baseURL: `${process.env.AZURE_OPENAI_ENDPOINT}/openai/deployments/gpt-35-turbo-instruct`,
  defaultQuery: { 'api-version': '2024-03-01-preview' },
  defaultHeaders: {
    'api-key': process.env.AZURE_OPENAI_API_KEY,
  },
});

async function main() {
  const completion = await client.completions.create({
    model: '',
    prompt: 'Example prompt where a severity level of low is detected',
  });

  console.log(JSON.stringify(completion, null, 2));
}

main();

Пример выходных данных

{
  "choices": [
    {
      "content_filter_results": {
        "hate": {
          "filtered": false,
          "severity": "safe"
        },
        "protected_material_code": {
          "citation": {
            "URL": "https://github.com/username/repository-name/path/to/file-example.txt",
            "license": "EXAMPLE-LICENSE"
          },
          "detected": true,
          "filtered": false
        },
        "protected_material_text": {
          "detected": false,
          "filtered": false
        },
        "self_harm": {
          "filtered": false,
          "severity": "safe"
        },
        "sexual": {
          "filtered": false,
          "severity": "safe"
        },
        "violence": {
          "filtered": false,
          "severity": "safe"
        }
      },
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Example model response will be returned",
        "role": "assistant"
      }
    }
  ],
  "created": 1699386280,
  "id": "chatcmpl-8IMI4HzcmcK6I77vpOJCPt0Vcf8zJ",
  "model": "gpt-35-turbo-instruct",
  "object": "text.completion",
  "usage": {
    "completion_tokens": 40,
    "prompt_tokens": 11,
    "total_tokens": 417
  },
  "prompt_filter_results": [
    {
      "content_filter_results": {
        "hate": {
          "filtered": false,
          "severity": "safe"
        },
        "jailbreak": {
          "detected": false,
          "filtered": false
        },
        "profanity": {
          "detected": false,
          "filtered": false
        },
        "self_harm": {
          "filtered": false,
          "severity": "safe"
        },
        "sexual": {
          "filtered": false,
          "severity": "safe"
        },
        "violence": {
          "filtered": false,
          "severity": "safe"
        }
      },
      "prompt_index": 0
    }
  ]
}

Дополнительные сведения о конечных точках REST API инференции для Azure OpenAI и о создании чатов и завершений см. в Руководство по REST API Azure OpenAI. Аннотации возвращаются для всех сценариев при использовании любой предварительной версии API, начиная с 2023-06-01-preview, а также для общедоступной версии API 2024-02-01.

Внедрение документов в запросы

Средства Guardrail работают лучше, если они могут различать различные элементы запроса, такие как системные входные данные, входные данные пользователя и выходные данные помощника по искусственному интеллекту. Для расширенных возможностей обнаружения запросы должны быть отформатированы в соответствии со следующими рекомендуемыми методами.

Поведение по умолчанию в API завершения чата

API завершения чата структурирован по определению. Входные данные состоят из списка сообщений, каждый из которых имеет назначенную роль.

Система безопасности анализирует этот структурированный формат и применяет следующее поведение:

На последнем "пользовательском" содержимом обнаруживаются следующие категории рисков:

• Ненавижу
• Сексуальный
• Насилия
• Самоповреждение
• Подсказки (необязательно)

Пример массива сообщений:

[
  {"role": "system", "content": "Provide some context and/or instructions to the model."},
  {"role": "user", "content": "Example question goes here."},
  {"role": "assistant", "content": "Example answer goes here."},
  {"role": "user", "content": "First question/message for the model to actually respond to."}
]

Встраивание документов в ваш запрос

Помимо обнаружения последнего содержимого пользователя, системы защиты также поддерживают обнаружение специфических рисков в контекстных документах с помощью щитов запроса — обнаружение атак через непрямые запросы и проверка обоснованности информации. Необходимо определить части данных на входе, которые являются документом (например, извлеченным веб-сайтом, электронной почтой и т. д.) со следующим разделителем документов:

""" <documents> *insert your document content here* </documents> """

В этом случае для обнаружения в помеченных документах доступны следующие опции:

• Косвенные атаки (необязательно)
• Обнаружение заземления

Пример массива сообщений о завершении чата:

[
  {"role": "system", "content": "Provide some context and/or instructions to the model."},
  {"role": "user", "content": "First question/message for the model to actually respond to, including document context. \"\"\" <documents>\n*insert your document content here*\n</documents> \"\"\""}
]

Экранирование JSON

Если вы помечаете непроверенные документы для обнаружения, содержимое документа должно быть экранировано в формате JSON, чтобы обеспечить успешный разбор системой безопасности Azure AI.

Например, см. следующий текст сообщения электронной почты:

Hello José,

I hope this email finds you well today.

После экранирования JSON это будет читаться как:

Hello Jos\u00E9,\nI hope this email finds you well today.

Изолированный текст в контексте завершения чата читается:

[
  {"role": "system", "content": "Provide some context and/or instructions to the model, including document context. \"\"\" <documents>\n Hello Jos\\u00E9,\\nI hope this email finds you well today. \n</documents> \"\"\""},
  {"role": "user", "content": "First question/message for the model to respond to"}
]

Укажите конфигурацию ограждения в момент запроса

Помимо ограничителя уровня развертывания модели, можно указать собственный ограничитель для каждого вызова API в момент запроса, используя заголовок запроса.

curl --request POST \
    --url 'URL' \
    --header 'Content-Type: application/json' \
    --header 'api-key: API_KEY' \
    --header 'x-policy-id: CUSTOM_CONTENT_FILTER_NAME' \
    --data '{
        "messages": [
            {
                "role": "system",
                "content": "You are a creative assistant."
            },
            {
                "role": "user",
                "content": "Write a poem about the beauty of nature."
            }
        ]
    }'

Конфигурация защиты уровня запроса переопределит конфигурацию уровня развертывания для конкретного вызова API.

Если указана конфигурация, которая не существует, возвращается следующее сообщение об ошибке:

{
    "error": {
        "code": "InvalidContentFilterPolicy",
        "message": "Your request contains invalid content filter policy. Please provide a valid policy."
    }
}

Лучшие практики

Следуйте этим рекомендациям при настройке ограничителей:

• Тестирование перед рабочей средой. Перед применением изменений в рабочих развертываниях используйте игровую площадку для тестирования поведения защиты.
• Начните с ограничений, а потом ослабьте их: начните с более высоких пороговых значений серьезности и уменьшайте их только после подтверждения приемлемого поведения.
• Тестируйте вашу конфигурацию с использованием red-team: Выполните тестирование red-team, стресс-тестирование и анализ, чтобы выявить потенциальные угрозы, характерные для вашей модели, приложения и сценария развертывания.
• Измерение после изменений: После внедрения или обновления ограничений повторите процесс измерения, чтобы убедиться в их эффективности.
• Мониторинг влияния на производительность: обработка Guardrail добавляет приблизительно 50–100 мс задержки на точку воздействия. Для сценариев высокой пропускной способности начните только с основных элементов управления и отслеживайте метрики задержки.

Полные рекомендации по ответственному ИИ см. в обзоре ответственного ИИ.

Устранение неполадок

Дальнейшие действия

• Обзор ограничителей и элементов управления
• Точки вмешательства и элементы управления
• Фильтрация содержимого
• Настройка фильтров содержания для Azure OpenAI