Introdução à segurança de documentos de chat para Python

Ao criar um aplicativo de bate-papo usando o padrão de geração aumentada de recuperação (RAG) com seus próprios dados, certifique-se de que cada usuário receba uma resposta com base em suas permissões. Siga o processo neste artigo para adicionar controle de acesso a documentos ao seu aplicativo de bate-papo.

• Usuário autorizado: essa pessoa deve ter acesso às respostas contidas nos documentos do aplicativo de bate-papo.

  

• Usuário não autorizado: essa pessoa não deve ter acesso a respostas de documentos seguros que não tem autorização para ver.

  

Observação

Este artigo usa um ou mais modelos de aplicação de IA como base para os exemplos e orientações no artigo. Os modelos de aplicativos de IA fornecem implementações de referência bem mantidas que são fáceis de implantar. Eles ajudam a garantir um ponto de partida de alta qualidade para seus aplicativos de IA.

Visão geral da arquitetura

Sem uma funcionalidade de segurança documental, a aplicação de chat empresarial tem uma arquitetura simples, utilizando Azure AI Search e Azure OpenAI Models no Microsoft Foundry. Uma resposta é determinada a partir de consultas ao Azure AI Search onde os documentos são armazenados, em combinação com uma resposta de um modelo GPT OpenAI do Azure. Nenhuma autenticação de usuário é usada nesse fluxo simples.

Para adicionar segurança aos documentos, você precisa atualizar o aplicativo de bate-papo corporativo:

• Adicione autenticação de cliente ao aplicativo de chat com o Microsoft Entra.
• Adicione lógica do lado do servidor para preencher um índice de pesquisa com acesso de usuário e grupo.

O Azure AI Search não fornece permissões nativas no nível do documento e não pode variar os resultados da pesquisa de dentro de um índice por permissões de usuário. Em vez disso, seu aplicativo pode usar filtros de pesquisa para garantir que um documento seja acessível a um usuário específico ou por um grupo específico. Dentro do seu índice de pesquisa, cada documento deve ter um campo filtrável que armazena informações de identidade de usuário ou grupo.

Como a autorização não está contida nativamente no Azure AI Search, você precisa adicionar um campo para armazenar informações de usuário ou grupo e, em seguida, filtrar quaisquer documentos que não correspondam. Para implementar essa técnica, você precisa:

• Crie um campo de controle de acesso a documentos em seu índice dedicado a armazenar os detalhes de usuários ou grupos com acesso a documentos.
• Preencha o campo de controle de acesso do documento com os detalhes relevantes do usuário ou grupo.
• Atualize este campo de controle de acesso sempre que houver alterações nas permissões de acesso de usuário ou grupo.

Se as atualizações de índice forem agendadas com um indexador, as alterações serão captadas na próxima execução do indexador. Se você não usar um indexador, precisará reindexar manualmente.

Neste artigo, o processo de proteção de documentos no Azure AI Search é possível com scripts de exemplo , que você, como administrador de pesquisa, executaria. Os scripts associam um único documento a uma única identidade de usuário. Você pode utilizar esses scripts e aplicar os seus próprios requisitos de segurança e produção para escalar conforme as suas necessidades.

Determinar a configuração de segurança

A solução fornece variáveis de ambiente booleano para ativar os recursos necessários para a segurança do documento neste exemplo.

Parâmetro	Propósito
AZURE_USE_AUTHENTICATION	Quando definido como true, habilita a entrada do usuário no aplicativo de chat e a autenticação do Serviço de Aplicativo do Azure. Habilita Use oid security filter nas configurações do desenvolvedor do aplicativo de bate-papo.
AZURE_ENFORCE_ACCESS_CONTROL	Quando definido como true, requer autenticação para qualquer acesso a documentos. As configurações do desenvolvedor para ID de objeto (OID) e segurança de grupo são ativadas e desabilitadas para que não possam ser desabilitadas da interface do usuário.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS	Quando definida como true, essa configuração permite que usuários autenticados pesquisem em documentos que não têm controles de acesso atribuídos, mesmo quando o controle de acesso é necessário. Este parâmetro deve ser usado somente quando AZURE_ENFORCE_ACCESS_CONTROL estiver habilitado.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS	Quando definida como true, essa configuração permite que usuários não autenticados usem o aplicativo, mesmo quando o controle de acesso é imposto. Este parâmetro deve ser usado somente quando AZURE_ENFORCE_ACCESS_CONTROL estiver habilitado.

Use as seções a seguir para entender os perfis de segurança suportados neste exemplo. Este artigo configura o perfil Enterprise.

Empresa: Conta obrigatória + filtro de documentos

Cada utilizador do site tem de iniciar sessão. O site contém conteúdo público para todos os usuários. O filtro de segurança no nível do documento é aplicado a todas as solicitações.

