Configurar um serviço de pesquisa para se conectar usando uma identidade gerenciada no Azure AI Search

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 o princípio 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".

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 conexões com o Azure OpenAI, Azure AI Studio e Azure Functions por meio de habilidades/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 Studio.

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.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

Criar uma identidade gerida atribuída pelo utilizador

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.

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.

1. Entre no portal do Azure com sua conta do Azure e vá para seu recurso do Azure OpenAI.

2. Selecione Controle de acesso no menu à esquerda.

3. Selecione Adicionar e, em seguida, selecione Adicionar atribuição de função.

4. Em Funções de função de trabalho, selecione Usuário OpenAI de Serviços Cognitivos e, em seguida, selecione Avançar.

5. Em Membros, selecione Identidade gerenciada e, em seguida, selecione Membros.

6. 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.

7. 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.

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}"
  }

Loja de conhecimento:

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};"
}

Cache de enriquecimento:

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. Pode encontrar o ID do objeto na página Identidade do seu serviço de pesquisa no portal.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Sessão de depuração:

Uma sessão de depuração é executada no portal 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};",

Habilidade personalizada:

Uma habilidade personalizada tem como alvo o ponto de extremidade de uma função do Azure ou aplicativo que hospeda código personalizado. O ponto de extremidade é especificado na definição de habilidade personalizada. A presença do "authResourceId" diz ao serviço de pesquisa para se conectar usando uma identidade gerenciada, passando o 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 se configurada e se "apikey" e "authIdentity" estiverem vazias. A propriedade "authIdentity" é 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"
    }
  ]
}

 "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:

{
  "@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>"
   }
}

 "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, certifique-se de que existe uma regra de entrada que admite pedidos do seu serviço de pesquisa.

• 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 da Pesquisa. Consulte Acesso do indexador ao conteúdo protegido pelos recursos de segurança de rede do Azure para obter detalhes.

Consulte também

• Descrição geral da segurança
• Visão geral do enriquecimento de IA
• Descrição geral dos indexadores
• Autenticar com o Microsoft Entra ID
• Sobre identidades gerenciadas (Microsoft Entra ID)