Inicio rápido: Clasificación semántica

En esta guía de inicio rápido, usará la biblioteca cliente Búsqueda de Azure AI para .NET 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. Crear una cuenta gratuita.

• Un Azure AI Search service con semantic ranker habilitado.

• Índice con campos de texto descriptivos con atributos como y . En este inicio rápido se asume el índice hotels-sample.

• .NET 9 o posterior.

• Visual Studio Code.

• Git para clonar el repositorio de ejemplo.

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

Configurar acceso

Antes de comenzar, asegúrese de tener permisos para acceder a contenido y operaciones en Búsqueda de Azure AI. En esta guía rápida se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Owner o User Access Administrator para poder asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en roles recomendado:

1. Habilitar acceso basado en roles para su 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 de búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona al servicio acceso a la red. En una sección posterior, especifique este punto de conexión para conectarse a su servicio de búsqueda de forma programática.

Para obtener el punto de conexión:

1. Inicie sesión en el Portal de Azure y seleccione su servicio de búsqueda.

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 de Azure Portal.

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 en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como y .

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

1. Inicie sesión en el Portal de Azure y seleccione su servicio de búsqueda.

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

3. Seleccione muestra de hoteles.

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 Power Query.

   {
     "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, coincide con y y coinciden de forma independiente 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
   ]
   

   Sugerencia

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de establecer una configuración semántica, agregue y para ver cómo la clasificación semántica clasifica la misma consulta de manera diferente.

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. Diríjase a la carpeta quickstart y ábrala en Visual Studio Code.

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

3. En , reemplace el valor de marcador de posición por la dirección URL que obtuvo en Obtener punto de conexión.

4. Repita el paso anterior para .

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 de búsqueda de Azure AI.

   az login
   

Ejecución del código

1. Ejecute el primer project 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 archivos definen el punto de conexión de búsqueda y usan 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);

Puntos 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.
• administra las operaciones de nivel de índice, como actualizar el esquema de índice.
• 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 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;
}

Puntos 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 volver a generar.
• establece el campo que representa el título del documento.
• establece los campos que contienen el contenido principal.
• establece los campos que contienen palabras clave o etiquetas.

Consulta del índice

El QueryIndex project ejecuta cuatro consultas en secuencia, progresando 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" }
});

Puntos clave:

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

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);

Puntos clave:

• habilita la clasificación semántica en la consulta.
• especifica la configuración semántica que se va a usar.
• 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 subtítulos para extraer los pasajes más relevantes de cada resultado, con resaltado de aciertos aplicados 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
);

Puntos clave:

• habilita títulos extractivos de los campos de contenido.
• Las leyendas muestran los pasajes más relevantes y agregan etiquetas <em> alrededor de términos importantes.

Consulta semántica con respuestas

La consulta final agrega respuestas semánticas. Esta consulta usa una cadena de búsqueda diferente () 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 del código. Para las respuestas compuestas, considere un patrón RAG o una 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
);

Puntos clave:

• habilita respuestas extractivas para consultas de tipo pregunta.
• Las respuestas son contenido textual extraído del índice, no texto generado.

En este inicio rápido, usará la biblioteca cliente Búsqueda de Azure AI para Java 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. Crear una cuenta gratuita.

• Un Azure AI Search service con semantic ranker habilitado.

• Índice con campos de texto descriptivos con atributos como y . En este inicio rápido se asume el índice hotels-sample.

• Java 21 (LTS) y Maven.

• Visual Studio Code.

• Git para clonar el repositorio de ejemplo.

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

Configurar acceso

Antes de comenzar, asegúrese de tener permisos para acceder a contenido y operaciones en Búsqueda de Azure AI. En esta guía rápida se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Owner o User Access Administrator para poder asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en roles recomendado:

1. Habilitar acceso basado en roles para su 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 de búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona al servicio acceso a la red. En una sección posterior, especifique este punto de conexión para conectarse a su servicio de búsqueda de forma programática.

Para obtener el punto de conexión:

1. Inicie sesión en el Portal de Azure y seleccione su servicio de búsqueda.

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 de Azure Portal.

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 en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como y .

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

1. Inicie sesión en el Portal de Azure y seleccione su servicio de búsqueda.

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

3. Seleccione muestra de hoteles.

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 Power Query.

   {
     "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, coincide con y y coinciden de forma independiente 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
   ]
   

   Sugerencia

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de establecer una configuración semántica, agregue y para ver cómo la clasificación semántica clasifica la misma consulta de manera diferente.

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. Diríjase a la carpeta quickstart y ábrala en Visual Studio Code.

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

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

4. Compila 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 de 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 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 del sistema enumera todas las configuraciones semánticas en el índice, incluida la que añadió el código, seguido de un mensaje de éxito.

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

Salida de devuelve todos los documentos coincidentes ordenados por la puntuación del reclasificador 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 agrega un elemento caption 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.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 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 clase carga las propiedades de {} y crea un {} para la autenticación sin clave.

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();
}

Puntos 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 archivo de la ruta de clase.
• Los campos estáticos (SEARCH_ENDPOINT, INDEX_NAME, SEMANTIC_CONFIG_NAME, CREDENTIAL) se comparten en todas las clases del project.

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

La clase 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.

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);

Puntos clave:

• define los campos que evalúa el clasificador semántico. establece el título del documento, establece el contenido principal y establece los campos de palabra clave o etiqueta.
• 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 search service 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 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"));
}

Puntos clave:

• habilita la clasificación semántica en la consulta.
• especifica la configuración semántica que se va a usar.
• proporciona un iterable sobre los resultados reordenados. Cada uno contiene un accesor para la puntuación del reranker.

Consulta semántica con subtítulos

La clase añade leyendas para extraer los pasajes más relevantes de cada resultado, aplicando resaltado 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());
        }
    }
}

Puntos clave:

• habilita títulos extractivos de los campos de contenido.
• agrega etiquetas en torno a términos importantes en los títulos.
• Cada proporciona en el descriptor de acceso de búsqueda semántica.

Consulta semántica con respuestas

La 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 del código. Para las respuestas compuestas, considere un patrón RAG o una 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());
}

Puntos clave:

• habilita respuestas extractivas para consultas de tipo pregunta.
• Las respuestas son contenido textual extraído del índice, no texto generado.
• 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 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. Crear una cuenta gratuita.

• Un Azure AI Search service con semantic ranker habilitado.

• Índice con campos de texto descriptivos con atributos como y . En este inicio rápido se asume el índice hotels-sample.

• Node.js 20 LTS o posterior.

• Visual Studio Code.

• Git para clonar el repositorio de ejemplo.

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

Configurar acceso

Antes de comenzar, asegúrese de tener permisos para acceder a contenido y operaciones en Búsqueda de Azure AI. En esta guía rápida se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Owner o User Access Administrator para poder asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en roles recomendado:

1. Habilitar acceso basado en roles para su 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 de búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona al servicio acceso a la red. En una sección posterior, especifique este punto de conexión para conectarse a su servicio de búsqueda de forma programática.

Para obtener el punto de conexión:

1. Inicie sesión en el Portal de Azure y seleccione su servicio de búsqueda.

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 de Azure Portal.

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 en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como y .

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

1. Inicie sesión en el Portal de Azure y seleccione su servicio de búsqueda.

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

3. Seleccione muestra de hoteles.

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 Power Query.

   {
     "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, coincide con y y coinciden de forma independiente 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
   ]
   

   Sugerencia

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de establecer una configuración semántica, agregue y para ver cómo la clasificación semántica clasifica la misma consulta de manera diferente.

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. Diríjase a la carpeta quickstart y ábrala en Visual Studio Code.

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

3. En , reemplace el valor de marcador de posición por la dirección URL que obtuvo en Obtener punto de conexión.

4. Cambie el nombre de a .

   mv sample.env .env
   

