Creación de un conjunto de aptitudes (API rest de Azure AI Search)

  • Artículo

Un conjunto de aptitudes es una colección de aptitudes cognitivas que se usan para el enriquecimiento con IA, con una especificación opcional para crear un almacén de conocimiento externo en Azure Storage. Las aptitudes invocan el procesamiento de lenguaje natural y otras transformaciones, como el reconocimiento de entidades, la extracción de frases clave, la fragmentación de texto en páginas lógicas, entre otras.

Un conjunto de aptitudes se adjunta a un indexador. Para usar el conjunto de aptitudes, haga referencia a él en un indexador y, a continuación, ejecute el indexador para importar datos, invocar transformaciones y enriquecimiento, y asignar los campos de salida a un índice. Un conjunto de aptitudes es un recurso de alto nivel, pero solo está operativo dentro del procesamiento del indexador. Como recurso de alto nivel, puede diseñar un conjunto de aptitudes una vez y luego hacer referencia a él en varios indizadores.

Puede usar POST o PUT en la solicitud. Para cualquiera de ellos, el documento JSON del cuerpo de la solicitud proporciona la definición de objeto.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
  Content-Type: application/json  
  api-key: [admin key]

HTTPS es necesario para todas las solicitudes de servicio. Si el conjunto de aptitudes no existe, se crea. Si ya existe, se actualiza a la nueva definición.

Nota

Los conjuntos de aptitudes son la base del enriquecimiento con inteligencia artificial. Un recurso gratuito está disponible para un procesamiento limitado, pero para cargas de trabajo más grandes o más frecuentes, se requiere un recurso de Cognitive Services facturable .

Parámetros de identificador URI

Parámetro Descripción
nombre del servicio Necesario. Establézcalo en el nombre único definido por el usuario del servicio de búsqueda.
nombre del conjunto de aptitudes Obligatorio en el URI si usa PUT. El nombre debe estar en minúsculas, comenzar con una letra o un número, no tener barras diagonales ni puntos y tener menos de 128 caracteres. El nombre debe comenzar con una letra o un número, pero el resto del nombre puede incluir cualquier letra, número y guiones, siempre y cuando los guiones no sean consecutivos.
api-version Necesario. Consulte Versiones de API para obtener una lista de las versiones admitidas.

Encabezados de solicitud

En la siguiente tabla se describen los encabezados de solicitud obligatorios y opcionales.

Campos Descripción
Content-Type Necesario. Establézcalo en application/json
api-key Opcional si usa roles de Azure y se proporciona un token de portador en la solicitud; de lo contrario, se requiere una clave. Las solicitudes de creación deben incluir un api-key encabezado establecido en la clave de administración (en lugar de una clave de consulta). Consulte Conexión a Azure AI Search mediante la autenticación de claves para más información.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene la definición del conjunto de aptitudes. Las aptitudes son independientes o encadenadas juntas a través de asociaciones de entrada-salida, donde la salida de una transformación se convierte en entrada a otra. Un conjunto de aptitudes debe tener al menos una aptitud. No hay ningún límite teórico en el número máximo de aptitudes, pero de tres a cinco es una configuración común.

El siguiente JSON es una representación de alto nivel de las partes principales de la definición.

{   
  "name" : (optional on PUT; required on POST) "Name of the skillset",  
  "description" : (optional) "Anything you want, or nothing at all",   
  "skills" : (required) ["An array of skills. Each skill has an odata.type, name, input and output parameters"],
  "cognitiveServices": 
      {
        "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
        "description": "Optional. Anything you want, or null",
        "key": "<YOUR-COGNITIVE-SERVICES-ALL-IN-ONE-KEY>"
      },
  "knowledgeStore": (optional) { ... },
  "encryptionKey": (optional) { }
}

La solicitud contiene las siguientes propiedades:

Propiedad Descripción
name Necesario. Nombre del conjunto de aptitudes. El nombre debe estar en minúsculas, comenzar con una letra o un número, no tener barras diagonales ni puntos y tener menos de 128 caracteres. El nombre debe comenzar con una letra o un número, pero el resto del nombre puede incluir cualquier letra, número y guiones, siempre y cuando los guiones no sean consecutivos.
skills Matriz de aptitudes. Cada aptitud tiene un parámetro odata.type, name, context y input y output. La matriz puede incluir aptitudes integradas y aptitudes personalizadas. Se requiere al menos una aptitud. Si usa un almacén de conocimiento, incluya una aptitud conformador a menos que defina la forma de datos dentro de la proyección.
cognitiveServices Se requiere una clave todo en uno para las aptitudes facturables que llaman a Cognitive Services APIs en más de 20 documentos diariamente, por indizador. La clave debe ser para un recurso de la misma región que el servicio de búsqueda. Para más información, consulte Asociación de un recurso de Cognitive Services. Si usa la aptitud Búsqueda de entidades personalizadas , incluya esta sección y una clave para habilitar las transacciones más allá de 20 transacciones diariamente por indizador.

No necesita la clave de Cognitive Services, por lo que puede excluir cognitiveServices la sección si el conjunto de aptitudes consta solo de aptitudes personalizadas, aptitudes de utilidad (condicional, conformador, combinación de texto, división de texto) o la aptitud Extracción de documentos. Si desea quitar el recurso de Cognitive Services asociado de un conjunto de aptitudes (para revertir al uso de los límites "predeterminados") especifique @odata.type como #Microsoft.Azure.Search.DefaultCognitiveServices, consulte este ejemplo para obtener más información.
knowledgeStore Opcional. Destino de la salida de enriquecimiento en Azure Storage. Requiere una cadena de conexión a una cuenta y proyecciones de Azure Storage.

storageConnectionString (obligatorio) Cadena con este formato: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net".

projections (obligatorio) Matriz de objetos de proyección que consta de tables, objects, files, que se especifican o son NULL.

