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

Artículo
11/19/2024

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

2024-07-01 es la versión estable más reciente.
2024-11-01-preview es la versión preliminar más reciente de la API.

Las instrucciones de actualización se centran en los cambios de código que le permiten realizar cambios importantes de versiones anteriores para que el código existente se ejecute igual que antes, pero en la versión más reciente de la API. Una vez que el código está en orden de trabajo, puede decidir si adoptar características más recientes. Para obtener más información sobre las características nuevas, consulte Ejemplos de código vectorial y Novedades.

Se recomienda actualizar las versiones de API sucesivamente, trabajando en cada versión hasta que llegue a la más reciente.

2023-07-01-preview fue la primera API de REST para la compatibilidad con vectores. No usar esta versión de API. Ahora está en desuso y debe migrar a las API de REST estables o más recientes de la versión preliminar inmediatamente.

Nota:

Los documentos de referencia de la API de REST ahora tienen versiones. Para el contenido específico de la versión, abra una página de referencia y, a continuación, use el selector situado a la derecha, encima de la tabla de contenido, para elegir la versión.

Cuándo actualizar

Azure AI Search interrumpe la compatibilidad con versiones anteriores como último recurso. La actualización es necesaria cuando:

El código hace referencia a una versión de API retirada o sin soporte técnico y está sujeta a uno o varios cambios importantes. Debe abordar los cambios importantes si el código tiene como destino 2023-07-10-preview para vectores, 2020-06-01-preview para el clasificador semántico y 2019-05-06 para aptitudes y soluciones alternativas obsoletas.
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).

Procedimiento de actualización

Revise las notas de la versión para cada versión de API.
Actualice el parámetro api-version, especificado en el encabezado de solicitud, a una versión más reciente.

En el código de la aplicación que realiza llamadas directas a las API REST, busque todas las instancias de la versión existente y, a continuación, reemplácela por la nueva versión. Para obtener más información sobre cómo estructurar una llamada REST, consulte Inicio rápido: uso de REST.

Si usa un SDK de Azure, esos paquetes tienen como destino versiones específicas de la API REST. Las actualizaciones de paquetes pueden coincidir con una actualización de la API de REST, pero cada SDK está en su propia programación de versiones que se distribuye independientemente de las versiones de la API de REST de Búsqueda de Azure AI. Compruebe el registro de cambios del paquete del SDK para determinar si una versión de paquete tiene como destino la versión más reciente de la API REST.
Revise los cambios importantes documentados en este artículo e implemente las soluciones alternativas. Comience con la versión usada por el código y resuelva cualquier cambio importante para cada versión de API más reciente hasta que llegue a la versión estable o preliminar más reciente.

Cambio importante del código de cliente que lee la información de conexión

A partir del 29 de marzo de 2024 y aplicable a todas las API de REST admitidas:

GET Skillset, GET Index y GET Indexer ya no devuelven claves ni propiedades de conexión en una respuesta. Se trata de un cambio importante si tiene código de nivel inferior que lee claves o conexiones (datos confidenciales) de una respuesta GET.
Si necesita recuperar claves de API de administrador o de consulta para el servicio de búsqueda, use las API REST de administración.
Si necesita recuperar cadenas de conexión de otro recurso de Azure, como Azure Storage o Azure Cosmos DB, use las API de ese recurso y la guía publicada para obtener la información.

Cambio importante para el clasificador semántico

Clasificador semántico está disponible con carácter general en 2023-11-01. Estos son los cambios importantes para el clasificador semántico de versiones anteriores:

En todas las versiones después de 2020-06-01-preview: semanticConfiguration reemplaza searchFields como mecanismo para especificar qué campos se usarán para la clasificación L2.
Para todas las versiones de API, las actualizaciones del 14 de julio de 2023 a los modelos semánticos hospedados por Microsoft hicieron que el clasificador semántico sea independiente del lenguaje, retirando eficazmente la propiedad queryLanguage. No hay ningún "cambio importante" en el código, pero se omite la propiedad.

