Use com segurança o Azure OpenAI em seus dados

Use este artigo para saber como usar o Azure OpenAI On Your Data com segurança, protegendo dados e recursos com o controle de acesso baseado em função do Microsoft Entra ID, redes virtuais e pontos de extremidade privados.

Este artigo só é aplicável ao usar o Azure OpenAI On Your Data com texto. Ele não se aplica ao Azure OpenAI On Your Data com imagens.

Arquitetura de ingestão de dados

Quando você usa o Azure OpenAI On Your Data para ingerir dados do armazenamento de blob do Azure, arquivos locais ou URLs no Azure AI Search, o processo a seguir é usado para processar os dados.

• As etapas 1 e 2 são usadas apenas para o upload de arquivos.
• O download de URLs para seu armazenamento de blob não é ilustrado neste diagrama. Depois que as páginas da Web são baixadas da Internet e carregadas para o armazenamento de blobs, as etapas 3 em diante são as mesmas.
• Dois indexadores, dois índices, duas fontes de dados e uma habilidade personalizada são criados no recurso Azure AI Search.
• O contêiner de blocos é criado no armazenamento de blob.
• Se a ingestão for desencadeada por uma atualização programada, o processo de ingestão começa a partir da etapa 7.
• A API do preprocessing-jobs Azure OpenAI implementa o protocolo da API Web de habilidade do cliente do Azure AI Search e processa os documentos em uma fila.
• Azure OpenAI:
  1. Internamente usa o primeiro indexador criado anteriormente para quebrar os documentos.
  2. Usa um algoritmo baseado em heurística para executar o chunking, honrando layouts de tabela e outros elementos de formatação no limite do bloco para garantir a melhor qualidade de fragmentação.
  3. Se você optar por habilitar a pesquisa vetorial, o Azure OpenAI usará a implantação de incorporação selecionada para vetorizar os blocos internamente.
• Quando todos os dados que o serviço está monitorando são processados, o Azure OpenAI aciona o segundo indexador.
• O indexador armazena os dados processados em um serviço Azure AI Search.

Para as identidades gerenciadas usadas em chamadas de serviço, apenas as identidades gerenciadas atribuídas ao sistema são suportadas. Não há suporte para identidades gerenciadas atribuídas pelo usuário.

Arquitetura de inferência

Quando você envia chamadas de API para conversar com um modelo OpenAI do Azure em seus dados, o serviço precisa recuperar os campos de índice durante a inferência para executar o mapeamento de campos automaticamente se o mapeamento de campos não estiver explicitamente definido na solicitação. Portanto, o serviço requer que a identidade OpenAI do Azure tenha a função para o serviço de pesquisa, mesmo durante a Search Service Contributor inferência.

Se uma implantação de incorporação for fornecida na solicitação de inferência, a consulta reescrita será vetorizada pelo Azure OpenAI, e a consulta e o vetor serão enviados à Pesquisa do Azure AI para pesquisa vetorial.

Controle de acesso no nível do documento

Nota

O controle de acesso no nível de documento é suportado apenas para a pesquisa de IA do Azure.

O Azure OpenAI On Your Data permite restringir os documentos que podem ser usados em respostas para diferentes usuários com os filtros de segurança do Azure AI Search. Quando você habilita o acesso no nível do documento, os resultados da pesquisa retornados da Pesquisa de IA do Azure e usados para gerar uma resposta serão cortados com base na associação do usuário ao grupo Microsoft Entra. Você só pode habilitar o acesso no nível do documento em índices existentes do Azure AI Search. Para habilitar o acesso no nível do documento:

1. Siga as etapas na documentação do Azure AI Search para registrar seu aplicativo e criar usuários e grupos.

2. Indexe seus documentos com os grupos permitidos. Certifique-se de que seus novos campos de segurança tenham o esquema abaixo:

   {"name": "group_ids", "type": "Collection(Edm.String)", "filterable": true }
   

   group_ids é o nome do campo padrão. Se você usar um nome de campo diferente como my_group_ids, poderá mapear o campo no mapeamento de campo de índice.

