Inicio rápido: Clasificación semántica

En este inicio rápido, usará la biblioteca cliente Búsqueda de Azure AI para .NET para agregar semantic ranking a un índice de búsqueda existente y consultar el índice.

La clasificación semántica es una funcionalidad del lado de consulta que usa la comprensión de lectura automática para volver a puntuar los resultados de búsqueda, lo que promueve las coincidencias más semánticamente relevantes en la parte superior de la lista. Puede agregar una configuración semántica a un índice existente sin necesidad de recompilación. La clasificación semántica es más eficaz para texto informativo o descriptivo.

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

• Un servicio Búsqueda de Azure AI.

• Un índice con campos de texto descriptivos atribuidos como searchable y retrievable. En este inicio rápido se da por supuesto el índice hotels-sample.

• .NET 9 o posterior.

• Git para clonar el repositorio de ejemplo.

• El CLI de Azure para la autenticación sin claves con Microsoft Entra ID.

Configuración del acceso

Antes de empezar, asegúrese de que tiene permisos para acceder al contenido y las operaciones en Búsqueda de Azure AI. En este inicio rápido se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Propietario o Administrador de acceso de usuarios para asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en rol recomendado:

1. Habilite el acceso basado en roles para el servicio de búsqueda.

2. Asigne los siguientes roles a la cuenta de usuario.

   • Colaborador del servicio de búsqueda

   • Lector de datos de índice de búsqueda

Obtención del punto de conexión

Cada servicio Búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona acceso de red al servicio. En una sección posterior, especifique este punto de conexión para conectarse al servicio de búsqueda mediante programación.

Para obtener el punto de conexión:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Información general.

3. Anote el punto de conexión, que debería tener un aspecto similar a https://my-service.search.windows.net.

Empezar con un índice

En este inicio rápido se modifica un índice existente para incluir una configuración semántica. Se recomienda el índice hotels-sample, que puede crear en cuestión de minutos mediante un asistente del portal de Azure.

Para usar un índice diferente, reemplace el nombre del índice, los nombres de campo en la configuración semántica y los nombres de campo de las instrucciones de consulta select en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como searchable y retrievable.

Para revisar y consultar el índice hotels-sample antes de la clasificación semántica:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Índices de administración de> búsqueda.

3. Seleccione hotels-sample.

4. Seleccione Configuraciones semánticas para ver las configuraciones existentes. Si ha habilitado la clasificación semántica durante el flujo de creación del asistente, debe haber una configuración predeterminada.

   

5. Seleccione Explorador de búsqueda y, a continuación, seleccione Ver>vista JSON.

6. Pegue el siguiente JSON en el editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Seleccione Buscar para ejecutar la consulta.

   La respuesta debe ser similar al ejemplo siguiente. Se trata de una consulta de texto completo clasificada por BM25, por lo que los resultados coinciden con términos de consulta individuales y variantes lingüísticas en lugar del significado general de la consulta. Por ejemplo, walking coincide con walk, y live y music coinciden independientemente en lugar de como una frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Propina

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de configurar una configuración semántica, agregue "queryType": "semantic" y "semanticConfiguration": "semantic-config" para ver cómo la misma consulta se clasifica de forma diferente por clasificación semántica.

Configuración del entorno

1. Use Git para clonar el repositorio de ejemplo.

   git clone https://github.com/Azure-Samples/azure-search-dotnet-samples
   

2. Vaya a la carpeta de inicio rápido.

   cd azure-search-dotnet-samples/quickstart-semantic-ranking
   

3. En BuildIndex/Program.cs, reemplace el valor del marcador de posición de endpoint por la dirección URL que obtuvo en Get endpoint.

4. Repita el paso anterior para QueryIndex/Program.cs.

5. Para la autenticación sin claves con Microsoft Entra ID, inicie sesión en la cuenta de Azure. Si tiene varias suscripciones, seleccione la que contiene el servicio Búsqueda de Azure AI.

   az login
   

Ejecución del código

1. Ejecute el primer proyecto para actualizar el índice con una configuración semántica.

   dotnet run --project BuildIndex
   

2. Ejecute el segundo proyecto para consultar el índice. Presione Entrar entre consultas para ver la progresión de una consulta simple a una consulta semántica con subtítulos y respuestas.

   dotnet run --project QueryIndex
   

Salida

El primer proyecto actualiza el índice hotels-sample con una configuración semántica. La salida incluye confirmación de la configuración semántica.

Here's a list of all indexes on the search service. You should see hotels-sample:
hotels-sample

Added new semantic configuration 'semantic-config' to the index definition.
Index updated successfully.
Here is the revised index definition:
{
  "Name": "hotels-sample",
  ... // Trimmed for brevity
  "SemanticSearch": {
    "DefaultConfigurationName": "semantic-config",
    "Configurations": [
      {
        "Name": "hotels-sample-semantic-configuration",
        ... // Trimmed for brevity
      },
      {
        "Name": "semantic-config",
        "PrioritizedFields": {
          "TitleField": {
            "FieldName": "HotelName"
          },
          "ContentFields": [
            {
              "FieldName": "Description"
            }
          ],
          "KeywordsFields": [
            {
              "FieldName": "Tags"
            }
          ]
        },
        "RankingOrder": {}
      }
    ]
  }
}

El segundo proyecto ejecuta cuatro consultas. La salida incluye los resultados de búsqueda con puntuaciones de relevancia, subtítulos y respuestas.

Query 1: Simple query using the search string 'walking distance to live music'.
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
----------------------------------------
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.
@search.score: 4.555706
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 2: Semantic query (no captions, no answers) for 'walking distance to live music'.
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.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
@search.rerankerScore: 2.271434783935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 3: Semantic query with captions.
Caption: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>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.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.
Extractive Answers:
  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<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
----------------------------------------
... // Trimmed for brevity

Descripción del código

Ahora que ha ejecutado el código, vamos a desglosar los pasos clave:

1. Configuración y autenticación
2. Actualización del índice con una configuración semántica
3. Consulta del índice

Configuración y autenticación

Ambos proyectos comparten el mismo patrón de configuración. Los Program.cs archivos definen el punto de conexión de búsqueda y usan DefaultAzureCredential para la autenticación sin claves.

var endpoint = new Uri("PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE");
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(endpoint, credential);

Conclusiones clave:

• DefaultAzureCredential proporciona autenticación sin claves mediante Microsoft Entra ID. Encadena varios tipos de credenciales, incluida la credencial de CLI de Azure de az login.
• SearchIndexClient administra las operaciones de nivel de índice, como actualizar el esquema de índice.
• SearchClient controla las operaciones de nivel de documento, como consultar el índice.

Actualización del índice con una configuración semántica

El código siguiente de BuildIndex/Program.cs agrega una configuración semántica al índice existente. Esta operación no elimina ningún documento de búsqueda y el índice permanece operativo después de agregar la configuración.

static void AddSemanticConfiguration(
    SearchIndex index,
    string semanticConfigName)
{
    if (index.SemanticSearch == null)
    {
        index.SemanticSearch = new SemanticSearch();
    }
    var configs = index.SemanticSearch.Configurations;
    if (!configs.Any(c => c.Name == semanticConfigName))
    {
        var prioritizedFields =
            new SemanticPrioritizedFields
        {
            TitleField = new SemanticField("HotelName"),
            ContentFields =
            {
                new SemanticField("Description")
            },
            KeywordsFields =
            {
                new SemanticField("Tags")
            }
        };

        configs.Add(
            new SemanticConfiguration(
                semanticConfigName,
                prioritizedFields
            )
        );
    }
    index.SemanticSearch.DefaultConfigurationName =
        semanticConfigName;
}

Conclusiones clave:

• Una configuración semántica especifica los campos usados para la clasificación semántica.
• Las configuraciones semánticas se pueden agregar a índices existentes sin reconstruir.
• TitleField establece el campo que representa el título del documento.
• ContentFields establece los campos que contienen el contenido principal.
• KeywordsFields establece los campos que contienen palabras clave o etiquetas.

Consulta del índice

El QueryIndex proyecto ejecuta cuatro consultas en secuencia, avanzando desde una búsqueda de palabras clave simple hasta la clasificación semántica con subtítulos y respuestas.

Consulta simple

La primera consulta es una búsqueda de palabras clave sencilla que no usa la clasificación semántica. Esta consulta sirve como línea de base para comparar los resultados con y sin el reranking semántico.

await RunQuery(client, searchText, new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Simple,
    IncludeTotalCount = true,
    Select = { "HotelId", "HotelName", "Description" }
});

Conclusiones clave:

• SearchQueryType.Simple usa el algoritmo de clasificación BM25 predeterminado.
• Los resultados solo se clasifican por relevancia de palabra clave (@search.score).

