Compartir vía

Configuración de un servicio de búsqueda para conectarse mediante una identidad administrada en Búsqueda de Azure AI

  • Artículo

Importante

La asignación de identidad administrada asignada por el usuario está en versión preliminar pública en Términos de uso complementarios. La API REST de la versión preliminar de administración proporciona asignación de identidad administrada asignada por el usuario para Búsqueda de Azure AI. La compatibilidad con una identidad administrada asignada por el sistema está disponible con carácter general.

Puede usar Microsoft Entra ID y las asignaciones de roles para las conexiones salientes de Búsqueda de Azure AI a los recursos que proporcionan datos, IA aplicada o vectorización durante la indexación o las consultas.

Para usar roles en una conexión saliente, configure primero el servicio de búsqueda para que use una identidad administrada asignada por el sistema o asignada por el usuario como principio de seguridad para el servicio de búsqueda en un inquilino de Microsoft Entra. Una vez que tenga una identidad administrada, puede asignar roles para el acceso autorizado. Las identidades administradas y las asignaciones de roles eliminan la necesidad de pasar secretos y credenciales en una cadena de conexión o el código.

Requisitos previos

  • Un servicio de búsqueda en el nivel de servicio Básico o superior, cualquier región.

  • Un recurso de Azure que acepta las solicitudes entrantes de una entidad de seguridad de Microsoft Entra que tiene una asignación de roles válida.

Escenarios admitidos

Búsqueda de Azure AI puede conectarse a otros recursos de Azure en su identidad administrada asignada por el sistema o asignada por el usuario.

  • La configuración del servicio de búsqueda de una identidad administrada asignada por el sistema está disponible con carácter general.
  • La configuración del servicio de búsqueda de una identidad administrada asignada por el usuario está en versión preliminar pública, en términos de uso complementarios.
  • El uso del plano de datos de una identidad administrada, ya sea asignada por el sistema o el usuario, está disponible con carácter general. Por ejemplo, si quiere una identidad administrada asignada por el usuario en una conexión de origen de datos de indexador, almacén de claves, sesión de depuración o caché de enriquecimiento, puede usar una versión de API REST disponible con carácter general para crear la conexión, suponiendo que la característica que usa también esté disponible con carácter general.

Se indica una identidad administrada del sistema cuando una cadena de conexión es el identificador de recurso único de un servicio o aplicación compatible con Microsoft Entra ID. Una identidad administrada asignada por el usuario se especifica mediante una propiedad "identity".

Un servicio de búsqueda usa Azure Storage como origen de datos de indizador y como receptor de datos para sesiones de depuración, almacenamiento en caché de enriquecimiento y almacén de conocimiento. Para las características de búsqueda que se reescribieron en el almacenamiento, la identidad administrada necesita una asignación de roles de colaborador, tal como se describe en la sección "Asignar un rol".

Escenario Sistema Asignada por el usuario
Conexiones del indexador a orígenes de datos de Azure compatibles 1 Sí Sí
Azure Key Vault para claves administradas por el cliente Sí Sí
Sesiones de depuración (hospedadas en Azure Storage)1 Sí No
Caché de enriquecimiento (hospedada en Azure Storage) 1 2 Sí Sí
Almacén de conocimiento (hospedado en Azure Storage) 1 Sí Sí
Conexiones con Azure OpenAI, Azure AI Foundry y Azure Functions a través de aptitudes o vectorizadores 3 Sí Sí

1 Para la conectividad entre la búsqueda y el almacenamiento, la configuración de seguridad de red impone restricciones en el tipo de identidad administrada que puede usar. Solo se puede usar una identidad administrada del sistema para una conexión de la misma región al almacenamiento a través de la regla de instancia de recurso o excepción de servicio de confianza. Ver Acceso a una cuenta de almacenamiento protegida por red para obtener más información.

2 El servicio de búsqueda de IA no se puede conectar actualmente a tablas en una cuenta de almacenamiento que tenga desactivado el acceso a claves compartidas.

3 Las conexiones con Azure OpenAI, Azure AI Foundry y Azure Functions a través de aptitudes o vectorizadores incluyen: Aptitud personalizada, Vectorizador personalizado, Aptitud de inserción de Azure OpenAI, Vectorizador de Azure OpenAI, Aptitud AML y Vectorizador de catálogo de modelo de Azure AI Foundry.

Creación de una identidad administrada por el sistema

