Начало работы с безопасностью документов чата для Python

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

• Авторизованный пользователь: этот пользователь должен иметь доступ к ответам, содержащимся в документах приложения чата.

  

• Неавторизованный пользователь: этот пользователь не должен иметь доступа к ответам из защищенных документов, которые у них нет авторизации для просмотра.

  

Обзор архитектуры

Без функции безопасности документов приложение корпоративного чата имеет простую архитектуру с помощью поиска ИИ Azure и Azure OpenAI. Ответ определяется из запросов к службе "Поиск ИИ Azure", где хранятся документы в сочетании с ответом модели Azure OpenAI GPT. В этом простом потоке проверка подлинности пользователя не используется.

Чтобы добавить безопасность документов, необходимо обновить корпоративное приложение чата:

• Добавьте проверку подлинности клиента в приложение чата с помощью Microsoft Entra.
• Добавьте серверную логику для заполнения индекса поиска доступом пользователей и групп.

Поиск azure AI не предоставляет собственные разрешения на уровне документа и не может изменять результаты поиска в индексе по разрешениям пользователя. Вместо этого приложение может использовать фильтры поиска, чтобы убедиться, что документ доступен конкретному пользователю или определенной группе. В индексе поиска каждый документ должен иметь фильтруемое поле, в котором хранятся сведения о пользователе или группе.

Так как авторизация не содержится в службе "Поиск ИИ Azure", необходимо добавить поле для хранения сведений о пользователе или группе, а затем отфильтровать все документы, которые не соответствуют. Для реализации этого метода необходимо выполнить следующие действия.

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

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

В этой статье процесс защиты документов в службе "Поиск ИИ Azure" осуществляется с использованием примерных сценариев, которые выполняются администратором поиска. Скрипты связывают один документ с одним удостоверением пользователя. Эти скрипты можно адаптировать, применив собственные требования к безопасности и условиям эксплуатации, чтобы масштабироваться под ваши нужды.

Определение конфигурации безопасности

Решение предоставляет логические переменные среды для включения функций, необходимых для обеспечения безопасности документов в этом примере.

Используйте следующие разделы, чтобы понять профили безопасности, поддерживаемые в этом примере. В этой статье настраивается профиль Enterprise.

Корпоративная: обязательная учетная запись + фильтр документов

Каждый пользователь сайта должен войти в систему. Сайт содержит содержимое, общедоступное для всех пользователей. Фильтр безопасности на уровне документа применяется ко всем запросам.

Переменные среды:

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true

Смешанное использование: необязательная учетная запись + фильтр документов

Каждый пользователь сайта может войти. Сайт содержит содержимое, общедоступное для всех пользователей. Фильтр безопасности на уровне документа применяется ко всем запросам.

Переменные среды:

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true
• AZURE_ENABLE_UNAUTHENTICATED_ACCESS=true

Предпосылки

Среда контейнера разработки доступна со всеми зависимостями , необходимыми для выполнения этой статьи. Контейнер разработки можно запустить в GitHub Codespaces (в браузере) или локально с помощью Visual Studio Code.

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

• Подписка Azure. Создайте его бесплатно.
• Разрешения учетной записи Azure: у вашей учетной записи Azure должны быть следующие:
  • Разрешение на управление приложениями в идентификаторе Microsoft Entra.
  • Microsoft.Authorization/roleAssignments/write разрешения, такие как администратор доступа пользователей или владелец.

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

Открытие среды разработки

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

Получение необходимых сведений с помощью Azure CLI

Получите идентификатор подписки и идентификатор клиента с помощью следующей команды Azure CLI. Скопируйте значение для использования в качестве вашего значения AZURE_TENANT_ID.

az account list --query "[].{subscription_id:id, name:name, tenantId:tenantId}" -o table

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

• Ваш первый тенант, связанный с вашей учетной записью пользователя, используется для переменной среды AZURE_TENANT_ID.
• Ваш второй тенант, без условного доступа, используется для переменной среды AZURE_AUTH_TENANT_ID для доступа к Microsoft Graph. Для клиентов с политикой условного доступа найдите идентификатор второго клиента без политики условного доступа или создайте новый клиент.