Consulta semántica (sin títulos, sin respuestas)

La siguiente consulta agrega una clasificación semántica sin títulos ni respuestas. El código siguiente muestra el requisito mínimo para invocar la clasificación semántica.

var semanticOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config"
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(client, searchText, semanticOptions);

Conclusiones clave:

• SearchQueryType.Semantic habilita la clasificación semántica en la consulta.
• SemanticConfigurationName especifica la configuración semántica que se va a usar.
• @search.rerankerScore indica la relevancia semántica (mayor es mejor).
• Los resultados iniciales de la consulta de términos se vuelven a puntuar mediante modelos de clasificación semántica. Para este conjunto de datos y consulta, los efectos de la clasificación semántica se pronuncian más en los resultados con clasificación inferior.

Consulta semántica con subtítulos

El código siguiente agrega descripciones para extraer los pasajes más relevantes de cada resultado, con el resaltado de coincidencias aplicado a los términos y frases importantes.

var captionsOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryCaption =
            new QueryCaption(QueryCaptionType.Extractive)
        {
            HighlightEnabled = true
        }
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
captionsOptions.HighlightFields.Add("Description");
await RunQuery(
    client, searchText, captionsOptions, showCaptions: true
);

Conclusiones clave:

• QueryCaption habilita subtítulos extractivos en los campos de contenido.
• Los títulos exponen los pasajes más relevantes y agregan <em> etiquetas en torno a términos importantes.

Consulta semántica con respuestas

La consulta final agrega respuestas semánticas. Esta consulta usa una cadena de búsqueda diferente (searchText2) porque las respuestas semánticas funcionan mejor cuando la consulta se frase como una pregunta. La respuesta es un pasaje textual extraído del índice, no una respuesta compuesta de un modelo de finalización de chat.

La consulta y el contenido indizado deben estar estrechamente alineados para que se devuelva una respuesta. Si ningún candidato cumple el umbral de confianza, la respuesta no incluye una respuesta. En este ejemplo se usa una pregunta conocida para generar un resultado para que pueda ver la sintaxis. Si las respuestas no son útiles para su escenario, omita QueryAnswer del código. Para las respuestas compuestas, considere un patrón RAG o recuperación agentiva.

var answersOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryAnswer =
            new QueryAnswer(QueryAnswerType.Extractive)
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(
    client, searchText2, answersOptions, showAnswers: true
);

Conclusiones clave:

• QueryAnswer habilita respuestas extractivas para consultas similares a preguntas.
• Las respuestas son contenido textual extraído del índice, no texto generado.

En esta guía de inicio rápido, usará la biblioteca cliente Búsqueda de Azure AI para Java para agregar clasificación semántica a un índice de búsqueda existente y consultar el índice.

La clasificación semántica es una funcionalidad del lado de consulta que usa la comprensión de lectura automática para volver a puntuar los resultados de búsqueda, lo que promueve las coincidencias más semánticamente relevantes en la parte superior de la lista. Puede agregar una configuración semántica a un índice existente sin necesidad de recompilación. La clasificación semántica es más eficaz para texto informativo o descriptivo.

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

• Un servicio Búsqueda de Azure AI.

• Un índice con campos de texto descriptivos atribuidos como searchable y retrievable. En este inicio rápido se da por supuesto el índice hotels-sample.

• Java 21 (LTS) y Maven.

• Git para clonar el repositorio de ejemplo.

• El CLI de Azure para la autenticación sin claves con Microsoft Entra ID.

Configuración del acceso

Antes de empezar, asegúrese de que tiene permisos para acceder al contenido y las operaciones en Búsqueda de Azure AI. En este inicio rápido se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Propietario o Administrador de acceso de usuarios para asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en rol recomendado:

1. Habilite el acceso basado en roles para el servicio de búsqueda.

2. Asigne los siguientes roles a la cuenta de usuario.

   • Colaborador del servicio de búsqueda

   • Lector de datos de índice de búsqueda

Obtención del punto de conexión

Cada servicio Búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona acceso de red al servicio. En una sección posterior, especifique este punto de conexión para conectarse al servicio de búsqueda mediante programación.

Para obtener el punto de conexión:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Información general.

3. Anote el punto de conexión, que debería tener un aspecto similar a https://my-service.search.windows.net.

Empezar con un índice

En este inicio rápido se modifica un índice existente para incluir una configuración semántica. Se recomienda el índice hotels-sample, que puede crear en cuestión de minutos mediante un asistente del portal de Azure.

Para usar un índice diferente, reemplace el nombre del índice, los nombres de campo en la configuración semántica y los nombres de campo de las instrucciones de consulta select en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como searchable y retrievable.

Para revisar y consultar el índice hotels-sample antes de la clasificación semántica:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Índices de administración de> búsqueda.

3. Seleccione hotels-sample.

4. Seleccione Configuraciones semánticas para ver las configuraciones existentes. Si ha habilitado la clasificación semántica durante el flujo de creación del asistente, debe haber una configuración predeterminada.

   

5. Seleccione Explorador de búsqueda y, a continuación, seleccione Ver>vista JSON.

6. Pegue el siguiente JSON en el editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Seleccione Buscar para ejecutar la consulta.

   La respuesta debe ser similar al ejemplo siguiente. Se trata de una consulta de texto completo clasificada por BM25, por lo que los resultados coinciden con términos de consulta individuales y variantes lingüísticas en lugar del significado general de la consulta. Por ejemplo, walking coincide con walk, y live y music coinciden independientemente en lugar de como una frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Propina

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de configurar una configuración semántica, agregue "queryType": "semantic" y "semanticConfiguration": "semantic-config" para ver cómo la misma consulta se clasifica de forma diferente por clasificación semántica.

Configuración del entorno

1. Use Git para clonar el repositorio de ejemplo.

   git clone https://github.com/Azure-Samples/azure-search-java-samples
   

2. Vaya a la carpeta de inicio rápido.

   cd azure-search-java-samples/quickstart-semantic-ranking
   

3. En src/main/resources/application.properties, reemplace el valor del marcador de posición de azure.search.endpoint por la dirección URL que obtuvo en Get endpoint.

4. Compile el proyecto para resolver las dependencias, incluidos azure-search-documents.

   mvn compile
   

   Cuando se complete la compilación, compruebe que no aparece ningún error en la salida.

5. Para la autenticación sin claves con Microsoft Entra ID, inicie sesión en la cuenta de Azure. Si tiene varias suscripciones, seleccione la que contiene el servicio Búsqueda de Azure AI.

   az login
   

Ejecución del código

1. Obtenga la configuración de índice existente.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.GetIndexSettings"
   

2. Actualice el índice con una configuración semántica.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.UpdateIndexSettings"
   

3. Ejecute una consulta semántica.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQuery"
   

4. Ejecute una consulta semántica con subtítulos.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQueryWithCaptions"
   

5. Ejecute una consulta semántica con respuestas.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticAnswer"
   

Salida

La salida de GetIndexSettings.java es el nombre del índice, sus campos y sus configuraciones semánticas. Antes de agregar una nueva configuración, el índice solo tiene el predeterminado.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic search configurations: 1
Configuration name: hotels-sample-semantic-configuration

La salida de UpdateIndexSettings.java enumera todas las configuraciones semánticas del índice, incluida la que agregó el código, seguido de un mensaje de confirmación.

// Trimmed for brevity
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

La salida de SemanticQuery.java devuelve todos los documentos que coinciden, ordenados según la puntuación del reordenador de clasificación semántica.

Search result #1:
  Re-ranker Score: 2.61
  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.

Search result #2:
  Re-ranker Score: 2.27
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.99
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

La salida de SemanticQueryWithCaptions.java agrega un elemento de título con resaltado de coincidencias junto con los campos de búsqueda. Los títulos son los pasajes más relevantes en un resultado. Si el índice incluye texto más grande, los subtítulos ayudan a extraer las oraciones más interesantes.

Search result #1:
  Re-ranker Score: 2.61
  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.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.27
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

La salida de SemanticAnswer.java incluye una respuesta semántica extraída de uno de los resultados que mejor coincide con la pregunta, seguido de resultados de búsqueda con subtítulos.

Semantic answer result #1:
Semantic Answer: 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<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.98

Search Results:

Search result #1:
Re-ranker Score: 2.12
Hotel: Stay-Kay City Hotel
Description: This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.

Search result #2:
Re-ranker Score: 2.07
Hotel: Double Sanctuary Resort
Description: 5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
Caption: <em>5 star Luxury Hotel </em>-<em> Biggest </em>Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
// Trimmed for brevity

Descripción del código

Ahora que ha ejecutado el código, vamos a desglosar los pasos clave:

1. Configuración y autenticación
2. Actualización del índice con una configuración semántica
3. Consulta del índice

Configuración y autenticación