Consulte Migración de la versión preliminar para realizar la transición del código para usar semanticConfiguration.

Actualización a 2024-11-01-preview

2024-11-01-preview para la reescritura de consultas, la aptitud Diseño de documento, la facturación sin claves para el procesamiento de aptitudes, el modo de análisis de Markdown y las opciones de revisión para vectores comprimidos.

Si va a actualizar desde 2024-09-01-preview, puede usar las nuevas API de versión preliminar sin ningún cambio en el código existente.

Sin embargo, la nueva versión introduce cambios de sintaxis en vectorSearch.compressions:

Reemplaza rerankWithOriginalVectors por enableRescoring
Mueve defaultOversampling a un nuevo objeto de propiedad rescoringOptions

La compatibilidad con versiones anteriores se conserva debido a una asignación de API interna, pero se recomienda cambiar la sintaxis si adopta la nueva versión preliminar. Para consultar una comparación de la sintaxis, vea Comprimir vectores mediante cuantificación escalar o binaria.

Actualización a 2024-09-01-versión preliminar

2024-09-01-preview agrega compresión de Matryoshka Representation Learning (MRL) para modelos de text-embedding-3, filtrado de vectores dirigidos para consultas híbridas, detalles de subpuntuación de vectores para depuración y fragmentación de tokens para la aptitud de División de texto.

Si va a actualizar desde 2024-05-01-preview, puede usar las nuevas API de versión preliminar sin ningún cambio en el código existente.

Actualice a 2024-07-01

2024-07-01 es una versión general. Las características de versión preliminar anteriores ahora están disponibles con carácter general: fragmentación y vectorización integrada (aptitud División de texto, aptitud AzureOpenAIEmbedding), vectorizador de consultas basado en AzureOpenAIEmbedding, compresión vectorial (cuantificación escalar, cuantificación binaria, propiedad almacenada, tipos de datos estrechos).

No hay cambios importantes si actualiza de 2024-05-01-preview a la versión estable. Para usar la nueva versión estable, cambie la versión de la API y pruebe el código.

Hay cambios importantes si actualiza directamente desde 2023-11-01. Siga los pasos descritos para cada versión preliminar más reciente para migrar de 2023-11-01 a 2024-07-01.

Actualización a 2024-05-01-versión preliminar

2024-05-01-preview agrega un índice OneLake, admitir con vectores binarios y admitir con más modelos de inserción.

Si va a actualizar desde 2024-03-01-preview, la aptitud AzureOpenAIEmbedding ahora requiere un nombre de modelo y una propiedad de dimensiones.

Busque referencias de AzureOpenAIEmbedding.
Establezca modelName en "text-embeding-ada-002" y establezca dimensions en "1536".

Actualización a 2024-03-01-versión preliminar

2024-03-01-preview agrega tipos de datos estrechos, cuantificación escalar y opciones de almacenamiento de vectores.

Si va a actualizar desde 2023-10-01-preview, no hay cambios importantes. Sin embargo, hay una diferencia de comportamiento: para 2023-11-01 y versiones preliminares más recientes, el vectorFilterMode valor predeterminado ha cambiado de postfiltro a prefiltro para expresiones de filtro.

Busque las referencias de vectorFilterMode en el código base.
Si la propiedad se establece explícitamente, no se requiere ninguna acción. Si usó el valor predeterminado, tenga en cuenta que el nuevo comportamiento predeterminado es filtrar antes de la ejecución de la consulta. Si desea filtrar después de la consulta, establezca vectorFilterMode a postfiltro para conservar el comportamiento anterior.

Actualice a 2023-11-01

2023-11-01 es una versión general. Las características en vista previa (GB) anteriores ahora están disponibles con carácter general: clasificador semántico, índice vectorial y compatibilidad con consultas.

No hay cambios importantes de 2023-10-01-preview, pero hay varios cambios importantes de 2023-07-01-preview a 2023-11-01. Para obtener más información, consulte Actualización de la versión preliminar 2023-07-01.