Al habilitar una identidad administrada asignada por el sistema, Microsoft Entra ID crea una identidad para el servicio de búsqueda que se puede usar para autenticarse en otros servicios de Azure dentro del mismo inquilino. A continuación, puede usar esta identidad en asignaciones de roles para acceder a datos y modelos.

Una identidad administrada asignada por el sistema es única para el servicio de búsqueda y está enlazada al servicio durante su vigencia. Un servicio de búsqueda solo puede tener una identidad administrada asignada por el sistema.

  1. Inicie sesión en Azure Portal y encuentre su servicio de búsqueda.

  2. En Configuración, seleccione Identidad.

  3. En la pestaña Asignado por el sistema, en Estado, seleccione Activado.

  4. Seleccione Guardar.

    Captura de pantalla de la página Identidad en Azure Portal.

    Después de guardar la configuración, la página se actualiza para mostrar un identificador de objeto asignado al servicio de búsqueda.

    Captura de pantalla de un identificador de objeto de identidad de sistema.

Crear una identidad administrada asignada por el usuario

Importante

Parte de este escenario está en versión preliminar pública en Términos de uso complementarios. La API REST de la versión preliminar de administración proporciona la configuración de identidad administrada asignada por el usuario para Búsqueda de Azure AI.

Una identidad administrada asignada por el usuario es un recurso en Azure. Puede crear varias identidades administradas asignadas por el usuario si desea una mayor granularidad en las asignaciones de roles. Por ejemplo, es posible que desee identidades independientes para diferentes aplicaciones y escenarios.

Los pasos son:

  • En la suscripción de Azure, cree una identidad administrada asignada por el usuario.
  • En el servicio de búsqueda, actualice la definición del servicio para habilitar la identidad administrada asignada por el usuario (este paso está en versión preliminar).
  • En otros servicios de Azure a los que quiere conectarse, cree una asignación de roles para la identidad.
  • En las conexiones de origen de datos en Búsqueda de Azure AI, como un origen de datos de indexador, haga referencia a la identidad administrada por el usuario en los detalles de conexión (este paso está disponible con carácter general si la compatibilidad con la característica está disponible con carácter general).

Una identidad administrada asignada por el usuario se puede limitar a suscripciones, grupos de recursos o tipos de recursos.

La asociación de una identidad administrada asignada por el usuario se admite en Azure Portal, en versiones preliminares de las API REST de administración y en los paquetes del SDK beta que proporcionan la característica.

  1. Inicie sesión en el Portal de Azure

  2. Seleccione Crear un recurso.

  3. En la barra de búsqueda "Servicios de búsqueda y Marketplace", busque "Identidad administrada asignada por el usuario" y, después, seleccione Crear.

    Captura de pantalla del mosaico de identidad administrada por usuario asignado en Azure Marketplace.

  4. Seleccione la suscripción, el grupo de recursos y la región. Asigne un nombre descriptivo a la identidad.

  5. Seleccione Crear y espere a que el recurso termine de implementarse.

    Pasarán varios minutos hasta que pueda utilizar la identidad.

  6. En la página del servicio de búsqueda, en Configuración, seleccione Identidad.

  7. En la pestaña Usuario asignado, seleccione Agregar.

  8. Elija la suscripción y, a continuación, seleccione el recurso administrado asignado por el usuario que creó en el paso anterior.

Asignar un rol

Una vez que tenga una identidad administrada, asigne roles que determinen los permisos del servicio de búsqueda en el recurso de Azure.

  • Se necesitan permisos de lectura para las conexiones de datos del indexador y para acceder a una clave administrada por el cliente en Azure Key Vault.

  • Se necesitan permisos de escritura para las características de enriquecimiento con IA que usan Azure Storage para hospedar datos de sesión de depuración, almacenamiento en caché enriquecido y almacenamiento de contenido a largo plazo en un almacén de conocimiento.

Los pasos siguientes muestran el flujo de trabajo de asignación de roles. Este ejemplo es para Azure OpenAI. Para ver otros recursos de Azure, consulte Conexión a Azure Storage, Conexión a Azure Cosmos DB o Conexión a Azure SQL.

  1. Inicie sesión en Azure Portal con su cuenta de Azure y vaya al recurso de Azure OpenAI.

  2. Seleccione Control de acceso en el menú izquierdo.

  3. Seleccione Agregar y, luego, Agregar asignación de roles.

  4. En Roles de función de trabajo, seleccione Usuario OpenAI de Cognitive Services y, a continuación, Siguiente.

  5. En Miembros, seleccione Identidad administrada y, a continuación, Miembros.

  6. Filtre por suscripción y tipo de recurso (Servicios de búsqueda) y seleccione la identidad administrada del servicio de búsqueda.

  7. Seleccione Revisar y asignar.

