Actualización a la API REST más reciente de Azure AI Search

Artículo
04/23/2024

Use este artículo para migrar llamadas del plano de datos a versiones más recientes de la API de REST de Search.

2023-11-01 es la versión estable más reciente. En esta versión, tanto la clasificación semántica como la compatibilidad con los vectores de indexación y consulta están disponibles con carácter general.
La versión preliminar 2023-10-01 es la versión preliminar más reciente. Entre las características en vista previa (GB) se incluyen la vectorización de consultas integrada, la vectorización y fragmentación de datos integrada durante la indexación (usa la aptitud División de texto y la aptitud Inserción de Azure OpenAI). Consulte los ejemplos de código y tutoriales para obtener ayuda con las nuevas características.
2023-07-01-preview fue la primera API REST para la compatibilidad con vectores. Ahora está en desuso y debe migrar a 2023-11-01 o 2023-10-01-preview de inmediato.

Nota:

Ahora se han versionado los documentos de referencia de API. Para obtener el contenido adecuado, abra una página de referencia y, después, filtre por versión, para lo que debe usar el selector que se encuentra encima de la tabla de contenido.

Procedimiento de actualización

Azure AI Search interrumpe la compatibilidad con versiones anteriores como último recurso. En esta sección se proporcionan instrucciones que le ayuden a modificar el código existente que no se ejecutará en una versión más reciente. La actualización es necesaria cuando:

El código hace referencia a una versión retirada o en desuso de la API y está sujeta a un cambio importante, o a varios. Las versiones de la API que se encuentran en esta categoría se incluyen 2023-07-10-preview para vectores y 2019-05-06.
Se produce un error en el código cuando se devuelven propiedades no reconocidas en una respuesta de la API. Como procedimiento recomendado, la aplicación debe omitir las propiedades que no entiende.
El código conserva las solicitudes de API e intenta volver a enviarlas a la nueva versión de API. Por ejemplo, esto podría suceder si la aplicación conserva tokens de continuación devueltos por la API de búsqueda (para más información, busque @search.nextPageParameters en la referencia de la API de búsqueda).

Actualización a 2023-10-01-preview

Esta versión es idéntica a la 2023-11-01, pero tiene características adicionales en versión preliminar pública: vectorizador de consulta integrado y modo de filtro previo vectorial. Si desea usar esas características, debe realizar la actualización a la versión preliminar más reciente.

La configuración del algoritmo del vector de búsqueda en un índice de búsqueda es idéntica a la de la versión 2023-11-01. Para reparar los cambios importantes de la versión 2023-07-01-preview, siga las instrucciones de la siguiente sección.

Actualice a 2023-11-01

Esta versión tiene cambios importantes y diferencias de comportamiento para la clasificación semántica y la compatibilidad con el vector de búsqueda.

La clasificación semántica está disponible con carácter general y no usa la propiedad queryLanguage. También requiere una definición de semanticConfiguration.

Para realizar la actualización desde la versión 2020-06-30-preview, cree un elemento semanticConfiguration para reemplazar searchFields. Consulte Migración desde la versión preliminar para ver los pasos.
La compatibilidad con el vector de búsqueda se introdujo en Crear o actualizar índice (versión preliminar 2023-07-01).

Para realizar la actualización de la versión 2023-07-01-preview, cambie el nombre de la configuración de vectores y reestructúrela en el índice, y vuelva a escribir la sintaxis de consulta vectorial, para lo que debe seguir las instrucciones de esta sección.

Para realizar una actualización desde la versión preliminar 2023-10-01, no hay cambios importantes, pero hay una diferencia de comportamiento: el valor predeterminado vectorFilterMode ha cambiado de postfiltro a prefiltro para las expresiones de filtro. Si el código de 2023-10-01-preview no establece vectorFilterMode explícitamente, asegúrese de que conoce el nuevo comportamiento o de establecer el modo en postfiltro para conservar el comportamiento anterior.

Sugerencia

Azure Portal admite una ruta de actualización con un solo clic para los índices de la versión preliminar 2023-07-01. El portal detecta índices de la versión preliminar 2023-07-01 y proporciona un botón Migrar. Antes de seleccionar Migrar, seleccione Editar JSON para revisar primero el esquema actualizado. Debe encontrar un esquema que se ajuste a los cambios descritos en esta sección. La migración del portal solo controla los índices con una configuración de algoritmo de vector de búsqueda, creando un perfil predeterminado que se asigna al algoritmo. Los índices con varias configuraciones requieren una migración manual.

Estos son los pasos para migrar desde la versión preliminar 2023-07-01:

Llame a Obtener índice para recuperar la definición existente.

