Inicio rápido: Clasificación semántica

En este inicio rápido, aprenderá a usar la clasificación semántica agregando una configuración semántica a un índice de búsqueda y agregando parámetros semánticos a una consulta. Puede usar el índice de muestra de hoteles o uno propio.

En Azure AI Search, la clasificación semántica es la funcionalidad del lado de consulta que usa la comprensión de lectura automática de Microsoft 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. Según el contenido y la consulta, la clasificación semántica puede mejorar significativamente la relevancia de búsqueda con un esfuerzo mínimo para desarrolladores.

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 en el texto que es informativo o descriptivo.

Requisitos previos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Un servicio azure AI Search con clasificador semántico habilitado.
Índice nuevo o existente con campos de texto descriptivos o detallados que se atribuyen como recuperables. En este inicio rápido asume el hotels-sample-index.

Configurar el acceso

Puede conectarse al servicio Azure AI Search mediante claves de API o identificador de Microsoft Entra con asignaciones de roles. Las claves son más fáciles de empezar, pero los roles son más seguros. Para más información, consulte Conexión a la Búsqueda de Azure AI usando los roles.

Para configurar el acceso basado en roles:

Inicie sesión en Azure Portal y seleccione el servicio de búsqueda.
En el panel izquierdo, seleccione Configuración>Claves.
En Control de acceso de API, seleccione Control de acceso basado en rol o Ambos si necesita tiempo para realizar la transición de los clientes al acceso basado en roles.
En el panel izquierdo, seleccione Control de acceso (IAM) .
Seleccione Agregar>Agregar asignación de rol.
Asigne los roles Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda a su cuenta de usuario.

Empezar con un índice

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

Para empezar con un índice existente:

Inicie sesión en Azure Portal y busque su servicio de búsqueda.
En Gestión de búsqueda>Índices, seleccione el hotels-sample-index.
Seleccione Configuraciones semánticas para asegurarse de que el índice no tiene una configuración semántica.
Seleccione Explorador de búsqueda y, a continuación, seleccione la vista JSON.

Pegue el siguiente JSON en el editor de consultas.

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

Seleccione Buscar para ejecutar la consulta.

Esta consulta es una búsqueda de palabras clave. La respuesta debe ser similar al ejemplo siguiente, como se puntúa con el clasificador BM25 L1 predeterminado para la búsqueda de texto completo.

Para mejorar la legibilidad, el ejemplo solo selecciona los HotelIdcampos , HotelNamey Description . Los resultados contienen coincidencias textuales en los términos de consulta (walking, distance, live, music) o variantes lingüísticas (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Más adelante, puede ejecutar la misma consulta después de configurar la clasificación semántica para ver cómo cambia la respuesta.

Sugerencia

Puede agregar una configuración semántica en Azure Portal. Sin embargo, si desea aprender a agregar una configuración semántica mediante programación, continúe con este inicio rápido.

Configuración del cliente

En este inicio rápido, usará un IDE y la biblioteca cliente Azure.Search.Documents para agregar la clasificación semántica a un índice de búsqueda existente.

Se recomienda Visual Studio para este inicio rápido.

Sugerencia

Puede descargar el código fuente para empezar con un proyecto terminado o seguir estos pasos para crear su propio código fuente.

Instalación de bibliotecas

Inicie Visual Studio y abra el quickstart-semantic-search.sln o cree un proyecto con una plantilla de aplicación de consola.
En Herramientas>Administrador de paquetes NuGet seleccione Administrar paquetes NuGet para la solución.....
Haga clic en Examinar.
Busque el paquete de Azure.Search.Documents y seleccione la versión estable más reciente.
Busque el paquete Azure.Identity y seleccione la versión estable más reciente.
Seleccione Instalar para agregar el ensamblado al proyecto y la solución.

Si ha iniciado sesión en Azure Portal, ha iniciado sesión en Azure. Si no está seguro, use la CLI de Azure o Azure PowerShell para iniciar sesión: az login o az connect. Si tiene varios inquilinos y suscripciones, consulte Inicio rápido: Conexión sin claves para obtener ayuda sobre cómo conectarse.

Actualización del índice

En esta sección, actualizará un índice de búsqueda para incluir una configuración semántica. El código obtiene la definición de índice del servicio de búsqueda y agrega una configuración semántica.

Abra el proyecto BuildIndex en Visual Studio. El programa consta del código siguiente.

Este código usa searchIndexClient para actualizar un índice en el servicio de búsqueda.

class BuildIndex
{
    static async Task Main(string[] args)
    {
        string searchServiceName = "PUT-YOUR-SEARCH-SERVICE-NAME-HERE";
        string indexName = "hotels-sample-index";
        string endpoint = $"https://{searchServiceName}.search.windows.net";
        var credential = new Azure.Identity.DefaultAzureCredential();

        await ListIndexesAsync(endpoint, credential);
        await UpdateIndexAsync(endpoint, credential, indexName);
    }

    // Print a list of all indexes on the search service
    // You should see hotels-sample-index in the list
    static async Task ListIndexesAsync(string endpoint, Azure.Core.TokenCredential credential)
    {
        try
        {
            var indexClient = new Azure.Search.Documents.Indexes.SearchIndexClient(
                new Uri(endpoint),
                credential
            );

            var indexes = indexClient.GetIndexesAsync();

            Console.WriteLine("Here's a list of all indexes on the search service. You should see hotels-sample-index:");
            await foreach (var index in indexes)
            {
                Console.WriteLine(index.Name);
            }
            Console.WriteLine(); // Add an empty line for readability
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error listing indexes: {ex.Message}");
        }
    }

    static async Task UpdateIndexAsync(string endpoint, Azure.Core.TokenCredential credential, string indexName)
    {
        try
        {
            var indexClient = new Azure.Search.Documents.Indexes.SearchIndexClient(
                new Uri(endpoint),
                credential
            );

            // Get the existing definition of hotels-sample-index
            var indexResponse = await indexClient.GetIndexAsync(indexName);
            var index = indexResponse.Value;

            // Add a semantic configuration
            const string semanticConfigName = "semantic-config";
            AddSemanticConfiguration(index, semanticConfigName);

            // Update the index with the new information
            var updatedIndex = await indexClient.CreateOrUpdateIndexAsync(index);
            Console.WriteLine("Index updated successfully.");

            // Print the updated index definition as JSON
            var refreshedIndexResponse = await indexClient.GetIndexAsync(indexName);
            var refreshedIndex = refreshedIndexResponse.Value;
            var jsonOptions = new JsonSerializerOptions { WriteIndented = true };
            string indexJson = JsonSerializer.Serialize(refreshedIndex, jsonOptions);
            Console.WriteLine($"Here is the revised index definition:\n{indexJson}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error updating index: {ex.Message}");
        }
    }

    // This is the semantic configuration definition
    static void AddSemanticConfiguration(SearchIndex index, string semanticConfigName)
    {
        if (index.SemanticSearch == null)
        {
            index.SemanticSearch = new SemanticSearch();
        }
        var configs = index.SemanticSearch.Configurations;
        if (configs == null)
        {
            throw new InvalidOperationException("SemanticSearch.Configurations is null and cannot be assigned. Your service must be Basic tier or higher.");
        }
        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
                )
            );
            Console.WriteLine($"Added new semantic configuration '{semanticConfigName}' to the index definition.");
        }
        else
        {
            Console.WriteLine($"Semantic configuration '{semanticConfigName}' already exists in the index definition.");
        }
        index.SemanticSearch.DefaultConfigurationName = semanticConfigName;
    }
}

Reemplace la dirección URL del servicio de búsqueda por un punto de conexión válido.
Ejecute el programa.
La salida se registra en una ventana de consola desde Console.WriteLine. Debería ver los mensajes de cada paso, incluido el JSON del esquema de índice con la nueva configuración semántica incluida.

Ejecución de consultas semánticas

En esta sección, el programa ejecuta varias consultas semánticas en secuencia.

Abra el proyecto QueryIndex en Visual Studio. El programa consta del código siguiente.

Este código usa searchClient para enviar consultas a un índice.

class SemanticQuery
{
    static async Task Main(string[] args)
    {
        string searchServiceName = "PUT-YOUR-SEARCH-SERVICE-NAME-HERE";
        string indexName = "hotels-sample-index";
        string endpoint = $"https://{searchServiceName}.search.windows.net";
        var credential = new Azure.Identity.DefaultAzureCredential();

        var client = new SearchClient(new Uri(endpoint), indexName, credential);

        // Query 1: Simple query
        string searchText = "walking distance to live music";
        Console.WriteLine("\nQuery 1: Simple query using the search string 'walking distance to live music'.");
        await RunQuery(client, searchText, new SearchOptions
        {
            Size = 5,
            QueryType = SearchQueryType.Simple,
            IncludeTotalCount = true,
            Select = { "HotelId", "HotelName", "Description" }
        });
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 2: Semantic query (no captions, no answers)
        Console.WriteLine("\nQuery 2: Semantic query (no captions, no answers) for 'walking distance to live music'.");
        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);
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 3: Semantic query with captions
        Console.WriteLine("\nQuery 3: Semantic query with captions.");
        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" }
        };
        // Add the field(s) you want captions for to the QueryCaption.Fields collection
        captionsOptions.HighlightFields.Add("Description");
        await RunQuery(client, searchText, captionsOptions, showCaptions: true);
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 4: Semantic query with answers
        // This query uses different search text designed for an answers scenario
        string searchText2 = "what's a good hotel for people who like to read";
        searchText = searchText2; // Update searchText for the next query
        Console.WriteLine("\nQuery 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.");
        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);

        static async Task RunQuery(
        SearchClient client,
        string searchText,
        SearchOptions options,
        bool showCaptions = false,
        bool showAnswers = false)
        {
            try
            {
                var response = await client.SearchAsync<SearchDocument>(searchText, options);

                if (showAnswers && response.Value.SemanticSearch?.Answers != null)
                {
                    Console.WriteLine("Extractive Answers:");
                    foreach (var answer in response.Value.SemanticSearch.Answers)
                    {
                        Console.WriteLine($"  {answer.Highlights}");
                    }
                    Console.WriteLine(new string('-', 40));
                }

                await foreach (var result in response.Value.GetResultsAsync())
                {
                    var doc = result.Document;
                    // Print captions first if available
                    if (showCaptions && result.SemanticSearch?.Captions != null)
                    {
                        foreach (var caption in result.SemanticSearch.Captions)
                        {
                            Console.WriteLine($"Caption: {caption.Highlights}");
                        }
                    }
                    Console.WriteLine($"HotelId: {doc.GetString("HotelId")}");
                    Console.WriteLine($"HotelName: {doc.GetString("HotelName")}");
                    Console.WriteLine($"Description: {doc.GetString("Description")}");
                    Console.WriteLine($"@search.score: {result.Score}");

                    // Print @search.rerankerScore if available
                    if (result.SemanticSearch != null && result.SemanticSearch.RerankerScore.HasValue)
                    {
                        Console.WriteLine($"@search.rerankerScore: {result.SemanticSearch.RerankerScore.Value}");
                    }
                    Console.WriteLine(new string('-', 40));
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error querying index: {ex.Message}");
            }
        }
    }
}

