Adición de la clasificación semántica a las consultas en Búsqueda de Azure AI

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.

Puede aplicar la clasificación semántica a consultas de texto, consultas híbridas y consultas vectoriales si los documentos de búsqueda contienen campos de cadena y la consulta vectorial tiene una representación de texto en el documento de búsqueda.

En este artículo se explica cómo invocar el clasificador semántico en las consultas. Se supone que usa las API estables o preliminares más recientes. Para obtener ayuda con versiones anteriores, consulte Migración del código de clasificación semántica.

Requisitos previos

Búsqueda de Azure AI en cualquier región que proporcione la clasificación semántica.
Índice de búsqueda existente con una configuración semántica y contenido de texto enriquecido.
Familiaridad con la clasificación semántica.

Nota

Los títulos y respuestas se extraen textualmente del texto del documento de búsqueda. El subsistema semántico usa la comprensión de lectura automática para reconocer el contenido que tiene las características de un título o respuesta, pero no compone nuevas oraciones o frases excepto en el caso de reescritura de consultas. Por este motivo, el contenido que incluye explicaciones o definiciones funciona mejor para la clasificación semántica. Si desea una interacción estilo chat con las respuestas generadas, consulte Recuperación de agentes o Generación aumentada de recuperación (RAG).

Elección de un cliente

Puede usar cualquiera de las siguientes herramientas y SDK para crear una consulta que use la clasificación semántica:

Azure portal, mediante el diseñador de índices para agregar una configuración semántica.
Visual Studio Code con un cliente REST
SDK de Azure para .NET
SDK de Azure para Python
SDK de Azure para Java
SDK de Azure para JavaScript

Evitar características que omiten la puntuación de relevancia

Algunas funcionalidades de consulta omiten la puntuación de relevancia, lo que hace que sean incompatibles con la clasificación semántica. Si la lógica de consulta incluye las siguientes características, no se puede clasificar semánticamente los resultados:

Una consulta con search=* o una cadena de búsqueda vacía, como una consulta de solo filtro pura, no funcionará porque no hay nada para medir la relevancia semántica y, por tanto, las puntuaciones de búsqueda son cero. La consulta debe proporcionar términos o frases que se pueden evaluar durante el procesamiento y que genere documentos de búsqueda puntuados para su relevancia. Los resultados puntuados son entradas para el clasificador semántico.
La ordenación (cláusulas orderBy) en campos específicos prima sobre las puntuaciones de búsqueda y una puntuación semántica. Dado que se supone que la puntuación semántica proporciona la clasificación, agregar una cláusula orderby produce un error HTTP 400 si aplica la clasificación semántica sobre los resultados ordenados.

Configuración de la consulta

De forma predeterminada, las consultas no usan la clasificación semántica. Para usar la clasificación semántica, se pueden usar dos parámetros diferentes. Cada parámetro admite un conjunto diferente de formatos de consulta.

Todas las consultas semánticas, ya sean especificadas a través de search más queryType, o a través de semanticQuery, deben ser texto sin formato y no pueden estar vacías. Como puede ver en la tabla siguiente, el queryType-semantic parámetro admite un subconjunto de formatos de consulta.

Parámetro	Búsqueda de texto sin formato	Sintaxis de búsqueda de texto simple	Sintaxis de búsqueda de texto completo	Búsqueda de vectores	Búsqueda híbrida	Respuestas semánticas y subtítulos
`queryType-semantic` ¹	✅	❌	❌	❌	✅	✅
`semanticQuery="<your plain text query>"` ²	✅	✅	✅	✅	✅	✅

¹queryType=semantic no puede admitir valores explícitos simple o full porque el queryType parámetro se usa para semantic. Los comportamientos de consulta efectivos son los valores predeterminados del analizador simple.

² El semanticQuery parámetro se puede usar para todos los tipos de consulta. Sin embargo, no se admite en el portal de Azure Search Explorer.

Independientemente del parámetro elegido, el índice debe contener campos de texto con contenido semántico enriquecido y una configuración semántica.