tables
Crea una o varias tablas en Azure Table Storage, proyectando contenido de cada documento como filas de una tabla. Cada tabla puede tener las tres propiedades siguientes:
  • name (obligatorio) determina la tabla que se va a crear o usar en Azure Table Storage.
  • generatedKeyName (opcional) es el nombre de una columna que identifica de forma única un documento. Los valores de esta columna se generarán durante el enriquecimiento. Si lo omite, el servicio de búsqueda creará una columna de clave predeterminada basada en el nombre de la tabla.
  • source (obligatorio) es la ruta de acceso a un nodo del árbol de enriquecimiento que proporciona la forma de la proyección. Normalmente es la salida de una aptitud conformador. Las rutas de acceso comienzan por /document/, que representan el documento enriquecido raíz y, a continuación, se extienden a /document/<shaper-output>/, o /document/content/, u otro nodo dentro del árbol de enriquecimiento. Ejemplos: /document/countries/* (todos los países) o /document/countries/*/states/* (todos los estados de todos los países).

objects
Proyecta documentos como blobs en Azure Blob Storage. Cada objeto tiene dos propiedades necesarias:
  • storageContaineres el nombre del contenedor que se va a crear o usar en Azure Blob Storage.
  • source es la ruta de acceso al nodo del árbol de enriquecimiento que proporciona la forma de la proyección. Debe ser JSON válido. El nodo debe proporcionar un objeto JSON, ya sea desde una aptitud que emita JSON válido o la salida de una aptitud conformador.

files
Cada entrada de archivo define el almacenamiento de imágenes binarias en Blob Storage. Las proyecciones de archivo tienen dos propiedades necesarias:
  • storageContaineres el nombre del contenedor que se va a crear o usar en Azure Blob Storage.
  • source es la ruta de acceso al nodo del árbol de enriquecimiento que es la raíz de la proyección. Un valor válido para esta propiedad es "/document/normalized_images/*" para las imágenes de origen de Blob Storage.
claveDeCifrado Opcional. Se usa para cifrar una definición de conjunto de aptitudes en reposo con sus propias claves, administradas en azure Key Vault. Disponible para los servicios de búsqueda facturables creados en o después de 2019-01-01.

Una encryptionKey sección contiene un elemento definido por keyVaultKeyName el usuario (obligatorio), un generado keyVaultKeyVersion por el sistema (obligatorio) y un elemento que keyVaultUri proporciona la clave (obligatorio, también denominado nombre DNS). Un URI de ejemplo podría ser "https://my-keyvault-name.vault.azure.net".

Opcionalmente, puede especificar accessCredentials si no usa una identidad de sistema administrada. Las propiedades de accessCredentials incluyen applicationId (Microsoft Entra ID identificador de aplicación al que se concedieron permisos de acceso a la Key Vault de Azure especificada) y applicationSecret (clave de autenticación de la aplicación registrada). Un ejemplo de la sección siguiente ilustra la sintaxis.

Response

Para una solicitud correcta, debería ver el código de estado "201 Created".

De forma predeterminada, el cuerpo de la respuesta contendrá el JSON de la definición del conjunto de aptitudes que se creó, Sin embargo, si el encabezado de Prefer solicitud está establecido return=minimalen , el cuerpo de la respuesta está vacío y el código de estado correcto es "204 Sin contenido" en lugar de "201 Creado". Esto es cierto independientemente de si se usa PUT o POST para crear el conjunto de aptitudes.

Ejemplos

Ejemplo: Conjunto de aptitudes que reconoce entidades empresariales y opiniones en las opiniones de los clientes

Este conjunto de aptitudes usa dos aptitudes de forma asincrónica, procesando /document/content de forma independiente como dos transformaciones diferentes. Las aptitudes son Reconocimiento de entidades y Sentimiento. En el árbol de enriquecimiento, /document/content proporciona el contenido (o las revisiones de clientes) del origen de datos externo.

{
  "name": "reviews-ss",
  "description": 
  "Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
  "skills":
  [
    {
      "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
      "context": "/document/content",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations",
          "targetName": "companyName"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
      "inputs": [
           {
              "name": "text",
              "source": "/document/content"
           },
          {
               "name": "languageCode",
               "source": "/document/languageCode"
           }
        ],
      "outputs": [
        {
            "name": "sentiment",
            "targetName": "reviewSentiment"
        },
        {
            "name": "confidenceScores",
            "targetName": "sentimentScore"
        }
      ]
    }
  ],
  "cognitiveServices": 
    {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "description": "mycogsvcs resource in West US 2",
    "key": "<your cognitive services all-in-one key goes here>"
    },
  "knowledgeStore": { },
  "encryptionKey": { }
}

Ejemplo: Almacén de conocimiento

Opcionalmente, un conjunto de aptitudes puede enviar la salida al almacén de conocimiento en Azure Storage. Requiere un cadena de conexión a una cuenta de Azure Storage y proyecciones que determinan si el contenido enriquecido llega a la tabla o al almacenamiento de blobs (como objetos o archivos). Normalmente, las proyecciones requieren una aptitud de conformador ascendente que recopila nodos de un árbol de enriquecimiento como entrada, lo que genera una sola forma que se puede pasar a la proyección. Normalmente, un conformador es la última aptitud que se va a procesar.

{
  "name": "reviews-ss",
  "description": 
  "Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
  "skills":
  [
    { ... },
    { ... },
    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "context": "/document/content",
      "inputs": [
        {
            "name": "Company",
            "source": "/document/content/companyName"
        },
        {
            "name": "Sentiment_Score",
            "source": "/document/content/sentimentScore"
        },
        {
            "name": "Sentiment_Label",
            "source": "/document/content/reviewSentiment"
        }
      ],
      "outputs": [
        {
          "name": "output",
          "targetName": "shapeCustomerReviews"
        }
      ]
    }
  ],
  "cognitiveServices": 
    {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "description": "mycogsvcs resource in West US 2",
    "key": "<your cognitive services all-in-one key goes here>"
    },
  "knowledgeStore": { 
      "storageConnectionString": "<your storage account connection string>", 
      "projections": [ 
          { 
            "tables": [ 
                { "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
                . . .
            ], 
            "objects": [ ], 
            "files": [ ]  
          }
      ]     
  } 
  "encryptionKey": { }
}

Ejemplo: Claves de cifrado

Las claves de cifrado son claves administradas por el cliente que se usan para el cifrado adicional de contenido confidencial. En este ejemplo se muestra cómo especificar el cifrado administrado por el cliente en un conjunto de aptitudes.

{
    "name": "reviews-ss",
    "description": "A brief description of the skillset",
    "skills":  [ omitted for brevity ],
    "cognitiveServices": { omitted for brevity },
    "knowledgeStore":  { omitted for brevity  },
    "encryptionKey": (optional) { 
        "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
        "keyVaultKeyVersion": "Version of the Azure Key Vault key",
        "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
        "accessCredentials": (optional, only if not using managed system identity) {
            "applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
            "applicationSecret": "Authentication key of the specified Azure AD application)"}
    }
}

Consulte también