Variáveis de ambiente:

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

Uso misto: Conta opcional + filtro de documentos

Cada utilizador do site pode iniciar sessão. O site contém conteúdo público para todos os usuários. O filtro de segurança no nível do documento é aplicado a todas as solicitações.

Variáveis de ambiente:

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

Pré-requisitos

Um ambiente de contêiner de desenvolvimento está disponível com todas as dependências necessárias para concluir este artigo. Você pode executar o contêiner de desenvolvimento no GitHub Codespaces (em um navegador) ou localmente usando o Visual Studio Code.

Para usar este artigo, você precisa dos seguintes pré-requisitos:

• Uma assinatura do Azure. Crie um gratuitamente.
• Permissões da conta do Azure: sua conta do Azure deve ter:
  • Permissão para gerenciar aplicativos no Microsoft Entra ID.
  • Microsoft.Authorization/roleAssignments/write permissões, como Administrador de Acesso de Usuário ou Proprietário.

Você precisa de mais pré-requisitos, dependendo do seu ambiente de desenvolvimento preferido.

GitHub Codespaces (recomendado)

• Conta do GitHub

Código do Visual Studio

• CLI do desenvolvedor do Azure.
• Área de trabalho do Docker. Inicie o Docker Desktop se ainda não estiver em execução.
• Código do Visual Studio.
• extensão Dev Containers.

Abra um ambiente de desenvolvimento

Use as instruções a seguir para implantar um ambiente de desenvolvimento pré-configurado contendo todas as dependências necessárias para concluir este artigo.

GitHub Codespaces (recomendado)

GitHub Codespaces executa um contentor de desenvolvimento gerido pelo GitHub com o Visual Studio Code for the Web como interface de utilizador. Para o ambiente de desenvolvimento mais simples, use o GitHub Codespaces para que você tenha as ferramentas de desenvolvedor corretas e as dependências pré-instaladas para concluir este artigo.

Importante

Todas as contas do GitHub podem usar o GitHub Codespaces por até 60 horas gratuitas por mês com duas instâncias principais. Para mais informações, consulte o armazenamento mensal incluído e as horas principais do GitHub Codespaces.

1. Inicie o processo para criar um novo espaço de código GitHub na main ramificação do repositório GitHub Azure-Samples/azure-search-openai-demo .

2. Clique com o botão direito do mouse no botão a seguir e selecione Abrir link em novas janelas para ter o ambiente de desenvolvimento e a documentação disponíveis ao mesmo tempo.

   

3. Na página Criar espaço de código , revise as definições de configuração do espaço de código e selecione Criar novo espaço de código.

   

4. Aguarde até que o codespace inicie. Este processo de arranque pode demorar alguns minutos.

5. No terminal na parte inferior do ecrã, inicie sessão no Azure com o Azure Developer CLI.

   azd auth login
   

6. Conclua o processo de autenticação.

7. As tarefas restantes neste artigo ocorrem no contexto desse contêiner de desenvolvimento.

Código do Visual Studio

A extensão Dev Containers para Visual Studio Code requer que o Docker esteja instalado na sua máquina local. A extensão hospeda o contêiner de desenvolvimento localmente usando o host Docker com as ferramentas de desenvolvedor corretas e dependências pré-instaladas para concluir este artigo.

1. Crie um novo diretório local no seu computador para o projeto.

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

2. Abra o Visual Studio Code nesse diretório.

   code .
   

3. Abra um novo terminal no Visual Studio Code.

4. Execute o seguinte AZD comando para trazer o repositório GitHub para o computador local.

   azd init -t azure-search-openai-demo
   

5. Abra a paleta de comandos , procure e selecione Dev Containers: Open Folder in Container para abrir o projeto em um contêiner de desenvolvimento. Aguarde até que o contêiner de desenvolvimento seja aberto antes de continuar.

6. Inicie sessão no Azure com a Azure Developer CLI.

   azd auth login
   

   Copie o código do terminal e cole-o em um navegador. Siga as instruções para autenticar com sua conta do Azure.

7. Os restantes exercícios deste projeto decorrem no contexto deste contentor de desenvolvimento.

Obtenha as informações necessárias com a CLI do Azure

Obtenha sua ID de assinatura e ID de locatário com o seguinte comando da CLI do Azure. Copie o valor para usar como seu AZURE_TENANT_ID valor.

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

Se receberes um erro sobre a política de acesso condicional do inquilino, precisarás de um segundo inquilino sem uma política de acesso condicional.

• O seu primeiro inquilino, associado à sua conta de utilizador, é usado para a variável de ambiente AZURE_TENANT_ID.
• O seu segundo inquilino, sem acesso condicional, é utilizado para a variável de ambiente para aceder ao AZURE_AUTH_TENANT_ID Microsoft Graph. Para locatários com uma política de acesso condicional, localize a ID de um segundo locatário sem uma política de acesso condicional ou crie um novo locatário.