La SearchConfig.java clase carga las propiedades de application.properties y crea un DefaultAzureCredential para la autenticación sin claves.

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;

public class SearchConfig {
    private static final Properties properties =
        new Properties();

    static {
        try (InputStream input = SearchConfig.class
            .getClassLoader()
            .getResourceAsStream(
                "application.properties")) {
            properties.load(input);
        } catch (IOException e) {
            throw new RuntimeException(
                "Failed to load application.properties",
                e);
        }
    }

    public static final String SEARCH_ENDPOINT =
        properties.getProperty(
            "azure.search.endpoint");
    public static final String INDEX_NAME =
        properties.getProperty(
            "azure.search.index.name");
    public static final String SEMANTIC_CONFIG_NAME =
        properties.getProperty(
            "semantic.configuration.name");

    public static final DefaultAzureCredential
        CREDENTIAL = new DefaultAzureCredentialBuilder()
            .build();
}

Conclusiones clave:

• DefaultAzureCredential proporciona autenticación sin claves mediante Microsoft Entra ID. Encadena varios tipos de credenciales, incluida la credencial de CLI de Azure de az login.
• Las propiedades se cargan desde el application.properties archivo de la ruta de clase.
• Los campos estáticos (SEARCH_ENDPOINT, INDEX_NAME, SEMANTIC_CONFIG_NAME, CREDENTIAL) se comparten entre todas las clases del proyecto.

Actualización del índice con una configuración semántica

La UpdateIndexSettings.java clase agrega una configuración semántica al índice existente hotels-sample . Esta operación no elimina ningún documento de búsqueda y el índice permanece operativo después de agregar la configuración.

import com.azure.search.documents.indexes
    .SearchIndexClientBuilder;
import com.azure.search.documents.indexes.models
    .SearchIndex;
import com.azure.search.documents.indexes.models
    .SemanticConfiguration;
import com.azure.search.documents.indexes.models
    .SemanticField;
import com.azure.search.documents.indexes.models
    .SemanticPrioritizedFields;
import com.azure.search.documents.indexes.models
    .SemanticSearch;

import java.util.ArrayList;
import java.util.List;

var indexClient = new SearchIndexClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

SearchIndex existingIndex =
    indexClient.getIndex(SearchConfig.INDEX_NAME);

var prioritizedFields =
    new SemanticPrioritizedFields()
        .setTitleField(
            new SemanticField("HotelName"))
        .setKeywordsFields(
            List.of(new SemanticField("Tags")))
        .setContentFields(
            List.of(
                new SemanticField("Description")));

var newSemanticConfiguration =
    new SemanticConfiguration(
        SearchConfig.SEMANTIC_CONFIG_NAME,
        prioritizedFields);

SemanticSearch semanticSearch =
    existingIndex.getSemanticSearch();
if (semanticSearch == null) {
    semanticSearch = new SemanticSearch();
    existingIndex.setSemanticSearch(semanticSearch);
}

List<SemanticConfiguration> configurations =
    semanticSearch.getConfigurations();
if (configurations == null) {
    configurations = new ArrayList<>();
    semanticSearch.setConfigurations(configurations);
}

configurations.add(newSemanticConfiguration);

indexClient.createOrUpdateIndex(existingIndex);

Conclusiones clave:

• SemanticPrioritizedFields define los campos que evalúa el clasificador semántico. setTitleField establece el título del documento, setContentFields establece el contenido principal y setKeywordsFields establece los campos de palabra clave o etiqueta.
• SemanticConfiguration empareja un nombre con los campos prioritarios, identificando qué configuración semántica se usará en el momento de la consulta.
• createOrUpdateIndex inserta el esquema actualizado en el servicio de búsqueda sin volver a generar el índice ni eliminar documentos.

Consulta del índice

Las tres clases siguientes consultan el índice en secuencia, progresando desde una búsqueda semántica básica a la clasificación semántica con subtítulos y respuestas.

Consulta semántica (sin títulos, sin respuestas)

La primera consulta agrega clasificación semántica sin subtítulos ni respuestas. La SemanticQuery.java clase muestra el requisito mínimo para invocar la clasificación semántica.

import com.azure.search.documents
    .SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryType;
import com.azure.search.documents.models.SearchOptions;
import com.azure.search.documents.models.SearchResult;
import com.azure.search.documents.models
    .SemanticSearchOptions;
import com.azure.search.documents.util
    .SearchPagedIterable;

var searchClient = new SearchClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .indexName(SearchConfig.INDEX_NAME)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME))
    .setSelect("HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    var document = result.getDocument(
        SearchDocument.class);
    double rerankerScore = result
        .getSemanticSearch().getRerankerScore();

    System.out.printf("Re-ranker Score: %.2f%n",
        rerankerScore);
    System.out.printf("HotelName: %s%n",
        document.get("HotelName"));
    System.out.printf("Description: %s%n%n",
        document.get("Description"));
}

Conclusiones clave:

• QueryType.SEMANTIC habilita la clasificación semántica en la consulta.
• setSemanticConfigurationName especifica la configuración semántica que se va a usar.
• SearchPagedIterable proporciona un iterable sobre los resultados reordenados. Cada SearchResult contiene un getSemanticSearch() accesor para la puntuación del 'reranker'.

Consulta semántica con subtítulos

La SemanticQueryWithCaptions.java clase agrega etiquetas para extraer los pasajes más relevantes de cada resultado, con resaltado de coincidencias aplicado a los términos y frases importantes.

import com.azure.search.documents.models
    .QueryCaption;
import com.azure.search.documents.models
    .QueryCaptionResult;
import com.azure.search.documents.models
    .QueryCaptionType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE)
                    .setHighlightEnabled(true)))
    .setSelect(
        "HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    List<QueryCaptionResult> captions =
        result.getSemanticSearch()
            .getQueryCaptions();
    if (captions != null && !captions.isEmpty()) {
        QueryCaptionResult caption = captions.get(0);
        if (caption.getHighlights() != null) {
            System.out.printf(
                "Caption: %s%n",
                caption.getHighlights());
        }
    }
}

Conclusiones clave:

• QueryCaption(QueryCaptionType.EXTRACTIVE) habilita subtítulos extractivos en los campos de contenido.
• setHighlightEnabled(true) agrega <em> etiquetas en torno a términos importantes en los títulos.
• Cada SearchResult proporciona getQueryCaptions() en el descriptor de acceso de búsqueda semántica.

Consulta semántica con respuestas

La SemanticAnswer.java clase agrega respuestas semánticas. Esta clase usa una pregunta como texto de búsqueda porque las respuestas semánticas funcionan mejor cuando la consulta se frase como una pregunta. La respuesta es un pasaje textual extraído del índice, no una respuesta compuesta de un modelo de finalización de chat.

La consulta y el contenido indizado deben estar estrechamente alineados para que se devuelva una respuesta. Si ningún candidato cumple el umbral de confianza, la respuesta no incluye una respuesta. En este ejemplo se usa una pregunta conocida para generar un resultado para que pueda ver la sintaxis. Si las respuestas no son útiles para su escenario, omita setQueryAnswer del código. Para las respuestas compuestas, considere un patrón RAG o recuperación agentiva.

import com.azure.search.documents.models
    .QueryAnswer;
import com.azure.search.documents.models
    .QueryAnswerResult;
import com.azure.search.documents.models
    .QueryAnswerType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE))
            .setQueryAnswer(
                new QueryAnswer(
                    QueryAnswerType.EXTRACTIVE)))
    .setSelect(
        "HotelName", "Description", "Category");

SearchPagedIterable results = searchClient.search(
    "What's a good hotel for people who like to read",
    searchOptions, null);

List<QueryAnswerResult> semanticAnswers =
    results.getSemanticResults().getQueryAnswers();

for (QueryAnswerResult answer :
    semanticAnswers != null ? semanticAnswers
        : List.<QueryAnswerResult>of()) {
    if (answer.getHighlights() != null) {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getHighlights());
    } else {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getText());
    }
    System.out.printf(
        "Semantic Answer Score: %.2f%n",
        answer.getScore());
}

Conclusiones clave:

• QueryAnswer(QueryAnswerType.EXTRACTIVE) habilita respuestas extractivas para consultas similares a preguntas.
• Las respuestas son contenido textual extraído del índice, no texto generado.
• results.getSemanticResults().getQueryAnswers() recupera los objetos de respuesta por separado de los resultados de la búsqueda.

En este inicio rápido, usará la biblioteca cliente de Búsqueda de Azure AI para JavaScript para agregar clasificación semántica a un índice de búsqueda existente y consultar el índice.