3. Verifique se cada documento confidencial no índice tem o valor definido corretamente neste campo de segurança para indicar os grupos permitidos do documento.

4. No Azure OpenAI Studio, adicione sua fonte de dados. Na seção Mapeamento de campo de índice, você pode mapear zero ou um valor para o campo Grupos permitidos, desde que o esquema seja compatível. Se o campo Grupos permitidos não estiver mapeado, o acesso no nível do documento não será habilitado.

Azure OpenAI Studio

Assim que o índice do Azure AI Search estiver conectado, suas respostas no estúdio terão acesso ao documento com base nas permissões do Microsoft Entra do usuário conectado.

Aplicação Web

Se você estiver usando um aplicativo Web publicado, precisará reimplantá-lo para atualizar para a versão mais recente. A versão mais recente do aplicativo Web inclui a capacidade de recuperar os grupos da conta Microsoft Entra do usuário conectado, armazená-la em cache e incluir as IDs de grupo em cada solicitação de API.

API

Ao usar a API, passe o filter parâmetro em cada solicitação de API. Por exemplo:

{
    "messages": [
        {
            "role": "user",
            "content": "who is my manager?"
        }
    ],
    "dataSources": [
        {
            "type": "AzureCognitiveSearch",
            "parameters": {
                "endpoint": "'$AZURE_AI_SEARCH_ENDPOINT'",
                "key": "'$AZURE_AI_SEARCH_API_KEY'",
                "indexName": "'$AZURE_AI_SEARCH_INDEX'",
                "filter": "my_group_ids/any(g:search.in(g, 'group_id1, group_id2'))"
            }
        }
    ]
}

• my_group_ids é o nome do campo que você selecionou para Grupos permitidos durante o mapeamento de campos.
• group_id1, group_id2 são grupos atribuídos ao utilizador com sessão iniciada. O aplicativo cliente pode recuperar e armazenar em cache grupos de usuários.

Configuração de recursos

Use as seções a seguir para configurar seus recursos para um uso seguro ideal. Mesmo que você planeje proteger apenas parte de seus recursos, ainda precisará seguir todas as etapas abaixo.

Este artigo descreve as configurações de rede relacionadas à desativação da rede pública para recursos do Azure OpenAI, recursos de pesquisa do Azure AI e contas de armazenamento. Não há suporte para o uso de redes selecionadas com regras de IP, porque os endereços IP dos serviços são dinâmicos.

Gorjeta

Você pode usar o script bash disponível no GitHub para validar sua configuração e determinar se todos os requisitos listados aqui estão sendo atendidos.

Criar grupo de recursos

Crie um grupo de recursos, para que você possa organizar todos os recursos relevantes. Os recursos no grupo de recursos incluem, mas não estão limitados a:

• Uma rede virtual
• Três serviços principais: um Azure OpenAI, um Azure AI Search, uma Conta de Armazenamento
• Três pontos de extremidade privados, cada um está vinculado a um serviço chave
• Três interfaces de rede, cada uma associada a um ponto de extremidade privado
• Um gateway de rede virtual, para o acesso a partir de máquinas cliente locais
• Uma aplicação Web com rede virtual integrada
• Uma zona DNS privada, para que o Aplicativo Web encontre o IP do seu Azure OpenAI

Criar a rede virtual

A rede virtual tem três sub-redes.

1. A primeira sub-rede é usada para os IPs privados dos três pontos de extremidade privados.
2. A segunda sub-rede é criada automaticamente quando você cria o gateway de rede virtual.
3. A terceira sub-rede está vazia e é usada para integração de rede virtual de saída do Aplicativo Web.

Observação A rede virtual gerenciada pela Microsoft é criada pela Microsoft e você não pode vê-la. A rede virtual gerenciada pela Microsoft é usada pelo Azure OpenAI para acessar com segurança sua Pesquisa de IA do Azure.

