Configurar um serviço de pesquisa para se conectar usando uma identidade gerenciada na Pesquisa de IA do Azure

Você pode usar o Microsoft Entra ID e as atribuições de função para conexões de saída, da Pesquisa de IA do Azure a recursos, fornecendo dados, IA aplicada ou vetorização durante a indexação ou as 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 usuário ou pelo sistema como o princípio de segurança do serviço de pesquisa em um locatário do Microsoft Entra. Quando você tiver uma identidade gerenciada, poderá atribuir funções para acesso autorizado. Identidades gerenciadas e atribuições de função eliminam a necessidade de passar segredos e credenciais em um código ou cadeia de conexão.

Pré-requisitos

• Um serviço de pesquisa no nível Básico ou superior, em qualquer região.

• Um recurso do Azure que aceita solicitações de entrada de uma entidade de segurança do Microsoft Entra que tem uma atribuição de função válida.

Cenários com suporte

A Pesquisa de IA do Azure pode se conectar a outros recursos do Azure sob sua identidade gerenciada atribuída pelo usuário ou pelo sistema.

• Geralmente, a configuração do serviço de pesquisa de uma identidade gerenciada atribuída pelo sistema está disponível.
• A configuração do serviço de pesquisa de uma identidade gerenciada atribuída pelo usuário está na visualização pública, sob os termos de uso complementares.
• O uso do plano de dados de uma identidade gerenciada, seja ela atribuída ao sistema ou ao usuário, geralmente está disponível. Por exemplo, se você quiser uma identidade gerenciada atribuída pelo usuário em uma conexão de fonte de dados do indexador, um cofre de chaves, uma sessão de depuração ou um 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 em geral.

Uma identidade gerenciada pelo sistema é indicada quando uma cadeia de conexão é a ID do recurso exclusiva de um serviço ou aplicativo com reconhecimento do Azure AD. Uma identidade gerenciada atribuída pelo usuário é especificada por meio de uma propriedade "identidade".

Um serviço de pesquisa usa o Armazenamento do Microsoft Azure como uma fonte de dados do indexador 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 novamente no armazenamento, a identidade gerenciada precisa de uma atribuição de função de colaborador, conforme descrito na seção "Atribuir uma função ".

¹ Para conectividade entre a pesquisa e o armazenamento, sua configuração de segurança de rede impõe restrições sobre qual tipo de identidade gerenciada você pode usar. Somente uma identidade gerenciada pelo sistema pode ser usada para uma conexão da mesma região com o armazenamento por meio da regra de instância de recurso ou exceção de serviço confiável. Consulte Acesso a uma conta de armazenamento protegida pela rede para obter detalhes.

²Atualmente, o serviço de pesquisa de IA não pode se conectar a tabelas em uma conta de armazenamento que tenha o acesso de chave compartilhada desativado.

³ As conexões com o OpenAI do Azure, o Azure AI Foundry e o Azure Functions por meio de habilidades/vetorizadores incluem: habilidades personalizadas, vetorizadores personalizados, habilidade de incorporação do OpenAI do Azure, vetorizador do OpenAI do Azure, habilidade do AML e vetorizador de catálogo de modelos do Azure AI Foundry.

Criar uma identidade gerenciada do sistema

Quando você habilita uma identidade gerenciada atribuída pelo sistema, o Microsoft Entra ID cria uma identidade para o serviço de pesquisa que pode ser usada para autenticar outros serviços do Azure no 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 pelo sistema é exclusiva para seu serviço de pesquisa e associada ao serviço durante seu tempo de vida. Um serviço de pesquisa só pode ter uma identidade gerenciada atribuída pelo 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 gerenciada atribuída ao usuário

A identidade gerenciada atribuída pelo usuário é um recurso no Azure. Você poderá criar várias identidades gerenciadas atribuídas pelo usuário se quiser mais granularidade em atribuições de função. Por exemplo, talvez você queira identidades separadas para diferentes aplicativos e cenários.

As etapas são:

• Na assinatura do Azure, crie uma identidade gerenciada atribuída pelo usuário.
• No serviço de pesquisa, atualize a definição de serviço para habilitar a identidade gerenciada atribuída pelo usuário (esta etapa está na versão prévia).
• 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 na Pesquisa de IA do Azure, como uma fonte de dados do indexador, faça referência à identidade gerenciada pelo usuário nos detalhes da conexão (essa etapa geralmente estará disponível se o suporte para o recurso estiver disponível em geral).

Uma identidade gerenciada atribuída pelo usuário pode ser definida como escopo para assinaturas, grupos de recursos ou tipos de recursos.

Há suporte para associar uma identidade gerenciada atribuída pelo usuário no portal do Azure, em versões prévias das APIs REST de Gerenciamento e em pacotes beta do SDK que fornecem o recurso.

Atribuir uma função

Depois de ter uma identidade gerenciada, atribua funções que determinam permissões de serviço de pesquisa no recurso do Azure.

• As permissões de leitura são necessárias para conexões de dados do indexador para acessar uma chave gerenciada pelo cliente no Azure Key Vault.

• 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 da 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 da atribuição de função. Este exemplo é para o OpenAI do Azure. Para outros recursos do Azure, consulte Conectar-se ao Armazenamento do Azure, Conectar-se ao Azure Cosmos DB ou Conectar-se ao SQL do Azure.

1. Entre no portal do Azure com sua conta do Azure e acesse o recurso de OpenAI do Azure.

2. Selecione Controle de acesso no menu à esquerda.

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

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

5. Em Membros selecione Identidade gerenciada e selecione Membros.

6. Filtre por assinatura e tipo de recurso (serviços de Pesquisa) e selecione a identidade gerenciada do serviço de pesquisa.

7. Selecione Examinar + atribuir.

Exemplos de cadeia de conexão

Após uma identidade gerenciada ser definida para o serviço de pesquisa e receber 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 disponíveis e pacotes do SDK do Azure para essas conexões.

Fonte de dados do blob (sistema):

Uma fonte de dados do indexador 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 a ID de recurso exclusiva 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 "contêiner" (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 do 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 de 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}"
  }

Repositório 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 é a ID de recurso exclusiva de sua conta de armazenamento. Observe que a cadeia de caracteres não inclui contêineres ou tabelas no caminho. Elas são definidas na projeção inserida, 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 aprimoramentos em cache. Não é necessário incluir o contêiner na cadeia de conexão do cache. Encontre a ID de objeto na página Identidade do 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};"
}

Sessão de depuração:

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 conexão 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 destino o ponto de extremidade de uma função do Azure ou um aplicativo que hospeda código personalizado.

• uri é o ponto de extremidade da função ou aplicativo.

• authResourceId instrui o serviço de pesquisa a se conectar usando uma identidade gerenciada, passando a ID do aplicativo da função ou do 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 direcionam o ponto de extremidade de um serviço do Azure OpenAI 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 Azure OpenAI.

A identidade gerenciada pelo sistema é usada automaticamente se "apikey" e "authIdentity" estiverem vazios, conforme demonstrado no exemplo a seguir. 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"
    }
  ]
}

Aqui está um exemplo de vetorizador configurado para uma identidade gerenciada atribuída pelo 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 pelo usuário é usada se "apiKey" estiver vazio e um "authIdentity" válido for fornecido.

{
  "@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 acesso ao firewall

Se o recurso do Azure estiver protegido por um firewall, verifique se há uma regra de entrada que admite solicitações de seu serviço de pesquisa.

• Para conexões de mesma região com o Armazenamento de Blobs do Azure ou Azure Data Lake Storage Gen2, use uma identidade gerenciada pelo sistema e a exceção de serviço confiável. Opcionalmente, configure uma regra de instância de recurso para admitir solicitações.

• Para todos os outros recursos e conexões, configure uma regra de firewall de IP que admite solicitações de Pesquisa. Consulte Acesso do indexador ao conteúdo protegido pelos recursos de segurança de rede do Azure para obter detalhes.

Confira também

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