5. Instale las dependencias.

   npm install
   

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

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 de 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 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 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 script devuelve todos los documentos coincidentes ordenados por la puntuación de clasificación del re-calificador semántico.

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 script devuelve un elemento de subtítulo con resaltado de coincidencias 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 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

Un archivo carga las variables de entorno y crea un mecanismo 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();

Puntos 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 archivo mediante .

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

El archivo 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.

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);

Puntos clave:

• Una configuración semántica especifica los campos usados para la clasificación semántica. define el título del documento, define el contenido principal y define los campos de palabra clave o etiqueta.
• Cree un objeto de configuración e insértelo en la matriz del índice existente.
• createOrUpdateIndex inserta el esquema actualizado en el search service 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"
        ]
    }
);

Puntos clave:

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

Consulta semántica con subtítulos

El código siguiente agrega subtítulos para extraer los pasajes más relevantes de cada resultado, con resaltado de aciertos aplicados 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}`
            );
        }
    }
}

Puntos clave:

• habilita títulos extractivos de los campos de contenido.
• Las leyendas muestran los pasajes más relevantes y agregan etiquetas <em> alrededor de 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 del código. Para las respuestas compuestas, considere un patrón RAG o una 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}`
    );
}

Puntos clave:

• habilita respuestas extractivas para consultas de tipo pregunta.
• Las respuestas son contenido textual extraído del índice, no texto generado.
• 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. Crear una cuenta gratuita.

• Un Azure AI Search service con semantic ranker habilitado.

• Índice con campos de texto descriptivos con atributos como y . En este inicio rápido se asume 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.

Configurar acceso

Antes de comenzar, asegúrese de tener permisos para acceder a contenido y operaciones en Búsqueda de Azure AI. En esta guía rápida se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Owner o User Access Administrator para poder asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en roles recomendado:

1. Habilitar acceso basado en roles para su 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 de búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona al servicio acceso a la red. En una sección posterior, especifique este punto de conexión para conectarse a su servicio de búsqueda de forma programática.

Para obtener el punto de conexión:

1. Inicie sesión en el Portal de Azure y seleccione su servicio de búsqueda.

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 de Azure Portal.

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 en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como y .

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

1. Inicie sesión en el Portal de Azure y seleccione su servicio de búsqueda.

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

3. Seleccione muestra de hoteles.

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 Power Query.

   {
     "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, coincide con y y coinciden de forma independiente 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
   ]
   

   Sugerencia

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de establecer una configuración semántica, agregue y para ver cómo la clasificación semántica clasifica la misma consulta de manera diferente.

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. Diríjase a la carpeta quickstart y ábrala en Visual Studio Code.

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

3. En , reemplace el valor de marcador de posición por la dirección URL que obtuvo en Obtener punto de conexión.

4. Cambie el nombre de a .

   mv sample.env .env
   

5. Abra .

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 carpeta .venv en el directorio project.

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 de búsqueda de Azure AI.

   az login
   

Ejecución del código

1. Ejecute las 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 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 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 célula 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 celda devuelve todos los documentos coincidentes ordenados por la puntuación del reordenador 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 celda agrega un elemento de título que resalta los 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 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 celda carga variables de entorno y crea un proceso 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"
)

Puntos 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 archivo mediante .

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

La celda 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.

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)

Puntos clave:

• Una configuración semántica especifica los campos usados para la clasificación semántica. establece el título del documento, establece el contenido principal y establece los campos de palabra clave o etiqueta.
• La configuración se crea con y su modelo asociado y, a continuación, se anexa al índice existente.
• create_or_update_index inserta el esquema actualizado en el search service 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 base)

La celda ejecuta una búsqueda de palabras clave mediante el método de 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
)

Puntos clave:

• especifica una búsqueda de palabras clave mediante la puntuación BM25.
• En los resultados se indica la puntuación de relevancia BM25.

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

La 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'
)

Puntos clave:

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

Consulta semántica con subtítulos