Modifique la configuración de vector de búsqueda. Esta API presenta el concepto de perfiles vectoriales que agrupa configuraciones relacionadas con vectores en un solo nombre. También cambia el nombre de algorithmConfigurations a algorithms.

Cambie el nombre de algorithmConfigurations a algorithms. Solo se trata de un cambio de nombre de la matriz. El contenido es compatible con versiones anteriores. Esto significa que se pueden usar los parámetros de configuración de HNSW existentes.
Agregue profiles, dando un nombre y una configuración de algoritmo para cada uno.

Antes de la migración (la versión preliminar 2023-07-01):

  "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}

Después de la migración (2023-11-01):

  "vectorSearch": {
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ],
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ]
  }

Modifique las definiciones de campo vectorial, reemplazando vectorSearchConfiguration por vectorSearchProfile. Asegúrese de que el nombre del perfil se resuelve en una nueva definición de perfil vectorial y no en el nombre de configuración del algoritmo. Otras propiedades de campo vectorial permanecen sin cambios. Por ejemplo, no pueden usar las propiedades "filterable", "sortable", o "facetable", ni usar analizadores, normalizadores ni mapas de sinónimos.

Antes (versión preliminar 2023-07-01):

  {
      "name": "contentVector",
      "type": "Collection(Edm.Single)",
      "key": false,
      "searchable": true,
      "retrievable": true,
      "filterable": false,  
      "sortable": false,  
      "facetable": false,
      "analyzer": "",
      "searchAnalyzer": "",
      "indexAnalyzer": "",
      "normalizer": "",
      "synonymMaps": "", 
      "dimensions": 1536,
      "vectorSearchConfiguration": "myHnswConfig"
  }

Después (versión 2023-11-01):

  {
    "name": "contentVector",
    "type": "Collection(Edm.Single)",
    "searchable": true,
    "retrievable": true,
    "filterable": false,  
    "sortable": false,  
    "facetable": false,
    "analyzer": "",
    "searchAnalyzer": "",
    "indexAnalyzer": "",
    "normalizer": "",
    "synonymMaps": "", 
    "dimensions": 1536,
    "vectorSearchProfile": "myHnswProfile"
  }

Llame a Crear o actualizar índice para publicar los cambios.

Modifique buscar POST para cambiar la sintaxis de la consulta. Este cambio de API permite admitir tipos de consulta de vector polimórficos.

Cambie el nombre de vectors a vectorQueries.
Para cada consulta vectorial, agregue kind, y establézcalo en "vector".
Para cada consulta vectorial, cambie el nombre de value a vector.
Opcionalmente, agregue vectorFilterMode si usa expresiones de filtro. El valor predeterminado es prefiltro para los índices creados después de la versión 2023-10-01. Los índices creados antes de esa fecha solo admiten postfiltro, independientemente de cómo establezca el modo de filtro.

Antes (versión preliminar 2023-07-01):

{
    "search": (this parameter is ignored in vector search),
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}

Después (versión 2023-11-01):

{
  "search": "(this parameter is ignored in vector search)",
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}

Estos pasos completan la migración a la versión de la API 2023-11-01.

Actualización a 2020-06-30

En esta versión, hay un cambio importante y varias diferencias de comportamiento. Las características disponibles con carácter general incluyen:

Almacén de conocimiento, almacenamiento persistente de contenido enriquecido creado a través de conjuntos de aptitudes, creado para el análisis y el procesamiento de nivel inferior a través de otras aplicaciones. Los almacenes de conocimiento se crean mediante las API REST de Azure AI Search, pero residen en Azure Storage.

Cambio importante

El código escrito en versiones anteriores de la API se interrumpe tanto en la versión 2020-06-30 como en las versiones posteriores si contiene la siguiente funcionalidad:

Los literales de Any Edm.Date (una fecha que consta de año-mes-día, como 2020-12-12) en expresiones de filtro deben seguir el formato Edm.DateTimeOffset: 2020-12-12T00:00:00Z. Este cambio era necesario para administrar los resultados de consulta erróneos o inesperados debido a las diferencias de zona horaria.

Cambios de comportamiento

El algoritmo de clasificación BM25 reemplaza el algoritmo de clasificación anterior por una tecnología más reciente. Los servicios creados después de 2019 usan este algoritmo automáticamente. Para los servicios anteriores, debe establecer parámetros para usar el nuevo algoritmo.
Los resultados ordenados de los valores NULL han cambiado en esta versión y los valores NULL aparecen en primer lugar si la ordenación es asc y al último si la ordenación es desc. Si escribió código para controlar cómo se ordenan los valores NULL, tenga en cuenta este cambio.

Actualización a 2019-05-06

Entre las características que estuvieron disponibles con carácter general en esta versión de la API se incluyen:

