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

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

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

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

Примечание.

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

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

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

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

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

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

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

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

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

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

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

Параметр	Характер использования
AZURE_USE_AUTHENTICATION	Если задано значениеtrue, включает вход пользователя в приложение чата и Служба приложений проверку подлинности. Use oid security filter Включается в параметрах разработчика приложения чата.
AZURE_ENFORCE_ACCESS_CONTROL	Если задано значение true, требуется проверка подлинности для доступа к документам. Параметры разработчика для безопасности oid и группы будут включены и отключены, чтобы они не могли быть отключены из пользовательского интерфейса.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS	Если задано значение true, этот параметр позволяет прошедшим проверку подлинности пользователям выполнять поиск по документам, у которых нет назначенных элементов управления доступом, даже если требуется управление доступом. Этот параметр следует использовать только при AZURE_ENFORCE_ACCESS_CONTROL включении.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS	Если задано значение true, этот параметр позволяет пользователям, не прошедшим проверку подлинности, использовать приложение, даже если применяется управление доступом. Этот параметр следует использовать только при AZURE_ENFORCE_ACCESS_CONTROL включении.

Используйте следующие разделы, чтобы понять профили безопасности, поддерживаемые в этом примере. В этой статье настраивается профиль 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/разрешения на запись, такие как администратор доступа пользователей или владелец.
• Службе Azure OpenAI предоставлен доступ в требуемой подписке Azure В настоящее время доступ к этой службе предоставляется только приложением. Вы можете подать заявку на доступ к Azure OpenAI, выполнив форму по адресу https://aka.ms/oai/access.

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

Пространства кода (рекомендуется)

• Учетная запись GitHub

Visual Studio Code

• Интерфейс командной строки разработчика Azure
• Docker Desktop — запустите Docker Desktop , если он еще не запущен
• Visual Studio Code
• Расширение контейнера разработки

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

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

Пространства кода GitHub (рекомендуется)

GitHub Codespaces запускает контейнер разработки, управляемый GitHub, с Помощью Visual Studio Code для Интернета в качестве пользовательского интерфейса. Для наиболее простой среды разработки используйте GitHub Codespaces, чтобы у вас были правильные средства разработчика и зависимости, предварительно установленные для выполнения этой статьи.

Внимание

Все учетные записи GitHub могут использовать пространства Кода до 60 часов бесплатно каждый месяц с 2 основными экземплярами. Дополнительные сведения см. в GitHub Codespaces ежемесячно включаемых в хранилище и основные часы.

1. Запустите процесс создания нового пространства кода GitHub в main ветви Azure-Samples/azure-search-openai-demo репозитория GitHub.

2. Щелкните правой кнопкой мыши следующую кнопку и выберите "Открыть ссылку" в новых окнах , чтобы одновременно иметь среду разработки и документацию.

   

3. На странице "Создание пространства кода" просмотрите параметры конфигурации пространства кода и выберите "Создать новое пространство кода"

   

4. Дождитесь запуска пространства кода. Этот процесс запуска может занять несколько минут.

5. В терминале в нижней части экрана войдите в Azure с помощью Интерфейса командной строки разработчика Azure.

   azd auth login
   

6. Завершите процесс проверки подлинности.

7. Остальные задачи в этой статье выполняются в контексте этого контейнера разработки.

Visual Studio Code

Расширение "Контейнеры разработки" для Visual Studio Code требует установки Docker на локальном компьютере. Расширение размещает контейнер разработки локально с помощью узла Docker с правильными средствами разработчика и предустановленными зависимостями для выполнения этой статьи.

1. Создайте локальный каталог на компьютере для проекта.

   mkdir my-intelligent-app && cd my-intelligent-app
   

2. Откройте Visual Studio Code в этом каталоге:

   code .
   

3. Откройте новый терминал в Visual Studio Code.

4. Выполните следующую команду AZD, чтобы перенести репозиторий GitHub на локальный компьютер.

   azd init -t azure-search-openai-demo
   

5. Откройте палитру команд, найдите и выберите "Контейнеры разработки": откройте папку в контейнере, чтобы открыть проект в контейнере разработки. Дождитесь, пока контейнер разработки не откроется, прежде чем продолжить.

6. Войдите в Azure с помощью Интерфейса командной строки разработчика Azure.

   azd auth login
   

   Скопируйте код из терминала и вставьте его в браузер. Следуйте инструкциям по проверке подлинности с помощью учетной записи Azure.

7. Остальные упражнения в этом проекте происходят в контексте этого контейнера разработки.

Получение необходимых сведений с помощью 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, чтобы подготовить ресурсы Azure и развернуть исходный код:

   azd up
   

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

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

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

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

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

   

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

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

7. Откройте параметры разработчика и обратите внимание, что эти параметры выбраны и выделены серым цветом (отключены для изменения).

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

8. Выберите карточку с What does a product manager do?.

9. Вы получите ответ, например: The provided sources do not contain specific information about the role of a Product Manager at 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-адрес большого двоичного объекта role_library.pdf в контейнере содержимого.

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

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

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

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

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

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

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

   ./scripts/manageacl.sh \
       -v \
       --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	Добавьте в поле индекса поиска. Другие варианты включают remove, remove_all, list.
   --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".

   ./scripts/manageacl.sh \
       -v \
       --acl-type oids \
       --acl-action list \
       --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
       --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Параметр	Характер использования
   -v	Подробные выходные данные.
   --acl-type	Группа или пользователь (oids): oids
   --acl-action	Вывод списка поля oidsиндекса поиска. Другие варианты включают remove, remove_all, list.
   --acl	Группа или пользователь USER_OBJECT_ID
   --url	Расположение файла в хранилище Azure, например 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.

Проверка USER_OBJECT_ID поиска Azure ИИ

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

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

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

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

5. Выберите представление> JSON.

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

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

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

7. Если у role_library.pdf вас нет oid, вернитесь к документу в разделе "Поиск Azure" и выполните действия.

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

Если вы выполнили действия, но не видите правильный ответ, убедитесь, что USER_OBJECT_ID настроен правильно в поиске ИИ Azure.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

GitHub Codespaces

Удаление среды GitHub Codespaces гарантирует, что вы можете максимально увеличить объем бесплатных прав на базовые часы, которые вы получаете для вашей учетной записи.

Внимание

Дополнительные сведения о правах учетной записи GitHub см . в GitHub Codespaces ежемесячно включено в хранилище и основные часы.

1. Войдите на панель мониторинга GitHub Codespaces (https://github.com/codespaces).

2. Найдите текущие запущенные пространства Codespaces, полученные из Azure-Samples/azure-search-openai-demo репозитория GitHub.

   

3. Откройте контекстное меню для пространства кода и нажмите кнопку "Удалить".

   

Visual Studio Code

Для очистки локальной среды не обязательно требуется, но вы можете остановить запущенный контейнер разработки и вернуться к запуску Visual Studio Code в контексте локальной рабочей области.

1. Откройте палитру команд, найдите команды "Контейнеры разработки", а затем выберите "Контейнеры разработки: открыть папку локально".

   

Совет

Visual Studio Code остановит запущенный контейнер разработки, но контейнер по-прежнему существует в Docker в остановленном состоянии. Вы всегда можете удалить экземпляр контейнера, образ контейнера и тома из Docker, чтобы освободить больше места на локальном компьютере.

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

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

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

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

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

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

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"
• Создание готового решения OpenAI enterprise с помощью Azure Управление API
• Перебор векторного поиска с гибридными возможностями извлечения и ранжирования