La clasificación semántica es una funcionalidad del lado de consulta que usa la comprensión de lectura automática para volver a puntuar los resultados de búsqueda, lo que promueve las coincidencias más semánticamente relevantes en la parte superior de la lista. Puede agregar una configuración semántica a un índice existente sin necesidad de recompilación. La clasificación semántica es más eficaz para texto informativo o descriptivo.

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

• Un servicio Búsqueda de Azure AI.

• Un índice con campos de texto descriptivos atribuidos como searchable y retrievable. En este inicio rápido se da por supuesto el índice hotels-sample.

• Node.js 20 LTS o posterior.

• Git para clonar el repositorio de ejemplo.

• El CLI de Azure para la autenticación sin claves con Microsoft Entra ID.

Configuración del acceso

Antes de empezar, asegúrese de que tiene permisos para acceder al contenido y las operaciones en Búsqueda de Azure AI. En este inicio rápido se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Propietario o Administrador de acceso de usuarios para asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en rol recomendado:

1. Habilite el acceso basado en roles para el servicio de búsqueda.

2. Asigne los siguientes roles a la cuenta de usuario.

   • Colaborador del servicio de búsqueda

   • Lector de datos de índice de búsqueda

Obtención del punto de conexión

Cada servicio Búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona acceso de red al servicio. En una sección posterior, especifique este punto de conexión para conectarse al servicio de búsqueda mediante programación.

Para obtener el punto de conexión:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Información general.

3. Anote el punto de conexión, que debería tener un aspecto similar a https://my-service.search.windows.net.

Empezar con un índice

En este inicio rápido se modifica un índice existente para incluir una configuración semántica. Se recomienda el índice hotels-sample, que puede crear en cuestión de minutos mediante un asistente del portal de Azure.

Para usar un índice diferente, reemplace el nombre del índice, los nombres de campo en la configuración semántica y los nombres de campo de las instrucciones de consulta select en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como searchable y retrievable.

Para revisar y consultar el índice hotels-sample antes de la clasificación semántica:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Índices de administración de> búsqueda.

3. Seleccione hotels-sample.

4. Seleccione Configuraciones semánticas para ver las configuraciones existentes. Si ha habilitado la clasificación semántica durante el flujo de creación del asistente, debe haber una configuración predeterminada.

   

5. Seleccione Explorador de búsqueda y, a continuación, seleccione Ver>vista JSON.

6. Pegue el siguiente JSON en el editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Seleccione Buscar para ejecutar la consulta.

   La respuesta debe ser similar al ejemplo siguiente. Se trata de una consulta de texto completo clasificada por BM25, por lo que los resultados coinciden con términos de consulta individuales y variantes lingüísticas en lugar del significado general de la consulta. Por ejemplo, walking coincide con walk, y live y music coinciden independientemente en lugar de como una frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Propina

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de configurar una configuración semántica, agregue "queryType": "semantic" y "semanticConfiguration": "semantic-config" para ver cómo la misma consulta se clasifica de forma diferente por clasificación semántica.

Configuración del entorno

1. Use Git para clonar el repositorio de ejemplo.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. Vaya a la carpeta de inicio rápido.

   cd azure-search-javascript-samples/quickstart-semantic-ranking-js
   

3. En sample.env, reemplace el valor del marcador de posición de AZURE_SEARCH_ENDPOINT por la dirección URL que obtuvo en Get endpoint.

4. Cambie el nombre sample.env a .env.

   mv sample.env .env
   

5. Instale las dependencias.

   npm install
   

   Cuando se complete la instalación, debería ver una node_modules carpeta en el directorio del proyecto.

6. Para la autenticación sin claves con Microsoft Entra ID, inicie sesión en la cuenta de Azure. Si tiene varias suscripciones, seleccione la que contiene el servicio Búsqueda de Azure AI.

   az login
   

Ejecución del código

1. Obtenga la configuración de índice existente.

   node -r dotenv/config src/getIndexSettings.js
   

2. Actualice el índice con una configuración semántica.

   node -r dotenv/config src/updateIndexSettings.js
   

3. Ejecute una consulta semántica.

   node -r dotenv/config src/semanticQuery.js
   

4. Ejecute una consulta semántica con subtítulos.

   node -r dotenv/config src/semanticQueryReturnCaptions.js
   

5. Ejecute una consulta semántica con respuestas.

   node -r dotenv/config src/semanticAnswer.js
   

Salida

El getIndexSettings.js script devuelve el nombre del índice, sus campos y cualquier configuración semántica existente.

Getting semantic ranking index settings...
Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
Field: Description_fr, Type: Edm.String, Searchable: true
Field: Category, Type: Edm.String, Searchable: true
Field: Tags, Type: Collection(Edm.String), Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

El updateIndexSettings.js script devuelve todas las configuraciones semánticas del índice, incluida la que ha agregado el código, seguida de un mensaje de operación correcta.

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

El semanticQuery.js script devuelve todos los documentos coincidentes ordenados por la puntuación del re-ranker de clasificación semántica.

Search result #1:
  Re-ranker Score: 2.613231658935547
  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.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.9861756563186646
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

El semanticQueryReturnCaptions.js script devuelve un elemento de título con resaltado de aciertos junto con campos de búsqueda. Los títulos son los pasajes más relevantes en un resultado. Si el índice incluye texto más grande, los subtítulos ayudan a extraer las oraciones más interesantes.

Search result #1:
  Re-ranker Score: 2.613231658935547
  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.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

El semanticAnswer.js script devuelve una respuesta semántica extraída de uno de los resultados que mejor coincide con la pregunta, seguido de resultados de búsqueda con subtítulos.

Answers:

Semantic answer result #1:
Semantic Answer: 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<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
// Trimmed for brevity

Descripción del código

Ahora que ha ejecutado el código, vamos a desglosar los pasos clave:

1. Configuración y autenticación
2. Actualización del índice con una configuración semántica
3. Consulta del índice

Configuración y autenticación

El config.js archivo carga las variables de entorno y crea un DefaultAzureCredential para la autenticación.

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

Conclusiones clave:

• DefaultAzureCredential proporciona autenticación sin claves mediante Microsoft Entra ID. Encadena varios tipos de credenciales, incluida la credencial de CLI de Azure de az login.
• Las variables de entorno se cargan desde el .env archivo mediante dotenv.

Actualización del índice con una configuración semántica

El updateIndexSettings.js archivo agrega una configuración semántica al índice existente hotels-sample . Esta operación no elimina ningún documento de búsqueda y el índice permanece operativo después de agregar la configuración.

import { SearchIndexClient }
    from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields = {
    titleField: { name: "HotelName" },
    keywordsFields: [{ name: "Tags" }],
    contentFields: [{ name: "Description" }]
};

const newSemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

Conclusiones clave:

• Una configuración semántica especifica los campos usados para la clasificación semántica. titleField define el título del documento, contentFields define el contenido principal y keywordsFields define los campos de palabra clave o etiqueta.
• Usted crea un objeto de configuración y lo inserta en el array del índice existente semanticSearch.configurations.
• createOrUpdateIndex inserta el esquema actualizado en el servicio de búsqueda sin volver a generar el índice ni eliminar documentos.

Consulta del índice

Los scripts de consulta ejecutan tres consultas en secuencia, avanzando desde una búsqueda semántica básica a la clasificación semántica con subtítulos y respuestas.

Consulta semántica (sin títulos, sin respuestas)

El código siguiente muestra el requisito mínimo para invocar la clasificación semántica.

import { SearchClient }
    from "@azure/search-documents";
import {
    credential, searchEndpoint,
    indexName, semanticConfigurationName
} from "./config.js";

const searchClient = new SearchClient(
    searchEndpoint, indexName, credential
);

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

Conclusiones clave:

• queryType: "semantic" habilita la clasificación semántica en la consulta.
• semanticSearchOptions.configurationName especifica la configuración semántica que se va a usar.
• Los rerankerScore resultados indican la relevancia semántica (mayor es mejor).

Consulta semántica con subtítulos

El código siguiente agrega descripciones para extraer los pasajes más relevantes de cada resultado, con el resaltado de coincidencias aplicado a los términos y frases importantes.

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

Conclusiones clave:

• captions.captionType: "extractive" habilita subtítulos extractivos en los campos de contenido.
• Los títulos exponen los pasajes más relevantes y agregan <em> etiquetas en torno a términos importantes.

Consulta semántica con respuestas

La consulta final agrega respuestas semánticas. Esta consulta usa una pregunta como texto de búsqueda porque las respuestas semánticas funcionan mejor cuando la consulta se frase como una pregunta. La respuesta es un pasaje textual extraído del índice, no una respuesta compuesta de un modelo de finalización de chat.

La consulta y el contenido indizado deben estar estrechamente alineados para que se devuelva una respuesta. Si ningún candidato cumple el umbral de confianza, la respuesta no incluye una respuesta. En este ejemplo se usa una pregunta conocida para generar un resultado para que pueda ver la sintaxis. Si las respuestas no son útiles para su escenario, omita answers del código. Para las respuestas compuestas, considere un patrón RAG o recuperación agentiva.

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