Ejemplos de cadena de conexión

Una vez definida una identidad administrada para el servicio de búsqueda y dada una asignación de roles, las conexiones salientes se pueden modificar para usar el identificador de recurso único del otro recurso de Azure. A continuación, se incluyen algunos ejemplos de cadenas de conexión para varios escenarios.

Puede usar las versiones de la API REST disponibles con carácter general y los paquetes del SDK de Azure para estas conexiones.

Sugerencia

Puede crear la mayoría de estos objetos en Azure Portal, especificando una identidad administrada asignada por el usuario o un sistema y, a continuación, ver la definición JSON para obtener la cadena de conexión.

Origen de datos de blob (sistema):

Un origen de datos del indexador incluye una propiedad "credentials" que determina cómo se realiza la conexión con el origen de datos. En el ejemplo siguiente se muestra una cadena de conexión que especifica el identificador de recurso único de una cuenta de almacenamiento.

Microsoft Entra ID autentica la solicitud mediante la identidad administrada del sistema del servicio de búsqueda. Observe que la cadena de conexión no incluye un contenedor. En la definición de un origen de datos, se especifica un nombre de contenedor en la propiedad "container" (no se muestra), no en la cadena de conexión.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Origen de datos de blob (usuario):

También se puede realizar una solicitud de búsqueda para Azure Storage en una identidad administrada asignada por el usuario. La identidad de usuario del servicio de búsqueda se especifica en la propiedad "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}"
  }

Almacén de conocimiento:

Una definición de almacén de conocimiento incluye una cadena de conexión a Azure Storage. La cadena de conexión es el identificador de recurso único de la cuenta de almacenamiento. Observe que la cadena no incluye contenedores ni tablas en la ruta de acceso. Estos elementos se definen en la definición de proyección insertada, no en la cadena de conexión.

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

Caché de enriquecimiento:

Un indexador crea, usa y recuerda el contenedor usado para los enriquecimientos en caché. No es necesario incluir el contenedor en la cadena de conexión de la caché. Puede encontrar el identificador de objeto en la página Identidad del servicio de búsqueda en el Azure Portal.

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

Sesión de depuración:

Una sesión de depuración se ejecuta en el Azure Portal y toma una cadena de conexión al iniciar la sesión. Puede pegar una cadena de conexión es similar a la del ejemplo siguiente.

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Aptitud personalizada:

Una aptitud personalizada tiene como destino el punto de conexión de una función de Azure o una aplicación que hospeda código personalizado.

  • uri es el punto de conexión de la función o la aplicación.

  • authResourceId indica al servicio de búsqueda que se conecte mediante una identidad administrada, pasando el identificador de aplicación de la función de destino o la aplicación en la propiedad.

{
  "@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": [ ...]
}

Aptitud de inserción de Azure OpenAI y vectorizador de Azure OpenAI:

Una aptitud y un vectorizador de inserción de Azure OpenAI en la Búsqueda de AI tienen como destino el punto de conexión de un servicio de OpenAI de Azure que hospeda un modelo de inserción. El punto de conexión se especifica en la definición de aptitud de inserción de Azure OpenAI o en la definición de vectorizador de Azure OpenAI.

La identidad administrada por el sistema se usa automáticamente si "apikey" y "authIdentity" están vacías, como se muestra en el ejemplo siguiente. La propiedad "authIdentity" solo se usa para la identidad administrada asignada por el usuario.

Ejemplo de identidad administrada por el 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"
    }
  ]
}

Este es un ejemplo de vectorizador configurado para una identidad administrada asignada por el sistema. Se especifica un vectorizador en un índice de búsqueda.

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

Ejemplo de identidad administrada asignada por el usuario

Se usa una identidad administrada asignada por el usuario si "apiKey" está vacía y se proporciona un valor válido "authIdentity".

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

Este es un ejemplo de vectorizador configurado para una identidad administrada asignada por el usuario. Se especifica un vectorizador en un índice de búsqueda.

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

Comprobación del acceso al firewall

Si el recurso de Azure está detrás de un firewall, asegúrese de que hay una regla de entrada que admita solicitudes del servicio de búsqueda y de Azure Portal.

Consulte también