Reemplace la dirección URL del servicio de búsqueda por un punto de conexión válido.
Ejecute el programa.
La salida se registra en una ventana de consola desde Console.WriteLine. Debería ver los resultados de la búsqueda para cada consulta.

Salida para la consulta semántica (sin subtítulos ni respuestas)

Esta salida procede de la consulta semántica, sin títulos ni respuestas. La cadena de consulta es "distancia a pie de la música en vivo".

Aquí, los resultados iniciales de la consulta de términos se vuelven a puntuar mediante los modelos de clasificación semántica. Para este conjunto de datos y consulta concretos, los primeros resultados se encuentran en posiciones similares. Los efectos de la clasificación semántica son más pronunciados en el resto de los resultados.

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: 5.074317
@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.5153193
@search.rerankerScore: 2.271434783935547
----------------------------------------
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.
@search.score: 4.8959594
@search.rerankerScore: 1.9861756563186646
----------------------------------------
HotelId: 39
HotelName: White Mountain Lodge & Suites
Description: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.
@search.score: 0.7334347
@search.rerankerScore: 1.9615401029586792
----------------------------------------
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.5502293
@search.rerankerScore: 1.9085469245910645
----------------------------------------
Press Enter to continue to the next query...

Salida de una consulta semántica con subtítulos

Estos son los resultados de la consulta que agrega subtítulos con resaltado de aciertos.

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: 5.074317
@search.rerankerScore: 2.613231658935547
----------------------------------------
Caption:
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.5153193
@search.rerankerScore: 2.271434783935547
----------------------------------------
Caption: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within<em> short walking distance </em>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,.
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.
@search.score: 4.8959594
@search.rerankerScore: 1.9861756563186646
----------------------------------------
Caption: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend<em> evening entertainment </em>on the patio features special<em> guest musicians </em>or.
HotelId: 39
HotelName: White Mountain Lodge & Suites
Description: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.
@search.score: 0.7334347
@search.rerankerScore: 1.9615401029586792
----------------------------------------
Caption: Book now and Save up to 30%. Central location. <em>Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood.</em> Brand new rooms. Impeccable service.
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.5502293
@search.rerankerScore: 1.9085469245910645
----------------------------------------
Press Enter to continue to the next query...

Salida para respuestas semánticas

La consulta final devuelve una respuesta semántica. Observe que hemos cambiado la cadena de consulta de este ejemplo: "qué es un buen hotel para las personas que les gusta leer".

El clasificador semántico puede generar una respuesta a una cadena de consulta que tenga las características de una pregunta. La respuesta generada se extrae textualmente del contenido, por lo que no incluirá contenido compuesto como lo que podría esperar de un modelo de finalización de chat. Si la respuesta semántica no es útil para su escenario, puede omitirlo semantic_answers del código.

Para generar una respuesta semántica, la pregunta y la respuesta deben estar estrechamente alineadas y el modelo debe encontrar contenido que responda claramente a la pregunta. Si las posibles respuestas no alcanzan el umbral de confianza, el modelo no devuelve una respuesta. Para fines de demostración, la pregunta de este ejemplo está diseñada para obtener una respuesta que le permita ver la sintaxis.

Recuerde que las respuestas son contenido textual extraído del índice y podrían faltar frases que un usuario esperaría ver. Para obtener respuestas compuestas generadas por un modelo de finalización de chat, considere la posibilidad de usar un patrón RAG o una recuperación mediante agente.

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.
----------------------------------------
HotelId: 1
HotelName: 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.
@search.score: 2.0361428
@search.rerankerScore: 2.124817371368408
----------------------------------------
HotelId: 16
HotelName: 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.
@search.score: 3.759768
@search.rerankerScore: 2.0705394744873047
----------------------------------------
HotelId: 38
HotelName: Lakeside B & B
Description: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
@search.score: 0.7308748
@search.rerankerScore: 2.041472911834717
----------------------------------------
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: 3.391012
@search.rerankerScore: 2.0231292247772217
----------------------------------------
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.3198771
@search.rerankerScore: 2.021622657775879
----------------------------------------

En este inicio rápido, aprenderá a usar la clasificación semántica agregando una configuración semántica a un índice de búsqueda y agregando parámetros semánticos a una consulta. Puede usar el índice de muestra de hoteles o uno propio.

En Azure AI Search, la clasificación semántica es la funcionalidad del lado de consulta que usa la comprensión de lectura automática de Microsoft 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. Según el contenido y la consulta, la clasificación semántica puede mejorar significativamente la relevancia de búsqueda con un esfuerzo mínimo para desarrolladores.

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 en el texto que es informativo o descriptivo.

Requisitos previos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Un servicio azure AI Search con clasificador semántico habilitado.
Índice nuevo o existente con campos de texto descriptivos o detallados que se atribuyen como recuperables. En este inicio rápido asume el hotels-sample-index.

Configurar el acceso

Puede conectarse al servicio Azure AI Search mediante claves de API o identificador de Microsoft Entra con asignaciones de roles. Las claves son más fáciles de empezar, pero los roles son más seguros. Para más información, consulte Conexión a la Búsqueda de Azure AI usando los roles.

Para configurar el acceso basado en roles:

Inicie sesión en Azure Portal y seleccione el servicio de búsqueda.
En el panel izquierdo, seleccione Configuración>Claves.
En Control de acceso de API, seleccione Control de acceso basado en rol o Ambos si necesita tiempo para realizar la transición de los clientes al acceso basado en roles.
En el panel izquierdo, seleccione Control de acceso (IAM) .
Seleccione Agregar>Agregar asignación de rol.
Asigne los roles Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda a su cuenta de usuario.

Empezar con un índice

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

Para empezar con un índice existente:

Inicie sesión en Azure Portal y busque su servicio de búsqueda.
En Gestión de búsqueda>Índices, seleccione el hotels-sample-index.
Seleccione Configuraciones semánticas para asegurarse de que el índice no tiene una configuración semántica.
Seleccione Explorador de búsqueda y, a continuación, seleccione la vista JSON.

Pegue el siguiente JSON en el editor de consultas.

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

Seleccione Buscar para ejecutar la consulta.

Esta consulta es una búsqueda de palabras clave. La respuesta debe ser similar al ejemplo siguiente, como se puntúa con el clasificador BM25 L1 predeterminado para la búsqueda de texto completo.