Conclusiones clave:

• answers.answerType: "extractive" habilita respuestas extractivas para consultas similares a preguntas.
• Las respuestas son contenido textual extraído del índice, no texto generado.
• results.answers recupera los objetos de respuesta por separado de los resultados de la búsqueda.

En este inicio rápido, usará la biblioteca cliente Búsqueda de Azure AI para Python para agregar semantic ranking a un índice de búsqueda existente y consultar el índice.

La clasificación semántica es una funcionalidad del lado de consulta que usa la comprensión de lectura automática para volver a puntuar los resultados de búsqueda, lo que promueve las coincidencias más semánticamente relevantes en la parte superior de la lista. Puede agregar una configuración semántica a un índice existente sin necesidad de recompilación. La clasificación semántica es más eficaz para texto informativo o descriptivo.

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

• Un servicio Búsqueda de Azure AI.

• Un índice con campos de texto descriptivos atribuidos como searchable y retrievable. En este inicio rápido se da por supuesto el índice hotels-sample.

• Python 3.10 o posterior.

• Visual Studio Code con la extensión Python.

• Git para clonar el repositorio de ejemplo.

• El CLI de Azure para la autenticación sin claves con Microsoft Entra ID.

Configuración del acceso

Antes de empezar, asegúrese de que tiene permisos para acceder al contenido y las operaciones en Búsqueda de Azure AI. En este inicio rápido se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Propietario o Administrador de acceso de usuarios para asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en rol recomendado:

1. Habilite el acceso basado en roles para el servicio de búsqueda.

2. Asigne los siguientes roles a la cuenta de usuario.

   • Colaborador del servicio de búsqueda

   • Lector de datos de índice de búsqueda

Obtención del punto de conexión

Cada servicio Búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona acceso de red al servicio. En una sección posterior, especifique este punto de conexión para conectarse al servicio de búsqueda mediante programación.

Para obtener el punto de conexión:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Información general.

3. Anote el punto de conexión, que debería tener un aspecto similar a https://my-service.search.windows.net.

Empezar con un índice

En este inicio rápido se modifica un índice existente para incluir una configuración semántica. Se recomienda el índice hotels-sample, que puede crear en cuestión de minutos mediante un asistente del portal de Azure.

Para usar un índice diferente, reemplace el nombre del índice, los nombres de campo en la configuración semántica y los nombres de campo de las instrucciones de consulta select en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como searchable y retrievable.

Para revisar y consultar el índice hotels-sample antes de la clasificación semántica:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Índices de administración de> búsqueda.

3. Seleccione hotels-sample.

4. Seleccione Configuraciones semánticas para ver las configuraciones existentes. Si ha habilitado la clasificación semántica durante el flujo de creación del asistente, debe haber una configuración predeterminada.

   

5. Seleccione Explorador de búsqueda y, a continuación, seleccione Ver>vista JSON.

6. Pegue el siguiente JSON en el editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Seleccione Buscar para ejecutar la consulta.

   La respuesta debe ser similar al ejemplo siguiente. Se trata de una consulta de texto completo clasificada por BM25, por lo que los resultados coinciden con términos de consulta individuales y variantes lingüísticas en lugar del significado general de la consulta. Por ejemplo, walking coincide con walk, y live y music coinciden independientemente en lugar de como una frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Propina

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de configurar una configuración semántica, agregue "queryType": "semantic" y "semanticConfiguration": "semantic-config" para ver cómo la misma consulta se clasifica de forma diferente por clasificación semántica.

Configuración del entorno

1. Use Git para clonar el repositorio de ejemplo.

   git clone https://github.com/Azure-Samples/azure-search-python-samples
   

2. Vaya a la carpeta quickstart y ábrala en Visual Studio Code.

   cd azure-search-python-samples/Quickstart-Semantic-Ranking
   code .
   

3. En sample.env, reemplace el valor del marcador de posición de AZURE_SEARCH_ENDPOINT por la dirección URL que obtuvo en Get endpoint.

4. Cambie el nombre sample.env a .env.

   mv sample.env .env
   

5. Abra semantic-ranking-quickstart.ipynb.

6. Presione Ctrl+Mayús+P, seleccione Cuaderno: Seleccione Kernel de cuaderno y siga las indicaciones para crear un entorno virtual. Seleccione requirements.txt para las dependencias.

   Cuando haya finalizado, debería ver una .venv carpeta en el directorio del proyecto.

7. Para la autenticación sin claves con Microsoft Entra ID, inicie sesión en la cuenta de Azure. Si tiene varias suscripciones, seleccione la que contiene el servicio Búsqueda de Azure AI.

   az login
   

Ejecución del código

1. Ejecute las Install packages and set variables celdas para instalar los paquetes necesarios y cargar variables de entorno.

2. Ejecute las celdas restantes secuencialmente para agregar una configuración semántica y consultar el índice.

Salida

La salida de la Get the index definition celda es el nombre del índice, sus campos y cualquier configuración semántica existente.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: True
Field: HotelName, Type: Edm.String, Searchable: True
Field: Description, Type: Edm.String, Searchable: True
Field: Description_fr, Type: Edm.String, Searchable: True
Field: Category, Type: Edm.String, Searchable: True
Field: Tags, Type: Collection(Edm.String), Searchable: True
// Trimmed for brevity
Semantic config: hotels-sample-semantic-configuration
Title field: HotelName

La salida de la Add a semantic configuration to the index celda muestra todas las configuraciones semánticas del índice, incluida la que ha agregado el código, seguida de un mensaje de operación correcta.

Semantic configurations:
----------------------------------------
  Configuration: hotels-sample-semantic-configuration
    Title field: HotelName
    Keywords fields: Category
    Content fields: Description

  Configuration: semantic-config
    Title field: HotelName
    Keywords fields: Tags
    Content fields: Description

✅ Semantic configuration successfully added!

La salida de la Run a term query celda devuelve todos los documentos coincidentes ordenados por la puntuación BM25. Esta consulta de línea base no usa la clasificación semántica.

5.360838
4
Sublime Palace Hotel
Description: Sublime Cliff Hotel is located in the heart of the
historic center of Sublime in an extremely vibrant and lively area
within short walking distance to the sites and landmarks of the city
and is surrounded by the extraordinary beauty of churches, buildings,
shops and monuments. Sublime Cliff is part of a lovingly restored
19th century resort, updated for every modern convenience.
4.691083
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

La salida de la Run a semantic query celda entrega todos los documentos coincidentes ordenados por la puntuación del re-ranker semántico.

2.613231658935547
24
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.
2.271434783935547
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

La salida de la Return captions celda agrega un elemento caption con resaltado de aciertos junto con los campos de búsqueda. Los títulos son los pasajes más relevantes en un resultado. Si el índice incluye texto más grande, los subtítulos ayudan a extraer las oraciones más interesantes.

2.613231658935547
24
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.
Caption: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to<em> theaters, </em>art galleries,
restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and
then head over to<em> Benaroya Hall </em>to catch the evening's
concert performance.
// Trimmed for brevity

La salida de la Return semantic answers celda incluye una respuesta semántica extraída de uno de los resultados que mejor coincide con la pregunta, seguido de resultados de búsqueda con subtítulos.

Semantic Answer: 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<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Descripción del código

Ahora que ha ejecutado el código, vamos a desglosar los pasos clave:

1. Configuración y autenticación
2. Actualización del índice con una configuración semántica
3. Consulta del índice

Configuración y autenticación

La Install packages and set variables celda carga variables de entorno y crea un DefaultAzureCredential para la autenticación.

from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.identity import get_bearer_token_provider
import os

load_dotenv(override=True)

search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
index_name = os.getenv(
    "AZURE_SEARCH_INDEX", "hotels-sample"
)

Conclusiones clave:

• DefaultAzureCredential proporciona autenticación sin claves mediante Microsoft Entra ID. Encadena varios tipos de credenciales, incluida la credencial de CLI de Azure de az login.
• Las variables de entorno se cargan desde el .env archivo mediante python-dotenv.

Actualización del índice con una configuración semántica

La Add a semantic configuration to the index celda agrega una configuración semántica al índice existente hotels-sample . Esta operación no elimina ningún documento de búsqueda y el índice permanece operativo después de agregar la configuración.

from azure.search.documents.indexes.models import (
    SemanticConfiguration,
    SemanticField,
    SemanticPrioritizedFields,
    SemanticSearch
)