Configurar o Azure OpenAI

Subdomínio personalizado habilitado

Se você criou o Azure OpenAI por meio do portal do Azure, o subdomínio personalizado já deve ter sido criado. O subdomínio personalizado é necessário para autenticação baseada no Microsoft Entra ID e zona DNS privada.

Ativar a identidade gerida

Para permitir que sua Conta de Pesquisa e Armazenamento do Azure AI reconheça seu serviço Azure OpenAI por meio da autenticação do Microsoft Entra ID, você precisa atribuir uma identidade gerenciada para seu serviço Azure OpenAI. A maneira mais fácil é ativar a identidade gerenciada atribuída ao sistema no portal do Azure.

Para definir as identidades gerenciadas por meio da API de gerenciamento, consulte a documentação de referência da API de gerenciamento.

"identity": {
  "principalId": "12345678-abcd-1234-5678-abc123def",
  "tenantId": "1234567-abcd-1234-1234-abcd1234",
  "type": "SystemAssigned, UserAssigned", 
  "userAssignedIdentities": {
    "/subscriptions/1234-5678-abcd-1234-1234abcd/resourceGroups/my-resource-group",
    "principalId": "12345678-abcd-1234-5678-abcdefg1234", 
    "clientId": "12345678-abcd-efgh-1234-12345678"
  }
}

Ativar serviço confiável

Para permitir que sua Pesquisa de IA do Azure chame seu Azure OpenAI preprocessing-jobs como API Web de habilidade personalizada, enquanto o Azure OpenAI não tem acesso à rede pública, você precisa configurar o Azure OpenAI para ignorar o Azure AI Search como um serviço confiável com base na identidade gerenciada. O Azure OpenAI identifica o tráfego da sua Pesquisa de IA do Azure verificando as declarações no JSON Web Token (JWT). O Azure AI Search deve usar a autenticação de identidade gerenciada atribuída ao sistema para chamar a API Web de habilidade personalizada.

AzureServices Defina networkAcls.bypass como a partir da API de gerenciamento. Para obter mais informações, consulte o artigo Redes virtuais.

Nota

O recurso de serviço confiável só está disponível usando o comando descrito acima e não pode ser feito usando o portal do Azure.

Esta etapa só pode ser ignorada se você tiver um link privado compartilhado para seu recurso Azure AI Search.

Desativar o acesso à rede pública

Você pode desabilitar o acesso à rede pública do seu recurso Azure OpenAI no portal do Azure.

Para permitir o acesso ao seu serviço Azure OpenAI a partir de suas máquinas cliente, como usar o Azure OpenAI Studio, você precisa criar conexões de ponto de extremidade privadas que se conectam ao seu recurso do Azure OpenAI.

Configurar a Pesquisa de IA do Azure

Você pode usar o nível de preço básico e superior para a configuração abaixo. Não é necessário, mas se você usar o nível de preço S2, verá opções adicionais disponíveis para seleção.

Ativar a identidade gerida

Para permitir que seus outros recursos reconheçam a Pesquisa de IA do Azure usando a autenticação de ID do Microsoft Entra, você precisa atribuir uma identidade gerenciada para sua Pesquisa de IA do Azure. A maneira mais fácil é ativar a identidade gerenciada atribuída ao sistema no portal do Azure.

Habilitar o controle de acesso baseado em função

Como o Azure OpenAI usa a identidade gerenciada para acessar a Pesquisa do Azure AI, você precisa habilitar o controle de acesso baseado em função em sua Pesquisa do Azure AI. Para fazer isso no portal do Azure, selecione Ambos na guia Chaves no portal do Azure.

Para habilitar o controle de acesso baseado em função por meio da API REST, defina authOptions como aadOrApiKey. Para obter mais informações, consulte o artigo Azure AI Search RBAC.

