Reescritura de consultas con clasificador semántico en Búsqueda de Azure AI (versión preliminar)

Nota

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

Importante

Las características, funcionalidades o propiedades marcadas (versión preliminar) no están cubiertas por un contrato de nivel de servicio, no se recomiendan para cargas de trabajo de producción y pueden cambiar o restringirse antes de que estén disponibles con carácter general. Los términos de la versión preliminar Búsqueda de Azure AI se aplican a todas las funciones de vista previa, ya sea independiente o parte de una característica disponible con carácter general.

La reescritura de consultas (versión preliminar) es el proceso de transformar la consulta de un usuario en una más eficaz, agregando más términos y refinando los resultados de búsqueda. El servicio de búsqueda envía la consulta de búsqueda (o una variación de ella) a un modelo generativo que genera consultas alternativas.

La reescritura de consultas mejora los resultados de la clasificación semántica mediante la corrección de errores tipográficos o ortográficos en las consultas de usuario y la expansión de consultas con sinónimos.

La búsqueda con reescritura de consultas funciona de la siguiente manera:

  • La consulta de usuario se envía a través de la search propiedad en la solicitud.
  • El servicio de búsqueda envía la consulta de búsqueda (o una variación de ella) a un modelo generativo que genera consultas alternativas.
  • El servicio de búsqueda usa la consulta original y las consultas reescritas para recuperar los resultados de la búsqueda.

La reescritura de consultas es una característica opcional. Sin reescritura de consultas, el servicio de búsqueda solo usa la consulta original para recuperar los resultados de la búsqueda.

Nota

Es posible que las consultas reescritas no contengan todos los términos exactos que tenía la consulta original. Esto podría afectar a los resultados de la búsqueda si la consulta era muy específica y requería coincidencias exactas para identificadores únicos o códigos de producto.

Requisitos previos

Sugerencia

El contenido que incluye explicaciones o definiciones funciona mejor para la clasificación semántica.

Haz una solicitud de búsqueda con consultas reescritas

En este ejemplo de API REST, use Search Documents (versión preliminar) para formular la solicitud.

  1. Pegue la siguiente solicitud en un cliente web como plantilla.

    POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
    "search": "newer hotel near the water with a great restaurant",
    "semanticConfiguration":"en-semantic-config",
    "queryType":"semantic",
    "queryRewrites":"generative|count-5",
    "queryLanguage":"en-US",
    "debug":"queryRewrites",
    "top": 1
}

    • Reemplace por search-service-name el nombre del servicio de búsqueda.

    • Reemplace hotels-sample por el nombre del índice si es diferente.

    • Establezca "search" en una consulta de búsqueda de texto completo. La propiedad de búsqueda es necesaria para la reescritura de consultas, a menos que especifique consultas vectoriales. Si especifica consultas vectoriales, el texto "search" debe coincidir con la "text" propiedad del "vectorQueries" objeto. La cadena de búsqueda puede admitir la sintaxis simple o la sintaxis completa de Lucene.

    • Establezca "semanticConfiguration" en un configuración semántica predefinida insertada en el índice.

    • Establezca "queryType" en "semantic". Debe configurar "queryType" como "semantic" o incluir una propiedad "semanticQuery" que no esté vacía en la solicitud. La clasificación semántica es necesaria para la reescritura de consultas.

    • Configure "queryRewrites" a "generative|count-5" para obtener hasta cinco reescrituras de consultas. Puede establecer el recuento en cualquier valor entre 1 y 10.

    • Dado que ha solicitado reescrituras de consultas mediante la propiedad "queryRewrites", debe establecer "queryLanguage" en el idioma del texto de búsqueda. El servicio de búsqueda usa el mismo lenguaje para las reescrituras de consultas. En este ejemplo, se usa "en-US". Las configuraciones regionales admitidas son: en-AU, en-CA, en-GB, en-IN, en-US, ar-EG, ar-JO, ar-KW, ar-MA, ar-SA, bg-BG, bn-IN, ca-ES, cs-CZ, da-DK, de-DE, el-GR, es-ES, es-MX, et-EE, eu-ES, fa-AE, fi-FI, fr-CA, fr-FR, ga-IE, gl-ES, gu-IN, he-IL, hi-IN, hr-BA, hr-HR, hu-HU, hy-AM, id-ID, is-IS, it-IT, ja-JP, kn-IN, ko-KR, lt-LT, lv-LV, ml-IN, mr-IN, ms-BN, ms-MY, nb-NO, nl-BE, nl-NL, no-NO, pa-IN, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sk-SK, sl-SL, sr-BA, sr-ME, sr-RS, sv-SE, ta-IN, te-IN, th-TH, tr-TR, uk-UA, ur-PK, vi-VN, zh-CN, zh-TW.

    • Establezca "debug" en "queryRewrites" para obtener las reescrituras de la consulta en la respuesta.

      Sugerencia

      Solo se establece "debug": "queryRewrites" con fines de prueba. Para mejorar el rendimiento, no use la depuración en producción.

    • Establezca "top" en 1 para devolver solo el resultado de búsqueda superior.

  2. Envíe la solicitud para ejecutar la consulta y devolver los resultados.

A continuación, evaluará los resultados de búsqueda con las reescrituras de la consulta.

Evaluación de la respuesta

Este es un ejemplo de una respuesta que incluye reescrituras de consultas:

"@search.debug": {
  "semantic": null,
  "queryRewrites": {
    "text": {
      "inputQuery": "newer hotel near the water with a great restaurant",
      "rewrites": [
        "new waterfront hotels with top-rated eateries",
        "new waterfront hotels with top-rated restaurants",
        "new waterfront hotels with excellent dining",
        "new waterfront hotels with top-rated dining",
        "new water-side hotels with top-rated restaurants"
      ]
    },
    "vectors": []
  }
},
"value": [
  {
    "@search.score": 58.992092,
    "@search.rerankerScore": 2.815633535385132,
    "HotelId": "18",
    "HotelName": "Ocean Water Resort & Spa",
    "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
    "Description_fr": "Nouvel h\u00f4tel de luxe pour des vacances inoubliables. Vue sur la baie depuis chaque chambre, emplacement pr\u00e8s de la jet\u00e9e, piscine sur le toit, restaurant au bord de l'eau et plus encore.",
    "Category": "Luxury",
    "Tags": [
      "view",
      "pool",
      "restaurant"
    ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2020-11-14T00:00:00Z",
    "Rating": 4.2,
    "Location": {
      "type": "Point",
      "coordinates": [
        -82.537735,
        27.943701
      ],
      "crs": {
        "type": "name",
        "properties": {
          "name": "EPSG:4326"
        }
      }
    },
    //... more properties redacted for brevity
  }
]

Estos son algunos puntos clave que se deben tener en cuenta:

  • Ya que ha configurado la propiedad "debug" como "queryRewrites" para las pruebas, la respuesta incluye un objeto @search.debug con la consulta de entrada de texto y las reescrituras de consultas.
  • Dado que establece la propiedad "queryRewrites" en "generative|count-5", la respuesta incluye hasta cinco reescrituras de consulta.
  • El "inputQuery" valor es la consulta enviada al modelo generativo para la reescritura de consultas. La consulta de entrada no siempre es la misma que la consulta del "search" usuario.

Este es un ejemplo de una respuesta sin reescrituras de consultas.

"@search.debug": {
  "semantic": null,
  "queryRewrites": {
    "text": {
      "inputQuery": "",
      "rewrites": []
    },
    "vectors": []
  }
},
"value": [
  {
    "@search.score": 7.774868,
    "@search.rerankerScore": 2.815633535385132,
    "HotelId": "18",
    "HotelName": "Ocean Water Resort & Spa",
    "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
    "Description_fr": "Nouvel h\u00f4tel de luxe pour des vacances inoubliables. Vue sur la baie depuis chaque chambre, emplacement pr\u00e8s de la jet\u00e9e, piscine sur le toit, restaurant au bord de l'eau et plus encore.",
    "Category": "Luxury",
    "Tags": [
      "view",
      "pool",
      "restaurant"
    ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2020-11-14T00:00:00Z",
    "Rating": 4.2,
    "Location": {
      "type": "Point",
      "coordinates": [
        -82.537735,
        27.943701
      ],
      "crs": {
        "type": "name",
        "properties": {
          "name": "EPSG:4326"
        }
      }
    },
    //... more properties redacted for brevity
  }
]

Consultas vectoriales con reescritura de consultas

Puede incluir consultas vectoriales en la solicitud de búsqueda para combinar la búsqueda de palabras clave y la búsqueda vectorial en una sola solicitud y una respuesta unificada.

Este es un ejemplo de una consulta que incluye una consulta vectorial con reescrituras de consultas. Modifique un ejemplo anterior para incluir una consulta vectorial.

  • Agregue un objeto "vectorQueries" a la solicitud. Este objeto incluye una consulta vectorial con el "kind" establecido en "text".
  • El valor "text" es el mismo que el valor "search". Estos valores deben ser idénticos para que la reescritura de consultas funcione.
POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
    "search": "newer hotel near the water with a great restaurant",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "newer hotel near the water with a great restaurant",
            "k": 50,
            "fields": "Description",
            "queryRewrites": "generative|count-3"
        }
    ],
    "semanticConfiguration":"en-semantic-config",
    "queryType":"semantic",
    "queryRewrites":"generative|count-5",
    "queryLanguage":"en-US",
    "top": 1
}

La respuesta incluye reescrituras de consultas para la consulta de texto y la consulta vectorial.

Prueba la reescritura de consultas con debug

Debería probar las reescrituras de las consultas para asegurarse de que funcionan según lo previsto. Establezca la propiedad "debug": "queryRewrites" en la solicitud de consulta para obtener las reescrituras de la consulta en la respuesta. La configuración "debug" es opcional con fines de prueba. Para mejorar el rendimiento, no configure esta propiedad en producción.

Motivos de respuesta parcial

Es posible que observe que la respuesta de depuración (prueba) incluye una matriz vacía para las text.rewrites propiedades y vectors .

{
  "@odata.context": "https://demo-search-svc.search.windows.net/indexes('hotels-sample')/$metadata#docs(*)",
  "@search.debug": {
    "semantic": null,
    "queryRewrites": {
      "text": {
        "rewrites": []
      },
      "vectors": []
    }
  },
  "@search.semanticPartialResponseReason": "Transient",
  "@search.semanticQueryRewriteResultType": "OriginalQueryOnly",
  //... more properties redacted for brevity
}

En el ejemplo anterior:

  • La respuesta incluye una @search.semanticPartialResponseReason propiedad con un valor de "Transitorio". Este mensaje significa que al menos una de las consultas no se pudo completar.
  • La respuesta también incluye una @search.semanticQueryRewriteResultType propiedad con un valor de "OriginalQueryOnly". Este mensaje significa que las reescrituras de consultas no están disponibles. Solo se usa la consulta original para recuperar los resultados de la búsqueda.

Pasos siguientes

La clasificación semántica se puede usar en consultas híbridas que combinan la búsqueda de palabras clave y la búsqueda vectorial en una sola solicitud y una respuesta unificada.

Consulta híbrida con clasificador semántico

  • Last updated on