El Explorador de búsqueda incluye opciones para la clasificación semántica. Recuerde que no se puede establecer el parámetro semanticQuery en el portal de Azure.

Vaya al servicio de búsqueda en el portal Azure.
Abra un índice de búsqueda y seleccione Explorador de búsqueda.
Seleccione Opciones de consulta. Si ya ha definido una configuración semántica, se selecciona de forma predeterminada. Si no tiene una, cree una configuración semántica para el índice.
Escriba una consulta, como "hotel histórico con buena comida" y seleccione Buscar.

Como alternativa, seleccione vista JSON y pegue definiciones en el editor de consultas. El portal de Azure no admite el uso de semanticQuery, por lo que es necesario establecer queryType en "semantic":

Ejemplo de JSON para establecer el tipo de consulta en la semántica que puede pegar en la vista:

{
  "search": "funky or interesting hotel with good food on site",
  "count": true,
  "queryType": "semantic",
  "semanticConfiguration": "my-semantic-config",
  "captions": "extractive|highlight-true",
  "answers": "extractive|count-3",
  "highlightPreTag": "<strong>",
  "highlightPostTag": "</strong>",
  "select": "HotelId,HotelName,Description,Category"
}

Use Buscar documentos para formular la solicitud.

Una respuesta incluye automáticamente @search.rerankerScore . Si desea títulos o respuestas en la respuesta, habilite la clasificación semántica estableciendo queryTypesemantic en o estableciendo semanticQuery y agregando subtítulos y respuestas a la solicitud.

En los ejemplos siguientes de esta sección se usa el índice hotels-sample para mostrar la clasificación semántica con respuestas semánticas y subtítulos.

Utilice queryType=semantic

Si desea configurar queryType como semantic, pegue la siguiente solicitud en un cliente web como plantilla. Reemplace search-service-name por el nombre del servicio de búsqueda y reemplace hotels-sample si tiene un nombre de índice diferente.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
      "search": "interesting hotel with restaurant on site and cozy lobby or shared area",
      "count": true,
      "queryType": "semantic",
      "semanticConfiguration": "semantic-config",
      "captions": "extractive|highlight-true",
      "answers": "extractive|count-3",
      "highlightPreTag": "<strong>",
      "highlightPostTag": "</strong>",
      "select": "HotelId,HotelName,Description,Category"
}