Настройка переменных среды

1. Выполните следующие команды, чтобы настроить приложение для профиля Enterprise .

   azd env set AZURE_USE_AUTHENTICATION true
   azd env set AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS true
   azd env set AZURE_ENFORCE_ACCESS_CONTROL true
   

2. Выполните следующую команду, чтобы задать арендатора, для авторизации пользователя в среде размещенного приложения. Замените <YOUR_TENANT_ID> идентификатором клиента.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Развертывание приложения чата в Azure

Развертывание состоит из следующих шагов:

• Создайте ресурсы Azure.
• Отправьте документы.
• Создайте приложения управления удостоверениями Microsoft Entra (клиентское и серверное).
• Включите идентификацию для ресурса размещения.

1. Подготовьте ресурсы Azure и разверните исходный код.

   azd up
   

2. Используйте следующую таблицу, чтобы ответить на AZD запросы на развертывание.

   Подсказка	Ответ
   Имя среды	Используйте короткое имя с информацией, которая идентифицирует, включая ваш псевдоним и приложение. И пример: tjones-secure-chat.
   Подписка	Выберите подписку, в которой нужно создать ресурсы.
   Расположение ресурсов Azure	Выберите местоположение рядом с вами.
   Расположение для documentIntelligentResourceGroupLocation	Выберите местоположение рядом с вами.
   Местоположение для openAIResourceGroupLocation	Выберите местоположение рядом с вами.

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

3. После успешного развертывания приложения в терминале появится URL-адрес.

4. Выберите URL-адрес, помеченный (✓) Done: Deploying service webapp для открытия приложения чата в браузере.

   

5. Примите всплывающее окно проверки подлинности приложения.

6. Когда появится приложение чата, обратите внимание на то, что в правом верхнем углу ваш пользователь вошел в систему.

7. Откройте параметры разработчика и обратите внимание, что оба следующих параметра выбраны и отключены для изменения:

   • Использование фильтра безопасности oid
   • Использование фильтра безопасности групп

8. Выберите карточку с надписью Что делает менеджер по продукту?.

9. Вы получите ответ, например: указанные источники не содержат конкретных сведений о роли диспетчера продуктов в Contoso Electronics.

   

Открытие доступа к документу для пользователя

Включите права доступа для конкретного документа, чтобы вы могли получить ответ. Вам потребуется несколько фрагментов информации:

• Служба хранилища Azure
  • Имя учетной записи
  • Имя контейнера
  • URL-адрес блоба или документа для role_library.pdf
• Идентификатор пользователя в идентификаторе Microsoft Entra

Когда эта информация известна, обновите поле индекса поиска oids ИИ Azure для role_library.pdf документа.

Получение URL-адреса документа в хранилище

1. .azure В папке в корне проекта найдите каталог среды и откройте .env файл с этим каталогом.

2. AZURE_STORAGE_ACCOUNT Найдите запись и скопируйте его значение.

3. Используйте следующие команды Azure CLI, чтобы получить URL-адрес BLOB-объекта role_library.pdf в контейнере content.

   az storage blob url \
       --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
       --container-name 'content' \
       --name 'role_library.pdf' 
   

   Параметр	Цель
   --account-name	служба хранилища Azure имя учетной записи.
   --container-name	Имя контейнера в этом примере .content
   --имя	Имя блоба на этом шаге role_library.pdf.

4. Скопируйте URL-адрес BLOB для последующего использования.

Получение идентификатора пользователя

1. В приложении чата выберите параметры разработчика.
2. Скопируйте objectidentifier параметр в разделе утверждений маркера идентификатора. Этот параметр известен в следующем разделе как USER_OBJECT_ID.

Предоставление пользователю доступа к документу в службе "Поиск Azure"

