Usar o OpenAI do Azure em seus Dados com segurança
Leia este artigo para saber como usar o OpenAI do Azure em seus Dados com segurança, protegendo dados e recursos com o controle de acesso baseado em função, as redes virtuais e os pontos de extremidade privados do Microsoft Entra ID.
Este artigo só é aplicável ao uso do OpenAI do Azure em seus Dados com textos. Ele não se aplica ao OpenAI do Azure em seus Dados com imagens.
Arquitetura de ingestão de dados
Quando você usa o OpenAI do Azure em seus Dados para ingerir dados do armazenamento de blobs do Azure, de arquivos locais ou de URLs na Pesquisa de IA do Azure, o processo a seguir é usado para processar os dados.
- As etapas 1 e 2 são usadas apenas para fazer upload de arquivos.
- O download de URLs para o armazenamento de blobs não está ilustrado neste diagrama. Depois que as páginas da Web forem baixadas da Internet e carregadas no armazenamento de blobs, as etapas a partir da etapa 3 em diante são as mesmas.
- Dois indexadores, dois índices, duas fontes de dados e uma habilidade personalizada são criados no recurso de Pesquisa de IA do Azure.
- O contêiner de partes é criado no armazenamento de blobs.
- Se a ingestão for disparada por uma atualização agendada, o processo de ingestão será iniciado a partir da etapa 7.
- A API
preprocessing-jobs
do OpenAI do Azure implementa o protocolo da API Web de habilidades do cliente da Pesquisa de IA do Azure e processa os documentos em uma fila. - OpenAI do Azure:
- Internamente, utiliza o primeiro indexador criado anteriormente para processar os documentos.
- Usa um algoritmo baseado em heurística para executar a divisão em partes, respeitando layouts de tabela e outros elementos de formatação no limite da parte para garantir a melhor qualidade de divisão em partes.
- Se você optar por habilitar a busca em vetores, o OpenAI do Azure usará a implantação de incorporação selecionada para vetorizar as partes internamente.
- Quando todos os dados que o serviço está monitorando são processados, o OpenAI do Azure dispara o segundo indexador.
- O indexador armazena os dados processados em um serviço da Pesquisa de IA do Azure.
Para as identidades gerenciadas usadas em chamadas de serviço, há suporte apenas para identidades gerenciadas atribuídas pelo sistema. Identidades gerenciadas atribuídas pelo usuário não têm suporte.
Arquitetura de inferência
Quando você envia chamadas à API para conversar com um modelo de 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 está definido explicitamente na solicitação. Portanto, o serviço requer que a identidade do Azure OpenAI tenha a função Search Service Contributor
para o serviço de pesquisa mesmo durante a inferência.
Se uma implantação de incorporação for fornecida na solicitação de inferência, a consulta reescrita será vetorizada pelo OpenAI do Azure e tanto a consulta quanto o vetor serão enviados à Pesquisa de IA do Azure para busca em vetores.
Controle de acesso no nível de documento
Observação
O controle de acesso no nível do documento só é compatível com a Pesquisa de IA do Azure.
O OpenAI do Azure em seus Dados permite restringir os documentos que podem ser usados em respostas para diferentes usuários com filtros de segurança da Pesquisa de IA do Azure. Quando você habilita o acesso no nível de 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 do Microsoft Entra. Você só pode habilitar o acesso no nível de documento em índices existentes da Pesquisa de IA do Azure. Para habilitar o acesso no nível do documento:
Siga as etapas na Documentação da Pesquisa de IA do Azure para registrar seu aplicativo e criar usuários e grupos.
Indexe seus documentos com os grupos permitidos. Verifique se os novos campos de segurança têm 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, comomy_group_ids
, poderá mapear o campo no mapeamento de campo do índice.Verifique se cada documento confidencial no índice tem o valor definido corretamente neste campo de segurança para indicar os grupos permitidos do documento.
No Estúdio OpenAI do Azure, adicione sua fonte de dados. na seção mapeamento de campo do índice, você pode mapear zero ou um valor para o campo de 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.
Estúdio do OpenAI do Azure
Depois que o índice da Pesquisa de IA do Azure estiver conectado, suas respostas no estúdio terão acesso a documentos com base nas permissões do Microsoft Entra do usuário conectado.
Aplicativo Web
Se você estiver usando um aplicativo Web publicado, será necessário 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 do Microsoft Entra do usuário conectado, armazená-la em cache e incluir as IDs do grupo em cada solicitação de API.
API
Ao usar a API, aprove o parâmetro filter
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 selecionado para Grupos permitidos durante o mapeamento de campos.group_id1, group_id2
são grupos atribuídos ao usuário conectado. O aplicativo cliente pode recuperar e armazenar em cache os grupos de usuários.
Configuração de recurso
Use as seções a seguir para configurar seus recursos para um uso seguro otimizado. Mesmo que você pretenda proteger apenas parte dos seus recursos, ainda precisará seguir todas as etapas abaixo.
Este artigo descreve as configurações de rede relacionadas à desabilitação da rede pública para recursos do OpenAI do Azure, recursos de pesquisa de IA do Azure e contas de armazenamento. Não há suporte para o uso de redes selecionadas com regras de IP, pois os endereços IP dos serviços são dinâmicos.
Dica
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 nesse grupo de recursos incluem, mas não se limitam a:
- Uma rede virtual
- Três serviços principais: um OpenAI do Azure, uma Pesquisa de IA do Azure, uma Conta de Armazenamento
- Três pontos de extremidade privados, cada um está vinculado a um serviço principal
- Três adaptadores de rede, cada um está associado a um ponto de extremidade privado
- Um gateway de rede virtual, para o acesso a partir de computadores cliente locais
- Um aplicativo Web com rede virtual integrada
- Uma zona DNS privada, de modo que o aplicativo Web localize o IP do OpenAI do Azure
Criar rede virtual
A rede virtual tem três sub-redes.
- A primeira sub-rede é usada para os IPs privados dos três pontos de extremidade privados.
- A segunda sub-rede é criada automaticamente quando você cria o gateway de rede virtual.
- A terceira sub-rede está vazia e é usada para integração de rede virtual de saída do aplicativo Web.
Observe que a rede virtual gerenciada pela Microsoft é criada pela Microsoft e você não pode vê-la. A rede virtual gerenciada pela Microsoft é usada pelo OpenAI do Azure para acessar com segurança a Pesquisa de IA do Azure.
Configurar o OpenAI do Azure
Subdomínio personalizado habilitado
Se você criou o OpenAI do Azure por meio do portal do Azure, o subdomínio personalizado já deve ter sido criado. O subdomínio personalizado é necessário para a autenticação baseada no Microsoft Entra ID e para a zona DNS privada.
Habilitar a identidade gerenciada
Para permitir que sua conta de armazenamento e Pesquisa de IA do Azure reconheçam seu serviço de OpenAI do Azure por meio da autenticação do Microsoft Entra ID, você precisa atribuir uma identidade gerenciada para o serviço de OpenAI do Azure. A maneira mais fácil é ativar a identidade gerenciada atribuída pelo 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"
}
}
Habilitar o serviço confiável
Para permitir que a Pesquisa de IA do Azure chame os preprocessing-jobs
do seu OpenAI do Azure como a API Web de habilidade personalizada, enquanto o OpenAI do Azure não tem acesso à rede pública, você precisa configurá-lo para que ignore a Pesquisa de IA do Azure como um serviço confiável com base na identidade gerenciada. O OpenAI do Azure identifica o tráfego de sua Pesquisa de IA do Azure verificando as declarações no JWT (Token Web JSON). A Pesquisa de IA do Azure precisa usar a autenticação de identidade gerenciada atribuída pelo sistema para chamar a API Web de habilidade personalizada.
Defina networkAcls.bypass
como AzureServices
da API de gerenciamento. Para obter mais informações, confira o artigo sobre Redes virtuais.
Observação
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.
Essa etapa só poderá ser ignorada se você tiver um link privado compartilhado para o recurso de Pesquisa de IA do Azure.
Desabilitar o acesso de redes públicas
Você pode desabilitar o acesso à rede pública do recurso de OpenAI do Azure no portal do Azure.
Para permitir o acesso ao serviço de OpenAI do Azure a partir de seus computadores cliente, como usar o Estúdio do OpenAI do Azure, você precisa criar conexões de ponto de extremidade privado que se conectem ao recurso de OpenAI do Azure.
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 tipo de preço S2, opções adicionais estarão disponíveis para seleção.
Habilitar a identidade gerenciada
Para permitir que seus outros recursos reconheçam a Pesquisa de IA do Azure usando a autenticação do Microsoft Entra ID, você precisa atribuir uma identidade gerenciada à sua Pesquisa de IA do Azure. A maneira mais fácil é ativar a identidade gerenciada atribuída pelo sistema no portal do Azure.
Habilitar o controle de acesso baseado em função
Como o OpenAI do Azure usa a identidade gerenciada para acessar a Pesquisa de IA do Azure, você precisa habilitar o controle de acesso baseado em função na Pesquisa de IA do Azure. 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 RBAC da Pesquisa de IA do Azure.
"disableLocalAuth": false,
"authOptions": {
"aadOrApiKey": {
"aadAuthFailureMode": "http401WithBearerChallenge"
}
}
Para usar o Estúdio de OpenAI do Azure, não é possível desabilitar a autenticação baseada em chave de API para a Pesquisa de IA do Azure, pois o Estúdio de OpenAI do Azure usa a chave de API para chamar a API da Pesquisa de IA do Azure do navegador.
Dica
Para obter a melhor segurança, quando você estiver pronto para produção e não precisar mais usar o Estúdio de OpenAI do Azure para teste, recomendamos desabilitar a chave de API. Consulte o artigo RBAC da Pesquisa de IA do Azure para obter detalhes.
Desabilitar o acesso de redes públicas
Você pode desabilitar o acesso à rede pública do recurso de Pesquisa de IA do Azure no portal do Azure.
Para permitir o acesso ao recurso de Pesquisa de IA do Azure a partir de seus computadores cliente, como usar o Estúdio de OpenAI do Azure, você precisa criar conexões de ponto de extremidade privado que se conectem ao recurso de Pesquisa de IA do Azure.
Observação
Para permitir o acesso ao recurso de Pesquisa de IA do Azure a partir do recurso de OpenAI do Azure, você precisa enviar um formulário de solicitação. A inscrição será analisada em cinco dias úteis e você será contatado por email sobre o resultado. Se você estiver qualificado, provisionaremos o ponto de extremidade privado na rede virtual gerenciada da Microsoft e enviaremos uma solicitação de conexão de ponto de extremidade privado para o serviço de pesquisa. Você precisará aprovar essa solicitação.
O recurso de ponto de extremidade privado é provisionado em um locatário gerenciado da Microsoft, enquanto o recurso vinculado está no seu locatário. Você não pode acessar o recurso de ponto de extremidade privado simplesmente clicando no link do ponto de extremidade privado (em letra azul) na guia Acesso privado da página de Rede. Em vez disso, clique em outro lugar na linha e, em seguida, o botão Aprovar acima deve se tornar clicável.
Saiba mais sobre o fluxo de trabalho de aprovação manual.
Criar link privado compartilhado
Dica
Se você estiver usando um tipo de preço básico ou padrão ou se estiver configurando pela primeira vez todos os recursos com segurança, ignore este tópico avançado.
Esta seção só é aplicável ao recurso de pesquisa do tipo de preço S2, pois requer suporte de ponto de extremidade privado para indexadores com um conjunto de habilidades.
Para criar um link privado compartilhado do recurso de pesquisa que se conecta ao recurso de OpenAI do Azure, consulte a documentação de pesquisa. Selecione Tipo de recurso como Microsoft.CognitiveServices/accounts
e ID do grupo como openai_account
.
Com o link privado compartilhado, a etapa oito do diagrama de arquitetura de ingestão de dados é alterada de ignorar serviço confiável para ponto de extremidade privado.
O link privado compartilhado da Pesquisa de IA do Azure 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 privado gerenciado [1]
do OpenAI do Azure para o Azure Search é provisionado por meio do aplicativo de formulário, enquanto o ponto de extremidade privado gerenciado [2]
do Azure Search para o OpenAI do Azure é provisionado por meio do portal do Azure ou da API REST do Azure Search.
Configurar Conta de Armazenamento
Habilitar o serviço confiável
Para permitir o acesso à sua conta de armazenamento a partir do OpenAI do Azure e da Pesquisa de IA do Azure, enquanto a conta de armazenamento não tem acesso à rede pública, você precisa configurá-la para que ignore o OpenAI do Azure e a Pesquisa de IA do Azure como serviços confiáveis com base na identidade gerenciada.
No portal do Azure, navegue até a guia Rede da conta de armazenamento, escolha "Redes selecionadas", selecione Permitir serviços do Azure na lista de serviços confiáveis para acessar essa conta de armazenamento e clique em Salvar.
Desabilitar o acesso de redes públicas
Você pode desabilitar o acesso à rede pública de sua conta de armazenamento no portal do Azure.
Para permitir o acesso à conta de armazenamento a partir de seus computadores cliente, como usar o Estúdio do OpenAI do Azure, você precisa criar conexões de ponto de extremidade privado que se conectem ao armazenamento de blobs.
Atribuições de função
Até agora, você já configurou cada recurso de maneira independente. Em seguida, você precisa permitir que os serviços autorizem uns aos outros.
Função | Atribuição | Recurso | Descrição |
---|---|---|---|
Search Index Data Reader |
OpenAI do Azure | IA do Azure Search | O serviço de inferência consulta os dados do índice. |
Search Service Contributor |
OpenAI do Azure | IA do Azure Search | O serviço de inferência consulta o esquema de índice para mapeamento de campos automático. 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 |
OpenAI do Azure | Conta de Armazenamento | Ele lê do contêiner de entrada e grava o resultado do pré-processo no contêiner de saída. |
Cognitive Services OpenAI Contributor |
IA do Azure Search | OpenAI do Azure | Habilidade personalizada |
Storage Blob Data Contributor |
IA do Azure Search | Conta de Armazenamento | Lê o blob e grava no repositório de conhecimento. |
Na tabela acima, o Assignee
significa a identidade gerenciada atribuída pelo sistema daquele recurso.
O administrador precisa ter a função Owner
nesses recursos para adicionar atribuições de função.
Confira 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 atribuições de função a seguir aos recursos.
Função | Recurso | Descrição |
---|---|---|
Cognitive Services OpenAI Contributor |
OpenAI do Azure | Chame a API de ingestão pública do Estúdio do OpenAI do Azure. A função Contributor não é suficiente, pois se você tiver apenas a função Contributor , não poderá chamar a API do plano de dados por meio da autenticação do Microsoft Entra ID e essa autenticação é necessária na configuração segura descrita neste artigo. |
Cognitive Services User |
OpenAI do Azure | Listar as chaves de API do Estúdio do OpenAI do Azure. |
Contributor |
IA do Azure Search | Listar chaves de API para listar índices do Estúdio do OpenAI do Azure. |
Contributor |
Conta de Armazenamento | Listar SAS de conta para carregar arquivos do Estúdio do OpenAI do Azure. |
Contributor |
O grupo de recursos ou a assinatura do Azure onde o desenvolvedor precisa implantar o aplicativo Web | Implante o aplicativo Web na assinatura do Azure do desenvolvedor. |
Configurar o gateway e o cliente
Para acessar o serviço de OpenAI do Azure a partir de seus computadores cliente locais, uma das abordagens é configurar o Gateway de VPN do Azure e o Cliente VPN do Azure.
Siga estas diretrizes para criar um gateway de rede virtual para sua rede virtual.
Siga estas diretrizes para adicionar a configuração ponto a site e habilitar a autenticação baseada no Microsoft Entra ID. Baixe o pacote de configuração de perfil do Cliente VPN do Azure, descompacte-o e importe o arquivo AzureVPN/azurevpnconfig.xml
para o cliente VPN do Azure.
Configure o arquivo hosts
do computador local para apontar os nomes de host dos recursos para os IPs privados em sua rede virtual. O arquivo hosts
está localizado em C:\Windows\System32\drivers\etc
no Windows e em /etc/hosts
no 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
Estúdio do OpenAI do Azure
Você deve ser capaz de usar todos os recursos do Estúdio do OpenAI do Azure, incluindo a ingestão e a inferência, a partir de seus computadores cliente locais.
Aplicativo Web
O aplicativo Web se comunica com o recurso de OpenAI do Azure. Como o recurso de OpenAI do Azure 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 o recurso de OpenAI do Azure.
O aplicativo Web precisa resolver o nome do host do OpenAI do Azure para o IP privado do ponto de extremidade privado do OpenAI do Azure. Portanto, você precisa configurar a zona DNS privada para sua rede virtual primeiro.
- Crie uma zona DNS privada em seu grupo de recursos.
- Adicione um registro DNS. O IP é o IP privado do ponto de extremidade privado para o recurso de OpenAI do Azure e você pode obter o endereço IP do adaptador de rede associado ao ponto de extremidade privado para o OpenAI do Azure.
- 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 no Estúdio do OpenAI do Azure, selecione o mesmo local da rede virtual e escolha um SKU adequado, para que ele possa dar suporte ao recurso de integração com a rede virtual.
Depois que o aplicativo Web for implantado, na guia Rede do portal do Azure, configure a integração da rede virtual do tráfego de saída do aplicativo Web e escolha a terceira sub-rede que você reservou para o aplicativo Web.
Usando a API
Verifique se a sua credencial de entrada tem a função Cognitive Services OpenAI Contributor
em seu recurso de 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 anotações:
JOB_NAME
no caminho da API será usado como o nome do índice na Pesquisa de IA do Azure.- Use o cabeçalho
Authorization
em vez de api-key. - Defina o cabeçalho
storageEndpoint
explicitamente. - Use o formato
ResourceId=
para o cabeçalhostorageConnectionString
, para que o OpenAI do Azure e a Pesquisa de IA do Azure usem a identidade gerenciada para autenticar a conta de armazenamento, o que é necessário para ignorar as restrições de rede. - Não defina o cabeçalho
searchServiceAdminKey
. A identidade atribuída pelo sistema do recurso de OpenAI do Azure é usada para autenticar a Pesquisa de IA do Azure. - Não defina
embeddingEndpoint
nemembeddingKey
. Em vez disso, use o cabeçalhoembeddingDeploymentName
para habilitar a vetorização de texto.
Exemplo de envio 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 \
'
{
}
'
Exemplo de obtenção de status do 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.