Establezca queryType a semantic. Esto mejora la precisión de los resultados de la búsqueda mediante la reasignación de las 50 coincidencias principales mediante un modelo de clasificación entrenado en el corpus de Bing para las consultas expresadas en lenguaje natural, en lugar de palabras clave. Si establece el tipo de consulta en "semantic", también debe configurar "semanticConfiguration". Opcionalmente, puede establecer respuestas si desea devolver también las tres respuestas principales si la entrada de consulta se formula en lenguaje natural ("qué es un ...)" y, opcionalmente, puede establecer subtítulos para extraer pasajes clave de los documentos clasificados más altos.
Establézcalo search en una consulta de texto sin formato simple. Puesto que se establece queryTypeen semantic , no se admite la sintaxis simple ni la sintaxis completa de Lucene. Si se proporciona * o una cadena vacía, no se aplica ninguna clasificación semántica a la consulta.
Establezca semanticConfiguration en una configuración semántica predefinida insertada en el índice.
Establézcalo answers para especificar si las respuestas semánticas se incluyen en el resultado. Los valores válidos para este parámetro son extractive y none. Este parámetro solo es válido si el tipo de consulta es "semántico". Cuando se establece en "extractivo", la consulta formula y devuelve respuestas a partir de los pasajes clave en los documentos con la clasificación semántica más alta. El valor predeterminado es una respuesta, pero puede especificar hasta 10 agregando un recuento. Por ejemplo, "answers": "extractive|count-3" devuelve tres respuestas. Para que se devuelva una respuesta, debe haber contenido textual en el campo de destino que parezca una respuesta. Los modelos de lenguaje que se usan para las respuestas se entrenan para reconocer las respuestas, no generarlas. Además, la propia consulta debe tener un aspecto similar a una pregunta.
Configure captions para especificar si los subtítulos semánticos se incluyen en el resultado. Los valores válidos son "none" y "extractive". El valor predeterminado es "ninguno". Este parámetro solo es válido si el tipo de consulta es "semántico". Cuando se establece en "extractivo", la consulta devuelve los subtítulos extraídos de los pasajes clave de los documentos con mayor clasificación.

Cuando los subtítulos se establecen en 'extractivo', el resaltado se habilita de forma predeterminada y se puede configurar anexando el carácter de barra vertical '|' seguido de la opción highlight-<true/false>, como extractive|highlight-true. En este ejemplo se devuelven subtítulos sin resaltados: extractive|highlight-false.

La base de los títulos y respuestas son los campos a los que se hace referencia en "semanticConfiguration". Estos campos están bajo un límite combinado en el intervalo de 2000 tokens o aproximadamente 20 000 caracteres. Si prevé que un recuento de tokens supere este límite, considere la posibilidad de usar un paso de fragmentación de datos mediante la aptitud División de texto. Este enfoque presenta una dependencia de un pipeline de enriquecimiento con IA y de indexadores.
Establezca highlightPreTag y highlightPostTag si desea invalidar el formato de resaltado predeterminado que se aplica a los títulos.

Los títulos aplican formato de resaltado sobre los pasajes clave del documento que resumen la respuesta. El valor predeterminado es <em>. Si desea especificar el tipo de formato (por ejemplo, fondo amarillo), puede establecer el highlightPreTag y highlightPostTag.
Establezca seleccionar para especificar qué campos se devuelven en la respuesta y "count" para devolver el número de coincidencias en el índice. Estos parámetros mejoran la calidad de la solicitud y la legibilidad de la respuesta.
Envíe la solicitud para ejecutar la consulta y devolver los resultados.

Uso de semanticQuery

semanticQueryMediante , puede aplicar explícitamente sintaxis de texto simple o sintaxis de texto completo, lo que significa que ahora puede realizar búsquedas por campos, aumento de términos y búsqueda de proximidad. También puede especificar una consulta de vector puro en lugar de solo híbrida.

Ajuste la solicitud al siguiente JSON para usar semanticQuery.

POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-01
{
    "search": "Description:breakfast",
    "semanticQuery": "interesting hotel with restaurant on site and cozy lobby or shared area",
    "count": true,
    "queryType": "full",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive|count-3",
    "highlightPreTag": "<strong>",
    "highlightPostTag": "</strong>",
    "select": "HotelId,HotelName,Description,Category"
}

Establezca queryType en la sintaxis de búsqueda que está usando, ya sea simple o completa.
Establezca semanticQuery en la consulta de texto sin formato simple que desea usar para la clasificación semántica. No se admiten consultas vacías. Evite operadores o cualquier sintaxis de consulta dentro de la propia cadena.

Use QueryType o SemanticQuery para invocar el clasificador semántico en una consulta semántica. El siguiente ejemplo procede del equipo de SDK de Azure.

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "interesting hotel with restaurant on site and cozy lobby or shared area",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive)
        },
        QueryType = SearchQueryType.Semantic
    });

int count = 0;
Console.WriteLine($"Semantic Search Results:");

Console.WriteLine($"\nQuery Answer:");
foreach (QueryAnswerResult result in response.SemanticSearch.Answers)
{
    Console.WriteLine($"Answer Highlights: {result.Highlights}");
    Console.WriteLine($"Answer Text: {result.Text}");
}

await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
{
    count++;
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.HotelId}: {doc.HotelName}");

    if (result.SemanticSearch.Captions != null)
    {
        var caption = result.SemanticSearch.Captions.FirstOrDefault();
        if (caption.Highlights != null && caption.Highlights != "")
        {
            Console.WriteLine($"Caption Highlights: {caption.Highlights}");
        }
        else
        {
            Console.WriteLine($"Caption Text: {caption.Text}");
        }
    }
}
Console.WriteLine($"Total number of search results:{count}");

Para usar semanticQuery en lugar de establecer queryType a semantic, el fragmento de código de búsqueda se puede reemplazar con el siguiente fragmento de código:

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "Luxury hotel",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive),
            SemanticQuery = "Is there any hotel located on the main commercial artery of the city in the heart of New York?"
        }
    });