new_semantic_config = SemanticConfiguration(
    name="semantic-config",
    prioritized_fields=SemanticPrioritizedFields(
        title_field=SemanticField(field_name="HotelName"),
        keywords_fields=[
            SemanticField(field_name="Tags")
        ],
        content_fields=[
            SemanticField(field_name="Description")
        ]
    )
)

if existing_index.semantic_search is None:
    existing_index.semantic_search = SemanticSearch(
        configurations=[new_semantic_config]
    )
else:
    existing_index.semantic_search.configurations.append(
        new_semantic_config
    )

result = index_client.create_or_update_index(existing_index)

Conclusiones clave:

• Una configuración semántica especifica los campos usados para la clasificación semántica. title_field establece el título del documento, content_fields establece el contenido principal y keywords_fields establece los campos de palabra clave o etiqueta.
• La configuración se crea con SemanticConfiguration y su modelo asociado SemanticPrioritizedFields y, a continuación, se anexa al índice existente.
• create_or_update_index inserta el esquema actualizado en el servicio de búsqueda sin volver a generar el índice ni eliminar documentos.

Consulta del índice

Las celdas de consulta ejecutan cuatro consultas en secuencia: una búsqueda de palabras clave de línea base seguida de tres variaciones de clasificación semántica con una funcionalidad creciente.

Consulta de términos (línea de referencia)

La Run a term query celda ejecuta una búsqueda de palabras clave mediante la puntuación BM25. Esta consulta de línea de base no usa la clasificación semántica y actúa como punto de comparación.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='simple',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    include_total_count=True
)

Conclusiones clave:

• query_type='simple' especifica una búsqueda de palabras clave mediante la puntuación BM25.
• El @search.score en los resultados indica la puntuación de relevancia BM25.

Consulta semántica (sin títulos, sin respuestas)

La Run a semantic query celda muestra el requisito mínimo para invocar la clasificación semántica.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    query_caption='extractive'
)

Conclusiones clave:

• query_type='semantic' habilita la clasificación semántica en la consulta.
• semantic_configuration_name especifica la configuración semántica que se va a usar.
• Los @search.reranker_score resultados indican la relevancia semántica (mayor es mejor).

Consulta semántica con subtítulos

La Return captions celda agrega epígrafes para extraer los pasajes más relevantes de cada resultado, con los términos y frases importantes resaltados.

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelName,HotelId,Description',
    query_caption='extractive'
)

for result in results:
    captions = result["@search.captions"]
    if captions:
        caption = captions[0]
        if caption.highlights:
            print(f"Caption: {caption.highlights}\n")

Conclusiones clave:

• query_caption='extractive' habilita subtítulos extractivos en los campos de contenido.
• Los títulos exponen los pasajes más relevantes y agregan <em> etiquetas en torno a términos importantes.

Consulta semántica con respuestas

La Return semantic answers celda agrega respuestas semánticas. Esta consulta usa una pregunta como texto de búsqueda porque las respuestas semánticas funcionan mejor cuando la consulta se frase como una pregunta. La respuesta es un pasaje textual extraído del índice, no una respuesta compuesta de un modelo de finalización de chat.

La consulta y el contenido indizado deben estar estrechamente alineados para que se devuelva una respuesta. Si ningún candidato cumple el umbral de confianza, la respuesta no incluye una respuesta. En este ejemplo se usa una pregunta conocida para generar un resultado para que pueda ver la sintaxis. Si las respuestas no son útiles para su escenario, omita query_answer del código. Para las respuestas compuestas, considere un patrón RAG o recuperación agentiva.

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="what's a good hotel for people who "
                "like to read",
    select='HotelName,Description,Category',
    query_caption='extractive',
    query_answer="extractive",
)

semantic_answers = results.get_answers()
for answer in semantic_answers:
    if answer.highlights:
        print(f"Semantic Answer: {answer.highlights}")
    else:
        print(f"Semantic Answer: {answer.text}")
    print(f"Semantic Answer Score: {answer.score}\n")

Conclusiones clave:

• query_answer="extractive" habilita respuestas extractivas para consultas similares a preguntas.
• Las respuestas son contenido textual extraído del índice, no texto generado.
• results.get_answers() recupera los objetos de respuesta por separado de los resultados de la búsqueda.

En este inicio rápido, usará la biblioteca cliente Búsqueda de Azure AI para JavaScript (compatible con TypeScript) para agregar semantic ranking a un índice de búsqueda existente y consultar el índice.

La clasificación semántica es una funcionalidad del lado de consulta que usa la comprensión de lectura automática para volver a puntuar los resultados de búsqueda, lo que promueve las coincidencias más semánticamente relevantes en la parte superior de la lista. Puede agregar una configuración semántica a un índice existente sin necesidad de recompilación. La clasificación semántica es más eficaz para texto informativo o descriptivo.

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

• Un servicio Búsqueda de Azure AI.

• Un índice con campos de texto descriptivos atribuidos como searchable y retrievable. En este inicio rápido se da por supuesto el índice hotels-sample.

• Node.js 20 LTS o posterior para ejecutar el código compilado.

• TypeScript para compilar TypeScript en JavaScript.

• Git para clonar el repositorio de ejemplo.

• El CLI de Azure para la autenticación sin claves con Microsoft Entra ID.

Configuración del acceso

Antes de empezar, asegúrese de que tiene permisos para acceder al contenido y las operaciones en Búsqueda de Azure AI. En este inicio rápido se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Propietario o Administrador de acceso de usuarios para asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en rol recomendado:

1. Habilite el acceso basado en roles para el servicio de búsqueda.

2. Asigne los siguientes roles a la cuenta de usuario.

   • Colaborador del servicio de búsqueda

   • Lector de datos de índice de búsqueda

Obtención del punto de conexión

Cada servicio Búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona acceso de red al servicio. En una sección posterior, especifique este punto de conexión para conectarse al servicio de búsqueda mediante programación.

Para obtener el punto de conexión:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Información general.

3. Anote el punto de conexión, que debería tener un aspecto similar a https://my-service.search.windows.net.

Empezar con un índice

En este inicio rápido se modifica un índice existente para incluir una configuración semántica. Se recomienda el índice hotels-sample, que puede crear en cuestión de minutos mediante un asistente del portal de Azure.

Para usar un índice diferente, reemplace el nombre del índice, los nombres de campo en la configuración semántica y los nombres de campo de las instrucciones de consulta select en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como searchable y retrievable.

Para revisar y consultar el índice hotels-sample antes de la clasificación semántica:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Índices de administración de> búsqueda.

3. Seleccione hotels-sample.

4. Seleccione Configuraciones semánticas para ver las configuraciones existentes. Si ha habilitado la clasificación semántica durante el flujo de creación del asistente, debe haber una configuración predeterminada.

   

5. Seleccione Explorador de búsqueda y, a continuación, seleccione Ver>vista JSON.

6. Pegue el siguiente JSON en el editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Seleccione Buscar para ejecutar la consulta.

   La respuesta debe ser similar al ejemplo siguiente. Se trata de una consulta de texto completo clasificada por BM25, por lo que los resultados coinciden con términos de consulta individuales y variantes lingüísticas en lugar del significado general de la consulta. Por ejemplo, walking coincide con walk, y live y music coinciden independientemente en lugar de como una frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Propina

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de configurar una configuración semántica, agregue "queryType": "semantic" y "semanticConfiguration": "semantic-config" para ver cómo la misma consulta se clasifica de forma diferente por clasificación semántica.

Configuración del entorno

1. Use Git para clonar el repositorio de ejemplo.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. Vaya a la carpeta de inicio rápido.

   cd azure-search-javascript-samples/quickstart-semantic-ranking-ts
   

3. En sample.env, reemplace el valor del marcador de posición de AZURE_SEARCH_ENDPOINT por la dirección URL que obtuvo en Get endpoint.

4. Cambie el nombre sample.env a .env.

   mv sample.env .env
   

5. Instale las dependencias.

   npm install
   

   Cuando se complete la instalación, debería ver una node_modules carpeta en el directorio del proyecto.

6. Compile los archivos TypeScript en JavaScript.

   npm run build
   

7. Para la autenticación sin claves con Microsoft Entra ID, inicie sesión en la cuenta de Azure. Si tiene varias suscripciones, seleccione la que contiene el servicio Búsqueda de Azure AI.

   az login
   

Ejecución del código

1. Obtenga la configuración de índice existente.

   node -r dotenv/config dist/getIndexSettings.js
   

2. Actualice el índice con una configuración semántica.

   node -r dotenv/config dist/updateIndexSettings.js
   

3. Ejecute una consulta semántica.

   node -r dotenv/config dist/semanticQuery.js
   

4. Ejecute una consulta semántica con subtítulos.

   node -r dotenv/config dist/semanticQueryReturnCaptions.js
   