Para mejorar la legibilidad, el ejemplo solo selecciona los HotelIdcampos , HotelNamey Description . Los resultados contienen coincidencias textuales en los términos de consulta (walking, distance, live, music) o variantes lingüísticas (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Más adelante, puede ejecutar la misma consulta después de configurar la clasificación semántica para ver cómo cambia la respuesta.

Sugerencia

Puede agregar una configuración semántica en Azure Portal. Sin embargo, si desea aprender a agregar una configuración semántica mediante programación, continúe con este inicio rápido.

Configuración del cliente

En este inicio rápido, usará un IDE y la biblioteca cliente de @azure/search-documents para agregar la clasificación semántica a un índice de búsqueda existente.

En el inicio rápido se da por supuesto que lo siguiente está disponible en el equipo:

Visual Studio Code para este inicio rápido.
Node.js (LTS) para ejecutar el ejemplo.

Sugerencia

Puede descargar el código fuente para empezar con un proyecto terminado o seguir estos pasos para crear su propio código fuente.

Configuración del entorno de desarrollo local

Inicie Visual Studio Code en un nuevo directorio.

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

Cree un nuevo paquete para los módulos ESM en el directorio del proyecto.
```
npm init -y
npm pkg set type=module
```

Instale paquetes, incluidos azure-search-documents.

npm install @azure/identity @azure/search-documents dotenv

Cree .env, y proporcione el punto de conexión del servicio de búsqueda. Puede obtener el punto de conexión desde Azure Portal en la página Información general del servicio de búsqueda.
```
AZURE_SEARCH_ENDPOINT=YOUR-SEARCH-SERVICE-ENDPOINT
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
SEMANTIC_CONFIGURATION_NAME=semantic-config
```
Cree un directorio src en el directorio del proyecto.
```
mkdir src
```

Si ha iniciado sesión en Azure Portal, ha iniciado sesión en Azure. Si no está seguro, use la CLI de Azure o Azure PowerShell para iniciar sesión: az login o az connect. Si tiene varios inquilinos y suscripciones, consulte Inicio rápido: Conexión sin claves para obtener ayuda sobre cómo conectarse.

Creación de un archivo de autenticación común

Cree un archivo en ./src llamado config.ts para leer el archivo .env y contener las variables de entorno y las credenciales de autenticación. Copie en el código siguiente; no lo cambies. Este archivo lo usarán todos los demás archivos de este inicio rápido.

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

// Configuration - use environment variables
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-index";
export const semanticConfigurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";

// Create credential
export const credential = new DefaultAzureCredential();

console.log(`Using Azure Search endpoint: ${searchEndpoint}`);
console.log(`Using index name: ${indexName}\n\n`);

Obtención del esquema de índice

En esta sección, obtendrá la configuración del índice existente hotels-sample-index en el servicio de búsqueda.

Cree un archivo en ./src llamado getIndexSettings.js y copie en el código siguiente.

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

const indexClient = new SearchIndexClient(searchEndpoint, credential);

console.log('Getting semantic search index settings...');

// Get the existing schema
const index = await indexClient.getIndex(indexName);

console.log(`Index name: ${index.name}`);
console.log(`Number of fields: ${index.fields.length}`);

for(const field of index.fields) {
    console.log(`Field: ${field.name}, Type: ${field.type}, Searchable: ${field.searchable}`);
}

if(index.semanticSearch && index.semanticSearch.configurations) {
    console.log(`Semantic search configurations: ${index.semanticSearch.configurations.length}`);
    for(const config of index.semanticSearch.configurations) {
        console.log(`Configuration name: ${config.name}`);
        console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
    }
} else {
    console.log("No semantic configuration exists for this index.");
}

Ejecute el código.

node -r dotenv/config src/getIndexSettings.js

La salida es el nombre del índice, la lista de campos y una instrucción que indica si existe una configuración semántica. Para los fines de este inicio rápido, el mensaje debe indicar No semantic configuration exists for this index.

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

Cree un archivo en ./src llamado updateIndexSettings.js y copie en el código siguiente para agregar una configuración semántica al índice existente hotels-sample-index en el servicio de búsqueda. Esta operación no elimina ningún documento de búsqueda y el índice sigue funcionando después de agregar la configuración.

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

try {

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

    // Add the new semantic configuration to the existing index
    if (existingIndex.semanticSearch && existingIndex.semanticSearch.configurations) {
        existingIndex.semanticSearch.configurations.push(newSemanticConfiguration);
    } else {
        const configExists = existingIndex.semanticSearch?.configurations?.some(
            config => config.name === semanticConfigurationName
        );
        if (!configExists) {
            existingIndex.semanticSearch = {
                configurations: [newSemanticConfiguration]
            };
        }
    }

    await indexClient.createOrUpdateIndex(existingIndex);

    const updatedIndex = await indexClient.getIndex(indexName);

    console.log(`Semantic configurations:`);
    console.log("-".repeat(40));

    if (updatedIndex.semanticSearch && updatedIndex.semanticSearch.configurations) {
        for (const config of updatedIndex.semanticSearch.configurations) {
            console.log(`Configuration name: ${config.name}`);
            console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
            console.log(`Keywords fields: ${config.prioritizedFields.keywordsFields?.map(f => f.name).join(", ")}`);
            console.log(`Content fields: ${config.prioritizedFields.contentFields?.map(f => f.name).join(", ")}`);
            console.log("-".repeat(40));
        }
    } else {
        console.log("No semantic configurations found.");
    }

    console.log("Semantic configuration updated successfully.");
} catch (error) {
    console.error("Error updating semantic configuration:", error);
}

Ejecute el código.

node -r dotenv/config src/updateIndexSettings.js

La salida es la configuración semántica que acaba de agregar, Semantic configuration updated successfully..

Ejecución de consultas semánticas

Una vez que el índice hotels-sample-index tiene una configuración semántica, puede ejecutar consultas que incluyan parámetros semánticos.

Cree un archivo en ./src llamado semanticQuery.js y copie en el código siguiente para crear una consulta semántica del índice. Este es 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"]
});

let rowNumber = 1;
for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const score = result.score;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelId: ${doc.HotelId}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);
}

Ejecute el código.

node -r dotenv/config src/semanticQuery.js

La salida debe constar de 13 documentos ordenados por el rerankerScoreDisplay.

Subtítulos devueltos

Opcionalmente, puede agregar subtítulos para extraer partes del texto y aplicar resaltado de aciertos a los términos y frases importantes. Esta consulta agrega subtítulos.

Cree un archivo en ./src llamado semanticQueryReturnCaptions.js y copie en el código siguiente para agregar subtítulos a la consulta.

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

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

console.log(`Using semantic configuration: ${semanticConfigurationName}`);
console.log("Search query: walking distance to live music");

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

console.log(`Found ${results.count} results with semantic search\n`);
let rowNumber = 1;

for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);

    // Caption handling with better debugging
    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];

        if (caption.highlights) {
            console.log(`  Caption with highlights: ${caption.highlights}`);
        } else if (caption.text) {
            console.log(`  Caption text: ${caption.text}`);
        } else {
            console.log(`  Caption exists but has no text or highlights content`);
        }
    } else {
        console.log("  No captions found for this result");
    }
    console.log("-".repeat(60));
}

Ejecute el código.

node -r dotenv/config src/semanticQueryReturnCaptions.js

La salida debe incluir un nuevo elemento caption junto con el campo de búsqueda. Los títulos son los pasajes más relevantes en un resultado. Si el índice incluye fragmentos de texto más grandes, un título es útil para 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.

Devolver respuestas semánticas

En esta consulta final, se devuelven respuestas semánticas.

El clasificador semántico puede generar una respuesta a una cadena de consulta que tenga las características de una pregunta. La respuesta generada se extrae textualmente del contenido, por lo que no incluirá contenido compuesto como lo que podría esperar de un modelo de finalización de chat. Si la respuesta semántica no es útil para su escenario, puede omitirlo semantic_answers del código.

Para generar una respuesta semántica, la pregunta y la respuesta deben estar estrechamente alineadas y el modelo debe encontrar contenido que responda claramente a la pregunta. Si las posibles respuestas no alcanzan el umbral de confianza, el modelo no devuelve una respuesta. Para fines de demostración, la pregunta de este ejemplo está diseñada para obtener una respuesta que le permita ver la sintaxis.

Cree un archivo en ./src llamado semanticAnswer.js y copie en el código siguiente para obtener respuestas semánticas.

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

console.log(`Answers:\n\n`);
let rowNumber = 1; 

// Extract semantic answers from the search results
const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    console.log(`Semantic answer result #${rowNumber++}:`);
    if (answer.highlights) {
        console.log(`Semantic Answer: ${answer.highlights}`);
    } else {
        console.log(`Semantic Answer: ${answer.text}`);
    }
    console.log(`Semantic Answer Score: ${answer.score}\n\n`);
}

console.log(`Search Results:\n\n`);
rowNumber = 1;

// Iterate through the search results
for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`${rerankerScoreDisplay}`);
    console.log(`${doc.HotelName}`);
    console.log(`${doc.Description || 'N/A'}`);

    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(`Caption: ${caption.highlights}\n`);
        } else {
            console.log(`Caption: ${caption.text}\n`);
        }
    }
}

Ejecute el código.

node -r dotenv/config src/semanticAnswer.js

La salida debe ser similar al ejemplo siguiente, donde se extrae la mejor respuesta a la pregunta de uno de los resultados.

Recuerde que las respuestas son contenido textual extraído del índice y podrían faltar frases que un usuario esperaría ver. Para obtener respuestas compuestas generadas por un modelo de finalización de chat, considere la posibilidad de usar un patrón RAG o una recuperación mediante agente.
```
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 library 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
```

En este inicio rápido, aprenderá a usar la clasificación semántica agregando una configuración semántica a un índice de búsqueda y agregando parámetros semánticos a una consulta. Puede usar el índice de muestra de hoteles o uno propio.

En Azure AI Search, la clasificación semántica es la funcionalidad del lado de consulta que usa la comprensión de lectura automática de Microsoft 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. Según el contenido y la consulta, la clasificación semántica puede mejorar significativamente la relevancia de búsqueda con un esfuerzo mínimo para desarrolladores.

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 en el texto que es informativo o descriptivo.

Requisitos previos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Un servicio azure AI Search con clasificador semántico habilitado.
Índice nuevo o existente con campos de texto descriptivos o detallados que se atribuyen como recuperables. En este inicio rápido asume el hotels-sample-index.

Configurar el acceso

Puede conectarse al servicio Azure AI Search mediante claves de API o identificador de Microsoft Entra con asignaciones de roles. Las claves son más fáciles de empezar, pero los roles son más seguros. Para más información, consulte Conexión a la Búsqueda de Azure AI usando los roles.

Para configurar el acceso basado en roles:

Inicie sesión en Azure Portal y seleccione el servicio de búsqueda.
En el panel izquierdo, seleccione Configuración>Claves.
En Control de acceso de API, seleccione Control de acceso basado en rol o Ambos si necesita tiempo para realizar la transición de los clientes al acceso basado en roles.
En el panel izquierdo, seleccione Control de acceso (IAM) .
Seleccione Agregar>Agregar asignación de rol.
Asigne los roles Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda a su cuenta de usuario.

Empezar con un índice

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

Para empezar con un índice existente:

Inicie sesión en Azure Portal y busque su servicio de búsqueda.
En Gestión de búsqueda>Índices, seleccione el hotels-sample-index.
Seleccione Configuraciones semánticas para asegurarse de que el índice no tiene una configuración semántica.
Seleccione Explorador de búsqueda y, a continuación, seleccione la vista JSON.

Pegue el siguiente JSON en el editor de consultas.

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

Seleccione Buscar para ejecutar la consulta.

Esta consulta es una búsqueda de palabras clave. La respuesta debe ser similar al ejemplo siguiente, como se puntúa con el clasificador BM25 L1 predeterminado para la búsqueda de texto completo.