Evaluación de la respuesta

Solo se pueden ordenar semánticamente las 50 coincidencias principales de los resultados iniciales. Al igual que con todas las consultas, una respuesta se compone de todos los campos marcados como recuperables o solo esos campos enumerados en el select parámetro . Una respuesta incluye la puntuación de relevancia original y también puede incluir un recuento o resultados por lotes, en función de cómo haya formulado la solicitud.

En la clasificación semántica, la respuesta tiene más elementos: una nueva puntuación de relevancia clasificada semánticamente, un título opcional en texto sin formato y con resaltados y una respuesta opcional. Si los resultados no incluyen estos elementos adicionales, es posible que la consulta esté mal configurada. Como primer paso para solucionar el problema, compruebe la configuración semántica para asegurarse de que se especifica en la definición de índice y la consulta.

En una aplicación cliente, puede estructurar la página de búsqueda para incluir un título como la descripción de la coincidencia, en lugar de todo el contenido de un campo específico. Este enfoque es útil cuando los campos individuales son demasiado densos para la página de resultados de búsqueda.

La respuesta de la consulta de ejemplo anterior ("hotel interesante con restaurante en el sitio y acogedor vestíbulo o área compartida") devuelve tres respuestas ("answers": "extractive|count-e"). Los subtítulos se devuelven porque se establece la propiedad "captions", con versiones de texto plano y resaltadas. Si no se puede determinar una respuesta, se omite de la respuesta. Por motivos de brevedad, en este ejemplo se muestran solo las tres respuestas y los tres resultados de puntuación más altos de la consulta.

{
  "@odata.count": 29,
  "@search.answers": [
    {
      "key": "24",
      "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "score": 0.9340000152587891
    },
    {
      "key": "40",
      "text": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
      "highlights": "Only 8 miles from Downtown. <strong>On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, </strong>All non-smoking<strong> hotel.</strong> Only 15 miles from airport.",
      "score": 0.9210000038146973
    },
    {
      "key": "38",
      "text": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our<strong> shared living space </strong>to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "score": 0.9200000166893005
    }
  ],
  "value": [
    {
      "@search.score": 3.2328331,
      "@search.rerankerScore": 2.575303316116333,
      "@search.captions": [
        {
          "text": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
          "highlights": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our<strong> penthouse </strong>suites offer views for miles and the rooftop<strong> plaza </strong>is open to all guests from sunset to 10 p.m. Enjoy a<strong> complimentary continental breakfast in the lobby, </strong>and free Wi-Fi<strong> throughout </strong>the hotel."
        }
      ],
      "HotelId": "50",
      "HotelName": "Head Wind Resort",
      "Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
      "Category": "Suite"
    },
    {
      "@search.score": 0.632956,
      "@search.rerankerScore": 2.5425150394439697,
      "@search.captions": [
        {
          "text": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
          "highlights": "Every stay starts with a warm cookie. Amenities like the<strong> Counting Sheep sleep experience, </strong>our<strong> Wake-up glorious breakfast buffet and spacious workout facilities </strong>await."
        }
      ],
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Description": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
      "Category": "Budget"
    },
    {
      "@search.score": 3.7076726,
      "@search.rerankerScore": 2.4554927349090576,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
          "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "Category": "Suite"
    },
   . . .
  ]
}

Cargas de trabajo esperadas

Para la clasificación semántica, debe esperar que un servicio de búsqueda admita hasta 10 consultas simultáneas por réplica.

El servicio limita las solicitudes de clasificación semántica si los volúmenes son demasiado altos. Un mensaje de error que incluye estas frases indica que el servicio está en capacidad para la clasificación semántica:

Error in search query: Operation returned an invalid status 'Partial Content'`
@search.semanticPartialResponseReason`
CapacityOverloaded

Si prevé requisitos de rendimiento coherentes cerca, en o superior a este nivel, envíe un ticket de soporte para que podamos provisionar para su carga de trabajo.

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

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-05-12