"disableLocalAuth": false,
"authOptions": { 
    "aadOrApiKey": { 
        "aadAuthFailureMode": "http401WithBearerChallenge"
    }
}

Para usar o Azure OpenAI Studio, você não pode desabilitar a autenticação baseada em chave de API para o Azure AI Search, porque o Azure OpenAI Studio usa a chave de API para chamar a API de Pesquisa do Azure AI do seu navegador.

Gorjeta

Para obter a melhor segurança, quando você estiver pronto para produção e não precisar mais usar o Azure OpenAI Studio para testes, recomendamos que você desabilite a chave de API. Consulte o artigo Azure AI Search RBAC para obter detalhes.

Desativar o acesso à rede pública

Você pode desabilitar o acesso à rede pública do seu recurso Azure AI Search no portal do Azure.

Para permitir o acesso ao seu recurso Azure AI Search a partir de suas máquinas cliente, como usar o Azure OpenAI Studio, você precisa criar conexões de ponto de extremidade privadas que se conectam ao seu recurso Azure AI Search.

Nota

Para permitir o acesso ao seu recurso Azure AI Search a partir do recurso Azure OpenAI, tem de submeter um formulário de candidatura. A candidatura será analisada em 5 dias úteis e será contactado via email sobre os resultados. Se você for elegível, provisionaremos o ponto de extremidade privado na rede virtual gerenciada pela Microsoft e enviaremos uma solicitação de conexão de ponto de extremidade privado para seu serviço de pesquisa, e você precisará aprovar a solicitação.

O recurso de ponto de extremidade privado é provisionado em um locatário gerenciado pela Microsoft, enquanto o recurso vinculado está em seu locatário. Você não pode acessar o recurso de ponto de extremidade privado apenas clicando no link do ponto de extremidade privado (em fonte azul) na guia Acesso privado da página Rede. Em vez disso, clique em outro lugar na linha e, em seguida, o botão Aprovar acima deve ser clicável.

Saiba mais sobre o fluxo de trabalho de aprovação manual.

Criar link privado compartilhado

Gorjeta

Se estiver a utilizar um escalão de preços básico ou padrão, ou se for a primeira vez que configura todos os seus recursos de forma segura, deve ignorar este tópico avançado.

Esta seção só é aplicável ao recurso de pesquisa da camada de preços do S2, pois requer suporte de ponto final privado para indexadores com um conjunto de habilidades.

Para criar um link privado compartilhado a partir do seu recurso de pesquisa conectando-se ao seu recurso do Azure OpenAI, consulte a documentação de pesquisa. Selecione Tipo de recurso como Microsoft.CognitiveServices/accounts e ID de grupo como openai_account.

Com o link privado compartilhado, a etapa oito do diagrama da arquitetura de ingestão de dados é alterada de ignorar serviço confiável para ponto de extremidade privado.

O link privado compartilhado do Azure AI Search que você criou também está em uma rede virtual gerenciada pela Microsoft, não em sua rede virtual. A diferença em comparação com o outro ponto de extremidade privado gerenciado criado anteriormente é que o ponto de extremidade [1] privado gerenciado do Azure OpenAI para a Pesquisa do Azure é provisionado por meio do aplicativo de formulário, enquanto o ponto de extremidade [2] privado gerenciado da Pesquisa do Azure para o Azure OpenAI é provisionado por meio do portal do Azure ou da API REST da Pesquisa do Azure.

Configurar conta de armazenamento

Ativar serviço confiável

Para permitir o acesso à sua Conta de Armazenamento a partir do Azure OpenAI e do Azure AI Search, enquanto a Conta de Armazenamento não tiver acesso à rede pública, tem de configurar a Conta de Armazenamento para ignorar o Azure OpenAI e o Azure AI Search como serviços fidedignos com base na identidade gerida.

No portal do Azure, navegue até a guia rede da sua conta de armazenamento, escolha "Redes selecionadas" e selecione Permitir serviços do Azure na lista de serviços confiáveis para acessar essa conta de armazenamento e clique em Salvar.