La celda agrega subtítulos para extraer los pasajes más relevantes de cada resultado, con resaltado de aciertos aplicados a los términos y frases importantes.

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")

Puntos clave:

• habilita títulos extractivos de los campos de contenido.
• Las leyendas muestran los pasajes más relevantes y agregan etiquetas <em> alrededor de términos importantes.

Consulta semántica con respuestas

La 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 del código. Para las respuestas compuestas, considere un patrón RAG o una 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")

Puntos clave:

• habilita respuestas extractivas para consultas de tipo pregunta.
• Las respuestas son contenido textual extraído del índice, no texto generado.
• 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. Crear una cuenta gratuita.

• Un Azure AI Search service con semantic ranker habilitado.

• Índice con campos de texto descriptivos con atributos como y . En este inicio rápido se asume el índice hotels-sample.

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

• TypeScript para compilar TypeScript en JavaScript.

• Visual Studio Code.

• Git para clonar el repositorio de ejemplo.

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

Configurar acceso

Antes de comenzar, asegúrese de tener permisos para acceder a contenido y operaciones en Búsqueda de Azure AI. En esta guía rápida se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Owner o User Access Administrator para poder asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en roles recomendado:

1. Habilitar acceso basado en roles para su 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 de búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona al servicio acceso a la red. En una sección posterior, especifique este punto de conexión para conectarse a su servicio de búsqueda de forma programática.

Para obtener el punto de conexión:

1. Inicie sesión en el portal de Azure y seleccione su servicio de búsqueda.

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 de Azure Portal.

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 en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como y .

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

1. Inicie sesión en el Portal de Azure y seleccione su servicio de búsqueda.

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

3. Seleccione muestra de hoteles.

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 Power Query.

   {
     "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, coincide con y y coinciden de forma independiente 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
   ]
   

   Sugerencia

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de establecer una configuración semántica, agregue y para ver cómo la clasificación semántica clasifica la misma consulta de manera diferente.

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. Diríjase a la carpeta quickstart y ábrala en Visual Studio Code.

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

3. En , reemplace el valor de marcador de posición por la dirección URL que obtuvo en Obtener punto de conexión.

4. Cambie el nombre de a .

   mv sample.env .env
   

5. Instale las dependencias.

   npm install
   

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

6. Compile los archivos TypeScript.

   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 de 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 archivos desde la carpeta porque anteriormente transpilaba de TypeScript a JavaScript con .

Salida

El script devuelve el nombre del índice, el recuento de campos, los detalles del campo con el estado de tipo y el estado que se puede buscar 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 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 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 script devuelve subtítulos extractivos con resaltado de coincidencias. 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 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 archivo carga variables de entorno, crea un mecanismo para la autenticación y define una 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[];
}

Puntos 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 interfaz HotelDocument proporciona la comprobación de tipos en tiempo de compilación para los resultados de búsqueda, lo que garantiza un acceso seguro a los campos del documento.
• Las variables de entorno se cargan desde el archivo mediante .

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

El archivo 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. 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);

Puntos clave:

• Los tipos de TypeScript como , y proporcionan validación en tiempo de compilación para la estructura de configuración.
• establece el título del documento, establece el contenido principal y establece los campos de palabra clave o etiqueta.
• createOrUpdateIndex inserta el esquema actualizado en el search service 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 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"
        ]
    }
);

Puntos clave:

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

Consulta semántica con subtítulos

El 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}`
            );
        }
    }
}

Puntos clave:

• habilita títulos extractivos de los campos de contenido.
• Las leyendas muestran los pasajes más relevantes y agregan etiquetas <em> alrededor de términos importantes.

Consulta semántica con respuestas

El 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 del código. Para las respuestas compuestas, considere un patrón RAG o una 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}`
    );
}

Puntos clave:

• habilita respuestas extractivas para consultas de tipo pregunta.
• Las respuestas son contenido textual extraído del índice, no texto generado.
• recupera los objetos de respuesta por separado de los resultados de la búsqueda.