Para mejorar la legibilidad, el ejemplo solo selecciona los HotelIdcampos , HotelNamey Description . Los resultados contienen coincidencias textuales en los términos de consulta (walking, distance, live, music) o variantes lingüísticas (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Más adelante, puede ejecutar la misma consulta después de configurar la clasificación semántica para ver cómo cambia la respuesta.

Sugerencia

Puede agregar una configuración semántica en Azure Portal. Sin embargo, si desea aprender a agregar una configuración semántica mediante programación, continúe con este inicio rápido.

Configuración del cliente

En este inicio rápido, usará un IDE y la biblioteca cliente del SDK de Java de Azure AI Search para agregar la clasificación semántica a un índice de búsqueda existente.

En el inicio rápido se da por supuesto que lo siguiente está disponible en el equipo:

Visual Studio Code con extensiones de Java o IntelliJ IDEA
Java 21 (LTS).
Maven.

Configuración del entorno de desarrollo local

Cree un nuevo directorio para un proyecto de Maven.

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

Cree un pom.xml archivo con dependencias necesarias.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.azure.search</groupId>
    <artifactId>semantic-ranking-quickstart</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.7.8</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.17.0</version>
        </dependency>
    </dependencies>
</project>

Compile el proyecto para resolver las dependencias.
```
mvn compile
```

Cree la estructura del directorio de origen.

mkdir -p src/main/java/com/azure/search/quickstart
mkdir -p src/main/resources

Cree src/main/resources/application.properties y proporcione el punto de conexión del servicio de búsqueda. Puede obtener el punto de conexión desde Azure Portal en la página Información general del servicio de búsqueda.
```
azure.search.endpoint=YOUR-SEARCH-SERVICE-ENDPOINT
azure.search.index.name=hotels-sample-index
semantic.configuration.name=semantic-config
```

Si ha iniciado sesión en Azure Portal, ha iniciado sesión en Azure. Si no está seguro, use la CLI de Azure para iniciar sesión: az login. Si tiene varios inquilinos y suscripciones, consulte Inicio rápido: Conexión sin claves para obtener ayuda sobre cómo conectarse.

Creación de una clase de configuración común

Cree un archivo en src/main/java/com/azure/search/quickstart llamado SearchConfig.java para leer el archivo de propiedades y almacenar los valores de configuración y las credenciales de autenticación.

package com.azure.search.quickstart;

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

    static {
        System.out.println("Using Azure Search endpoint: " + SEARCH_ENDPOINT);
        System.out.println("Using index name: " + INDEX_NAME + "\n");
    }
}

Obtención del esquema de índice

En esta sección, obtendrá la configuración del índice existente hotels-sample-index en el servicio de búsqueda.

Cree un archivo en src/main/java/com/azure/search/quickstart denominado GetIndexSettings.java.

package com.azure.search.quickstart;

import com.azure.search.documents.indexes.SearchIndexClientBuilder;
import com.azure.search.documents.indexes.models.SearchField;
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.SemanticSearch;

public class GetIndexSettings {
    public static void main(String[] args) {
        var indexClient = new SearchIndexClientBuilder()
            .endpoint(SearchConfig.SEARCH_ENDPOINT)
            .credential(SearchConfig.CREDENTIAL)
            .buildClient();

        System.out.println("Getting semantic search index settings...");

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

        System.out.println("Index name: " + index.getName());
        System.out.println("Number of fields: " + index.getFields().size());

        for (SearchField field : index.getFields()) {
            System.out.printf("Field: %s, Type: %s, Searchable: %s%n",
                field.getName(), field.getType(), field.isSearchable());
        }

        SemanticSearch semanticSearch = index.getSemanticSearch();
        if (semanticSearch != null &&
            semanticSearch.getConfigurations() != null) {
            System.out.println("Semantic search configurations: " +
                semanticSearch.getConfigurations().size());
            for (SemanticConfiguration config :
                semanticSearch.getConfigurations()) {
                System.out.println("Configuration name: " + config.getName());
                SemanticField titleField = config.getPrioritizedFields().getTitleField();
                if (titleField != null) {
                    System.out.println("Title field: " +
                        titleField.getFieldName());
                }
            }
        } else {
            System.out.println(
                "No semantic configuration exists for this index.");
        }

        System.exit(0);
    }
}

Compile y ejecute el código.

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

La salida es el nombre del índice, la lista de campos y una instrucción que indica si existe una configuración semántica. Para los fines de este inicio rápido, el mensaje debe indicar No semantic configuration exists for this index.

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

Cree un archivo en src/main/java/com/azure/search/quickstart llamado UpdateIndexSettings.java para agregar una configuración semántica al índice existente hotels-sample-index en el servicio de búsqueda.

package com.azure.search.quickstart;

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;

public class UpdateIndexSettings {
    public static void main(String[] args) {
        try {
            var indexClient = new SearchIndexClientBuilder()
                .endpoint(SearchConfig.SEARCH_ENDPOINT)
                .credential(SearchConfig.CREDENTIAL)
                .buildClient();

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

            // Create prioritized fields for semantic configuration
            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);

            // Add the semantic configuration to the index
            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);
            }

            // Check if configuration already exists
            boolean configExists = configurations.stream()
                .anyMatch(config -> SearchConfig.SEMANTIC_CONFIG_NAME
                    .equals(config.getName()));

            if (!configExists) {
                configurations.add(newSemanticConfiguration);
            }

            indexClient.createOrUpdateIndex(existingIndex);

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

            System.out.println("Semantic configurations:");
            System.out.println("-".repeat(40));

            SemanticSearch updatedSemanticSearch =
                updatedIndex.getSemanticSearch();
            if (updatedSemanticSearch != null &&
                updatedSemanticSearch.getConfigurations() != null) {
                for (SemanticConfiguration config :
                    updatedSemanticSearch.getConfigurations()) {
                    System.out.println("Configuration name: " + config.getName());

                    SemanticPrioritizedFields fields =
                        config.getPrioritizedFields();
                    if (fields.getTitleField() != null) {
                        System.out.println("Title field: " +
                            fields.getTitleField().getFieldName());
                    }
                    if (fields.getKeywordsFields() != null) {
                        List<String> keywords = fields.getKeywordsFields().stream()
                            .map(SemanticField::getFieldName)
                            .toList();
                        System.out.println("Keywords fields: " +
                            String.join(", ", keywords));
                    }
                    if (fields.getContentFields() != null) {
                        List<String> content = fields.getContentFields().stream()
                            .map(SemanticField::getFieldName)
                            .toList();
                        System.out.println("Content fields: " +
                            String.join(", ", content));
                    }
                    System.out.println("-".repeat(40));
                }
            } else {
                System.out.println("No semantic configurations found.");
            }

            System.out.println("Semantic configuration updated successfully.");

            System.exit(0);
        } catch (Exception e) {
            System.err.println("Error updating semantic configuration: " +
                e.getMessage());
        }
    }
}

Ejecute el código.

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

La salida es la configuración semántica que acaba de agregar, Semantic configuration updated successfully..

Ejecución de consultas semánticas

Una vez que el índice hotels-sample-index tiene una configuración semántica, puede ejecutar consultas que incluyan parámetros semánticos.

Cree un archivo en src/main/java/com/azure/search/quickstart llamado SemanticQuery.java para crear una consulta semántica del índice.

package com.azure.search.quickstart;

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;

public class SemanticQuery {
    public static void main(String[] args) {
        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);

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

            System.out.printf("Search result #%d:%n", rowNumber++);
            System.out.printf("  Re-ranker Score: %.2f%n", rerankerScore);
            System.out.printf("  HotelId: %s%n", document.get("HotelId"));
            System.out.printf("  HotelName: %s%n", document.get("HotelName"));
            System.out.printf("  Description: %s%n%n",
                document.get("Description") != null ?
                    document.get("Description") : "N/A");
        }

        System.exit(0);
    }
}

Ejecute el código.

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

La salida debe constar de 13 documentos, ordenados por la puntuación del reranker.

Subtítulos devueltos

Opcionalmente, puede agregar subtítulos para extraer partes del texto y aplicar resaltado de aciertos a los términos y frases importantes.

Cree un archivo en src/main/java/com/azure/search/quickstart denominado SemanticQueryWithCaptions.java.

package com.azure.search.quickstart;

import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryCaption;
import com.azure.search.documents.models.QueryCaptionResult;
import com.azure.search.documents.models.QueryCaptionType;
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;
import java.util.List;

public class SemanticQueryWithCaptions {
    public static void main(String[] args) {
        var searchClient = new SearchClientBuilder()
            .endpoint(SearchConfig.SEARCH_ENDPOINT)
            .indexName(SearchConfig.INDEX_NAME)
            .credential(SearchConfig.CREDENTIAL)
            .buildClient();

        System.out.println("Using semantic configuration: " +
            SearchConfig.SEMANTIC_CONFIG_NAME);
        System.out.println("Search query: walking distance to live music");

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

        System.out.printf("Found results with semantic search%n%n");
        int rowNumber = 1;

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

            System.out.printf("Search result #%d:%n", rowNumber++);
            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") != null ?
                    document.get("Description") : "N/A");

            // Handle captions
            List<QueryCaptionResult> captions =
                result.getSemanticSearch().getQueryCaptions();
            if (captions != null && !captions.isEmpty()) {
                QueryCaptionResult caption = captions.get(0);

                if (caption.getHighlights() != null &&
                    !caption.getHighlights().trim().isEmpty()) {
                    System.out.printf("  Caption with highlights: %s%n",
                        caption.getHighlights());
                } else if (caption.getText() != null &&
                    !caption.getText().trim().isEmpty()) {
                    System.out.printf("  Caption text: %s%n",
                        caption.getText());
                } else {
                    System.out.println(
                        "  Caption exists but has no text or highlights content");
                }
            } else {
                System.out.println("  No captions found for this result");
            }
            System.out.println("-".repeat(60));
        }

        System.exit(0);
    }
}

Ejecute el código.

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

La salida debe incluir un nuevo elemento caption junto con el campo de búsqueda. Los títulos son los pasajes más relevantes en un resultado. Si el índice incluye fragmentos de texto más grandes, un título es útil para 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.

Devolver respuestas semánticas

En esta consulta final, se devuelven respuestas semánticas.

El clasificador semántico puede generar una respuesta a una cadena de consulta que tenga las características de una pregunta. La respuesta generada se extrae textualmente del contenido, por lo que no incluirá contenido compuesto como lo que podría esperar de un modelo de finalización de chat.

Para generar una respuesta semántica, la pregunta y la respuesta deben estar estrechamente alineadas y el modelo debe encontrar contenido que responda claramente a la pregunta. Si las posibles respuestas no alcanzan el umbral de confianza, el modelo no devuelve una respuesta. Para fines de demostración, la pregunta de este ejemplo está diseñada para obtener una respuesta que le permita ver la sintaxis.

Cree un archivo en src/main/java/com/azure/search/quickstart denominado SemanticAnswer.java.

package com.azure.search.quickstart;

import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryAnswer;
import com.azure.search.documents.models.QueryAnswerResult;
import com.azure.search.documents.models.QueryAnswerType;
import com.azure.search.documents.models.QueryCaption;
import com.azure.search.documents.models.QueryCaptionResult;
import com.azure.search.documents.models.QueryCaptionType;
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;

import java.util.List;