Desativar o acesso à rede pública

Pode desativar o acesso à rede pública da sua Conta de Armazenamento no portal do Azure.

Para permitir o acesso à sua Conta de Armazenamento a partir de suas máquinas cliente, como usar o Azure OpenAI Studio, você precisa criar conexões de ponto de extremidade privadas que se conectam ao seu armazenamento de blobs.

Atribuições de funções

Até agora você já configurou cada recurso de forma independente. Em seguida, você precisa permitir que os serviços se autorizem.

Role	Cessionário	Recurso	Description
Search Index Data Reader	Azure OpenAI	Pesquisa de IA do Azure	O serviço de inferência consulta os dados do índice.
Search Service Contributor	Azure OpenAI	Pesquisa de IA do Azure	O serviço de inferência consulta o esquema de índice para mapeamento automático de campos. O serviço de ingestão de dados cria índice, fontes de dados, conjunto de habilidades, indexador e consulta o status do indexador.
Storage Blob Data Contributor	Azure OpenAI	Conta de Armazenamento	Lê do contêiner de entrada e grava o resultado do pré-processo no contêiner de saída.
Cognitive Services OpenAI Contributor	Pesquisa de IA do Azure	Azure OpenAI	Habilidade personalizada
Storage Blob Data Contributor	Pesquisa de IA do Azure	Conta de Armazenamento	Lê blob e escreve armazenamento de conhecimento.

Na tabela acima, o significa que o Assignee sistema atribuiu a identidade gerenciada desse recurso.

O administrador precisa ter a Owner função nesses recursos para adicionar atribuições de função.

Consulte a documentação do RBAC do Azure para obter instruções sobre como definir essas funções no portal do Azure. Você pode usar o script disponível no GitHub para adicionar as atribuições de função programaticamente.

Para permitir que os desenvolvedores usem esses recursos para criar aplicativos, o administrador precisa adicionar a identidade dos desenvolvedores com as seguintes atribuições de função aos recursos.

Role	Recurso	Description
Cognitive Services OpenAI Contributor	Azure OpenAI	Chame a API de ingestão pública do Azure OpenAI Studio. A Contributor função não é suficiente, porque se você tiver Contributor apenas função, não poderá chamar a API do plano de dados por meio da autenticação de ID do Microsoft Entra e a autenticação de ID do Microsoft Entra é necessária na configuração segura descrita neste artigo.
Cognitive Services User	Azure OpenAI	Liste chaves de API do Azure OpenAI Studio.
Contributor	Pesquisa de IA do Azure	Liste chaves de API para listar índices do Azure OpenAI Studio.
Contributor	Conta de Armazenamento	Listar Conta SAS para carregar arquivos do Azure OpenAI Studio.
Contributor	O grupo de recursos ou a assinatura do Azure em que o desenvolvedor precisa implantar o aplicativo Web	Implante o aplicativo Web na assinatura do Azure do desenvolvedor.

Configurar gateway e cliente

Para acessar o serviço Azure OpenAI de suas máquinas cliente locais, uma das abordagens é configurar o Gateway de VPN do Azure e o Cliente VPN do Azure.

Siga esta diretriz para criar um gateway de rede virtual para sua rede virtual.

Siga esta diretriz para adicionar configuração ponto a site e habilitar a autenticação baseada em ID do Microsoft Entra. Baixe o pacote de configuração do perfil do Cliente VPN do Azure, descompacte e importe o arquivo para seu AzureVPN/azurevpnconfig.xml cliente VPN do Azure.

Configure o arquivo da máquina hosts local para apontar os nomes de host dos recursos para os IPs privados na rede virtual. O hosts arquivo está localizado em C:\Windows\System32\drivers\etc para Windows e em /etc/hosts Linux. Exemplo:

10.0.0.5 contoso.openai.azure.com
10.0.0.6 contoso.search.windows.net
10.0.0.7 contoso.blob.core.windows.net