En este inicio rápido, usará las API REST de Búsqueda de Azure AI para agregar rango semántico a un índice de búsqueda existente y realizar consultas al í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. Crear una cuenta gratuita.

• Un Azure AI Search service con semantic ranker habilitado.

• Índice con campos de texto descriptivos con atributos como y . En este inicio rápido se asume 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.

Configurar acceso

Antes de comenzar, asegúrese de tener permisos para acceder a contenido y operaciones en Búsqueda de Azure AI. En esta guía rápida se usa Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Owner o User Access Administrator para poder asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso basado en roles recomendado:

1. Habilitar acceso basado en roles para su 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 de búsqueda de Azure AI tiene un endpoint, que es una dirección URL única que identifica y proporciona al servicio acceso a la red. En una sección posterior, especifique este punto de conexión para conectarse a su servicio de búsqueda de forma programática.

Para obtener el punto de conexión:

1. Inicie sesión en el Portal de Azure y seleccione su servicio de búsqueda.

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 de Azure Portal.

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 en todo el código de ejemplo. El índice debe contener campos de texto descriptivos que se atribuyen como y .

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

1. Inicie sesión en el Portal de Azure y seleccione su servicio de búsqueda.

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

3. Seleccione muestra de hoteles.

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 Power Query.

   {
     "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, coincide con y y coinciden de forma independiente 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
   ]
   

   Sugerencia

   Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Después de establecer una configuración semántica, agregue y para ver cómo la clasificación semántica clasifica la misma consulta de manera diferente.

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. Diríjase a la carpeta quickstart y ábrala en Visual Studio Code.

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

3. En , reemplace el valor de marcador de posición por la dirección URL que obtuvo en Obtener punto de conexión.

4. Repita el paso anterior para .

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 de búsqueda de Azure AI.

   az login
   

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

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

7. En ambos archivos, reemplace el valor del marcador de posición con el token del paso anterior.

Ejecución del código

1. Abra .

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

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

3. Envíe la solicitud para agregar una configuración semántica al índice.

   Si recibe un error, el esquema del índice es diferente al del ejemplo. Envíe la solicitud, copie el JSON de respuesta, agregue la sección del código fuente al JSON y reemplace el cuerpo de la solicitud PUT por el esquema combinado.

4. Cambie a [INSERT DETAIL] y envíe las solicitudes de manera secuencial: una consulta sencilla para la comparación con la línea de base y posteriormente consultas semánticas con clasificación, subtítulos y respuestas.

Salida

La solicitud devuelve resultados clasificados por relevancia BM25, que se indica mediante el 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 solicitud agrega . 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 solicitud añade 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 devuelve una respuesta extractiva 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 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 = 2025-09-01

Puntos clave:

• @searchUrl es el extremo de su 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.
• se incluye en cada encabezado de solicitud para la autenticación.

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

La solicitud envía el esquema del índice completo junto con una nueva sección. 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 sección :

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

Puntos clave:

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

Consulta del índice

Las solicitudes que están en curso van desde una búsqueda de palabras clave simple hasta el rango semántico con etiquetas y respuestas. Todas las consultas son solicitudes POST a documents - Search Post (API REST).

Consulta simple

La 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"
}

Puntos clave:

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

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

La 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"
}

Puntos clave:

• habilita la clasificación semántica en la consulta.
• especifica la configuración semántica que se va a usar.

Consulta semántica con subtítulos

La solicitud agrega descripciones para extraer los pasajes más relevantes de cada resultado, con 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"
}

Puntos clave:

• habilita títulos extractivos con etiquetas en torno a términos importantes.
• Los títulos aparecen en la matriz para cada resultado.

Consulta semántica con respuestas

La 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 de la solicitud. Para las respuestas compuestas, considere un patrón RAG o una 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"
}

Puntos clave:

• habilita respuestas extractivas para consultas de tipo pregunta.
• Las respuestas aparecen en la matriz de nivel superior, independiente de los resultados individuales.
• Las respuestas son contenido textual extraído del índice, no texto generado.