Autocompletar es una característica de escritura anticipada que completa una entrada de término especificada de forma parcial.
Los tipos complejos proporcionan compatibilidad nativa para los datos de objeto estructurado en un índice de búsqueda.
Los modos de análisis de JsonLines, parte de la indexación de Azure Blob, crean un documento de búsqueda por entidad JSON que está separado por una línea nueva.
El enriquecimiento con IA ofrece una indexación que utiliza los motores de enriquecimiento con inteligencia artificial de los servicios de Azure AI.

Cambios importantes

El código escrito en una versión anterior de la API se interrumpe en 2019-05-06 y versiones posteriores si contiene la siguiente funcionalidad:

Propiedad Type de Azure Cosmos DB. En el caso de los indizadores cuyo destino es un origen de datos de la API de Azure Cosmos DB for NoSQL, cambie "type": "documentdb" a "type": "cosmosdb".
Si el control de errores del indizador incluye referencias a la propiedad status, debe quitarla. Hemos quitado el estado de la respuesta de error, ya que no proporcionaba información útil.
Las cadenas de conexión del origen de datos no se devuelven en la respuesta. A partir de las versiones 2019-05-06 y 2019-05-06-Preview de la API, la API del origen de datos ya no devuelve cadenas de conexión en la respuesta de ninguna operación de REST. En versiones anteriores de la API, en el caso de los orígenes de datos creados mediante POST, Azure AI Search devolvía 201, seguido de la respuesta de OData, que contenía la cadena de conexión en texto sin formato.
Se retira la aptitud cognitiva de Reconocimiento de entidades con nombre. Si llamó a la capacidad Reconocimiento de entidades de nombre en el código, se producirá un error en la llamada. La funcionalidad de reemplazo es Aptitud Reconocimiento de entidades (V3). Siga las recomendaciones de Aptitudes en desuso para migrar a una aptitud admitida.

Actualización de tipos complejos

La versión de la API 2019-05-06 agrega compatibilidad formal con tipos complejos. Si el código implementó las recomendaciones anteriores para la equivalencia de tipo complejo en 2017-11-11-Preview o 2016-09-01-Preview, hay algunos límites nuevos y modificados a partir de la versión 2019-05-06 que tiene que tener en cuenta:

Se han reducido los límites de profundidad de campos secundarios y el número de colecciones complejas por índice. Si ha creado índices que superan estos límites mediante las versiones de la API en versión preliminar, cualquier intento de actualizarlos o volver a crearlos con la versión 2019-05-06 de la API producirá un error. Si se encuentra en esta misma situación, tendrá que volver a diseñar el esquema para ajustarlo a los nuevos límites y, después, volver a generar el índice.
Existe un límite nuevo a partir de la versión de la API 2019-05-06 para el número de elementos de colecciones complejas por documento. Si ha creado índices con documentos que superaban estos límites mediante las versiones de la API en versión preliminar, cualquier intento de indexar de nuevo esos datos con la versión 2019-05-06 de la API producirá un error. Si se encuentra en esta misma situación, tendrá que reducir el número de elementos de colección complejos por documento antes de volver a indexar los datos.

Para más información, consulte Límites de servicio en Azure AI Search.

Procedimientos para actualizar una estructura de tipo complejo anterior

Si en el código se usan tipos complejos con una de las versiones anteriores de la API en versión preliminar, es posible que use un formato de definición de índice con este aspecto:

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}

En la versión 2017-11-11-Preview de la API se ha introducido un nuevo formato de tipo árbol para definir campos de índice. En el nuevo formato, cada campo complejo tiene una colección de campos en la que se definen los campos secundarios. En la versión 2019-05-06 de la API, este nuevo formato se usa de forma exclusiva y los intentos de crear o actualizar un índice con el formato antiguo producirán un error. Si tiene índices creados con el formato antiguo, tendrá que usar la versión 2017-11-11-Preview de la API para actualizarlos al formato nuevo antes de poder administrarlos con la versión 2019-05-06 de la API.

Puede actualizar índices "planos" al formato nuevo mediante los pasos siguientes con la versión 2017-11-11-Preview de la API:

Realice una solicitud GET para recuperar el índice. Si ya está en el formato nuevo, ya ha terminado.
Traduzca el índice del formato "plano" al formato nuevo. Tendrá que escribir código para esta tarea, ya que en el momento de redactar este artículo no había ningún código de ejemplo disponible.
Realice una solicitud PUT para actualizar el índice al formato nuevo. Evite cambiar cualquier otro detalle del índice, como la capacidad de búsqueda o de filtrado de campos, ya que la API de actualización de índices no permite aquellos cambios que afectan a la expresión física del índice existente.