5. Ejecute una consulta semántica con respuestas.

   node -r dotenv/config dist/semanticAnswer.js
   

   Nota

   Estos comandos ejecutan los archivos compilados .js desde la dist carpeta . El código TypeScript debe transpilarse a JavaScript antes de que Node.js pueda ejecutarlo, por lo que anteriormente ejecutó npm run build.

Salida

El getIndexSettings.js script devuelve el nombre del índice, el recuento de campos, los detalles del campo con el tipo y el estado de búsqueda, y las configuraciones semánticas existentes.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

El updateIndexSettings.js script devuelve todas las configuraciones semánticas, incluida la que agregó.

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

El semanticQuery.js script devuelve los resultados ordenados por la puntuación del reranker.

Search result #1:
  Re-ranker Score: 2.613231658935547
  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.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza...
  // Trimmed for brevity

El semanticQueryReturnCaptions.js script devuelve subtítulos generados automáticamente con resaltado de resultados relevantes. Los títulos son los pasajes más relevantes en un resultado.

Search result #1:
  Re-ranker Score: 2.613231658935547
  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.

  Caption with highlights: Chic hotel near the city. High-rise hotel
  in downtown, within walking distance to<em> theaters, </em>art
  galleries, restaurants and shops. Visit<em> Seattle Art Museum
  </em>by day, and then head over to<em> Benaroya Hall </em>to catch
  the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  // Trimmed for brevity

El semanticAnswer.js script devuelve una respuesta semántica (contenido textual) extraída del resultado que mejor coincide con la pregunta.

Semantic answer result #1:
Semantic Answer: 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<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the
main commercial artery of the city in the heart of New York...
Caption: This classic hotel is<em> fully-refurbished </em>and
ideally located on the main commercial artery of the city...
// Trimmed for brevity

Descripción del código

Ahora que ha ejecutado el código, vamos a desglosar los pasos clave:

1. Configuración y autenticación
2. Actualización del índice con una configuración semántica
3. Consulta del índice

Configuración y autenticación

El config.ts archivo carga variables de entorno, crea un DefaultAzureCredential para la autenticación y define una HotelDocument interfaz para la seguridad de tipos.

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

export interface HotelDocument {
    HotelId: string;
    HotelName: string;
    Description: string;
    Category: string;
    Tags: string[];
}

Conclusiones clave:

• DefaultAzureCredential proporciona autenticación sin claves mediante Microsoft Entra ID. Encadena varios tipos de credenciales, incluida la credencial de CLI de Azure de az login.
• La HotelDocument interfaz proporciona comprobación de tipos en tiempo de compilación para los resultados de búsqueda, garantizando el acceso seguro a los campos del documento.
• Las variables de entorno se cargan desde el .env archivo mediante dotenv.

Actualización del índice con una configuración semántica

El updateIndexSettings.ts archivo agrega una configuración semántica al índice existente hotels-sample . Esta operación no elimina ningún documento de búsqueda y el índice permanece operativo después de agregar la configuración. Las anotaciones de tipo TypeScript garantizan que la configuración coincide con el esquema esperado.

import {
    SearchIndexClient,
    SemanticConfiguration,
    SemanticPrioritizedFields,
    SemanticField
} from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields: SemanticPrioritizedFields = {
    titleField: { name: "HotelName" },
    keywordsFields: [
        { name: "Tags" }
    ] as SemanticField[],
    contentFields: [
        { name: "Description" }
    ] as SemanticField[]
};

const newSemanticConfiguration:
    SemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

Conclusiones clave:

• Los tipos typeScript como SemanticPrioritizedFields, SemanticConfigurationy SemanticField proporcionan validación en tiempo de compilación para la estructura de configuración.
• titleField establece el título del documento, contentFields establece el contenido principal y keywordsFields establece los campos de palabra clave o etiqueta.
• createOrUpdateIndex inserta el esquema actualizado en el servicio de búsqueda sin volver a generar el índice ni eliminar documentos.

Consulta del índice

Los scripts de consulta ejecutan tres consultas en secuencia, avanzando desde una búsqueda semántica básica a la clasificación semántica con subtítulos y respuestas.

Consulta semántica (sin títulos, sin respuestas)

El semanticQuery.ts script muestra el requisito mínimo para invocar la clasificación semántica con resultados seguros para tipos.

import { SearchClient }
    from "@azure/search-documents";
import {
    HotelDocument, credential,
    searchEndpoint, indexName,
    semanticConfigurationName
} from "./config.js";

const searchClient =
    new SearchClient<HotelDocument>(
        searchEndpoint, indexName, credential
    );

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

Conclusiones clave:

• SearchClient<HotelDocument> proporciona acceso seguro de tipos a los campos de documento en los resultados, con autocompletar para los nombres de campo en select y result.document.
• queryType: "semantic" habilita la clasificación semántica en la consulta.
• semanticSearchOptions.configurationName especifica la configuración semántica que se va a usar.

Consulta semántica con subtítulos

El semanticQueryReturnCaptions.ts script agrega etiquetas para extraer los pasajes más relevantes de cada resultado, con resaltado de coincidencias aplicado a los términos y frases importantes.

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

Conclusiones clave:

• captions.captionType: "extractive" habilita subtítulos extractivos en los campos de contenido.
• Los títulos exponen los pasajes más relevantes y agregan <em> etiquetas en torno a términos importantes.

Consulta semántica con respuestas

El semanticAnswer.ts script agrega respuestas semánticas. Usa una pregunta como texto de búsqueda porque las respuestas semánticas funcionan mejor cuando la consulta se frase como una pregunta. La respuesta es un pasaje textual extraído del índice, no una respuesta compuesta de un modelo de finalización de chat.

La consulta y el contenido indizado deben estar estrechamente alineados para que se devuelva una respuesta. Si ningún candidato cumple el umbral de confianza, la respuesta no incluye una respuesta. En este ejemplo se usa una pregunta conocida para generar un resultado para que pueda ver la sintaxis. Si las respuestas no son útiles para su escenario, omita answers del código. Para las respuestas compuestas, considere un patrón RAG o recuperación agentiva.

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

Conclusiones clave:

• answers.answerType: "extractive" habilita respuestas extractivas para consultas similares a preguntas.
• Las respuestas son contenido textual extraído del índice, no texto generado.
• results.answers recupera los objetos de respuesta por separado de los resultados de la búsqueda.

En esta guía de inicio rápido, usará las API REST de Búsqueda de Azure AI para agregar clasificación semántica a un índice de búsqueda existente y consultar el índice.

La clasificación semántica es una funcionalidad del lado de consulta que usa la comprensión de lectura automática para volver a puntuar los resultados de búsqueda, lo que promueve las coincidencias más semánticamente relevantes en la parte superior de la lista. Puede agregar una configuración semántica a un índice existente sin necesidad de recompilación. La clasificación semántica es más eficaz para texto informativo o descriptivo.

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

• Un servicio Búsqueda de Azure AI.

• Un índice con campos de texto descriptivos atribuidos como searchable y retrievable. En este inicio rápido se da por supuesto el índice hotels-sample.

• Visual Studio Code con la extensión REST Client.

• Git para clonar el repositorio de ejemplo.

• El CLI de Azure para la autenticación sin claves con Microsoft Entra ID.

Configuración del acceso

Antes de empezar, asegúrese de que tiene permisos para acceder al contenido y las operaciones en Búsqueda de Azure AI. En este inicio rápido se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Propietario o Administrador de acceso de usuarios para asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en rol recomendado:

1. Habilite el acceso basado en roles para el servicio de búsqueda.

2. Asigne los siguientes roles a la cuenta de usuario.

   • Colaborador del servicio de búsqueda

   • Lector de datos de índice de búsqueda

Obtención del punto de conexión

Cada servicio Búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona acceso de red al servicio. En una sección posterior, especifique este punto de conexión para conectarse al servicio de búsqueda mediante programación.

Para obtener el punto de conexión:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Información general.

3. Anote el punto de conexión, que debería tener un aspecto similar a https://my-service.search.windows.net.

Empezar con un índice

En este inicio rápido se modifica un índice existente para incluir una configuración semántica. Se recomienda el índice hotels-sample, que puede crear en cuestión de minutos mediante un asistente del portal de Azure.

Para usar un índice diferente, reemplace el nombre del índice, los nombres de campo en la configuración semántica y los nombres de campo de las instrucciones de consulta select en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como searchable y retrievable.

Para revisar y consultar el índice hotels-sample antes de la clasificación semántica:

1. Vaya al servicio de búsqueda en el portal Azure.

2. En el panel izquierdo, seleccione Índices de administración de> búsqueda.

3. Seleccione hotels-sample.

4. Seleccione Configuraciones semánticas para ver las configuraciones existentes. Si ha habilitado la clasificación semántica durante el flujo de creación del asistente, debe haber una configuración predeterminada.

   