Definir variáveis de ambiente

1. Execute os seguintes comandos para configurar o aplicativo para o perfil 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. Execute o seguinte comando para definir o locatário, que autoriza a entrada do usuário no ambiente do aplicativo hospedado. Substitua <YOUR_TENANT_ID> pelo ID do locatário.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Observação

Se você tiver uma política de acesso condicional em seu locatário de usuário, precisará especificar um locatário de autenticação.

Implantar o aplicativo de chat no Azure

A implantação consiste nas seguintes etapas:

• Crie os recursos do Azure.
• Carregue os documentos.
• Crie os aplicativos de identidade do Microsoft Entra (cliente e servidor).
• Ative a identidade para o recurso de hospedagem.

1. Provisione os recursos do Azure e implante o código-fonte.

   azd up
   

2. Utilize a tabela seguinte para responder aos pedidos de implantação AZD.

   Pronta	Resposta
   Nome do ambiente	Use um nome curto com informações de identificação, como seu alias e aplicativo. E exemplo é tjones-secure-chat.
   Subscrição	Selecione uma assinatura na qual criar os recursos.
   Localização dos recursos do Azure	Selecione uma localização próxima de si.
   Localização para documentIntelligentResourceGroupLocation	Selecione uma localização próxima de si.
   Localização para openAIResourceGroupLocation	Selecione uma localização próxima de si.

   Aguarde 5 ou 10 minutos após a implantação do aplicativo para permitir que o aplicativo seja iniciado.

3. Depois que o aplicativo é implantado com êxito, uma URL aparece no terminal.

4. Selecione o URL rotulado (✓) Done: Deploying service webapp para abrir o aplicativo de bate-papo em um navegador.

   

5. Concorde com o pop-up de autenticação do aplicativo.

6. Quando o aplicativo de bate-papo aparecer, observe no canto superior direito que seu usuário está conectado.

7. Abra as Configurações do desenvolvedor e observe que ambas as opções a seguir estão selecionadas e desabilitadas para alteração:

   • Use o filtro de segurança oid
   • Usar filtro de segurança de grupos

8. Selecione o cartão com O que faz um gerente de produto?.

9. Você obtém uma resposta como: As fontes fornecidas não contêm informações específicas sobre a função de um Gerente de Produto na Contoso Electronics.

   

Acesso aberto a um documento para um utilizador

Ative suas permissões para o documento exato para que você possa obter a resposta. Você precisa de várias informações:

• Armazenamento do Azure
  • Nome da conta
  • Nome do contêiner
  • URL do Blob/documento para role_library.pdf
• ID do usuário no Microsoft Entra ID

Quando essas informações forem conhecidas, atualize o campo de índice oids do Azure AI Search para o role_library.pdf documento.

Obter o URL de um documento armazenado

1. .azure Na pasta na raiz do projeto, localize o diretório do ambiente e abra o .env arquivo com esse diretório.

2. Procure por a entrada AZURE_STORAGE_ACCOUNT e copie o seu valor.

3. Use os seguintes comandos da CLI do Azure para obter a URL do role_library.pdf blob no content contêiner.

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

   Parâmetro	Propósito
   --nome-da-conta	Nome da conta do Armazenamento do Azure.
   --nome-do-container	O nome do recipiente neste exemplo é content.
   --nome	O nome do blob nesta etapa é role_library.pdf.

4. Copie o URL do blob para usar mais tarde.

Obtenha o seu ID de utilizador

1. No aplicativo de bate-papo, selecione Configurações do desenvolvedor.
2. Na seção Declarações de token de ID, copie seu objectidentifier parâmetro. Este parâmetro é conhecido na próxima seção como USER_OBJECT_ID.

Fornecer acesso de usuário a um documento na Pesquisa do Azure

1. Use o script a seguir para alterar o oids campo na Pesquisa de IA do Azure para role_library.pdf que você tenha acesso a ele.

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

   Parâmetro	Propósito
   -v	Saída detalhada.
   --tipo ACL	OIDs de grupo ou utilizador: oids.
   --acl-action	Adicionar a um campo de índice de pesquisa. Outras opções incluem enable_acls, remove, remove_all, e view.
   --acl	Grupo ou utilizador USER_OBJECT_ID.
   --url	A localização do ficheiro no Armazenamento do Azure, como https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Não rodeie o URL com aspas no comando CLI.