1. Используйте следующий скрипт, чтобы изменить поле oids в службе "Поиск ИИ Azure role_library.pdf" для доступа к нему.

   python ./scripts/manageacl.py --acl-type oids --acl-action add --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Параметр	Цель
   -v	Подробные выходные данные.
   --acl-type	Группа или пользовательские идентификаторы OID: oids.
   --acl-action	Добавить в поле поискового индекса. Другие варианты включают enable_acls, removeи remove_allview.
   --acl	Группа или пользователь USER_OBJECT_ID.
   --url	Расположение файла в службе хранилища Azure, например https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Не заключайте URL-адрес кавычками в команде CLI.

2. Выходные данные консоли для этой команды выглядят следующим образом:

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action add --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   Adding acl 00000000-0000-0000-0000-000000000000 to 58 search documents
   

3. При необходимости используйте следующую команду, чтобы убедиться, что ваше разрешение указано для файла в службе "Поиск ИИ Azure".

   python ./scripts/manageacl.py -v --acl-type groups --acl-action view --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Параметр	Цель
   -v	Подробные выходные данные.
   --acl-type	Идентификаторы группы или пользователя: oids.
   --acl-action	Просмотр поля индекса поиска oids. Другие варианты включают enable_acls, removeи remove_alladd.
   --url	Расположение файла в этом примере, например https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Не заключайте URL-адрес кавычками в команде CLI.

4. Выходные данные консоли для этой команды выглядят следующим образом:

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action view --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   [00000000-0000-0000-0000-000000000000]
   

   Массив, находящийся в конце выходных данных, включает ваш параметр USER_OBJECT_ID и используется для определения того, включается ли документ в ответ с использованием Azure OpenAI.

Убедитесь, что Azure AI Search содержит ваш USER_OBJECT_ID

1. Откройте портал Azure и найдите AI Search.

2. Выберите ресурс поиска из списка.

3. Выберите управление поиском>индексы.

4. Выберите gptkbindex.

5. Выберите Вид>JSON.

6. Замените JSON следующим кодом JSON:

   {
     "search": "*",
     "select": "sourcefile, oids",
     "filter": "oids/any()"
   }
   

   Этот JSON выполняет поиск всех документов, в которых поле oids имеет любое значение, и возвращает поля sourcefile и oids.

7. Если у role_library.pdf отсутствует ваш OID, вернитесь к разделу Предоставление доступа пользователю к документу в Поиске Azure и выполните шаги.

Проверка доступа пользователей к документу

Если вы выполнили действия, но не видите правильный ответ, убедитесь, что параметр USER_OBJECT_ID настроен правильно в поиске Azure AI role_library.pdf.

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

2. Введите тот же запрос, чтобы role_library содержимое использовалось в ответе Azure OpenAI: What does a product manager do?

3. Просмотрите результат, который теперь содержит соответствующий ответ из документа библиотеки ролей.

   

Очистите ресурсы

В следующих шагах описан процесс очистки используемых ресурсов.

Очистка ресурсов Azure

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

Выполните следующую команду Интерфейса командной строки разработчика Azure, чтобы удалить ресурсы Azure и удалить исходный код.

azd down --purge

Очистка GitHub Codespaces и Visual Studio Code

В следующих шагах описан процесс очистки используемых ресурсов.

Получите помощь

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

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

В этом разделе рассматриваются и решаются проблемы, специфичные для этой статьи.

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

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

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

   azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
   

   Параметр	Цель
   AZURE_AUTH_TENANT_ID	Если AZURE_AUTH_TENANT_ID задано, это клиент, на котором размещается приложение.

2. Повторно разверните решение с помощью следующей команды:

   azd up
   

Связанный контент

• Создайте чат-приложение с архитектурой решения Azure OpenAI, основанной на лучших практиках.
• Узнайте о управлении доступом в генеративных приложениях ИИ с помощью поиска Azure.
• Создайте корпоративное решение Azure OpenAI готовое для использования на предприятии, с помощьюсистемы управления API Azure.
• См. Azure AI Search: превосходящий векторный поиск благодаря гибридным возможностям извлечения и ранжирования.