5. Seleccione Explorador de búsqueda y, a continuación, seleccione Ver>vista JSON.

6. Pegue el siguiente JSON en el editor de consultas.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. Seleccione Buscar para ejecutar la consulta.

   La respuesta debe ser similar al ejemplo siguiente. Se trata de una consulta de texto completo clasificada por BM25, por lo que los resultados coinciden con términos de consulta individuales y variantes lingüísticas en lugar del significado general de la consulta. Por ejemplo, walking coincide con walk, y live y music coinciden independientemente en lugar de como una frase.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "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."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   Propina

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de configurar una configuración semántica, agregue "queryType": "semantic" y "semanticConfiguration": "semantic-config" para ver cómo la misma consulta se clasifica de forma diferente por clasificación semántica.

Configuración del entorno

1. Use Git para clonar el repositorio de ejemplo.

   git clone https://github.com/Azure-Samples/azure-search-rest-samples
   

2. Vaya a la carpeta quickstart y ábrala en Visual Studio Code.

   cd azure-search-rest-samples/Quickstart-semantic-ranking
   code .
   

3. En semantic-index-update.rest, reemplace el valor del marcador de posición de @searchUrl por la dirección URL que obtuvo en Get endpoint.

4. Repita el paso anterior para semantic-query.rest.

5. Para la autenticación sin claves con Microsoft Entra ID, inicie sesión en la cuenta de Azure. Si tiene varias suscripciones, seleccione la que contiene el servicio Búsqueda de Azure AI.

   az login
   

6. Para la autenticación sin claves con Microsoft Entra ID, genere un token de acceso.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

7. En ambos .rest archivos, reemplace el valor de marcador de posición de por @personalAccessToken el token del paso anterior.

Ejecución del código

1. Abra semantic-index-update.rest.

2. Seleccione Enviar solicitud en la primera solicitud GET para comprobar la conexión.

   Una respuesta debe aparecer en un panel adyacente. Si tiene índices existentes, se muestran por nombre. Si el código HTTP es 200 OK, está listo para continuar.

3. Envíe la ### Update the hotels-sample index to include a semantic configuration solicitud para agregar una configuración semántica al índice.

   Si recibe un 400 Bad Request error, el esquema de índice difiere del ejemplo. Envíe la ### Get the schema of the index solicitud, copie el JSON de respuesta, agregue la sección semantic del código fuente al JSON y reemplace el cuerpo de la solicitud PUT con su esquema combinado.

4. Cambie a semantic-query.rest y envíe las solicitudes secuencialmente: una consulta sencilla para la comparación de línea de base y, a continuación, semántica con clasificación, subtítulos y respuestas.

Salida

La Send a search query to the hotels-sample index solicitud devuelve resultados clasificados por relevancia BM25, que se indica mediante el @search.score campo .

{
  "@odata.count": 30,
  "value": [
    {
      "@search.score": 5.004435,
      "HotelId": "2",
      "HotelName": "Old Century Hotel",
      "Description": "The hotel is situated in a nineteenth century plaza..."
    },
    // Trimmed for brevity
  ]
}

La Send a search query to the hotels-sample index with semantic ranking solicitud agrega @search.rerankerScore. Observe que el orden cambia de la consulta simple.

{
  "@odata.count": 30,
  "@search.answers": [],
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown..."
    },
    // Trimmed for brevity
  ]
}

La Return captions in the query solicitud agrega @search.captions con texto extraído y resaltado.

{
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops...",
          "highlights": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops..."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel"
    },
    // Trimmed for brevity
  ]
}

La solicitud Return semantic answers in the query devuelve una respuesta extractiva en @search.answers cuando la consulta se formula como una pregunta.

{
  "@odata.count": 46,
  "@search.answers": [
    {
      "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...",
      "highlights": "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<em> library </em>by night...",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.060124,
      "@search.rerankerScore": 2.124817371368408,
      "@search.captions": [
        {
          "text": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city...",
          "highlights": "This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city..."
        }
      ],
      "HotelId": "1",
      "HotelName": "Stay-Kay City Hotel"
    },
    // Trimmed for brevity
  ]
}

Descripción del código

Ahora que ha ejecutado el código, vamos a desglosar los pasos clave:

1. Configuración y autenticación
2. Actualización del índice con una configuración semántica
3. Consulta del índice

Configuración y autenticación

Ambos .rest archivos definen variables en la parte superior para reutilizarlas en todas las solicitudes.

@searchUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@personalAccessToken = PUT-YOUR-PERSONAL-ACCESS-TOKEN-HERE
@api-version = 2026-04-01

Conclusiones clave:

• @searchUrl es el extremo del servicio de búsqueda.
• @personalAccessToken es un token de Microsoft Entra ID obtenido del CLI de Azure. Esto reemplaza las claves de API por la autenticación sin clave.
• Authorization: Bearer {{personalAccessToken}} se incluye en cada encabezado de solicitud para la autenticación.

Actualización del índice con una configuración semántica

La solicitud de ### Update the hotels-sample index to include a semantic configuration en semantic-index-update.rest envía el esquema de índice completo junto con una sección nueva semantic. La API REST requiere el esquema completo para cualquier operación de actualización, por lo que no puede enviar solo la configuración semántica.

La adición clave es la semantic sección :

"semantic": {
    "configurations": [
        {
            "name": "semantic-config",
            "rankingOrder":
                "BoostedRerankerScore",
            "prioritizedFields": {
                "titleField": {
                    "fieldName": "HotelName"
                },
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ],
                "prioritizedKeywordsFields": [
                    {
                        "fieldName": "Tags"
                    }
                ]
            }
        }
    ]
}

Conclusiones clave:

• titleField identifica qué campo contiene el título del documento para la evaluación semántica.
• prioritizedContentFields identifica los campos de contenido principales. El clasificador semántico evalúa estos primeros al puntuar relevancia.
• prioritizedKeywordsFields identifica campos de palabra clave o etiqueta para contexto adicional.
• rankingOrder: BoostedRerankerScore combina la puntuación BM25 con la del reranker semántico.
• La API REST requiere el esquema completo para las operaciones PUT. Solo la semantic sección es nueva; todos los demás campos no se modifican.

Consulta del índice

Las solicitudes en semantic-query.rest progresan desde una búsqueda de palabras clave simple a una clasificación semántica con rótulos y respuestas. Todas las consultas son solicitudes POST a Documentos - Search Post (API REST).

Consulta simple

La ### Send a search query to the hotels-sample index solicitud es una búsqueda de palabras clave sencilla que no usa la clasificación semántica. Sirve como línea de base para comparar los resultados con y sin el reeranking semántico.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "simple"
}

Conclusiones clave:

• queryType: "simple" usa el algoritmo de clasificación BM25 predeterminado.
• Los resultados solo se clasifican por relevancia de palabra clave (@search.score).

Consulta semántica (sin títulos, sin respuestas)

La ### Send a search query to the hotels-sample index with semantic ranking solicitud agrega clasificación semántica. El siguiente JSON muestra el requisito mínimo para invocar la clasificación semántica.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config"
}

Conclusiones clave:

• queryType: "semantic" habilita la clasificación semántica en la consulta.
• semanticConfiguration especifica la configuración semántica que se va a usar.

Consulta semántica con subtítulos

La ### Return captions in the query solicitud agrega etiquetas para extraer los pasajes más relevantes de cada resultado, con el resaltado de términos coincidentes aplicado a los términos y frases importantes.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true"
}

Conclusiones clave:

• captions: "extractive|highlight-true" habilita títulos extractivos con <em> etiquetas en torno a términos importantes.
• Los títulos aparecen en la @search.captions matriz para cada resultado.

Consulta semántica con respuestas

La ### Return semantic answers in the query solicitud agrega respuestas semánticas. Usa una pregunta como texto de búsqueda porque las respuestas semánticas funcionan mejor cuando la consulta se frase como una pregunta. La respuesta es un pasaje textual extraído del índice, no una respuesta compuesta de un modelo de finalización de chat.

La consulta y el contenido indizado deben estar estrechamente alineados para que se devuelva una respuesta. Si ningún candidato cumple el umbral de confianza, la respuesta no incluye una respuesta. En este ejemplo se usa una pregunta conocida para generar un resultado para que pueda ver la sintaxis. Si las respuestas no son útiles para su escenario, omita el parámetro answers de la solicitud. Para las respuestas compuestas, considere un patrón RAG o recuperación agentiva.

{
    "search":
        "what's a good hotel for people who like to read",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive"
}

Conclusiones clave:

• answers: "extractive" habilita respuestas extractivas para consultas similares a preguntas.
• Las respuestas aparecen en la matriz de nivel @search.answers superior, independiente de los resultados individuales.
• Las respuestas son contenido textual extraído del índice, no texto generado.