2. A saída do console para este comando é a seguinte:

   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. Opcionalmente, use o comando a seguir para verificar se sua permissão está listada para o arquivo no Azure AI Search.

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

   Parâmetro	Propósito
   -v	Saída detalhada.
   --tipo ACL	OIDs de grupo ou utilizador: oids.
   --acl-action	Ver um campo do Índice de Pesquisa oids. Outras opções incluem enable_acls, remove, remove_all, e add.
   --url	A localização do arquivo é exibida, como https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Não rodeie o URL com aspas no comando CLI.

4. A saída do console para este comando é a seguinte:

   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]
   

   A matriz no final da saída inclui seu USER_OBJECT_ID parâmetro e é usada para determinar se o documento é usado na resposta com o Azure OpenAI.

Verifique se o Azure AI Search contém o seu USER_OBJECT_ID

1. Abra o portal do Azure e procure AI Search.

2. Selecione seu recurso de pesquisa na lista.

3. Selecione Gerenciamento de pesquisa>Índices.

4. Selecione gptkbindex.

5. Selecione Exibir>visualização JSON.

6. Substitua o JSON pelo seguinte JSON:

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

   Este JSON pesquisa todos os documentos onde o oids campo tem qualquer valor e retorna os sourcefile campos e oids .

7. Se o role_library.pdf não tiver seu OID, retorne à seção Fornecer acesso de usuário a um documento na Pesquisa do Azure e conclua as etapas.

Verificar o acesso do usuário ao documento

Se você concluiu as etapas, mas não viu a resposta correta, verifique se seu USER_OBJECT_ID parâmetro está definido corretamente no Azure AI Search for role_library.pdf.

1. Volte ao aplicativo de bate-papo. Poderá ter de iniciar sessão novamente.

2. Insira a mesma consulta para que o role_library conteúdo seja usado na resposta do Azure OpenAI: What does a product manager do?.

3. Exiba o resultado, que agora inclui a resposta apropriada do documento da biblioteca de funções.

   

Limpeza de recursos

As etapas a seguir orientam você pelo processo de limpeza dos recursos usados.

Limpar recursos do Azure

Os recursos do Azure criados neste artigo são cobrados na sua assinatura do Azure. Se você não espera precisar desses recursos no futuro, exclua-os para evitar incorrer em mais cobranças.

Execute o seguinte comando da CLI do Desenvolvedor do Azure para excluir os recursos do Azure e remover o código-fonte.

azd down --purge

Limpar os Codespaces do GitHub e o Visual Studio Code

As etapas a seguir orientam você pelo processo de limpeza dos recursos usados.

Espaços de código do GitHub

Excluir o ambiente do GitHub Codespaces garante que possais maximizar o número de horas gratuitas por núcleo a que tendes direito na vossa conta.

Importante

Para obter mais informações sobre os direitos da sua conta do GitHub, consulte armazenamento incluído mensalmente e horas de uso base do GitHub Codespaces.

1. Faça login no painel de controlo do GitHub Codespaces.

2. Localize seus espaços de código em execução no momento que são originados do repositório GitHub Azure-Samples/azure-search-openai-demo .

   

3. Abra o menu de contexto do espaço de código e selecione Excluir.

   

Código do Visual Studio

Você não é necessariamente obrigado a limpar seu ambiente local, mas pode parar o contêiner de desenvolvimento em execução e retornar à execução do Visual Studio Code no contexto de um espaço de trabalho local.

1. Abra a paleta de comandos e procure os comandos Dev Containers .

2. Selecione Dev Containers: Reabrir Pasta no Local.

   

Sugestão

Depois que o Visual Studio Code interrompe o contêiner de desenvolvimento em execução, o contêiner ainda existe no Docker em um estado interrompido. Você pode excluir a instância do contêiner, a imagem do contêiner e os volumes do Docker para liberar mais espaço em sua máquina local.

Obter ajuda

O repositório de exemplo oferece informações de solução de problemas.

Solução de problemas

Esta seção ajuda você a solucionar problemas específicos deste artigo.

Forneça o tenant de autenticação

Quando sua autenticação estiver em um locatário separado do seu aplicativo de hospedagem, você precisará definir esse locatário de autenticação com o seguinte processo.

1. Execute o seguinte comando para configurar o exemplo para usar um segundo tenant para autenticação.

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

   Parâmetro	Propósito
   AZURE_AUTH_TENANT_ID	Se AZURE_AUTH_TENANT_ID estiver definido, é o locatário que hospeda o aplicativo.

2. Reimplante a solução com o seguinte comando:

   azd up
   

Conteúdo relacionado

• Crie um aplicativo de chat com a arquitetura de solução de práticas recomendadas do Azure OpenAI .
• Saiba mais sobre o controle de acesso em aplicativos de IA generativa com o Azure AI Search.
• Crie uma solução OpenAI do Azure pronta para a empresa com o Azure API Management.
• Consulte Azure AI Search: Superando a pesquisa vetorial com recursos híbridos de recuperação e classificação.