public class SemanticAnswer {
    public static void main(String[] args) {
        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)
                .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);

        System.out.println("Answers:\n");

        // Extract semantic answers
        List<QueryAnswerResult> semanticAnswers =
            results.getSemanticResults().getQueryAnswers();
        int answerNumber = 1;

        if (semanticAnswers != null) {
            for (QueryAnswerResult answer : semanticAnswers) {
                System.out.printf("Semantic answer result #%d:%n",
                    answerNumber++);

                if (answer.getHighlights() != null &&
                    !answer.getHighlights().trim().isEmpty()) {
                    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%n",
                    answer.getScore());
            }
        }

        System.out.println("Search Results:\n");
        int rowNumber = 1;

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

            System.out.printf("Search result #%d:%n", rowNumber++);
            System.out.printf("Re-ranker Score: %.2f%n", rerankerScore);
            System.out.printf("Hotel: %s%n", document.get("HotelName"));
            System.out.printf("Description: %s%n",
                document.get("Description") != null ?
                    document.get("Description") : "N/A");

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

        System.exit(0);
    }
}

Ejecute el código.

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

La salida debe ser similar al ejemplo siguiente, donde se extrae la mejor respuesta a la pregunta de uno de los resultados.

Recuerde que las respuestas son contenido textual extraído del índice y podrían faltar frases que un usuario esperaría ver. Para obtener respuestas compuestas generadas por un modelo de finalización de chat, considere la posibilidad de usar un patrón RAG o una recuperación mediante agente.
```
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 library 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
```

En este inicio rápido, aprenderá a usar la clasificación semántica agregando una configuración semántica a un índice de búsqueda y agregando parámetros semánticos a una consulta. Puede usar el índice de muestra de hoteles o uno propio.

En Azure AI Search, la clasificación semántica es la funcionalidad del lado de consulta que usa la comprensión de lectura automática de Microsoft 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. Según el contenido y la consulta, la clasificación semántica puede mejorar significativamente la relevancia de búsqueda con un esfuerzo mínimo para desarrolladores.

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 en el texto que es informativo o descriptivo.

Requisitos previos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Un servicio azure AI Search con clasificador semántico habilitado.
Índice nuevo o existente con campos de texto descriptivos o detallados que se atribuyen como recuperables. En este inicio rápido asume el hotels-sample-index.

Configurar el acceso

Puede conectarse al servicio Azure AI Search mediante claves de API o identificador de Microsoft Entra con asignaciones de roles. Las claves son más fáciles de empezar, pero los roles son más seguros. Para más información, consulte Conexión a la Búsqueda de Azure AI usando los roles.

Para configurar el acceso basado en roles:

Inicie sesión en Azure Portal y seleccione el servicio de búsqueda.
En el panel izquierdo, seleccione Configuración>Claves.
En Control de acceso de API, seleccione Control de acceso basado en rol o Ambos si necesita tiempo para realizar la transición de los clientes al acceso basado en roles.
En el panel izquierdo, seleccione Control de acceso (IAM) .
Seleccione Agregar>Agregar asignación de rol.
Asigne los roles Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda a su cuenta de usuario.

Empezar con un índice

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

Para empezar con un índice existente:

Inicie sesión en Azure Portal y busque su servicio de búsqueda.
En Gestión de búsqueda>Índices, seleccione el hotels-sample-index.
Seleccione Configuraciones semánticas para asegurarse de que el índice no tiene una configuración semántica.
Seleccione Explorador de búsqueda y, a continuación, seleccione la vista JSON.

Pegue el siguiente JSON en el editor de consultas.

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

Seleccione Buscar para ejecutar la consulta.

Esta consulta es una búsqueda de palabras clave. La respuesta debe ser similar al ejemplo siguiente, como se puntúa con el clasificador BM25 L1 predeterminado para la búsqueda de texto completo.

Para mejorar la legibilidad, el ejemplo solo selecciona los HotelIdcampos , HotelNamey Description . Los resultados contienen coincidencias textuales en los términos de consulta (walking, distance, live, music) o variantes lingüísticas (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Más adelante, puede ejecutar la misma consulta después de configurar la clasificación semántica para ver cómo cambia la respuesta.

Sugerencia

Puede agregar una configuración semántica en Azure Portal. Sin embargo, si desea aprender a agregar una configuración semántica mediante programación, continúe con este inicio rápido.

Configuración del cliente

En este inicio rápido, use un cuaderno de Jupyter Notebook y la biblioteca azure-search-documents del SDK de Azure para Python para obtener información sobre la clasificación semántica.

Se recomienda Visual Studio Code con Python 3.10 o posterior y la extensión de Python para este inicio rápido.

Sugerencia

Puede descargar un cuaderno terminado para empezar con un proyecto terminado o seguir estos pasos para crear su propio cuaderno.

Se recomienda un entorno virtual para esta guía de inicio rápido:

Inicie Visual Studio Code.
Abra el archivo semantic-search-quickstart.ipynb o cree un cuaderno.
Abra la paleta de comandos mediante Ctrl+Mayús+P.
Busque Python: Crear entorno.
Seleccione Venv..
Seleccione un intérprete de Python. Elija 3.10 o posterior.

Puede tardar un minuto en configurarse. Si tiene problemas, consulte Entornos de Python en VS Code.

Instalación de paquetes y establecimiento de variables de entorno

Instale paquetes, incluidos azure-search-documents.
```
! pip install -r requirements.txt --quiet
```
Cambie el nombre sample.env a .envy proporcione el punto de conexión del servicio de búsqueda. Puede obtener el punto de conexión desde Azure Portal en la página Información general del servicio de búsqueda.
```
AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
```

Si ha iniciado sesión en Azure Portal, ha iniciado sesión en Azure. Si no está seguro, use la CLI de Azure o Azure PowerShell para iniciar sesión: az login o az connect. Si tiene varios inquilinos y suscripciones, consulte Inicio rápido: Conexión sin claves para obtener ayuda sobre cómo conectarse.

Actualización del índice

En esta sección, actualizará un índice de búsqueda para incluir una configuración semántica. El código obtiene la definición de índice del servicio de búsqueda y agrega una configuración semántica.

Abra el archivo semantic-search-quickstart.ipynb en Visual Studio Code o cree un archivo.

Proporcione las variables usadas en la solución.

# Provide variables
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
import os

load_dotenv(override=True) # Take environment variables from .env.

# The following variables from your .env file are used in this notebook
search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://search.azure.com/.default")
index_name = os.getenv("AZURE_SEARCH_INDEX", "hotels-sample-index")

Cree un SearchIndexClient y obtenga el índice hotels-sample-index existente.

from azure.search.documents.indexes import SearchIndexClient
from azure.identity import DefaultAzureCredential
import os

# Initialize the client (similar to what you already have)
search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
index_name = "hotels-sample-index"  # or use your existing index_name variable

# Create the SearchIndexClient
index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)

try:
    # Get the existing index schema
    index = index_client.get_index(index_name)

    print(f"Index name: {index.name}")
    print(f"Number of fields: {len(index.fields)}")

    # Print field details
    for field in index.fields:
        print(f"Field: {field.name}, Type: {field.type}, Searchable: {field.searchable}")

    # Access semantic configuration if it exists
    if index.semantic_search and index.semantic_search.configurations:
        for config in index.semantic_search.configurations:
            print(f"Semantic config: {config.name}")
            if config.prioritized_fields.title_field:
                print(f"Title field: {config.prioritized_fields.title_field.field_name}")
    else:
        print("No semantic configuration exists for this index")

except Exception as ex:
    print(f"Error retrieving index: {ex}")

Ejecute el código.
La salida es el nombre del índice, la lista de campos y una instrucción que indica si existe una configuración semántica. Para los fines de este inicio rápido, el mensaje debe decir "No existe ninguna configuración semántica para este índice".

Agregue una configuración semántica a un índice hotels-sample-index existente en el servicio de búsqueda. Esta operación no elimina ningún documento de búsqueda y el índice sigue funcionando después de agregar la configuración.

# Add semantic configuration to hotels-sample-index and display updated index details
from azure.search.documents.indexes.models import (
    SemanticConfiguration,
    SemanticField,
    SemanticPrioritizedFields,
    SemanticSearch
)

try:
    # Get the existing index
    existing_index = index_client.get_index(index_name)

    # Create a new semantic configuration
    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")]
        )
    )

    # Add semantic configuration to the index
    if existing_index.semantic_search is None:
        existing_index.semantic_search = SemanticSearch(configurations=[new_semantic_config])
    else:
        # Check if configuration already exists
        config_exists = any(config.name == "semantic-config" 
                          for config in existing_index.semantic_search.configurations)
        if not config_exists:
            existing_index.semantic_search.configurations.append(new_semantic_config)

    # Update the index
    result = index_client.create_or_update_index(existing_index)

    # Get the updated index and display detailed information
    updated_index = index_client.get_index(index_name)

    print("Semantic configurations:")
    print("-" * 40)
    if updated_index.semantic_search and updated_index.semantic_search.configurations:
        for config in updated_index.semantic_search.configurations:
            print(f"  Configuration: {config.name}")
            if config.prioritized_fields.title_field:
                print(f"    Title field: {config.prioritized_fields.title_field.field_name}")
            if config.prioritized_fields.keywords_fields:
                keywords = [kf.field_name for kf in config.prioritized_fields.keywords_fields]
                print(f"    Keywords fields: {', '.join(keywords)}")
            if config.prioritized_fields.content_fields:
                content = [cf.field_name for cf in config.prioritized_fields.content_fields]
                print(f"    Content fields: {', '.join(content)}")
            print()
    else:
        print("  No semantic configurations found")

    print("✅ Semantic configuration successfully added!")

except Exception as ex:
    print(f"❌ Error adding semantic configuration: {ex}")

Ejecute el código.
La salida es la configuración semántica que acaba de agregar.

Ejecución de consultas semánticas

Una vez que el índice tiene una configuración semántica, puede ejecutar consultas que incluyan parámetros semánticos.

Cree un SearchClient y una solicitud de consulta que incluya el tipo de consulta semántica y la configuración semántica. Este es el requisito mínimo para invocar la clasificación semántica.

# Set up the search client
search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

# Runs a semantic query (runs a BM25-ranked query, rescoring and promoting the most semantically relevant matches to the top)
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')

