Configurar um serviço de pesquisa para se conectar usando uma identidade gerenciada no Azure AI Search
Importante
A atribuição de identidade gerenciada atribuída pelo usuário está em visualização pública em Termos de Uso Suplementares. A API REST de visualização de gerenciamento fornece atribuição de identidade gerenciada atribuída pelo usuário para a Pesquisa de IA do Azure. O suporte para uma identidade gerenciada atribuída ao sistema está geralmente disponível.
Você pode usar a ID do Microsoft Entra e as atribuições de função para conexões de saída da Pesquisa de IA do Azure para recursos que fornecem dados, IA aplicada ou vetorização durante a indexação ou consultas.
Para usar funções em uma conexão de saída, primeiro configure seu serviço de pesquisa para usar uma identidade gerenciada atribuída pelo sistema ou pelo usuário como a entidade de segurança para seu serviço de pesquisa em um locatário do Microsoft Entra. Depois de ter uma identidade gerenciada, você pode atribuir funções para acesso autorizado. Identidades gerenciadas e atribuições de função eliminam a necessidade de passar segredos e credenciais em uma cadeia de conexão ou código.
Pré-requisitos
Um serviço de pesquisa na camada Básica ou superior, qualquer região.
Um recurso do Azure que aceita solicitações de entrada de uma entidade de segurança do Microsoft Entra que tenha uma atribuição de função válida.
Cenários suportados
O Azure AI Search pode se conectar a outros recursos do Azure sob sua identidade gerenciada atribuída pelo sistema ou pelo usuário.
- A configuração do serviço de pesquisa de uma identidade gerenciada atribuída ao sistema está geralmente disponível.
- A configuração do serviço de pesquisa de uma identidade gerenciada atribuída pelo usuário está em visualização pública, sob termos de uso suplementares.
- O uso do plano de dados de uma identidade gerenciada, seja do sistema ou atribuída pelo usuário, está geralmente disponível. Por exemplo, se você quiser uma identidade gerenciada atribuída pelo usuário em uma conexão de fonte de dados indexadora, cofre de chaves, sessão de depuração ou cache de enriquecimento, poderá usar uma versão da API REST geralmente disponível para criar a conexão, supondo que o recurso que você está usando também esteja disponível ao público.
Uma identidade gerenciada pelo sistema é indicada quando uma cadeia de conexão é a ID de recurso exclusiva de um serviço ou aplicativo com reconhecimento de ID do Microsoft Entra. Uma identidade gerenciada atribuída pelo usuário é especificada por meio de uma propriedade "identity".
Um serviço de pesquisa usa o Armazenamento do Azure como uma fonte de dados indexadora e como um coletor de dados para sessões de depuração, cache de enriquecimento e armazenamento de conhecimento. Para recursos de pesquisa que gravam de volta no armazenamento, a identidade gerenciada precisa de uma atribuição de função de colaborador, conforme descrito na seção "Atribuir uma função".
| Cenário | Sistema | Atribuída pelo utilizador |
|---|---|---|
| Conexões do indexador com fontes de dados do Azure com suporte 1 | Sim | Sim |
| Azure Key Vault para chaves gerenciadas pelo cliente | Sim | Sim |
| Sessões de depuração (hospedadas no Armazenamento do Azure)1 | Sim | No |
| Cache de enriquecimento (hospedado no Armazenamento do Azure) 1, 2 | Sim | Sim |
| Repositório de Conhecimento (hospedado no Armazenamento do Azure) 1 | Sim | Sim |
| Conexões com o Azure OpenAI, Azure AI Foundry e Azure Functions por meio de habilidades/vetorizadores 3 | Sim | Sim |
1 Para conectividade entre pesquisa e armazenamento, sua configuração de segurança de rede impõe restrições sobre o tipo de identidade gerenciada que você pode usar. Somente uma identidade gerenciada pelo sistema pode ser usada para uma conexão de mesma região com o armazenamento por meio da exceção de serviço confiável ou da regra de instância de recurso. Consulte Acesso a uma conta de armazenamento protegida pela rede para obter detalhes.
2 O serviço de pesquisa de IA atualmente não pode se conectar a tabelas em uma conta de armazenamento que tenha o acesso à chave compartilhada desativado.
3 As ligações ao Azure OpenAI, Azure AI Foundry e Azure Functions através de competências/vetorizadores incluem: Habilidade personalizada, Vetorizador personalizado, Habilidade de incorporação do Azure OpenAI, Vetorizador do Azure OpenAI, Habilidade AML e Vetorizador de catálogo de modelos do Azure AI Foundry.
Criar uma identidade gerenciada pelo sistema
Quando você habilita uma identidade gerenciada atribuída ao sistema, a ID do Microsoft Entra cria uma identidade para seu serviço de pesquisa que pode ser usada para autenticar outros serviços do Azure dentro do mesmo locatário. Em seguida, você pode usar essa identidade em atribuições de função para acessar dados e modelos.
Uma identidade gerenciada atribuída ao sistema é exclusiva do seu serviço de pesquisa e vinculada ao serviço por toda a sua vida. Um serviço de pesquisa só pode ter uma identidade gerenciada atribuída ao sistema.
Entre no portal do Azure e encontre seu serviço de pesquisa.
Em Configurações, selecione Identidade.
Na guia Sistema atribuído, em Status, selecione Ativado.
Selecione Guardar.
Depois de salvar as configurações, a página é atualizada para mostrar um identificador de objeto atribuído ao seu serviço de pesquisa.
Criar uma identidade gerida atribuída pelo utilizador
Importante
Parte deste cenário está em pré-visualização pública em Termos de Utilização Suplementares. A API REST de visualização de gerenciamento fornece configuração de identidade gerenciada atribuída pelo usuário para o Azure AI Search.
Uma identidade gerenciada atribuída pelo usuário é um recurso no Azure. Você pode criar várias identidades gerenciadas atribuídas pelo usuário se quiser mais granularidade nas atribuições de função. Por exemplo, você pode querer identidades separadas para diferentes aplicativos e cenários.
Os passos são:
- Na sua subscrição do Azure, crie uma identidade gerida atribuída pelo utilizador.
- No seu serviço de pesquisa, atualize a definição de serviço para habilitar a identidade gerenciada atribuída pelo usuário (esta etapa está em visualização).
- Em outros serviços do Azure aos quais você deseja se conectar, crie uma atribuição de função para a identidade.
- Em conexões de fonte de dados no Azure AI Search, como uma fonte de dados de indexador, faça referência à identidade gerenciada pelo usuário nos detalhes da conexão (esta etapa está geralmente disponível se o suporte para o recurso estiver disponível em geral).
Uma identidade gerenciada atribuída pelo usuário pode ter como escopo assinaturas ou tipos de recursos.
A associação de uma identidade gerenciada atribuída pelo usuário é suportada no portal do Azure, em versões de visualização das APIs REST de Gerenciamento e em pacotes SDK beta que fornecem o recurso.
Inicie sessão no portal do Azure
Selecione Criar um recurso.
Na barra de pesquisa "Serviços de pesquisa e marketplace", procure por "Identidade gerenciada atribuída pelo usuário" e selecione Criar.
Selecione a assinatura, o grupo de recursos e a região. Dê à identidade um nome descritivo.
Selecione Criar e aguarde até que o recurso termine a implantação.
Demora vários minutos até poder usar a identidade.
Na página do serviço de pesquisa, em Configurações, selecione Identidade.
Na guia Usuário atribuído, selecione Adicionar.
Escolha a assinatura e, em seguida, selecione o recurso gerenciado atribuído pelo usuário que você criou na etapa anterior.
Atribuir uma função
Depois de ter uma identidade gerenciada, atribua funções que determinam as permissões do serviço de pesquisa no recurso do Azure.
As permissões de leitura são necessárias para conexões de dados do indexador e para acessar uma chave gerenciada pelo cliente no Cofre de Chaves do Azure.
As permissões de gravação são necessárias para recursos de enriquecimento de IA que usam o Armazenamento do Azure para hospedar dados de sessão de depuração, cache de enriquecimento e armazenamento de conteúdo de longo prazo em um repositório de conhecimento.
As etapas a seguir ilustram o fluxo de trabalho de atribuição de função. Este exemplo é para o Azure OpenAI. Para outros recursos do Azure, consulte Conectar-se ao Armazenamento do Azure, Conectar-se ao Azure Cosmos DB ou Conectar-se ao Azure SQL.
Entre no portal do Azure com sua conta do Azure e vá para seu recurso do Azure OpenAI.
Selecione Controle de acesso no menu à esquerda.
Selecione Adicionar e, em seguida, selecione Adicionar atribuição de função.
Em Funções de função de trabalho, selecione Usuário OpenAI de Serviços Cognitivos e, em seguida, selecione Avançar.
Em Membros, selecione Identidade gerenciada e, em seguida, selecione Membros.
Filtre por subscrição e tipo de recurso (serviços de Pesquisa) e, em seguida, selecione a identidade gerida do seu serviço de pesquisa.
Selecione Rever + atribuir.
Exemplos de cadeia de conexão
Depois que uma identidade gerenciada é definida para o serviço de pesquisa e recebe uma atribuição de função, as conexões de saída podem ser modificadas para usar a ID de recurso exclusiva do outro recurso do Azure. Aqui estão alguns exemplos de cadeias de conexão para vários cenários.
Você pode usar versões de API REST geralmente disponíveis e pacotes do SDK do Azure para essas conexões.
Gorjeta
Você pode criar a maioria desses objetos no portal do Azure, especificando uma identidade gerenciada atribuída pelo sistema ou pelo usuário e, em seguida, exibir a definição JSON para obter a cadeia de conexão.
Fonte de dados de Blob (sistema):
Uma fonte de dados indexadora inclui uma propriedade "credenciais" que determina como a conexão é feita com a fonte de dados. O exemplo a seguir mostra uma cadeia de conexão especificando o ID de recurso exclusivo de uma conta de armazenamento.
O Microsoft Entra ID autentica a solicitação usando a identidade gerenciada pelo sistema do serviço de pesquisa. Observe que a cadeia de conexão não inclui um contêiner. Em uma definição de fonte de dados, um nome de contêiner é especificado na propriedade "container" (não mostrada), não na cadeia de conexão.
"credentials": {
"connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}
Fonte de dados de Blob (usuário):
Uma solicitação de pesquisa para o Armazenamento do Azure também pode ser feita sob uma identidade gerenciada atribuída pelo usuário. A identidade do usuário do serviço de pesquisa é especificada na propriedade "identity".
"credentials": {
"connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
},
. . .
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
}
Uma definição de repositório de conhecimento inclui uma cadeia de conexão para o Armazenamento do Azure. A cadeia de conexão é o ID de recurso exclusivo da sua conta de armazenamento. Observe que a cadeia de caracteres não inclui contêineres ou tabelas no caminho. Eles são definidos na definição de projeção incorporada, não na cadeia de conexão.
"knowledgeStore": {
"storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}
Um indexador cria, usa e lembra o contêiner usado para os enriquecimentos em cache. Não é necessário incluir o contêiner na cadeia de conexão de cache. Você pode encontrar a ID do objeto na página Identidade do seu serviço de pesquisa no portal do Azure.
"cache": {
"enableReprocessing": true,
"storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}
Uma sessão de depuração é executada no portal do Azure e usa uma cadeia de conexão quando você inicia a sessão. Você pode colar uma cadeia de caracteres semelhante ao exemplo a seguir.
"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",
Uma habilidade personalizada tem como alvo o ponto de extremidade de uma função do Azure ou aplicativo que hospeda código personalizado.
urié o ponto de extremidade da função ou aplicativo.authResourceIdinforma ao serviço de pesquisa para se conectar usando uma identidade gerenciada, passando a ID do aplicativo da função ou aplicativo de destino na propriedade.
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "A custom skill that can identify positions of different phrases in the source text",
"uri": "https://contoso.count-things.com",
"authResourceId": "<Azure-AD-registered-application-ID>",
"batchSize": 4,
"context": "/document",
"inputs": [ ... ],
"outputs": [ ...]
}
Habilidade de incorporação do Azure OpenAI e vetorizador do Azure OpenAI:
Uma habilidade de incorporação e vetorizador do Azure OpenAI na Pesquisa de IA tem como alvo o ponto de extremidade de um serviço OpenAI do Azure que hospeda um modelo de incorporação. O ponto de extremidade é especificado na definição de habilidade de incorporação do Azure OpenAI e/ou na definição do vetorizador do Azure OpenAI.
A identidade gerenciada pelo sistema é usada automaticamente se "apikey" e "authIdentity" estiver vazia, como demonstrado no exemplo a seguir. A "authIdentity" propriedade é usada apenas para identidade gerenciada atribuída pelo usuário.
Exemplo de identidade gerenciada pelo sistema:
{
"@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
"description": "Connects a deployed embedding model.",
"resourceUri": "https://url.openai.azure.com/",
"deploymentId": "text-embedding-ada-002",
"modelName": "text-embedding-ada-002",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "embedding"
}
]
}
Aqui está um exemplo de vetorizador configurado para uma identidade gerenciada atribuída ao sistema. Um vetorizador é especificado em um índice de pesquisa.
"vectorizers": [
{
"name": "my_azure_open_ai_vectorizer",
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://url.openai.azure.com",
"deploymentId": "text-embedding-ada-002",
"modelName": "text-embedding-ada-002"
}
}
]
Exemplo de identidade gerenciada atribuída pelo usuário:
Uma identidade gerenciada atribuída ao usuário é usada se "apiKey" estiver vazia e uma válida "authIdentity" for fornecida.
{
"@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
"description": "Connects a deployed embedding model.",
"resourceUri": "https://url.openai.azure.com/",
"deploymentId": "text-embedding-ada-002",
"modelName": "text-embedding-ada-002",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "embedding"
}
],
"authIdentity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
}
}
Aqui está um exemplo de vetorizador configurado para uma identidade gerenciada atribuída pelo usuário. Um vetorizador é especificado em um índice de pesquisa.
"vectorizers": [
{
"name": "my_azure_open_ai_vectorizer",
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://url.openai.azure.com",
"deploymentId": "text-embedding-ada-002",
"modelName": "text-embedding-ada-002"
"authIdentity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
}
}
}
]
Verificar o acesso ao firewall
Se o seu recurso do Azure estiver protegido por um firewall, verifique se há uma regra de entrada que admite solicitações do seu serviço de pesquisa e do portal do Azure.
Para conexões de mesma região com o Armazenamento de Blobs do Azure ou o Azure Data Lake Storage Gen2, use uma identidade gerenciada pelo sistema e a exceção de serviço confiável. Opcionalmente, você pode configurar uma regra de instância de recurso para admitir solicitações.
Para todos os outros recursos e conexões, configure uma regra de firewall IP que admita solicitações do Azure AI Search. Consulte Acesso do indexador ao conteúdo protegido pelos recursos de segurança de rede do Azure para obter detalhes.