Para usar la nueva versión estable, cambie la versión de la API y pruebe el código.

Actualización a 2023-10-01-preview

2023-10-01-preview fue la primera versión preliminar para agregar fragmentación y vectorización de datos integrados durante la indexación y la vectorizaciónde consulta integrada. También admite la indexación de vectores y las consultas de la versión anterior.

Si va a actualizar desde la versión anterior, la sección siguiente tiene los pasos.

Actualización de 2023-07-01-versión preliminar

No usar esta versión de API. Implementa una sintaxis de consulta vectorial incompatible con cualquier versión de API más reciente.

2023-07-01-preview ahora está en desuso, por lo que no debe basar el nuevo código en esta versión, ni debe actualizar a esta versión en ninguna circunstancia. En esta sección se explica la ruta de migración de 2023-07-01-preview a cualquier versión de API más reciente.

Actualización del portal para índices vectoriales

Azure Portal admite una ruta de actualización con un solo clic para 2023-07-01-preview índices. Detecta campos vectoriales y proporciona un botón Migrar.

La ruta de migración va de 2023-07-01-preview a 2024-05-01-preview.
Las actualizaciones se limitan a las definiciones de campos vectoriales y a las configuraciones del vector de búsqueda del algoritmo.
Las actualizaciones son unidireccionales. No se puede revertir la actualización. Una vez actualizado el índice, debe usar 2024-05-01-preview o posterior para consultar el índice.

No hay ninguna migración del portal para actualizar la sintaxis de consulta vectorial. Consulte actualizaciones de código para ver los cambios de sintaxis de consulta.

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 la sección actualización de código. La migración del portal solo controla los índices con una configuración del vector de búsqueda del algoritmo. Crea un perfil predeterminado que se asigna al algoritmo de vector de búsqueda 2023-07-01-preview. Los índices con varias configuraciones de vector de búsqueda requieren una migración manual.

Actualización de código para índices y consultas vectoriales

La compatibilidad con el vector de búsqueda se introdujo en Crear o actualizar índice (versión preliminar 2023-07-01).

Es necesario actualizar de 2023-07-01-preview a cualquier versión estable o preliminar más reciente:

Cambio de nombre y reestructuración de la configuración de vectores en el índice
Reescritura de las consultas vectoriales

Siga las instrucciones de esta sección para migrar campos vectoriales, configuración y consultas de 2023-07-01-preview.

Llame a Obtener índice para recuperar la definición existente.
Modifique la configuración de vector de búsqueda. 2023-11-01 y versiones posteriores presentan el concepto de perfiles de vector que agrupan configuraciones relacionadas con vectores con un nombre. Las versiones más recientes también cambian 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": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }
```

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, estando establecida 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 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 2023-11-01 versión estable de la API o versiones más recientes de la API en versión preliminar.

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 en 2020-06-30 y versiones posteriores si el código contiene la siguiente funcionalidad:

Los literales de 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. Desde versiones de API 2019-05-06 y 2019-05-06-Preview en adelante, la API del origen de datos ya no devuelve cadenas de conexión en la respuesta de ninguna operación 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 se ha agregado compatibilidad formal con tipos complejos. Si el código implementó recomendaciones anteriores para la equivalencia de tipos complejos 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 de los que debe 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 preliminares de api, se producirá un error en cualquier intento de actualizarlos o volver a crearlos mediante la versión de API 2019-05-06. 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.
Hay un nuevo límite a partir de la versión de api 2019-05-06 en el número de elementos de colecciones complejas por documento. Si ha creado índices con documentos que superan estos límites mediante la versión preliminar de api-versiones, se produce un error en cualquier intento de volver a indexar esos datos mediante api-versión 2019-05-06. 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" }
  ]
}

Se introdujo un formato similar a árbol más reciente para definir campos de índice en la versión de API 2017-11-11-Preview. 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 anterior, deberá usar la versión de API 2017-11-11-Preview para actualizarlos al nuevo formato antes de que se puedan administrar mediante la versión de API 2019-05-06.

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

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.