for result in results:
    print(result["@search.reranker_score"])
    print(result["HotelId"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

Ejecute el código.
La salida debe constar de 13 documentos ordenados por el "@search.reranker_score".

Subtítulos devueltos

Opcionalmente, puede agregar subtítulos para extraer partes del texto y aplicar resaltado de aciertos a los términos y frases importantes. Esta consulta agrega subtítulos.

Agregue captions a la consulta.

# Runs a semantic query that returns captions
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:
    print(result["@search.reranker_score"])
    print(result["HotelId"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

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

Ejecute el código.

La salida debe incluir un nuevo elemento caption junto con el campo de búsqueda. Los títulos son los pasajes más relevantes en un resultado. Si el índice incluye fragmentos de texto más grandes, un título es útil para 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.

Devolver respuestas semánticas

En esta consulta final, se devuelven respuestas semánticas.

El clasificador semántico puede generar una respuesta a una cadena de consulta que tenga las características de una pregunta. La respuesta generada se extrae textualmente del contenido, por lo que no incluirá contenido compuesto como lo que podría esperar de un modelo de finalización de chat. Si la respuesta semántica no es útil para su escenario, puede omitirlo semantic_answers del código.

Para generar una respuesta semántica, la pregunta y la respuesta deben estar estrechamente alineadas y el modelo debe encontrar contenido que responda claramente a la pregunta. Si las posibles respuestas no alcanzan el umbral de confianza, el modelo no devuelve una respuesta. Para fines de demostración, la pregunta de este ejemplo está diseñada para obtener una respuesta que le permita ver la sintaxis.

Agregue answers a la consulta.

# Run a semantic query that returns semantic answers  
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")

for result in results:
    print(result["@search.reranker_score"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

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

Ejecute el código.

La salida debe ser similar al ejemplo siguiente, donde se extrae la mejor respuesta a la pregunta de uno de los resultados.

Recuerde que las respuestas son contenido textual extraído del índice y podrían faltar frases que un usuario esperaría ver. Para obtener respuestas compuestas generadas por un modelo de finalización de chat, considere la posibilidad de usar un patrón RAG o una recuperación mediante agente.

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

2.124817371368408
1
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.

2.0705394744873047
16
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.

2.041472911834717
38
Lakeside B & B
Description: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Caption: 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.

2.084540843963623
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<em> city. #1 </em>Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.

...

En este inicio rápido, aprenderá a usar la clasificación semántica agregando una configuración semántica a un índice de búsqueda y agregando parámetros semánticos a una consulta. Puede usar el índice de muestra de hoteles o uno propio.

En Azure AI Search, la clasificación semántica es la funcionalidad del lado de consulta que usa la comprensión de lectura automática de Microsoft 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. Según el contenido y la consulta, la clasificación semántica puede mejorar significativamente la relevancia de búsqueda con un esfuerzo mínimo para desarrolladores.

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 en el texto que es informativo o descriptivo.

Requisitos previos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Un servicio azure AI Search con clasificador semántico habilitado.
Índice nuevo o existente con campos de texto descriptivos o detallados que se atribuyen como recuperables. En este inicio rápido asume el hotels-sample-index.

Configurar el acceso

Puede conectarse al servicio Azure AI Search mediante claves de API o identificador de Microsoft Entra con asignaciones de roles. Las claves son más fáciles de empezar, pero los roles son más seguros. Para más información, consulte Conexión a la Búsqueda de Azure AI usando los roles.

Para configurar el acceso basado en roles:

Inicie sesión en Azure Portal y seleccione el servicio de búsqueda.
En el panel izquierdo, seleccione Configuración>Claves.
En Control de acceso de API, seleccione Control de acceso basado en rol o Ambos si necesita tiempo para realizar la transición de los clientes al acceso basado en roles.
En el panel izquierdo, seleccione Control de acceso (IAM) .
Seleccione Agregar>Agregar asignación de rol.
Asigne los roles Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda a su cuenta de usuario.

Empezar con un índice

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

Para empezar con un índice existente:

Inicie sesión en Azure Portal y busque su servicio de búsqueda.
En Gestión de búsqueda>Índices, seleccione el hotels-sample-index.
Seleccione Configuraciones semánticas para asegurarse de que el índice no tiene una configuración semántica.
Seleccione Explorador de búsqueda y, a continuación, seleccione la vista JSON.

Pegue el siguiente JSON en el editor de consultas.

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

Seleccione Buscar para ejecutar la consulta.

Esta consulta es una búsqueda de palabras clave. La respuesta debe ser similar al ejemplo siguiente, como se puntúa con el clasificador BM25 L1 predeterminado para la búsqueda de texto completo.

Para mejorar la legibilidad, el ejemplo solo selecciona los HotelIdcampos , HotelNamey Description . Los resultados contienen coincidencias textuales en los términos de consulta (walking, distance, live, music) o variantes lingüísticas (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Más adelante, puede ejecutar la misma consulta después de configurar la clasificación semántica para ver cómo cambia la respuesta.

Sugerencia

Puede agregar una configuración semántica en Azure Portal. Sin embargo, si desea aprender a agregar una configuración semántica mediante programación, continúe con este inicio rápido.

Configuración del cliente

En este inicio rápido, usará un cliente REST y las API REST de Azure AI Search para configurar y usar un clasificador semántico.

Se recomienda Visual Studio Code con una extensión de cliente REST para este inicio rápido.

Sugerencia

Puede descargar el código fuente para empezar con un proyecto terminado o seguir estos pasos para crear su propio código fuente.

Inicie Visual Studio Code y abra el archivo semantic-search-index-update.rest o cree un archivo.
En la parte superior, establezca las variables de entorno para el servicio de búsqueda, la autorización y el nombre del índice.
- Para @searchURL, inicie sesión en Azure Portal y copie la dirección URL de la página Información general del servicio de búsqueda.
- Para @personalAccessToken, siga las instrucciones de Conexión sin claves para obtener el token de acceso personal.

Para probar la conexión, envíe la primera solicitud.

### List existing indexes by name (verify the connection)
 GET  {{searchUrl}}/indexes?api-version=2025-09-01&$select=name  HTTP/1.1
 Authorization: Bearer {{personalAccessToken}}

Seleccione Enviar solicitud.
La salida de esta solicitud GET devuelve una lista de índices existentes. Debe obtener un código de estado de éxito HTTP 200 y una lista de índices, incluido hotels-sample-index utilizado en este inicio rápido.

Actualización del índice

Para actualizar un índice mediante la API REST, debe proporcionar todo el esquema, además de las modificaciones que desea realizar. Esta solicitud proporciona el esquema hotels-sample-index, además de la configuración semántica. La modificación consta del siguiente JSON.

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

Formule una solicitud PUT que especifique el nombre del índice, la operación y el esquema JSON completo. Todos los elementos necesarios del esquema deben estar presentes. Esta solicitud incluye el esquema completo para hotels-sample-index más la configuración semántica.

PUT {{searchUrl}}/indexes/hotels-sample-index?api-version=2025-09-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

{
   "name": "hotels-sample-index",
   "fields": [
       { "name": "HotelId", "type": "Edm.String", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "key": true },
       { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
       { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
       { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
       { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
       { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
       { "name": "ParkingIncluded", "type": "Edm.Boolean", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
       { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "searchable": false, "filterable": false, "retrievable": true, "stored": true, "sortable": true, "facetable": false },
       { "name": "Rating", "type": "Edm.Double", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": true, "facetable": true },
       { "name": "Address", "type": "Edm.ComplexType", "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
          { "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" }]},
       { "name": "Location", "type": "Edm.GeographyPoint", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": true, "facetable": false },
       { "name": "Rooms", "type": "Collection(Edm.ComplexType)", "fields": [
          { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
          { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
          { "name": "Type", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "BaseRate", "type": "Edm.Double", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "BedOptions", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "SleepsCount", "type": "Edm.Int64", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "SmokingAllowed", "type": "Edm.Boolean", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" }]},
       { "name": "id", "type": "Edm.String", "searchable": false, "filterable": false, "retrievable": false, "stored": true, "sortable": false, "facetable": false },
       { "name": "rid", "type": "Edm.String", "searchable": false, "filterable": false, "retrievable": false, "stored": true, "sortable": false, "facetable": false }],
  "scoringProfiles": [],
  "suggesters": [],
  "analyzers": [],
  "normalizers": [],
  "tokenizers": [],
  "tokenFilters": [],
  "charFilters": [],
  "similarity": {
    "@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
  },
  "semantic": {
    "configurations": [
      {
        "name": "semantic-config",
        "rankingOrder": "BoostedRerankerScore",
        "prioritizedFields": {
          "titleField": {
            "fieldName": "HotelName"
          },
          "prioritizedContentFields": [
            {
              "fieldName": "Description"
            }
          ],
          "prioritizedKeywordsFields": [
            {
              "fieldName": "Tags"
            }
          ]
        }
      }
    ]
  }
}

Seleccione Enviar solicitud.
La salida de esta solicitud POST es un HTTP 200 Success mensaje de estado.

Ejecución de consultas semánticas

Los parámetros semánticos necesarios incluyen query_type y semantic_configuration_name. Este es un ejemplo de una consulta semántica básica mediante los parámetros mínimos.

Abra el archivo semantic-search-query.rest o cree un nuevo archivo.
En la parte superior del archivo, establezca variables de entorno para el servicio de búsqueda, la autorización y el nombre del índice.
- Para @searchURL, inicie sesión en Azure Portal y copie la dirección URL de la página Información general del servicio de búsqueda.
- Para @personalAccessToken, siga las instrucciones de Conexión sin claves para obtener el token de acceso personal.

Pruebe la conexión con una solicitud GET que devuelve el índice hotels-sample-index.

GET {{searchUrl}}/indexes/hotels-sample-index?api-version=2025-09-01  HTTP/1.1
Authorization: Bearer {{personalAccessToken}}

Envíe una consulta que incluya el tipo de consulta semántica y el nombre de configuración.

 POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-09-01  HTTP/1.1
 Content-Type: application/json
 Authorization: Bearer {{personalAccessToken}}

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

La salida consta de resultados de búsqueda JSON. Trece hoteles coinciden con la consulta. Los siete primeros se incluyen en este ejemplo.

{
   "@odata.count": 13,
   "@search.answers": [],
   "value": [
     {
       "@search.score": 5.074317,
       "@search.rerankerScore": 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.score": 5.5153193,
       "@search.rerankerScore": 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.score": 4.8959594,
       "@search.rerankerScore": 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."
     },
     {
       "@search.score": 0.7334347,
       "@search.rerankerScore": 1.9615401029586792,
       "HotelId": "39",
       "HotelName": "White Mountain Lodge & Suites",
       "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
     },
     {
       "@search.score": 1.5502293,
       "@search.rerankerScore": 1.9085469245910645,
       "HotelId": "15",
       "HotelName": "By the Market Hotel",
       "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
     },
     {
       "@search.score": 1.7595702,
       "@search.rerankerScore": 1.90234375,
       "HotelId": "49",
       "HotelName": "Swirling Currents Hotel",
       "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
     },
     {
       "@search.score": 2.0364518,
       "@search.rerankerScore": 1.9012802839279175,
       "HotelId": "31",
       "HotelName": "Country Residence Hotel",
       "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
     }
   ]
 }

Subtítulos devueltos

Opcionalmente, puede agregar subtítulos para extraer partes del texto y aplicar resaltado de aciertos a los términos y frases importantes. Esta consulta agrega subtítulos que incluyen resaltado de resultados.

Agregue el captions parámetro y envíe la solicitud.

POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-09-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

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

La salida consta de los mismos resultados, con la adición de "@search.captions". Este es el código JSON de un único documento. Cada coincidencia incluye puntuaciones de búsqueda, subtítulos en texto sin formato y formato de resaltado, y los campos seleccionables.

{
   "@search.score": 5.074317,
   "@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. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
       "highlights": "Chic hotel near the city. 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."
}

Devolver respuestas semánticas

En esta consulta final, se devuelven respuestas semánticas.

El clasificador semántico puede generar una respuesta a una cadena de consulta que tenga las características de una pregunta. La respuesta generada se extrae textualmente del contenido, por lo que no incluirá contenido compuesto como lo que podría esperar de un modelo de finalización de chat. Si la respuesta semántica no es útil para su escenario, puede omitirlo semantic_answers del código.

Para generar una respuesta semántica, la pregunta y la respuesta deben estar estrechamente alineadas y el modelo debe encontrar contenido que responda claramente a la pregunta. Si las posibles respuestas no alcanzan el umbral de confianza, el modelo no devuelve una respuesta. Para fines de demostración, la pregunta de este ejemplo está diseñada para obtener una respuesta que le permita ver la sintaxis.

Formule la solicitud mediante una cadena de búsqueda que formula una pregunta.

POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-09-01  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

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

El resultado consta de 41 resultados para la nueva consulta, con "@search.answers" para la pregunta en la consulta sobre hoteles para personas a las que les gustan leer.

Recuerde que las respuestas son contenido textual extraído del índice y podrían faltar frases que un usuario esperaría ver. Para obtener respuestas compuestas generadas por un modelo de finalización de chat, considere la posibilidad de usar un patrón RAG o una recuperación mediante agente.

En este ejemplo, la respuesta se considera una buena opción para la pregunta.

{
  "@odata.count": 41,
  "@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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our 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.",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.0361428,
      "@search.rerankerScore": 2.124817371368408,
      "HotelId": "1",
      "HotelName": "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."
    },
    {
      "@search.score": 3.759768,
      "@search.rerankerScore": 2.0705394744873047,
      "HotelId": "16",
      "HotelName": "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."
    },
    {
      "@search.score": 0.7308748,
      "@search.rerankerScore": 2.041472911834717,
      "HotelId": "38",
      "HotelName": "Lakeside B & B",
      "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
    },
    {
      "@search.score": 3.391012,
      "@search.rerankerScore": 2.0231292247772217,
      "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": 1.3198771,
      "@search.rerankerScore": 2.021622657775879,
      "HotelId": "15",
      "HotelName": "By the Market Hotel",
      "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
    },
    {
      "@search.score": 1.3983066,
      "@search.rerankerScore": 2.005582809448242,
      "HotelId": "5",
      "HotelName": "Red Tide Hotel",
      "Description": "On entering this charming hotel in Scarlet Harbor, you'll notice an uncommon blend of antiques, original artwork, and contemporary comforts that give this hotel its signature look. Each suite is furnished to accentuate the views and unique characteristics of the building's classic architecture. No two suites are alike. However, all guests are welcome in the mezzanine plaza, the surrounding gardens, and the northside terrace for evening refreshments."
    },
    {
      "@search.score": 1.4815493,
      "@search.rerankerScore": 1.9739465713500977,
      "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."
    }
  ]
}

En este inicio rápido, aprenderá a usar la clasificación semántica agregando una configuración semántica a un índice de búsqueda y agregando parámetros semánticos a una consulta. Puede usar el índice de muestra de hoteles o uno propio.

En Azure AI Search, la clasificación semántica es la funcionalidad del lado de consulta que usa la comprensión de lectura automática de Microsoft 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. Según el contenido y la consulta, la clasificación semántica puede mejorar significativamente la relevancia de búsqueda con un esfuerzo mínimo para desarrolladores.

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 en el texto que es informativo o descriptivo.

Requisitos previos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Un servicio azure AI Search con clasificador semántico habilitado.
Índice nuevo o existente con campos de texto descriptivos o detallados que se atribuyen como recuperables. En este inicio rápido asume el hotels-sample-index.

Configurar el acceso

Puede conectarse al servicio Azure AI Search mediante claves de API o identificador de Microsoft Entra con asignaciones de roles. Las claves son más fáciles de empezar, pero los roles son más seguros. Para más información, consulte Conexión a la Búsqueda de Azure AI usando los roles.

Para configurar el acceso basado en roles:

Inicie sesión en Azure Portal y seleccione el servicio de búsqueda.
En el panel izquierdo, seleccione Configuración>Claves.
En Control de acceso de API, seleccione Control de acceso basado en rol o Ambos si necesita tiempo para realizar la transición de los clientes al acceso basado en roles.
En el panel izquierdo, seleccione Control de acceso (IAM) .
Seleccione Agregar>Agregar asignación de rol.
Asigne los roles Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda a su cuenta de usuario.

Empezar con un índice

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

Para empezar con un índice existente:

Inicie sesión en Azure Portal y busque su servicio de búsqueda.
En Gestión de búsqueda>Índices, seleccione el hotels-sample-index.
Seleccione Configuraciones semánticas para asegurarse de que el índice no tiene una configuración semántica.
Seleccione Explorador de búsqueda y, a continuación, seleccione la vista JSON.

Pegue el siguiente JSON en el editor de consultas.

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

Seleccione Buscar para ejecutar la consulta.

Esta consulta es una búsqueda de palabras clave. La respuesta debe ser similar al ejemplo siguiente, como se puntúa con el clasificador BM25 L1 predeterminado para la búsqueda de texto completo.

Para mejorar la legibilidad, el ejemplo solo selecciona los HotelIdcampos , HotelNamey Description . Los resultados contienen coincidencias textuales en los términos de consulta (walking, distance, live, music) o variantes lingüísticas (walk, living).

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

Esta consulta muestra cómo se ve la respuesta antes de aplicar la clasificación semántica. Más adelante, puede ejecutar la misma consulta después de configurar la clasificación semántica para ver cómo cambia la respuesta.

Sugerencia

Puede agregar una configuración semántica en Azure Portal. Sin embargo, si desea aprender a agregar una configuración semántica mediante programación, continúe con este inicio rápido.

Configuración del cliente

En este inicio rápido, usará un IDE y la biblioteca cliente de @azure/search-documents para agregar la clasificación semántica a un índice de búsqueda existente.

En el inicio rápido se da por supuesto que lo siguiente está disponible en el equipo:

Visual Studio Code para este inicio rápido.
Node.js (LTS) para ejecutar el ejemplo.
TypeScript para escribir el código de ejemplo.

Sugerencia

Puede descargar el código fuente para empezar con un proyecto terminado o seguir estos pasos para crear su propio código fuente.

Configuración del entorno de desarrollo local

Inicie Visual Studio Code en un nuevo directorio.

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

Cree un nuevo paquete para los módulos ESM en el directorio del proyecto.
```
npm init -y
npm pkg set type=module
```
Instale paquetes de desarrollo, incluidos azure-search-documents.
```
npm install @azure/identity @azure/search-documents dotenv
```
Instale paquetes de dependencias de desarrollo.
```
npm install dotenv @types/node --save-dev
```

Cree un archivo tsconfig.json en el directorio del proyecto para habilitar módulos ESM y establecer la resolución del módulo.

 {
   "compilerOptions": {
     "target": "es2022",
     "module": "esnext",
     "moduleResolution": "bundler",
     "rootDir": "./src",
     "outDir": "./dist/",
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "strict": true,
     "skipLibCheck": true,
     "declaration": true,
     "sourceMap": true,
     "resolveJsonModule": true,
     "moduleDetection": "force",
     "allowSyntheticDefaultImports": true,
     "verbatimModuleSyntax": false
   },
   "include": [
     "src/**/*.ts"
   ],
   "exclude": [
     "node_modules/**/*",
     "**/*.spec.ts"
   ]
 }

Actualice package.json para incluir un script para compilar archivos TypeScript. Agregue la siguiente línea a la scripts sección .
```
"build": "tsc"
```
Cree .env, y proporcione el punto de conexión del servicio de búsqueda. Puede obtener el punto de conexión desde Azure Portal en la página Información general del servicio de búsqueda.
```
AZURE_SEARCH_ENDPOINT=YOUR-SEARCH-SERVICE-ENDPOINT
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
SEMANTIC_CONFIGURATION_NAME=semantic-config
```
Cree un directorio src en el directorio del proyecto.
```
mkdir src
```

Si ha iniciado sesión en Azure Portal, ha iniciado sesión en Azure. Si no está seguro, use la CLI de Azure o Azure PowerShell para iniciar sesión: az login o az connect. Si tiene varios inquilinos y suscripciones, consulte Inicio rápido: Conexión sin claves para obtener ayuda sobre cómo conectarse.

Creación de un archivo de autenticación común

Cree un archivo en ./src llamado config.ts para leer el archivo .env y contener las variables de entorno y las credenciales de autenticación. Copie en el código siguiente; no lo cambies. Este archivo lo usarán todos los demás archivos de este inicio rápido.

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

// Configuration - use environment variables
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-index";
export const semanticConfigurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";

// Create credential
export const credential = new DefaultAzureCredential();

console.log(`Using Azure Search endpoint: ${searchEndpoint}`);
console.log(`Using index name: ${indexName}\n\n`);

// Hotel document interface
export interface HotelDocument {
    "@search.action"?: string;
    HotelId: string;
    HotelName: string;
    Description: string;
    Category: string;
    Tags: string[];
    ParkingIncluded: string;
    LastRenovationDate: string;
    Rating: number;
    Address: {
        StreetAddress: string;
        City: string;
        StateProvince: string;
        PostalCode: string;
        Country: string;
    };
}

Obtención del esquema de índice

En esta sección, obtendrá la configuración del índice existente hotels-sample-index en el servicio de búsqueda.

Cree un archivo en ./src llamado getIndexSettings.ts y copie en el código siguiente.

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

const indexClient = new SearchIndexClient(searchEndpoint, credential);

console.log('Updating semantic search index...');

// Get the existing schema
const index = await indexClient.getIndex(indexName);

console.log(`Index name: ${index.name}`);
console.log(`Number of fields: ${index.fields.length}`);

for(const field of index.fields) {

    // @ts-ignore
    console.log(`Field: ${field.name}, Type: ${field.type}, Searchable: ${field.searchable}`);
}

if(index.semanticSearch && index.semanticSearch.configurations) {
    console.log(`Semantic search configurations: ${index.semanticSearch.configurations.length}`);
    for(const config of index.semanticSearch.configurations) {
        console.log(`Configuration name: ${config.name}`);
        console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
    }
} else {
    console.log("No semantic configuration exists for this index.");
}

Ejecute el código.

npm run build && node -r dotenv/config dist/getIndexSettings.js

La salida es el nombre del índice, la lista de campos y una instrucción que indica si existe una configuración semántica. Para los fines de este inicio rápido, el mensaje debe indicar No semantic configuration exists for this index.

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

Cree un archivo en ./src llamado updateIndexSettings.ts y copie en el código siguiente para agregar una configuración semántica al índice existente hotels-sample-index en el servicio de búsqueda. Esta operación no elimina ningún documento de búsqueda y el índice sigue funcionando después de agregar la configuración.

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

try {

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

    // Add the new semantic configuration to the existing index
    if (existingIndex.semanticSearch && existingIndex.semanticSearch.configurations) {
        existingIndex.semanticSearch.configurations.push(newSemanticConfiguration);
    } else {
        const configExists = existingIndex.semanticSearch?.configurations?.some(
            config => config.name === semanticConfigurationName
        );
        if (!configExists) {
            existingIndex.semanticSearch = {
                configurations: [newSemanticConfiguration]
            };
        }
    }

    await indexClient.createOrUpdateIndex(existingIndex);

    const updatedIndex = await indexClient.getIndex(indexName);

    console.log(`Semantic configurations:`);
    console.log("-".repeat(40));

    if (updatedIndex.semanticSearch && updatedIndex.semanticSearch.configurations) {
        for (const config of updatedIndex.semanticSearch.configurations) {
            console.log(`Configuration name: ${config.name}`);
            console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
            console.log(`Keywords fields: ${config.prioritizedFields.keywordsFields?.map(f => f.name).join(", ")}`);
            console.log(`Content fields: ${config.prioritizedFields.contentFields?.map(f => f.name).join(", ")}`);
            console.log("-".repeat(40));
        }
    } else {
        console.log("No semantic configurations found.");
    }

    console.log("Semantic configuration updated successfully.");
} catch (error) {
    console.error("Error updating semantic configuration:", error);
}

Ejecute el código.

npm run build && node -r dotenv/config dist/updateIndexSettings.js

La salida es la configuración semántica que acaba de agregar, Semantic configuration updated successfully..

Ejecución de consultas semánticas

Una vez que el índice hotels-sample-index tiene una configuración semántica, puede ejecutar consultas que incluyan parámetros semánticos.

Cree un archivo en ./src llamado semanticQuery.ts y copie en el código siguiente para crear una consulta semántica del índice. Este es el requisito mínimo para invocar la clasificación semántica.

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"]
});

let rowNumber = 1;
for await (const result of results.results) {

    // Log each result
    const doc = result.document;
    const score = result.score;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelId: ${doc.HotelId}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);
}

Ejecute el código.

npm run build && node -r dotenv/config dist/semanticQuery.js

La salida debe constar de 13 documentos ordenados por el rerankerScoreDisplay.

Subtítulos devueltos

Opcionalmente, puede agregar subtítulos para extraer partes del texto y aplicar resaltado de aciertos a los términos y frases importantes. Esta consulta agrega subtítulos.

Cree un archivo en ./src llamado semanticQueryReturnCaptions.ts y copie en el código siguiente para agregar subtítulos a la consulta.

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

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

// Debug info
console.log(`Using semantic configuration: ${semanticConfigurationName}`);
console.log("Search query: walking distance to live music");

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

console.log(`Found ${results.count} results with semantic search\n`);
let rowNumber = 1;

for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);

    // Caption handling with better debugging
    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];

        if (caption.highlights) {
            console.log(`  Caption with highlights: ${caption.highlights}`);
        } else if (caption.text) {
            console.log(`  Caption text: ${caption.text}`);
        } else {
            console.log(`  Caption exists but has no text or highlights content`);
        }
    } else {
        console.log("  No captions found for this result");
    }
    console.log("-".repeat(60));
}

Ejecute el código.

npm run build && node -r dotenv/config dist/semanticQueryReturnCaptions.js

La salida debe incluir un nuevo elemento caption junto con el campo de búsqueda. Los títulos son los pasajes más relevantes en un resultado. Si el índice incluye fragmentos de texto más grandes, un título es útil para 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.

Devolver respuestas semánticas

En esta consulta final, se devuelven respuestas semánticas.

El clasificador semántico puede generar una respuesta a una cadena de consulta que tenga las características de una pregunta. La respuesta generada se extrae textualmente del contenido, por lo que no incluirá contenido compuesto como lo que podría esperar de un modelo de finalización de chat. Si la respuesta semántica no es útil para su escenario, puede omitirlo semantic_answers del código.

Para generar una respuesta semántica, la pregunta y la respuesta deben estar estrechamente alineadas y el modelo debe encontrar contenido que responda claramente a la pregunta. Si las posibles respuestas no alcanzan el umbral de confianza, el modelo no devuelve una respuesta. Para fines de demostración, la pregunta de este ejemplo está diseñada para obtener una respuesta que le permita ver la sintaxis.

Cree un archivo en ./src llamado semanticAnswer.ts y copie en el código siguiente para obtener respuestas semánticas.

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

console.log(`Answers:\n\n`);
let rowNumber = 1; 

// Extract semantic answers from the search results
const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    console.log(`Semantic answer result #${rowNumber++}:`);
    if (answer.highlights) {
        console.log(`Semantic Answer: ${answer.highlights}`);
    } else {
        console.log(`Semantic Answer: ${answer.text}`);
    }
    console.log(`Semantic Answer Score: ${answer.score}\n\n`);
}

console.log(`Search Results:\n\n`);
rowNumber = 1;

// Iterate through the search results
for await (const result of results.results) {


    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;
    console.log(`Search result #${rowNumber++}:`);
    console.log(`${rerankerScoreDisplay}`);
    console.log(`${doc.HotelName}`);
    console.log(`${doc.Description || 'N/A'}`);

    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(`Caption: ${caption.highlights}\n`);
        } else {
            console.log(`Caption: ${caption.text}\n`);
        }
    }
}

Ejecute el código.

npm run build && node -r dotenv/config dist/semanticAnswer.js

La salida debe ser similar al ejemplo siguiente, donde se extrae la mejor respuesta a la pregunta de uno de los resultados.

Recuerde que las respuestas son contenido textual extraído del índice y podrían faltar frases que un usuario esperaría ver. Para obtener respuestas compuestas generadas por un modelo de finalización de chat, considere la posibilidad de usar un patrón RAG o una recuperación mediante agente.
```
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 library 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
```

Compartir a través de

Requisitos previos

Configurar el acceso

Empezar con un índice

Configuración del cliente

Instalación de bibliotecas

Inicio de sesión en Azure

Actualización del índice

Ejecución de consultas semánticas

Salida para la consulta semántica (sin subtítulos ni respuestas)

Salida de una consulta semántica con subtítulos

Salida para respuestas semánticas

Requisitos previos

Configurar el acceso

Empezar con un índice

Configuración del cliente

Configuración del entorno de desarrollo local

Inicio de sesión en Azure

Creación de un archivo de autenticación común

Obtención del esquema de índice

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

Ejecución de consultas semánticas

Subtítulos devueltos

Devolver respuestas semánticas

Requisitos previos

Configurar el acceso

Empezar con un índice

Configuración del cliente

Configuración del entorno de desarrollo local

Inicio de sesión en Azure

Creación de una clase de configuración común

Obtención del esquema de índice

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

Ejecución de consultas semánticas

Subtítulos devueltos

Devolver respuestas semánticas

Requisitos previos

Configurar el acceso

Empezar con un índice

Configuración del cliente

Instalación de paquetes y establecimiento de variables de entorno

Inicio de sesión en Azure

Actualización del índice

Ejecución de consultas semánticas

Subtítulos devueltos

Devolver respuestas semánticas

Requisitos previos

Configurar el acceso

Empezar con un índice

Configuración del cliente

Actualización del índice

Ejecución de consultas semánticas

Subtítulos devueltos

Devolver respuestas semánticas

Requisitos previos

Configurar el acceso

Empezar con un índice

Configuración del cliente

Configuración del entorno de desarrollo local

Inicio de sesión en Azure

Creación de un archivo de autenticación común

Obtención del esquema de índice

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

Ejecución de consultas semánticas

Subtítulos devueltos

Devolver respuestas semánticas

Limpieza de recursos

Contenido relacionado

Comentarios

Recursos adicionales