Azure OpenAI Studio

Você deve ser capaz de usar todos os recursos do Azure OpenAI Studio, incluindo ingestão e inferência, de suas máquinas cliente locais.

Aplicação Web

O aplicativo Web se comunica com seu recurso OpenAI do Azure. Como seu recurso do Azure OpenAI tem a rede pública desabilitada, o aplicativo Web precisa ser configurado para usar o ponto de extremidade privado em sua rede virtual para acessar seu recurso do Azure OpenAI.

O aplicativo Web precisa resolver seu nome de host do Azure OpenAI para o IP privado do ponto de extremidade privado do Azure OpenAI. Então, você precisa configurar a zona DNS privada para sua rede virtual primeiro.

1. Crie uma zona DNS privada no seu grupo de recursos.
2. Adicione um registo DNS. O IP é o IP privado do ponto de extremidade privado para seu recurso do Azure OpenAI, e você pode obter o endereço IP da interface de rede associada ao ponto de extremidade privado para seu Azure OpenAI.
3. Vincule a zona DNS privada à sua rede virtual para que o aplicativo Web integrado nessa rede virtual possa usar essa zona DNS privada.

Ao implantar o aplicativo Web do Azure OpenAI Studio, selecione o mesmo local com a rede virtual e selecione uma SKU adequada, para que possa dar suporte ao recurso de integração de rede virtual.

Depois que o aplicativo Web for implantado, na guia Rede do portal do Azure, configure a integração de rede virtual de tráfego de saída do aplicativo Web, escolha a terceira sub-rede que você reservou para o aplicativo Web.

Usando a API

Certifique-se de que a sua credencial de início de sessão tem Cognitive Services OpenAI Contributor função no seu recurso OpenAI do Azure e execute az login primeiro.

API de ingestão

Consulte o artigo de referência da API de ingestão para obter detalhes sobre os objetos de solicitação e resposta usados pela API de ingestão.

Mais notas:

• JOB_NAME no caminho da API será usado como o nome do índice no Azure AI Search.
• Use o Authorization cabeçalho em vez da chave api.
• Defina storageEndpoint explicitamente o cabeçalho.
• Use ResourceId= o formato para storageConnectionString cabeçalho, para que o Azure OpenAI e o Azure AI Search usem a identidade gerenciada para autenticar a conta de armazenamento, que é necessária para ignorar as restrições de rede.
• Não defina o searchServiceAdminKey cabeçalho. A identidade atribuída ao sistema do recurso Azure OpenAI é usada para autenticar o Azure AI Search.
• Não definir embeddingEndpoint ou embeddingKey. Em vez disso, use o cabeçalho para habilitar a vetorização de embeddingDeploymentName texto.

Enviar exemplo de trabalho

accessToken=$(az account get-access-token --resource https://cognitiveservices.azure.com/ --query "accessToken" --output tsv)
curl -i -X PUT https://my-resource.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/vpn1025a?api-version=2023-10-01-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $accessToken" \
-H "storageEndpoint: https://mystorage.blob.core.windows.net/" \
-H "storageConnectionString: ResourceId=/subscriptions/1234567-abcd-1234-5678-1234abcd/resourceGroups/my-resource/providers/Microsoft.Storage/storageAccounts/mystorage" \
-H "storageContainer: my-container" \
-H "searchServiceEndpoint: https://mysearch.search.windows.net" \
-H "embeddingDeploymentName: ada" \
-d \
'
{
}
'

Obter exemplo de status de trabalho

accessToken=$(az account get-access-token --resource https://cognitiveservices.azure.com/ --query "accessToken" --output tsv)
curl -i -X GET https://my-resource.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/abc1234?api-version=2023-10-01-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $accessToken"

API de inferência

Consulte o artigo de referência da API de inferência para obter detalhes sobre os objetos de solicitação e resposta usados pela API de inferência.