Compartir a través de

Inicio rápido: Búsqueda de vectores

En este inicio rápido, usará la biblioteca cliente Búsqueda de Azure AI para .NET para crear, cargar y consultar un índice vector. La biblioteca cliente de .NET proporciona una abstracción sobre las API REST para las operaciones de índice.

En Búsqueda de Azure AI, un índice vectorial tiene un esquema de índice que define los campos vector y nonvector, una configuración de búsqueda de vectores para algoritmos que crean el espacio de inserción y la configuración en las definiciones de campo vectorial que se evalúan en el momento de la consulta. Índices: crear o actualizar (API REST) crea el índice vectorial.

Sugerencia

  • ¿Quieres empezar de inmediato? Descargue el código source en GitHub.
  • En este inicio rápido se omite el paso de vectorización y se proporcionan instrucciones insertadas. Para la vectorización integrada en su propio contenido, pruebe el Asistente para la importación de datos (nuevo).

Requisitos previos

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

  • Un servicio Búsqueda de Azure AI. Puede usar el nivel Gratis para la mayoría de estos inicios rápidos, pero se recomienda Básico o superior para archivos de datos más grandes.

  • Clasificador semántico habilitado en el servicio de búsqueda para la consulta híbrida semántica opcional.

  • .NET 8 o posterior.

  • Visual Studio Code.

  • Git para clonar el repositorio de ejemplo.

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

Configurar el acceso

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

Para configurar el acceso basado en rol recomendado:

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

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

    • Colaborador del servicio Search

    • Colaborador de datos de índice de búsqueda

    • Lector de datos de índice de búsqueda

Obtención del punto de conexión

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

Para obtener el punto de conexión:

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

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

  3. Anote el punto de conexión, que debería tener un aspecto similar a .

Configuración del entorno

  1. Use Git para clonar el repositorio de ejemplo.

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

  2. Dirígete a la carpeta quickstart y ábrela en Visual Studio Code.

    cd azure-search-dotnet-samples/quickstart-vector-search
code .

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

  4. Repita el paso anterior para .

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

    az login

Ejecución del código

  1. Ejecute el primer proyecto para crear y rellenar el índice.

    cd VectorSearchCreatePopulateIndex
dotnet run

  2. En , descomente los métodos de consulta que desea ejecutar.

  3. Ejecute el segundo proyecto para ejecutar esas consultas en el índice.

    cd ..\VectorSearchExamples
dotnet run

Salida

La salida del primer proyecto incluye la confirmación de la creación de índices y las subidas de documentos exitosas.

Creating or updating index 'hotels-vector-quickstart'...
Index 'hotels-vector-quickstart' updated.

Key: 1, Succeeded: True
Key: 2, Succeeded: True
Key: 3, Succeeded: True
Key: 4, Succeeded: True
Key: 48, Succeeded: True
Key: 49, Succeeded: True
Key: 13, Succeeded: True

La salida del segundo proyecto muestra los resultados de búsqueda de cada método de consulta habilitado. En el ejemplo siguiente se muestran los resultados de búsqueda de vectores únicos.

Single Vector Search Results:
Score: 0.6605852, HotelId: 48, HotelName: Nordick's Valley Motel
Score: 0.6333684, HotelId: 13, HotelName: Luxury Lion Resort
Score: 0.605672, HotelId: 4, HotelName: Sublime Palace Hotel
Score: 0.6026341, HotelId: 49, HotelName: Swirling Currents Hotel
Score: 0.57902366, HotelId: 2, HotelName: Old Century Hotel

Descripción del código

Nota

Es posible que los fragmentos de código de esta sección se hayan modificado para mejorar la legibilidad. Para obtener un ejemplo de trabajo completo, consulte el código fuente.

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

  1. Crear un índice vectorial
  2. Carga de documentos en el índice
  3. Consulta del índice

Crear un índice vectorial

Antes de agregar contenido a Búsqueda de Azure AI, debe crear un índice para definir cómo se almacena y estructura el contenido.

El esquema de índice se organiza en torno al contenido del hotel. Los datos de muestra constan de descripciones vectoriales y no vectoriales de hoteles ficticios. El código siguiente de crea el esquema de índice, incluido el campo vectorial .

static async Task CreateSearchIndex(string indexName, SearchIndexClient indexClient)
{
    var addressField = new ComplexField("Address");
    addressField.Fields.Add(new SearchableField("StreetAddress") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft });
    addressField.Fields.Add(new SearchableField("City") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });
    addressField.Fields.Add(new SearchableField("StateProvince") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });
    addressField.Fields.Add(new SearchableField("PostalCode") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });
    addressField.Fields.Add(new SearchableField("Country") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });

    var allFields = new List<SearchField>()
    {
        new SimpleField("HotelId", SearchFieldDataType.String) { IsKey = true, IsFacetable = true, IsFilterable = true },
        new SearchableField("HotelName") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft },
        new SearchableField("Description") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft },
        new VectorSearchField("DescriptionVector", 1536, "my-vector-profile"),
        new SearchableField("Category") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true },
        new SearchableField("Tags", collection: true) { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true },
        new SimpleField("ParkingIncluded", SearchFieldDataType.Boolean) { IsFacetable = true, IsFilterable = true },
        new SimpleField("LastRenovationDate", SearchFieldDataType.DateTimeOffset) { IsSortable = true },
        new SimpleField("Rating", SearchFieldDataType.Double) { IsFacetable = true, IsFilterable = true, IsSortable = true },
        addressField,
        new SimpleField("Location", SearchFieldDataType.GeographyPoint) { IsFilterable = true, IsSortable = true },
    };

    // Create the suggester configuration
    var suggester = new SearchSuggester("sg", new[] { "Address/City", "Address/Country" });

    // Create the semantic search
    var semanticSearch = new SemanticSearch()
    {
        Configurations =
        {
            new SemanticConfiguration(
                name: "semantic-config",
                prioritizedFields: new SemanticPrioritizedFields
                {
                    TitleField = new SemanticField("HotelName"),
                    KeywordsFields = { new SemanticField("Category") },
                    ContentFields = { new SemanticField("Description") }
                })
        }
    };

    // Add vector search configuration
    var vectorSearch = new VectorSearch();
    vectorSearch.Algorithms.Add(new HnswAlgorithmConfiguration(name: "my-hnsw-vector-config-1"));
    vectorSearch.Profiles.Add(new VectorSearchProfile(name: "my-vector-profile", algorithmConfigurationName: "my-hnsw-vector-config-1"));

    var definition = new SearchIndex(indexName)
    {
        Fields = allFields,
        Suggesters = { suggester },
        VectorSearch = vectorSearch,
        SemanticSearch = semanticSearch
    };

    // Create or update the index
    Console.WriteLine($"Creating or updating index '{indexName}'...");
    var result = await indexClient.CreateOrUpdateIndexAsync(definition);
    Console.WriteLine($"Index '{result.Value.Name}' updated.");
    Console.WriteLine();
}

Puntos clave:

  • Para definir un índice, cree una lista de campos.

  • Este índice concreto admite varias funcionalidades de búsqueda:

    • Búsqueda de texto completo ()

    • Búsqueda de vectores ()

    • Clasificación semántica ()

    • Búsqueda por facetas (campos marcados con )

    • Búsqueda geoespacial ( campo con )

    • Filtrado y ordenación (campos marcados con y )

  • El segundo parámetro de especifica , que debe coincidir con el tamaño de salida del modelo de inserción. En este inicio rápido se usan 1536 dimensiones para coincidir con el modelo .

  • La configuración define el algoritmo de vecino más cercano aproximado (ANN). Los algoritmos compatibles incluyen Hierarchical Navigable Small World (HNSW) y k vecinos más cercanos (KNN). Para obtener más información, vea Relevancia en la búsqueda de vectores.

Cargar documentos en el índice

Los índices recién creados están vacíos. Para rellenar un índice y hacer que se pueda realizar búsquedas, debe cargar documentos JSON que se ajusten al esquema de índice.

En Búsqueda de Azure AI, los documentos actúan como entradas para la indexación y las salidas de las consultas. Para simplificar, esta guía de inicio rápido proporciona documentos de hotel de ejemplo con vectores predefinidos. En escenarios de producción, el contenido se extrae a menudo de orígenes de datos conectados y se transforma en JSON mediante indexadores.

El código siguiente carga documentos desde en el servicio de búsqueda.

static async Task UploadDocs(SearchClient searchClient)
{
    var jsonPath = Path.Combine(Directory.GetCurrentDirectory(), "HotelData.json");

    // Read and parse hotel data
    var json = await File.ReadAllTextAsync(jsonPath);
    List<Hotel> hotels = new List<Hotel>();
    try
    {
        using var doc = JsonDocument.Parse(json);
        if (doc.RootElement.ValueKind != JsonValueKind.Array)
        {
            Console.WriteLine("HotelData.json root is not a JSON array.");
        }
        // Deserialize all hotel objects
        hotels = doc.RootElement.EnumerateArray()
            .Select(e => JsonSerializer.Deserialize<Hotel>(e.GetRawText()))
            .Where(h => h != null)
            .ToList();
    }
    catch (JsonException ex)
    {
        Console.WriteLine($"Failed to parse HotelData.json: {ex.Message}");
    }

    try
    {
        // Upload hotel documents to Azure Search
        var result = await searchClient.UploadDocumentsAsync(hotels);
        foreach (var r in result.Value.Results)
        {
            Console.WriteLine($"Key: {r.Key}, Succeeded: {r.Succeeded}");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Failed to upload documents: " + ex);
    }
}

El código interactúa con un índice de búsqueda específico hospedado en el servicio de Búsqueda de Azure AI a través del SearchClient, que es el objeto principal proporcionado por el paquete de Azure.Search.Documents. proporciona acceso a las operaciones de índice, como:

  • Ingesta de datos: , ,

  • Operaciones de búsqueda: , ,

Consultas al índice

Las consultas de muestran diferentes patrones de búsqueda. Las consultas vectoriales de ejemplo se basan en dos cadenas:

  • Cadena de búsqueda de texto completo:

  • Cadena de consulta vectorial: (vectorizada en una representación matemática)

La cadena de consulta vectorial es semánticamente similar a la cadena de búsqueda de texto completo, pero incluye términos que no existen en el índice. Una búsqueda de solo palabra clave para la cadena de consulta vectorial devuelve cero resultados. Sin embargo, la búsqueda de vectores busca coincidencias relevantes en función del significado en lugar de las palabras clave exactas.

Los ejemplos siguientes comienzan con una consulta vectorial básica y agregan progresivamente filtros, búsqueda de palabras clave y reranking semántico.

El método muestra un escenario básico en el que desea buscar descripciones de documentos que coincidan estrechamente con la cadena de consulta vectorial. configura la búsqueda vectorial:

  • limita el número de resultados que se devuelven en función de la similitud de vectores.
  • especifica el campo vectorial en el que se va a buscar.
public static async Task SearchSingleVector(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" },
        });

    Console.WriteLine($"Single Vector Search Results:");
    await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}, HotelId: {doc.HotelId}, HotelName: {doc.HotelName}");
    }
    Console.WriteLine();
}

Búsqueda de un solo vector con un filtro

En Búsqueda de Azure AI, filters se aplican a campos no vectores de un índice. El método filtra en el campo para filtrar los hoteles que no proporcionan conexión Wi-Fi gratuita.

public static async Task SearchSingleVectorWithFilter(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithFilter = await searchClient.SearchAsync<Hotel>(
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Filter = "Tags/any(tag: tag eq 'free wifi')",
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" }
        });

    Console.WriteLine($"Single Vector Search With Filter Results:");
    await foreach (SearchResult<Hotel> result in responseWithFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}, HotelId: {doc.HotelId}, HotelName: {doc.HotelName}, Tags: {string.Join(String.Empty, doc.Tags)}");
    }
    Console.WriteLine();
}

Búsqueda de un solo vector con un filtro geográfico

Puede especificar un filtro geoespacial para limitar los resultados a un área geográfica específica. El método especifica un punto geográfico (Washington D.C., utilizando coordenadas de longitud y latitud) y devuelve hoteles dentro de 300 kilómetros. De forma predeterminada, los filtros se ejecutan después de la búsqueda vectorial.

public static async Task SingleSearchWithGeoFilter(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithGeoFilter = await searchClient.SearchAsync<Hotel>(
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Filter = "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
            Select = { "HotelId", "HotelName", "Description", "Address", "Category", "Tags" },
            Facets = { "Address/StateProvince" },
        });

    Console.WriteLine($"Vector query with a geo filter:");
    await foreach (SearchResult<Hotel> result in responseWithGeoFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"HotelId: {doc.HotelId}");
        Console.WriteLine($"HotelName: {doc.HotelName}");
        Console.WriteLine($"Score: {result.Score}");
        Console.WriteLine($"City/State: {doc.Address.City}/{doc.Address.StateProvince}");
        Console.WriteLine($"Description: {doc.Description}");
        Console.WriteLine();
    }
    Console.WriteLine();
}

La búsqueda híbrida combina consultas de texto completo y vectores en una sola solicitud. El método ejecuta ambos tipos de consulta simultáneamente y, a continuación, usa la Fusión de Clasificación Recíproca (RRF) para combinar los resultados en una clasificación unificada. RRF usa el inverso de las clasificaciones de resultados de cada conjunto de resultados para generar una clasificación combinada. Observe que las puntuaciones de búsqueda híbrida son uniformemente más pequeñas que las puntuaciones de consulta única.

public static async Task<SearchResults<Hotel>> SearchHybridVectorAndText(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithFilter = await searchClient.SearchAsync<Hotel>(
        "historic hotel walk to restaurants and shopping",
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" },
            Size = 5,
        });

    Console.WriteLine($"Hybrid search results:");
    await foreach (SearchResult<Hotel> result in responseWithFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}");
        Console.WriteLine($"HotelId: {doc.HotelId}");
        Console.WriteLine($"HotelName: {doc.HotelName}");
        Console.WriteLine($"Description: {doc.Description}");
        Console.WriteLine($"Category: {doc.Category}");
        Console.WriteLine($"Tags: {string.Join(String.Empty, doc.Tags)}");
        Console.WriteLine();
    }
    Console.WriteLine();
    return responseWithFilter;
}

El método demuestra la clasificación semántica, que reordena los resultados en función de la comprensión del lenguaje.

public static async Task SearchHybridVectorAndSemantic(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithFilter = await searchClient.SearchAsync<Hotel>(
        "historic hotel walk to restaurants and shopping",
        new SearchOptions
        {
            IncludeTotalCount = true,
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" },
            SemanticSearch = new SemanticSearchOptions
            {
                SemanticConfigurationName = "semantic-config"
            },
            QueryType = SearchQueryType.Semantic,
            Size = 5
        });

    Console.WriteLine($"Hybrid search results:");
    await foreach (SearchResult<Hotel> result in responseWithFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}");
        Console.WriteLine($"HotelId: {doc.HotelId}");
        Console.WriteLine($"HotelName: {doc.HotelName}");
        Console.WriteLine($"Description: {doc.Description}");
        Console.WriteLine($"Category: {doc.Category}");
        Console.WriteLine();
    }
    Console.WriteLine();
}

Compare estos resultados con los resultados de la búsqueda híbrida de la consulta anterior. Sin reajuste semántico, Sublime Palace Hotel ocupa el primer lugar porque la Fusión de Clasificación Recíproca (RRF) combina las puntuaciones de texto y vector para generar un resultado combinado. Después de la reordenación semántica, Swirling Currents Hotel se mueve al primer puesto.

El clasificador semántico usa modelos de comprensión automática para evaluar el grado de coincidencia de cada resultado con la intención de la consulta. La descripción de Swirling Currents Hotel menciona , que se alinea estrechamente con la consulta de búsqueda de . La coincidencia semántica con los restaurantes y compras cercanos lo eleva por encima del Sublime Palace Hotel, que no destaca las comodidades accesibles a pie en su descripción.

Puntos clave:

  • En una búsqueda híbrida, puede integrar el vector de búsqueda con búsqueda de texto completo sobre palabras clave. Los filtros y la clasificación semántica solo se aplican al contenido textual, no a los vectores.

  • Entre los resultados reales se incluyen más detalles, incluidos los títulos semánticos y los resaltados. En este inicio rápido se modifican los resultados para mejorar la legibilidad. Para obtener la estructura completa de la respuesta, use REST para ejecutar la solicitud.

Limpieza de recursos

Cuando trabaja en su propia suscripción, es una buena idea finalizar un proyecto quitando los recursos que ya no necesita. Los recursos que quedan en ejecución pueden costar dinero.

En el portal de Azure, seleccione Todos los recursos o Grupos de recursos en el panel izquierdo para buscar y administrar recursos. Puede eliminar recursos individualmente o eliminar el grupo de recursos para quitar todos los recursos a la vez.

En este inicio rápido, usará la biblioteca cliente Búsqueda de Azure AI para Java para crear, cargar y consultar un índice vector. La biblioteca cliente de Java proporciona una abstracción sobre las API REST para las operaciones de índice.

En Búsqueda de Azure AI, un índice vectorial tiene un esquema de índice que define los campos vector y nonvector, una configuración de búsqueda de vectores para algoritmos que crean el espacio de inserción y la configuración en las definiciones de campo vectorial que se evalúan en el momento de la consulta. Índices: crear o actualizar (API REST) crea el índice vectorial.

Sugerencia

  • ¿Quieres empezar de inmediato? Descargue el código source en GitHub.
  • En este inicio rápido se omite el paso de vectorización y se proporcionan instrucciones insertadas. Para la vectorización integrada en su propio contenido, pruebe el Asistente para la importación de datos (nuevo).

Requisitos previos

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

  • Un servicio Búsqueda de Azure AI. Puede usar el nivel Gratis para la mayoría de estos inicios rápidos, pero se recomienda Básico o superior para archivos de datos más grandes.

  • Clasificador semántico habilitado en el servicio de búsqueda para la consulta híbrida semántica opcional.

  • Java 21 (LTS) y Maven.

  • Visual Studio Code.

  • Git para clonar el repositorio de ejemplo.

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

Configurar el acceso

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

Para configurar el acceso basado en rol recomendado:

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

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

    • Colaborador del servicio Search

    • Colaborador de datos de índice de búsqueda

    • Lector de datos de índice de búsqueda

Obtención del punto de conexión

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

Para obtener el punto de conexión:

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

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

  3. Anote el punto de conexión, que debería tener un aspecto similar a .

Configuración del entorno

  1. Use Git para clonar el repositorio de ejemplo.

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

  2. Dirígete a la carpeta quickstart y ábrela en Visual Studio Code.

    cd azure-search-java-samples/quickstart-vector-search
code .

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

  4. Instale las dependencias.

    mvn clean dependency:copy-dependencies

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

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

    az login

Ejecución del código

  1. Cree un índice vectorial.

    mvn compile exec:java "-Dexec.mainClass=com.example.search.CreateIndex"

  2. Cargue documentos que contengan inserciones precalculadas.

    mvn compile exec:java "-Dexec.mainClass=com.example.search.UploadDocuments"

  3. Ejecute una consulta de búsqueda vectorial.

    mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSingle"

  4. (Opcional) Ejecute variaciones de consulta adicionales.

    mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSingleWithFilter"
mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSingleWithFilterGeo"
mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchHybrid"
mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSemanticHybrid"

Salida

La salida de muestra el nombre del índice y la confirmación.

Using Azure Search endpoint: https://<search-service-name>.search.windows.net
Using Azure Search index: hotels-vector-quickstart
Creating index...
hotels-vector-quickstart created

La salida de muestra el estado de éxito de cada documento indexado.

Uploading documents...
Key: 1, Succeeded: true, ErrorMessage: none
Key: 2, Succeeded: true, ErrorMessage: none
Key: 3, Succeeded: true, ErrorMessage: none
Key: 4, Succeeded: true, ErrorMessage: none
Key: 48, Succeeded: true, ErrorMessage: none
Key: 49, Succeeded: true, ErrorMessage: none
Key: 13, Succeeded: true, ErrorMessage: none
Waiting for indexing... Current count: 0
All documents indexed successfully.

La salida de muestra los resultados de la búsqueda vectorial clasificados por puntuación de similitud.

Single Vector search found 5
- HotelId: 48, HotelName: Nordick's Valley Motel, Tags: ["continental breakfast","air conditioning","free wifi"], Score 0.6605852
- HotelId: 13, HotelName: Luxury Lion Resort, Tags: ["bar","concierge","restaurant"], Score 0.6333684
- HotelId: 4, HotelName: Sublime Palace Hotel, Tags: ["concierge","view","air conditioning"], Score 0.605672
- HotelId: 49, HotelName: Swirling Currents Hotel, Tags: ["air conditioning","laundry service","24-hour front desk service"], Score 0.6026341
- HotelId: 2, HotelName: Old Century Hotel, Tags: ["pool","free wifi","air conditioning","concierge"], Score 0.57902366

Descripción del código

Nota

Es posible que los fragmentos de código de esta sección se hayan modificado para mejorar la legibilidad. Para obtener un ejemplo de trabajo completo, consulte el código fuente.

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

  1. Crear un índice vectorial
  2. Carga de documentos en el índice
  3. Consulta del índice

Crear un índice vectorial

Antes de agregar contenido a Búsqueda de Azure AI, debe crear un índice para definir cómo se almacena y estructura el contenido.

El esquema de índice se organiza en torno al contenido del hotel. Los datos de muestra constan de descripciones vectoriales y no vectoriales de hoteles ficticios. El código siguiente de crea el esquema de índice, incluido el campo vectorial .

// Define fields
List<SearchField> fields = Arrays.asList(
    new SearchField("HotelId", SearchFieldDataType.STRING)
        .setKey(true)
        .setFilterable(true),
    new SearchField("HotelName", SearchFieldDataType.STRING)
        .setSortable(true)
        .setSearchable(true),
    new SearchField("Description", SearchFieldDataType.STRING)
        .setSearchable(true),
    new SearchField("DescriptionVector",
        SearchFieldDataType.collection(SearchFieldDataType.SINGLE))
        .setSearchable(true)
        .setVectorSearchDimensions(1536)
        .setVectorSearchProfileName("my-vector-profile"),
    new SearchField("Category", SearchFieldDataType.STRING)
        .setSortable(true)
        .setFilterable(true)
        .setFacetable(true)
        .setSearchable(true),
    new SearchField("Tags", SearchFieldDataType.collection(
        SearchFieldDataType.STRING))
        .setSearchable(true)
        .setFilterable(true)
        .setFacetable(true),
    // Additional fields: ParkingIncluded, LastRenovationDate, Rating, Address, Location
);

var searchIndex = new SearchIndex(indexName, fields);

// Define vector search configuration
var hnswParams = new HnswParameters()
    .setM(16)
    .setEfConstruction(200)
    .setEfSearch(128);
var hnsw = new HnswAlgorithmConfiguration("hnsw-vector-config");
hnsw.setParameters(hnswParams);

var vectorProfile = new VectorSearchProfile(
    "my-vector-profile",
    "hnsw-vector-config");
var vectorSearch = new VectorSearch()
    .setAlgorithms(Arrays.asList(hnsw))
    .setProfiles(Arrays.asList(vectorProfile));
searchIndex.setVectorSearch(vectorSearch);

// Define semantic configuration
var prioritizedFields = new SemanticPrioritizedFields()
    .setTitleField(new SemanticField("HotelName"))
    .setContentFields(Arrays.asList(new SemanticField("Description")))
    .setKeywordsFields(Arrays.asList(new SemanticField("Category")));
var semanticConfig = new SemanticConfiguration(
    "semantic-config",
    prioritizedFields);
var semanticSearch = new SemanticSearch()
    .setConfigurations(Arrays.asList(semanticConfig));
searchIndex.setSemanticSearch(semanticSearch);

// Define suggesters
var suggester = new SearchSuggester("sg", Arrays.asList("HotelName"));
searchIndex.setSuggesters(Arrays.asList(suggester));

// Create the search index
SearchIndex result = searchIndexClient.createOrUpdateIndex(searchIndex);

Puntos clave:

  • Para definir un índice, cree una lista de campos.

  • Este índice concreto admite varias funcionalidades de búsqueda:

    • Búsqueda de texto completo ()

    • Búsqueda vectorial ( con )

    • Clasificación semántica ()

    • Búsqueda por facetas (campos marcados con )

    • Búsqueda geoespacial ( campo con )

    • Filtrado y ordenación (campos marcados con y )

  • El valor debe coincidir con el tamaño de salida del modelo de inserción. En este inicio rápido se usan 1536 dimensiones para coincidir con el modelo .

  • La configuración define el algoritmo de vecino más cercano aproximado (ANN). Los algoritmos compatibles incluyen Hierarchical Navigable Small World (HNSW) y k vecinos más cercanos (KNN). Para obtener más información, vea Relevancia en la búsqueda de vectores.

Cargar documentos en el índice

Los índices recién creados están vacíos. Para rellenar un índice y hacer que se pueda realizar búsquedas, debe cargar documentos JSON que se ajusten al esquema de índice.

En Búsqueda de Azure AI, los documentos actúan como entradas para la indexación y las salidas de las consultas. Para simplificar, esta guía de inicio rápido proporciona documentos de hotel de ejemplo con vectores predefinidos. En escenarios de producción, el contenido se extrae a menudo de orígenes de datos conectados y se transforma en JSON mediante indexadores.

El código siguiente de carga documentos en el servicio de búsqueda.

// Documents contain hotel data with 1536-dimension vectors for DescriptionVector
static final List<Map<String, Object>> DOCUMENTS = Arrays.asList(
    new HashMap<>() {{
        put("@search.action", "mergeOrUpload");
        put("HotelId", "1");
        put("HotelName", "Stay-Kay City Hotel");
        put("Description", "This classic hotel is fully-refurbished...");
        put("DescriptionVector", Arrays.asList(/* 1536 float values */));
        put("Category", "Boutique");
        put("Tags", Arrays.asList("view", "air conditioning", "concierge"));
        // Additional fields...
    }}
    // Additional hotel documents
);

// Upload documents to the index
IndexDocumentsResult result = searchClient.uploadDocuments(DOCUMENTS);
for (IndexingResult r : result.getResults()) {
    System.out.println("Key: %s, Succeeded: %s".formatted(r.getKey(), r.isSucceeded()));
}

El código interactúa con un índice de búsqueda específico hospedado en el servicio de Búsqueda de Azure AI a través del SearchClient, que es el objeto principal proporcionado por el paquete de azure-search-documents. proporciona acceso a operaciones como:

  • Ingesta de datos: , ,

  • Operaciones de búsqueda: , ,

Consultas al índice

Las consultas de los archivos de búsqueda muestran diferentes patrones de búsqueda. Las consultas vectoriales de ejemplo se basan en dos cadenas:

  • Cadena de búsqueda de texto completo:

  • Cadena de consulta vectorial: (vectorizada en una representación matemática)

La cadena de consulta vectorial es semánticamente similar a la cadena de búsqueda de texto completo, pero incluye términos que no existen en el índice. Una búsqueda de solo palabra clave para la cadena de consulta vectorial devuelve cero resultados. Sin embargo, la búsqueda de vectores busca coincidencias relevantes en función del significado en lugar de las palabras clave exactas.

Los ejemplos siguientes comienzan con una consulta vectorial básica y agregan progresivamente filtros, búsqueda de palabras clave y reranking semántico.

muestra un escenario básico en el que desea buscar descripciones de documentos que coincidan estrechamente con la cadena de consulta vectorial. configura la búsqueda vectorial:

  • limita el número de resultados que se devuelven en función de la similitud de vectores.
  • especifica el campo vectorial en el que se va a buscar.
var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

var searchOptions = new SearchOptions()
    .setTop(7)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Description", "Category", "Tags")
    .setVectorSearchOptions(vectorSearchOptions);

var results = searchClient.search("*", searchOptions, Context.NONE);

for (SearchResult result : results) {
    SearchDocument document = result.getDocument(SearchDocument.class);
    System.out.println("HotelId: %s, HotelName: %s, Score: %s".formatted(
        document.get("HotelId"), document.get("HotelName"), result.getScore()));
}

Búsqueda de un solo vector con un filtro

En Búsqueda de Azure AI, filters se aplican a campos no vectores de un índice. filtra en el campo para filtrar los hoteles que no proporcionan conexión Wi-Fi gratuita.

var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

// Add filter for "free wifi" tag
var searchOptions = new SearchOptions()
    .setTop(7)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Description", "Category", "Tags")
    .setFilter("Tags/any(tag: tag eq 'free wifi')")
    .setVectorSearchOptions(vectorSearchOptions);

var results = searchClient.search("*", searchOptions, Context.NONE);

Búsqueda de un solo vector con un filtro geográfico

Puede especificar un filtro geoespacial para limitar los resultados a un área geográfica específica. especifica un punto geográfico (Washington D.C., utilizando coordenadas de longitud y latitud) y devuelve hoteles dentro de 300 kilómetros. El método, al que se llama en , determina cuándo se ejecuta el filtro. En este caso, ejecuta el filtro después de la búsqueda vectorial.

var searchOptions = new SearchOptions()
    .setTop(5)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Category", "Description",
               "Address/City", "Address/StateProvince")
    .setFacets("Address/StateProvince")
    .setFilter("geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300")
    .setVectorSearchOptions(vectorSearchOptions);

La búsqueda híbrida combina consultas de texto completo y vectores en una sola solicitud. ejecuta ambos tipos de consulta simultáneamente y, a continuación, usa La fusión de clasificación recíproca (RRF) para combinar los resultados en una clasificación unificada. RRF usa el inverso de las clasificaciones de resultados de cada conjunto de resultados para generar una clasificación combinada. Observe que las puntuaciones de búsqueda híbrida son uniformemente más pequeñas que las puntuaciones de consulta única.

var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

var searchOptions = new SearchOptions()
    .setTop(5)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Description", "Category", "Tags")
    .setVectorSearchOptions(vectorSearchOptions);

// Pass both text query and vector search options
var results = searchClient.search(
    "historic hotel walk to restaurants and shopping",
    searchOptions, Context.NONE);

muestra la clasificación semántica, que vuelve a clasificar los resultados en función del reconocimiento del lenguaje.

var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

SemanticSearchOptions semanticSearchOptions = new SemanticSearchOptions()
    .setSemanticConfigurationName("semantic-config");

var searchOptions = new SearchOptions()
    .setTop(5)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Category", "Description")
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(semanticSearchOptions)
    .setVectorSearchOptions(vectorSearchOptions);

var results = searchClient.search(
    "historic hotel walk to restaurants and shopping",
    searchOptions, Context.NONE);

Compare estos resultados con los resultados de la búsqueda híbrida de la consulta anterior. Sin reajuste semántico, Sublime Palace Hotel ocupa el primer lugar porque la Fusión de Clasificación Recíproca (RRF) combina las puntuaciones de texto y vector para generar un resultado combinado. Después de la reordenación semántica, Swirling Currents Hotel se mueve al primer puesto.

El clasificador semántico usa modelos de comprensión automática para evaluar el grado de coincidencia de cada resultado con la intención de la consulta. La descripción de Swirling Currents Hotel menciona , que se alinea estrechamente con la consulta de búsqueda de . La coincidencia semántica con los restaurantes y compras cercanos lo eleva por encima del Sublime Palace Hotel, que no destaca las comodidades accesibles a pie en su descripción.

Puntos clave:

  • En una búsqueda híbrida, puede integrar el vector de búsqueda con búsqueda de texto completo sobre palabras clave. Los filtros y la clasificación semántica solo se aplican al contenido textual, no a los vectores.

  • Entre los resultados reales se incluyen más detalles, incluidos los títulos semánticos y los resaltados. En este inicio rápido se modifican los resultados para mejorar la legibilidad. Para obtener la estructura completa de la respuesta, use REST para ejecutar la solicitud.

Limpieza de recursos

Cuando trabaja en su propia suscripción, es una buena idea finalizar un proyecto quitando los recursos que ya no necesita. Los recursos que quedan en ejecución pueden costar dinero.

En el portal de Azure, seleccione Todos los recursos o Grupos de recursos en el panel izquierdo para buscar y administrar recursos. Puede eliminar recursos individualmente o eliminar el grupo de recursos para quitar todos los recursos a la vez.

De lo contrario, ejecute el siguiente comando para eliminar el índice que creó en este inicio rápido.

mvn compile exec:java "-Dexec.mainClass=com.example.search.DeleteIndex"

En este inicio rápido, usará la biblioteca cliente Búsqueda de Azure AI para JavaScript para crear, cargar y consultar un índice de vector. La biblioteca cliente de JavaScript proporciona una abstracción sobre las API REST para las operaciones de índice.

En Búsqueda de Azure AI, un índice vectorial tiene un esquema de índice que define los campos vector y nonvector, una configuración de búsqueda de vectores para algoritmos que crean el espacio de inserción y la configuración en las definiciones de campo vectorial que se evalúan en el momento de la consulta. Índices: crear o actualizar (API REST) crea el índice vectorial.

Sugerencia

  • ¿Quieres empezar de inmediato? Descargue el código source en GitHub.
  • En este inicio rápido se omite el paso de vectorización y se proporcionan instrucciones insertadas. Para la vectorización integrada en su propio contenido, pruebe el Asistente para la importación de datos (nuevo).

Requisitos previos

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

  • Un servicio Búsqueda de Azure AI. Puede usar el nivel Gratis para la mayoría de estos inicios rápidos, pero se recomienda Básico o superior para archivos de datos más grandes.

  • Clasificador semántico habilitado en el servicio de búsqueda para la consulta híbrida semántica opcional.

  • Node.js 20 LTS o posterior.

  • Visual Studio Code.

  • Git para clonar el repositorio de ejemplo.

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

Configurar el acceso

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

Para configurar el acceso basado en rol recomendado:

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

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

    • Colaborador del servicio Search

    • Colaborador de datos de índice de búsqueda

    • Lector de datos de índice de búsqueda

Obtención del punto de conexión

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

Para obtener el punto de conexión:

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

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

  3. Anote el punto de conexión, que debería tener un aspecto similar a .

Configuración del entorno

  1. Use Git para clonar el repositorio de ejemplo.

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

  2. Dirígete a la carpeta quickstart y ábrela en Visual Studio Code.

    cd azure-search-javascript-samples/quickstart-vector-js
code .

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

  4. Cambie el nombre de a .

    mv sample.env .env

  5. Instale las dependencias.

    npm install

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

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

    az login

Ejecución del código

  1. Cree un índice vectorial.

    node -r dotenv/config src/createIndex.js

  2. Cargue documentos que contengan inserciones precalculadas.

    node -r dotenv/config src/uploadDocuments.js

  3. Ejecute una consulta de búsqueda vectorial.

    node -r dotenv/config src/searchSingle.js

  4. (Opcional) Ejecute variaciones de consulta adicionales.

    node -r dotenv/config src/searchSingleWithFilter.js
node -r dotenv/config src/searchSingleWithFilterGeo.js
node -r dotenv/config src/searchHybrid.js
node -r dotenv/config src/searchSemanticHybrid.js

Salida

La salida de muestra el nombre del índice y la confirmación.

Using Azure Search endpoint: https://<search-service-name>.search.windows.net
Using Azure Search index: hotels-vector-quickstart
Creating index...
hotels-vector-quickstart created

La salida de muestra el estado de éxito de cada documento indexado.

Uploading documents...
Key: 1, Succeeded: true, ErrorMessage: none
Key: 2, Succeeded: true, ErrorMessage: none
Key: 3, Succeeded: true, ErrorMessage: none
Key: 4, Succeeded: true, ErrorMessage: none
Key: 48, Succeeded: true, ErrorMessage: none
Key: 49, Succeeded: true, ErrorMessage: none
Key: 13, Succeeded: true, ErrorMessage: none
Waiting for indexing... Current count: 0
All documents indexed successfully.

La salida de muestra los resultados de la búsqueda vectorial clasificados por puntuación de similitud.

Single Vector search found 5
- HotelId: 48, HotelName: Nordick's Valley Motel, Tags: ["continental breakfast","air conditioning","free wifi"], Score 0.6605852
- HotelId: 13, HotelName: Luxury Lion Resort, Tags: ["bar","concierge","restaurant"], Score 0.6333684
- HotelId: 4, HotelName: Sublime Palace Hotel, Tags: ["concierge","view","air conditioning"], Score 0.605672
- HotelId: 49, HotelName: Swirling Currents Hotel, Tags: ["air conditioning","laundry service","24-hour front desk service"], Score 0.6026341
- HotelId: 2, HotelName: Old Century Hotel, Tags: ["pool","free wifi","air conditioning","concierge"], Score 0.57902366

Descripción del código

Nota

Es posible que los fragmentos de código de esta sección se hayan modificado para mejorar la legibilidad. Para obtener un ejemplo de trabajo completo, consulte el código fuente.

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

  1. Crear un índice vectorial
  2. Carga de documentos en el índice
  3. Consulta del índice

Crear un índice vectorial

Antes de agregar contenido a Búsqueda de Azure AI, debe crear un índice para definir cómo se almacena y estructura el contenido.

El esquema de índice se organiza en torno al contenido del hotel. Los datos de muestra constan de descripciones vectoriales y no vectoriales de hoteles ficticios. El código siguiente de crea el esquema de índice, incluido el campo vectorial .

const searchFields = [
    { name: "HotelId", type: "Edm.String", key: true, sortable: true, filterable: true, facetable: true },
    { name: "HotelName", type: "Edm.String", searchable: true, filterable: true },
    { name: "Description", type: "Edm.String", searchable: true },
    {
        name: "DescriptionVector",
        type: "Collection(Edm.Single)",
        searchable: true,
        vectorSearchDimensions: 1536,
        vectorSearchProfileName: "vector-profile"
    },
    { name: "Category", type: "Edm.String", filterable: true, facetable: true },
    { name: "Tags", type: "Collection(Edm.String)", filterable: true },
    // Additional fields: ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

const vectorSearch = {
    profiles: [
        {
            name: "vector-profile",
            algorithmConfigurationName: "vector-search-algorithm"
        }
    ],
    algorithms: [
        {
            name: "vector-search-algorithm",
            kind: "hnsw",
            parameters: { m: 4, efConstruction: 400, efSearch: 1000, metric: "cosine" }
        }
    ]
};

const semanticSearch = {
    configurations: [
        {
            name: "semantic-config",
            prioritizedFields: {
                contentFields: [{ name: "Description" }],
                keywordsFields: [{ name: "Category" }],
                titleField: { name: "HotelName" }
            }
        }
    ]
};

const searchIndex = {
    name: indexName,
    fields: searchFields,
    vectorSearch: vectorSearch,
    semanticSearch: semanticSearch,
    suggesters: [{ name: "sg", searchMode: "analyzingInfixMatching", sourceFields: ["HotelName"] }]
};

const result = await indexClient.createOrUpdateIndex(searchIndex);

Puntos clave:

  • Para definir un índice, cree una lista de campos.

  • Este índice concreto admite varias funcionalidades de búsqueda:

    • Búsqueda de texto completo ()

    • Búsqueda vectorial ( con )

    • Clasificación semántica ()

    • Búsqueda por facetas (campos marcados con )

    • Búsqueda geoespacial ( campo con )

    • Filtrado y ordenación (campos marcados con y )

  • La propiedad debe coincidir con el tamaño de salida del modelo de inserción. En este inicio rápido se usan 1536 dimensiones para coincidir con el modelo .

  • La configuración define el algoritmo de vecino más cercano aproximado (ANN). Los algoritmos compatibles incluyen Hierarchical Navigable Small World (HNSW) y k vecinos más cercanos (KNN). Para obtener más información, vea Relevancia en la búsqueda de vectores.

Cargar documentos en el índice

Los índices recién creados están vacíos. Para rellenar un índice y hacer que se pueda realizar búsquedas, debe cargar documentos JSON que se ajusten al esquema de índice.

En Búsqueda de Azure AI, los documentos actúan como entradas para la indexación y las salidas de las consultas. Para simplificar, esta guía de inicio rápido proporciona documentos de hotel de ejemplo con vectores predefinidos. En escenarios de producción, el contenido se extrae a menudo de orígenes de datos conectados y se transforma en JSON mediante indexadores.

El código siguiente de carga documentos en el servicio de búsqueda.

const DOCUMENTS = [
    // Array of hotel documents with embedded 1536-dimension vectors
    // Each document contains: HotelId, HotelName, Description, DescriptionVector,
    // Category, Tags, ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

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

const result = await searchClient.uploadDocuments(DOCUMENTS);
for (const r of result.results) {
    console.log(`Key: ${r.key}, Succeeded: ${r.succeeded}`);
}

El código interactúa con un índice de búsqueda específico hospedado en el servicio de Búsqueda de Azure AI a través del SearchClient, que es el objeto principal proporcionado por el paquete de @azure/search-documents. proporciona acceso a las operaciones de índice, como:

  • Ingesta de datos: , ,

  • Operaciones de búsqueda: , ,

Consultas al índice

Las consultas de los archivos de búsqueda muestran diferentes patrones de búsqueda. Las consultas vectoriales de ejemplo se basan en dos cadenas:

  • Cadena de búsqueda de texto completo:

  • Cadena de consulta vectorial: (vectorizada en una representación matemática)

La cadena de consulta vectorial es semánticamente similar a la cadena de búsqueda de texto completo, pero incluye términos que no existen en el índice. Una búsqueda de solo palabra clave para la cadena de consulta vectorial devuelve cero resultados. Sin embargo, la búsqueda de vectores busca coincidencias relevantes en función del significado en lugar de las palabras clave exactas.

Los ejemplos siguientes comienzan con una consulta vectorial básica y agregan progresivamente filtros, búsqueda de palabras clave y reranking semántico.

muestra un escenario básico en el que desea buscar descripciones de documentos que coincidan estrechamente con la cadena de consulta vectorial. El objeto configura la búsqueda vectorial:

  • limita el número de resultados que se devuelven en función de la similitud de vectores.
  • especifica el campo vectorial en el que se va a buscar.
const vectorQuery = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"],
    includeTotalCount: true,
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results = await searchClient.search("*", searchOptions);

for await (const result of results.results) {
    const doc = result.document;
    console.log(`HotelId: ${doc.HotelId}, HotelName: ${doc.HotelName}, Score: ${result.score}`);
}

Búsqueda de un solo vector con un filtro

En Búsqueda de Azure AI, filters se aplican a campos no vectores de un índice. filtra en el campo para filtrar los hoteles que no proporcionan conexión Wi-Fi gratuita.

const searchOptions = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"],
    includeTotalCount: true,
    filter: "Tags/any(tag: tag eq 'free wifi')", // Adding filter for "free wifi" tag
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results = await searchClient.search("*", searchOptions);

Búsqueda de un solo vector con un filtro geográfico

Puede especificar un filtro geoespacial para limitar los resultados a un área geográfica específica. especifica un punto geográfico (Washington D.C., utilizando coordenadas de longitud y latitud) y devuelve hoteles dentro de 300 kilómetros. La propiedad determina cuándo se ejecuta el filtro. En este caso, ejecuta el filtro después de la búsqueda vectorial.

const searchOptions = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description", "Address/City", "Address/StateProvince"],
    facets: ["Address/StateProvince"],
    filter: "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

La búsqueda híbrida combina consultas de texto completo y vectores en una sola solicitud. ejecuta ambos tipos de consulta simultáneamente y, a continuación, usa La fusión de clasificación recíproca (RRF) para combinar los resultados en una clasificación unificada. RRF usa el inverso de las clasificaciones de resultados de cada conjunto de resultados para generar una clasificación combinada. Observe que las puntuaciones de búsqueda híbrida son uniformemente más pequeñas que las puntuaciones de consulta única.

const vectorQuery = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"],
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

// Use search text for keyword search (hybrid search = vector + keyword)
const searchText = "historic hotel walk to restaurants and shopping";
const results = await searchClient.search(searchText, searchOptions);

muestra la clasificación semántica, que vuelve a clasificar los resultados en función del reconocimiento del lenguaje.

const searchOptions = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description"],
    queryType: "semantic",
    semanticSearchOptions: {
        configurationName: "semantic-config"
    },
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const searchText = "historic hotel walk to restaurants and shopping";
const results = await searchClient.search(searchText, searchOptions);

for await (const result of results.results) {
    console.log(`Score: ${result.score}, Re-ranker Score: ${result.rerankerScore}`);
}

Compare estos resultados con los resultados de la búsqueda híbrida de la consulta anterior. Sin reajuste semántico, Sublime Palace Hotel ocupa el primer lugar porque la Fusión de Clasificación Recíproca (RRF) combina las puntuaciones de texto y vector para generar un resultado combinado. Después de la reordenación semántica, Swirling Currents Hotel se mueve al primer puesto.

El clasificador semántico usa modelos de comprensión automática para evaluar el grado de coincidencia de cada resultado con la intención de la consulta. La descripción de Swirling Currents Hotel menciona , que se alinea estrechamente con la consulta de búsqueda de . La coincidencia semántica con los restaurantes y compras cercanos lo eleva por encima del Sublime Palace Hotel, que no destaca las comodidades accesibles a pie en su descripción.

Puntos clave:

  • En una búsqueda híbrida, puede integrar el vector de búsqueda con búsqueda de texto completo sobre palabras clave. Los filtros y la clasificación semántica solo se aplican al contenido textual, no a los vectores.

  • Entre los resultados reales se incluyen más detalles, incluidos los títulos semánticos y los resaltados. En este inicio rápido se modifican los resultados para mejorar la legibilidad. Para obtener la estructura completa de la respuesta, use REST para ejecutar la solicitud.

Limpieza de recursos

Cuando trabaja en su propia suscripción, es una buena idea finalizar un proyecto quitando los recursos que ya no necesita. Los recursos que quedan en ejecución pueden costar dinero.

En el portal de Azure, seleccione Todos los recursos o Grupos de recursos en el panel izquierdo para buscar y administrar recursos. Puede eliminar recursos individualmente o eliminar el grupo de recursos para quitar todos los recursos a la vez.

De lo contrario, ejecute el siguiente comando para eliminar el índice que creó en este inicio rápido.

node -r dotenv/config src/deleteIndex.js

En este inicio rápido, usará la biblioteca cliente Búsqueda de Azure AI para Python para crear, cargar y consultar un índice vector. La biblioteca cliente de Python proporciona una abstracción sobre las API REST para las operaciones de índice.

En Búsqueda de Azure AI, un índice vectorial tiene un esquema de índice que define los campos vector y nonvector, una configuración de búsqueda de vectores para algoritmos que crean el espacio de inserción y la configuración en las definiciones de campo vectorial que se evalúan en el momento de la consulta. Índices: crear o actualizar (API REST) crea el índice vectorial.

Sugerencia

  • ¿Quieres empezar de inmediato? Descargue el código source en GitHub.
  • En este inicio rápido se omite el paso de vectorización y se proporcionan instrucciones insertadas. Para la vectorización integrada en su propio contenido, pruebe el Asistente para la importación de datos (nuevo).

Requisitos previos

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

  • Un servicio Búsqueda de Azure AI. Puede usar el nivel Gratis para la mayoría de estos inicios rápidos, pero se recomienda Básico o superior para archivos de datos más grandes.

  • Clasificador semántico habilitado en el servicio de búsqueda para la consulta híbrida semántica opcional.

  • Python 3.8 o posterior.

  • Visual Studio Code con las extensiones Python y Jupyter.

  • Git para clonar el repositorio de ejemplo.

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

Configurar el acceso

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

Para configurar el acceso basado en rol recomendado:

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

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

    • Colaborador del servicio Search

    • Colaborador de datos de índice de búsqueda

    • Lector de datos de índice de búsqueda

Obtención del punto de conexión

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

Para obtener el punto de conexión:

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

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

  3. Anote el punto de conexión, que debería tener un aspecto similar a .

Configuración del entorno

  1. Use Git para clonar el repositorio de ejemplo.

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

  2. Dirígete a la carpeta quickstart y ábrela en Visual Studio Code.

    cd azure-search-python-samples/Quickstart-Vector-Search
code .

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

  4. Cambie el nombre de a .

    mv sample.env .env

  5. Abierto .

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

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

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

    az login

Ejecución del código

  1. Ejecute la celda para instalar los paquetes necesarios y cargar variables de entorno.

  2. Ejecute las celdas restantes secuencialmente para crear un índice vectorial, cargar documentos y ejecutar diferentes tipos de consultas vectoriales.

Salida

Cada celda de código imprime su salida en el cuaderno. El ejemplo siguiente es la salida de , que muestra los resultados de búsqueda vectorial clasificados por puntuación de similitud.

Total results: 7
- HotelId: 48, HotelName: Nordick's Valley Motel, Category: Boutique
- HotelId: 13, HotelName: Luxury Lion Resort, Category: Luxury
- HotelId: 4, HotelName: Sublime Palace Hotel, Category: Boutique
- HotelId: 49, HotelName: Swirling Currents Hotel, Category: Suite
- HotelId: 2, HotelName: Old Century Hotel, Category: Boutique

Descripción del código

Nota

Es posible que los fragmentos de código de esta sección se hayan modificado para mejorar la legibilidad. Para obtener un ejemplo de trabajo completo, consulte el código fuente.

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

  1. Crear un índice vectorial
  2. Carga de documentos en el índice
  3. Consulta del índice

Crear un índice vectorial

Antes de agregar contenido a Búsqueda de Azure AI, debe crear un índice para definir cómo se almacena y estructura el contenido.

El esquema de índice se organiza en torno al contenido del hotel. Los datos de muestra constan de descripciones vectoriales y no vectoriales de hoteles ficticios. La celda del cuaderno crea el esquema de índice, incluido el campo vectorial .

fields = [
    SimpleField(name="HotelId", type=SearchFieldDataType.String, key=True, filterable=True),
    SearchableField(name="HotelName", type=SearchFieldDataType.String, sortable=True),
    SearchableField(name="Description", type=SearchFieldDataType.String),
    SearchField(
        name="DescriptionVector",
        type=SearchFieldDataType.Collection(SearchFieldDataType.Single),
        searchable=True,
        vector_search_dimensions=1536,
        vector_search_profile_name="my-vector-profile"
    ),
    SearchableField(name="Category", type=SearchFieldDataType.String, sortable=True, filterable=True, facetable=True),
    SearchField(name="Tags", type=SearchFieldDataType.Collection(SearchFieldDataType.String), searchable=True, filterable=True, facetable=True),
    # Additional fields omitted for brevity
]

Puntos clave:

  • Para definir un índice, cree una lista de campos. Cada campo se crea mediante un método auxiliar que define el tipo de campo y su configuración.

  • Este índice concreto admite varias funcionalidades de búsqueda:

    • Búsqueda de texto completo ()

    • Búsqueda vectorial ( con )

    • Clasificación semántica ()

    • Búsqueda por facetas (campos marcados con )

    • Búsqueda geoespacial ( campo con )

    • Filtrado y ordenación (campos marcados con y )

  • La propiedad debe coincidir con el tamaño de salida del modelo de inserción. En este inicio rápido se usan 1536 dimensiones para coincidir con el modelo .

  • La configuración define el algoritmo de vecino más cercano aproximado (ANN). Los algoritmos compatibles incluyen Hierarchical Navigable Small World (HNSW) y k vecinos más cercanos (KNN). Para obtener más información, vea Relevancia en la búsqueda de vectores.

Cargar documentos en el índice

Los índices recién creados están vacíos. Para rellenar un índice y hacer que se pueda realizar búsquedas, debe cargar documentos JSON que se ajusten al esquema de índice.

En Búsqueda de Azure AI, los documentos actúan como entradas para la indexación y las salidas de las consultas. Para simplificar, esta guía de inicio rápido proporciona documentos de hotel de ejemplo con vectores predefinidos. En escenarios de producción, el contenido se extrae a menudo de orígenes de datos conectados y se transforma en JSON mediante indexadores.

Las celdas y cargan documentos en el índice.

documents = [
    # List of hotel documents with embedded 1536-dimension vectors
    # Each document contains: HotelId, HotelName, Description, DescriptionVector,
    # Category, Tags, ParkingIncluded, LastRenovationDate, Rating, Address, Location
]

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

result = search_client.upload_documents(documents=documents)
for r in result:
    print(f"Key: {r.key}, Succeeded: {r.succeeded}, ErrorMessage: {r.error_message}")

El código interactúa con un índice de búsqueda específico hospedado en el servicio de Búsqueda de Azure AI a través del SearchClient, que es el objeto principal proporcionado por el paquete de azure-search-documents. proporciona acceso a las operaciones de índice, como:

  • Ingesta de datos: , ,

  • Operaciones de búsqueda: , ,

Consultas al índice

Las consultas del cuaderno muestran diferentes patrones de búsqueda. Las consultas vectoriales de ejemplo se basan en dos cadenas:

  • Cadena de búsqueda de texto completo:

  • Cadena de consulta vectorial: (vectorizada en una representación matemática)

La cadena de consulta vectorial es semánticamente similar a la cadena de búsqueda de texto completo, pero incluye términos que no existen en el índice. Una búsqueda de solo palabra clave para la cadena de consulta vectorial devuelve cero resultados. Sin embargo, la búsqueda de vectores busca coincidencias relevantes en función del significado en lugar de las palabras clave exactas.

Los ejemplos siguientes comienzan con una consulta vectorial básica y agregan progresivamente filtros, búsqueda de palabras clave y reranking semántico.

La celda muestra un escenario básico en el que desea buscar descripciones de documentos que coincidan estrechamente con la cadena de consulta vectorial. configura la búsqueda vectorial:

  • limita el número de resultados que se devuelven en función de la similitud de vectores.
  • especifica el campo vectorial en el que se va a buscar.
vector_query = VectorizedQuery(
    vector=vector,
    k_nearest_neighbors=5,
    fields="DescriptionVector",
    kind="vector",
    exhaustive=True
)

results = search_client.search(
    vector_queries=[vector_query],
    select=["HotelId", "HotelName", "Description", "Category", "Tags"],
    top=5,
    include_total_count=True
)

Búsqueda de un solo vector con un filtro

En Búsqueda de Azure AI, filters se aplican a campos no vectores de un índice. La celda aplica un filtro al campo para excluir los hoteles que no ofrecen Wi-Fi gratis.

# vector_query omitted for brevity

results = search_client.search(
    vector_queries=[vector_query],
    filter="Tags/any(tag: tag eq 'free wifi')",
    select=["HotelId", "HotelName", "Description", "Category", "Tags"],
    top=7,
    include_total_count=True
)

Búsqueda de un solo vector con un filtro geográfico

Puede especificar un filtro geoespacial para limitar los resultados a un área geográfica específica. La celda especifica un punto geográfico (Washington D.C., utilizando coordenadas de longitud y latitud) y devuelve hoteles dentro de 300 kilómetros. El parámetro determina cuándo se ejecuta el filtro. En este caso, ejecuta el filtro después de la búsqueda vectorial.

# vector_query omitted for brevity

results = search_client.search(
    include_total_count=True,
    top=5,
    select=[
        "HotelId", "HotelName", "Category", "Description", "Address/City", "Address/StateProvince"
    ],
    facets=["Address/StateProvince"],
    filter="geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    vector_filter_mode="postFilter",
    vector_queries=[vector_query]
)

La búsqueda híbrida combina consultas de texto completo y vectores en una sola solicitud. La celda ejecuta ambos tipos de consulta simultáneamente y luego utiliza la fusión de clasificación recíproca (RRF) para combinar los resultados en una clasificación unificada. RRF usa el inverso de las clasificaciones de resultados de cada conjunto de resultados para generar una clasificación combinada. Observe que las puntuaciones de búsqueda híbrida son uniformemente más pequeñas que las puntuaciones de consulta única.

# vector_query omitted for brevity

results = search_client.search(
    search_text="historic hotel walk to restaurants and shopping",
    vector_queries=[vector_query],
    select=["HotelId", "HotelName", "Description", "Category", "Tags"],
    top=5,
    include_total_count=True
)

La celda muestra la clasificación semántica, que cambia los resultados en función de la comprensión del lenguaje.

# vector_query omitted for brevity

results = search_client.search(
    search_text="historic hotel walk to restaurants and shopping",
    vector_queries=[vector_query],
    select=["HotelId", "HotelName", "Category", "Description"],
    query_type="semantic",
    semantic_configuration_name="my-semantic-config",
    top=5,
    include_total_count=True
)

Compare estos resultados con los resultados de la búsqueda híbrida de la consulta anterior. Sin reajuste semántico, Sublime Palace Hotel ocupa el primer lugar porque la Fusión de Clasificación Recíproca (RRF) combina las puntuaciones de texto y vector para generar un resultado combinado. Después de la reordenación semántica, Swirling Currents Hotel se mueve al primer puesto.

El clasificador semántico usa modelos de comprensión automática para evaluar el grado de coincidencia de cada resultado con la intención de la consulta. La descripción de Swirling Currents Hotel menciona , que se alinea estrechamente con la consulta de búsqueda de . La coincidencia semántica con los restaurantes y compras cercanos lo eleva por encima del Sublime Palace Hotel, que no destaca las comodidades accesibles a pie en su descripción.

Puntos clave:

  • En una búsqueda híbrida, puede integrar el vector de búsqueda con búsqueda de texto completo sobre palabras clave. Los filtros y la clasificación semántica solo se aplican al contenido textual, no a los vectores.

  • Entre los resultados reales se incluyen más detalles, incluidos los títulos semánticos y los resaltados. En este inicio rápido se modifican los resultados para mejorar la legibilidad. Para obtener la estructura completa de la respuesta, use REST para ejecutar la solicitud.

Limpieza de recursos

Cuando trabaja en su propia suscripción, es una buena idea finalizar un proyecto quitando los recursos que ya no necesita. Los recursos que quedan en ejecución pueden costar dinero.

En el portal de Azure, seleccione Todos los recursos o Grupos de recursos en el panel izquierdo para buscar y administrar recursos. Puede eliminar recursos individualmente o eliminar el grupo de recursos para quitar todos los recursos a la vez.

De lo contrario, puede ejecutar la celda de código para eliminar el índice que creó en este inicio rápido.

En este inicio rápido, usará la biblioteca cliente Búsqueda de Azure AI para JavaScript (compatible con TypeScript) para crear, cargar y consultar un índice vector. La biblioteca cliente de JavaScript proporciona una abstracción sobre las API REST para las operaciones de índice.

En Búsqueda de Azure AI, un índice vectorial tiene un esquema de índice que define los campos vector y nonvector, una configuración de búsqueda de vectores para algoritmos que crean el espacio de inserción y la configuración en las definiciones de campo vectorial que se evalúan en el momento de la consulta. Índices: crear o actualizar (API REST) crea el índice vectorial.

Sugerencia

  • ¿Quieres empezar de inmediato? Descargue el código source en GitHub.
  • En este inicio rápido se omite el paso de vectorización y se proporcionan instrucciones insertadas. Para la vectorización integrada en su propio contenido, pruebe el Asistente para la importación de datos (nuevo).

Requisitos previos

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

  • Un servicio Búsqueda de Azure AI. Puede usar el nivel Gratis para la mayoría de estos inicios rápidos, pero se recomienda Básico o superior para archivos de datos más grandes.

  • Clasificador semántico habilitado en el servicio de búsqueda para la consulta híbrida semántica opcional.

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

  • TypeScript para compilar TypeScript en JavaScript.

  • Visual Studio Code.

  • Git para clonar el repositorio de ejemplo.

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

Configurar el acceso

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

Para configurar el acceso basado en rol recomendado:

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

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

    • Colaborador del servicio Search

    • Colaborador de datos de índice de búsqueda

    • Lector de datos de índice de búsqueda

Obtención del punto de conexión

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

Para obtener el punto de conexión:

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

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

  3. Anote el punto de conexión, que debería tener un aspecto similar a .

Configuración del entorno

  1. Use Git para clonar el repositorio de ejemplo.

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

  2. Dirígete a la carpeta quickstart y ábrela en Visual Studio Code.

    cd azure-search-javascript-samples/quickstart-vector-ts
code .

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

  4. Cambie el nombre de a .

    mv sample.env .env

  5. Instale las dependencias.

    npm install

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

  6. Compile los archivos TypeScript.

    npm run build

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

    az login

Ejecución del código

  1. Cree un índice vectorial.

    node -r dotenv/config dist/createIndex.js

  2. Cargue documentos que contengan inserciones precalculadas.

    node -r dotenv/config dist/uploadDocuments.js

  3. Ejecute una consulta de búsqueda vectorial.

    node -r dotenv/config dist/searchSingle.js

  4. (Opcional) Ejecute variaciones de consulta adicionales.

    node -r dotenv/config dist/searchSingleWithFilter.js
node -r dotenv/config dist/searchSingleWithFilterGeo.js
node -r dotenv/config dist/searchHybrid.js
node -r dotenv/config dist/searchSemanticHybrid.js

    Nota

    Estos comandos ejecutan archivos desde la carpeta porque anteriormente transpilaba de TypeScript a JavaScript con .

Salida

La salida de muestra el nombre del índice y la confirmación.

Using Azure Search endpoint: https://<search-service-name>.search.windows.net
Using index name: hotels-vector-quickstart
Creating index...
hotels-vector-quickstart created

La salida de muestra el estado de éxito de cada documento indexado.

Uploading documents...
Key: 1, Succeeded: true, ErrorMessage: none
Key: 2, Succeeded: true, ErrorMessage: none
Key: 3, Succeeded: true, ErrorMessage: none
Key: 4, Succeeded: true, ErrorMessage: none
Key: 48, Succeeded: true, ErrorMessage: none
Key: 49, Succeeded: true, ErrorMessage: none
Key: 13, Succeeded: true, ErrorMessage: none
All documents indexed successfully.

La salida de muestra los resultados de la búsqueda vectorial clasificados por puntuación de similitud.

Single Vector search found 5
- HotelId: 48, HotelName: Nordick's Valley Motel, Tags: ["continental breakfast","air conditioning","free wifi"], Score 0.6605852
- HotelId: 13, HotelName: Luxury Lion Resort, Tags: ["bar","concierge","restaurant"], Score 0.6333684
- HotelId: 4, HotelName: Sublime Palace Hotel, Tags: ["concierge","view","air conditioning"], Score 0.605672
- HotelId: 49, HotelName: Swirling Currents Hotel, Tags: ["air conditioning","laundry service","24-hour front desk service"], Score 0.6026341
- HotelId: 2, HotelName: Old Century Hotel, Tags: ["pool","free wifi","air conditioning","concierge"], Score 0.57902366

Descripción del código

Nota

Es posible que los fragmentos de código de esta sección se hayan modificado para mejorar la legibilidad. Para obtener un ejemplo de trabajo completo, consulte el código fuente.

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

  1. Crear un índice vectorial
  2. Carga de documentos en el índice
  3. Consulta del índice

Crear un índice vectorial

Antes de agregar contenido a Búsqueda de Azure AI, debe crear un índice para definir cómo se almacena y estructura el contenido.

El esquema de índice se organiza en torno al contenido del hotel. Los datos de muestra constan de descripciones vectoriales y no vectoriales de hoteles ficticios. El código siguiente de crea el esquema de índice, incluido el campo vectorial .

const searchFields: SearchField[] = [
    { name: "HotelId", type: "Edm.String", key: true, sortable: true, filterable: true, facetable: true },
    { name: "HotelName", type: "Edm.String", searchable: true, filterable: true },
    { name: "Description", type: "Edm.String", searchable: true },
    {
        name: "DescriptionVector",
        type: "Collection(Edm.Single)",
        searchable: true,
        vectorSearchDimensions: 1536,
        vectorSearchProfileName: "vector-profile"
    },
    { name: "Category", type: "Edm.String", filterable: true, facetable: true },
    { name: "Tags", type: "Collection(Edm.String)", filterable: true },
    // Additional fields: ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

const vectorSearch: VectorSearch = {
    profiles: [
        {
            name: "vector-profile",
            algorithmConfigurationName: "vector-search-algorithm"
        }
    ],
    algorithms: [
        {
            name: "vector-search-algorithm",
            kind: "hnsw",
            parameters: { m: 4, efConstruction: 400, efSearch: 1000, metric: "cosine" }
        }
    ]
};

const semanticSearch: SemanticSearch = {
    configurations: [
        {
            name: "semantic-config",
            prioritizedFields: {
                contentFields: [{ name: "Description" }],
                keywordsFields: [{ name: "Category" }],
                titleField: { name: "HotelName" }
            }
        }
    ]
};

const searchIndex: SearchIndex = {
    name: indexName,
    fields: searchFields,
    vectorSearch: vectorSearch,
    semanticSearch: semanticSearch,
    suggesters: [{ name: "sg", searchMode: "analyzingInfixMatching", sourceFields: ["HotelName"] }]
};

const result = await indexClient.createOrUpdateIndex(searchIndex);

Puntos clave:

  • Para definir un índice, cree una lista de campos.

  • Este índice concreto admite varias funcionalidades de búsqueda:

    • Búsqueda de texto completo ()

    • Búsqueda vectorial ( con )

    • Clasificación semántica ()

    • Búsqueda por facetas (campos marcados con )

    • Búsqueda geoespacial ( campo con )

    • Filtrado y ordenación (campos marcados con y )

  • La propiedad debe coincidir con el tamaño de salida del modelo de inserción. En este inicio rápido se usan 1536 dimensiones para coincidir con el modelo .

  • La configuración define el algoritmo de vecino más cercano aproximado (ANN). Los algoritmos compatibles incluyen Hierarchical Navigable Small World (HNSW) y k vecinos más cercanos (KNN). Para obtener más información, vea Relevancia en la búsqueda de vectores.

Cargar documentos en el índice

Los índices recién creados están vacíos. Para rellenar un índice y hacer que se pueda realizar búsquedas, debe cargar documentos JSON que se ajusten al esquema de índice.

En Búsqueda de Azure AI, los documentos actúan como entradas para la indexación y las salidas de las consultas. Para simplificar, esta guía de inicio rápido proporciona documentos de hotel de ejemplo con vectores predefinidos. En escenarios de producción, el contenido se extrae a menudo de orígenes de datos conectados y se transforma en JSON mediante indexadores.

El código siguiente de carga documentos en el servicio de búsqueda.

const DOCUMENTS = [
    // Array of hotel documents with embedded 1536-dimension vectors
    // Each document contains: HotelId, HotelName, Description, DescriptionVector,
    // Category, Tags, ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

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

const result = await searchClient.uploadDocuments(DOCUMENTS);
for (const r of result.results) {
    console.log(`Key: ${r.key}, Succeeded: ${r.succeeded}`);
}

El código interactúa con un índice de búsqueda específico hospedado en el servicio de Búsqueda de Azure AI a través del SearchClient, que es el objeto principal proporcionado por el paquete de @azure/search-documents. proporciona acceso a las operaciones de índice, como:

  • Ingesta de datos: , ,

  • Operaciones de búsqueda: , ,

Consultas al índice

Las consultas de los archivos de búsqueda muestran diferentes patrones de búsqueda. Las consultas vectoriales de ejemplo se basan en dos cadenas:

  • Cadena de búsqueda de texto completo:

  • Cadena de consulta vectorial: (vectorizada en una representación matemática)

La cadena de consulta vectorial es semánticamente similar a la cadena de búsqueda de texto completo, pero incluye términos que no existen en el índice. Una búsqueda de solo palabra clave para la cadena de consulta vectorial devuelve cero resultados. Sin embargo, la búsqueda de vectores busca coincidencias relevantes en función del significado en lugar de las palabras clave exactas.

Los ejemplos siguientes comienzan con una consulta vectorial básica y agregan progresivamente filtros, búsqueda de palabras clave y reranking semántico.

muestra un escenario básico en el que desea buscar descripciones de documentos que coincidan estrechamente con la cadena de consulta vectorial. El objeto configura la búsqueda vectorial:

  • limita el número de resultados que se devuelven en función de la similitud de vectores.
  • especifica el campo vectorial en el que se va a buscar.
const vectorQuery: VectorQuery<HotelDocument> = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions: SearchOptions<HotelDocument> = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"] as const,
    includeTotalCount: true,
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results: SearchDocumentsResult<HotelDocument> = await searchClient.search("*", searchOptions);

for await (const result of results.results) {
    const doc = result.document;
    console.log(`HotelId: ${doc.HotelId}, HotelName: ${doc.HotelName}, Score: ${result.score}`);
}

Búsqueda de un solo vector con un filtro

En Búsqueda de Azure AI, filters se aplican a campos no vectores de un índice. filtra en el campo para filtrar los hoteles que no proporcionan conexión Wi-Fi gratuita.

const searchOptions: SearchOptions<HotelDocument> = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"] as const,
    includeTotalCount: true,
    filter: "Tags/any(tag: tag eq 'free wifi')", // Adding filter for "free wifi" tag
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results: SearchDocumentsResult<HotelDocument> = await searchClient.search("*", searchOptions);

Búsqueda de un solo vector con un filtro geográfico

Puede especificar un filtro geoespacial para limitar los resultados a un área geográfica específica. especifica un punto geográfico (Washington D.C., utilizando coordenadas de longitud y latitud) y devuelve hoteles dentro de 300 kilómetros. La propiedad determina cuándo se ejecuta el filtro. En este caso, ejecuta el filtro después de la búsqueda vectorial.

const searchOptions: SearchOptions<HotelDocument> = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description", "Address/City", "Address/StateProvince"] as const,
    facets: ["Address/StateProvince"],
    filter: "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

La búsqueda híbrida combina consultas de texto completo y vectores en una sola solicitud. ejecuta ambos tipos de consulta simultáneamente y, a continuación, usa La fusión de clasificación recíproca (RRF) para combinar los resultados en una clasificación unificada. RRF usa el inverso de las clasificaciones de resultados de cada conjunto de resultados para generar una clasificación combinada. Observe que las puntuaciones de búsqueda híbrida son uniformemente más pequeñas que las puntuaciones de consulta única.

const vectorQuery: VectorQuery<HotelDocument> = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions: SearchOptions<HotelDocument> = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"] as const,
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

// Use search text for keyword search (hybrid search = vector + keyword)
const searchText = "historic hotel walk to restaurants and shopping";
const results: SearchDocumentsResult<HotelDocument> = await searchClient.search(searchText, searchOptions);

muestra la clasificación semántica, que vuelve a clasificar los resultados en función del reconocimiento del lenguaje.

const searchOptions: SearchOptions<HotelDocument> = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description"] as const,
    queryType: "semantic" as const,
    semanticSearchOptions: {
        configurationName: "semantic-config"
    },
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const searchText = "historic hotel walk to restaurants and shopping";
const results: SearchDocumentsResult<HotelDocument> = await searchClient.search(searchText, searchOptions);

for await (const result of results.results) {
    console.log(`Score: ${result.score}, Re-ranker Score: ${result.rerankerScore}`);
}

Compare estos resultados con los resultados de la búsqueda híbrida de la consulta anterior. Sin reajuste semántico, Sublime Palace Hotel ocupa el primer lugar porque la Fusión de Clasificación Recíproca (RRF) combina las puntuaciones de texto y vector para generar un resultado combinado. Después de la reordenación semántica, Swirling Currents Hotel se mueve al primer puesto.

El clasificador semántico usa modelos de comprensión automática para evaluar el grado de coincidencia de cada resultado con la intención de la consulta. La descripción de Swirling Currents Hotel menciona , que se alinea estrechamente con la consulta de búsqueda de . La coincidencia semántica con los restaurantes y compras cercanos lo eleva por encima del Sublime Palace Hotel, que no destaca las comodidades accesibles a pie en su descripción.

Puntos clave:

  • En una búsqueda híbrida, puede integrar el vector de búsqueda con búsqueda de texto completo sobre palabras clave. Los filtros y la clasificación semántica solo se aplican al contenido textual, no a los vectores.

  • Entre los resultados reales se incluyen más detalles, incluidos los títulos semánticos y los resaltados. En este inicio rápido se modifican los resultados para mejorar la legibilidad. Para obtener la estructura completa de la respuesta, use REST para ejecutar la solicitud.

Limpieza de recursos

Cuando trabaja en su propia suscripción, es una buena idea finalizar un proyecto quitando los recursos que ya no necesita. Los recursos que quedan en ejecución pueden costar dinero.

En el portal de Azure, seleccione Todos los recursos o Grupos de recursos en el panel izquierdo para buscar y administrar recursos. Puede eliminar recursos individualmente o eliminar el grupo de recursos para quitar todos los recursos a la vez.

De lo contrario, ejecute el siguiente comando para eliminar el índice que creó en este inicio rápido.

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

En este inicio rápido, usará las API REST Búsqueda de Azure AI para crear, cargar y consultar un índice de vector.

En Búsqueda de Azure AI, un índice vectorial tiene un esquema de índice que define los campos vector y nonvector, una configuración de búsqueda de vectores para algoritmos que crean el espacio de inserción y la configuración en las definiciones de campo vectorial que se evalúan en el momento de la consulta. Índices: crear o actualizar (API REST) crea el índice vectorial.

Sugerencia

  • ¿Quieres empezar de inmediato? Descargue el código source en GitHub.
  • En este inicio rápido se omite el paso de vectorización y se proporcionan instrucciones insertadas. Para la vectorización integrada en su propio contenido, pruebe el Asistente para la importación de datos (nuevo).

Requisitos previos

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

  • Un servicio Búsqueda de Azure AI. Puede usar el nivel Gratis para la mayoría de estos inicios rápidos, pero se recomienda Básico o superior para archivos de datos más grandes.

  • Clasificador semántico habilitado en el servicio de búsqueda para la consulta híbrida semántica opcional.

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

  • Git para clonar el repositorio de ejemplo.

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

Configurar el acceso

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

Para configurar el acceso basado en rol recomendado:

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

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

    • Colaborador del servicio Search

    • Colaborador de datos de índice de búsqueda

    • Lector de datos de índice de búsqueda

Obtención del punto de conexión

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

Para obtener el punto de conexión:

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

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

  3. Anote el punto de conexión, que debería tener un aspecto similar a .

Configuración del entorno

  1. Use Git para clonar el repositorio de ejemplo.

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

  2. Dirígete a la carpeta quickstart y ábrela en Visual Studio Code.

    cd azure-search-rest-samples/Quickstart-vectors
code .

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

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

    az login

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

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

  6. Reemplace el valor del marcador de posición de por el token del paso anterior.

Ejecución del código

  1. En , seleccione Enviar solicitud para comprobar la conexión.

    Debe aparecer una respuesta en un panel adyacente. Si tiene índices existentes, se muestran. En caso contrario, la lista está vacía. Si el código HTTP es , está listo para continuar.

  2. Envíe las solicitudes restantes secuencialmente para crear un índice vectorial, cargar documentos y ejecutar diferentes tipos de consultas vectoriales.

Salida

Cada solicitud de consulta devuelve resultados JSON. El ejemplo siguiente es la salida de la solicitud, que muestra los resultados de búsqueda vectorial clasificados por puntuación de similitud.

{
  "@odata.count": 5,
  "value": [
    {
      "@search.score": 0.6605852,
      "HotelId": "48",
      "HotelName": "Nordick's Valley Motel",
      "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer. Hiking? Wine Tasting? Exploring the caverns? It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.",
      "Category": "Boutique",
      "Tags": [
        "continental breakfast",
        "air conditioning",
        "free wifi"
      ]
    },
    {
      "@search.score": 0.6333684,
      "HotelId": "13",
      "HotelName": "Luxury Lion Resort",
      "Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium and transportation hubs, we feature the best in convenience and comfort.",
      "Category": "Luxury",
      "Tags": [
        "bar",
        "concierge",
        "restaurant"
      ]
    },
    {
      "@search.score": 0.605672,
      "HotelId": "4",
      "HotelName": "Sublime Palace Hotel",
      "Description": "Sublime Palace 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.",
      "Category": "Boutique",
      "Tags": [
        "concierge",
        "view",
        "air conditioning"
      ]
    },
    {
      "@search.score": 0.6026341,
      "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.",
      "Category": "Suite",
      "Tags": [
        "air conditioning",
        "laundry service",
        "24-hour front desk service"
      ]
    },
    {
      "@search.score": 0.57902366,
      "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.",
      "Category": "Boutique",
      "Tags": [
        "pool",
        "free wifi",
        "air conditioning",
        "concierge"
      ]
    }
  ]
}

Descripción del código

Nota

Es posible que los fragmentos de código de esta sección se hayan modificado para mejorar la legibilidad. Para obtener un ejemplo de trabajo completo, consulte el código fuente.

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

  1. Crear un índice vectorial
  2. Carga de documentos en el índice
  3. Consulta del índice

Crear un índice vectorial

Antes de agregar contenido a Búsqueda de Azure AI, debe crear un índice para definir cómo se almacena y estructura el contenido. En este inicio rápido se llama a Indexes- Create (REST API) para crear un índice vectorial denominado y sus estructuras de datos físicas en el servicio de búsqueda.

El esquema de índice se organiza en torno al contenido del hotel. Los datos de muestra constan de descripciones vectoriales y no vectoriales de hoteles ficticios. En el fragmento siguiente se muestra la estructura clave de la solicitud.

PUT {{baseUrl}}/indexes/hotels-vector-quickstart?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "name": "hotels-vector-quickstart",
    "fields": [
        { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
        { "name": "HotelName", "type": "Edm.String", "searchable": true },
        { "name": "Description", "type": "Edm.String", "searchable": true },
        {
            "name": "DescriptionVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "dimensions": 1536,
            "vectorSearchProfile": "my-vector-profile"
        },
        { "name": "Category", "type": "Edm.String", "filterable": true, "facetable": true },
        { "name": "Tags", "type": "Collection(Edm.String)", "filterable": true, "facetable": true }
        // Additional fields omitted for brevity
    ],
    "vectorSearch": {
        "algorithms": [
            { "name": "hnsw-vector-config", "kind": "hnsw" }
        ],
        "profiles": [
            { "name": "my-vector-profile", "algorithm": "hnsw-vector-config" }
        ]
    },
    "semantic": {
        "configurations": [
            {
                "name": "semantic-config",
                "prioritizedFields": {
                    "titleField": { "fieldName": "HotelName" },
                    "prioritizedContentFields": [{ "fieldName": "Description" }]
                }
            }
        ]
    }
}

Puntos clave:

  • Este índice concreto admite varias funcionalidades de búsqueda:

    • Búsqueda de texto completo (campos con establecido en )

    • Búsqueda vectorial ( con )

    • Clasificación semántica ( configuración)

    • Búsqueda por facetas (campos con establecido en )

    • Búsqueda geoespacial ( campo con )

    • Filtrado y ordenación (campos con y establecidos en )

  • La propiedad debe coincidir con el tamaño de salida del modelo de inserción. En este inicio rápido se usan 1536 dimensiones para coincidir con el modelo .

  • En la sección se define el algoritmo de vecino más cercano aproximado (ANN). Los algoritmos compatibles incluyen Hierarchical Navigable Small World (HNSW) y k vecinos más cercanos (KNN). Para obtener más información, vea Relevancia en la búsqueda de vectores.

Cargar documentos en el índice

Los índices recién creados están vacíos. Para rellenar un índice y hacer que se pueda realizar búsquedas, debe cargar documentos JSON que se ajusten al esquema de índice.

En Búsqueda de Azure AI, los documentos actúan como entradas para la indexación y las salidas de las consultas. Para simplificar, esta guía de inicio rápido proporciona documentos de hotel de ejemplo como JSON insertados. Sin embargo, en escenarios de producción, el contenido se extrae a menudo de orígenes de datos conectados y se transforma en JSON mediante indexadores.

En este inicio rápido se llama a Documentos - índice (API REST) para agregar documentos de hoteles de ejemplo al índice. En el fragmento siguiente se muestra la estructura de la solicitud.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/index?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "value": [
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "HotelName": "Stay-Kay City Hotel",
            "Description": "This classic hotel is ideally located on the main commercial artery of the city...",
            "DescriptionVector": [-0.0347, 0.0289, ... ],  // 1536 floats
            "Category": "Boutique",
            "Tags": ["view", "air conditioning", "concierge"],
            "ParkingIncluded": false,
            "Rating": 3.60,
            "Address": { "City": "New York", "StateProvince": "NY" },
            "Location": { "type": "Point", "coordinates": [-73.975403, 40.760586] }
        }
        // Additional documents omitted for brevity
    ]
}

Puntos clave:

  • Cada documento de la matriz representa un hotel y contiene campos que coinciden con el esquema de índice. El parámetro especifica la operación que se va a realizar para cada documento. En este inicio rápido se usa , que agrega el documento si no existe o actualiza el documento si existe.

  • Los documentos de la carga constan de campos definidos en el esquema de índice.

Consultas al índice

Las consultas del archivo de ejemplo muestran diferentes patrones de búsqueda. Las consultas vectoriales de ejemplo se basan en dos cadenas:

  • Cadena de búsqueda de texto completo:

  • Cadena de consulta vectorial: (vectorizada en una representación matemática)

La cadena de consulta vectorial es semánticamente similar a la cadena de búsqueda de texto completo, pero incluye términos que no existen en el índice. Una búsqueda de solo palabra clave para la cadena de consulta vectorial devuelve cero resultados. Sin embargo, la búsqueda de vectores busca coincidencias relevantes en función del significado en lugar de las palabras clave exactas.

Los ejemplos siguientes comienzan con una consulta vectorial básica y agregan progresivamente filtros, búsqueda de palabras clave y reranking semántico.

La solicitud muestra un escenario básico en el que desea buscar descripciones de documentos que coincidan estrechamente con la cadena de consulta vectorial. La matriz configura la búsqueda vectorial:

  • limita el número de resultados que se devuelven en función de la similitud de vectores.
  • especifica el campo vectorial en el que se va a buscar.
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "select": "HotelId, HotelName, Description, Category, Tags",
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector of "quintessential lodging near running trails, eateries, retail"
            "k": 5,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

Búsqueda de un solo vector con un filtro

En Búsqueda de Azure AI, filters se aplican a campos no vectores de un índice. La solicitud filtra el campo para filtrar los hoteles que no proporcionan conexión Wi-Fi gratuita.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "select": "HotelId, HotelName, Description, Category, Tags",
    "filter": "Tags/any(tag: tag eq 'free wifi')",
    "vectorFilterMode": "postFilter",
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

Búsqueda de un solo vector con un filtro geográfico

Puede especificar un filtro geoespacial para limitar los resultados a un área geográfica específica. La solicitud especifica un punto geográfico (Washington D.C., utilizando coordenadas de longitud y latitud) y devuelve hoteles dentro de 300 kilómetros. El parámetro determina cuándo se ejecuta el filtro. En este caso, ejecuta el filtro después de la búsqueda vectorial.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "select": "HotelId, HotelName, Address/City, Address/StateProvince, Description",
    "filter": "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    "vectorFilterMode": "postFilter",
    "top": 5,
    "facets": [ "Address/StateProvince"],
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 5,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

La búsqueda híbrida combina consultas de texto completo y vectores en una sola solicitud. La solicitud ejecuta ambos tipos de consulta simultáneamente y, a continuación, utiliza la Fusión de Clasificación Recíproca (RRF) para fusionar los resultados en una clasificación unificada. RRF usa el inverso de las clasificaciones de resultados de cada conjunto de resultados para generar una clasificación combinada. Observe que las puntuaciones de búsqueda híbrida son uniformemente más pequeñas que las puntuaciones de consulta única.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "top": 5,
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 5,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

La solicitud muestra la clasificación semántica, que vuelve a clasificar los resultados en función del reconocimiento del lenguaje.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelId, HotelName, Category, Description",
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "top": 5,
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

Compare estos resultados con los resultados de la búsqueda híbrida de la consulta anterior. Sin reajuste semántico, Sublime Palace Hotel ocupa el primer lugar porque la Fusión de Clasificación Recíproca (RRF) combina las puntuaciones de texto y vector para generar un resultado combinado. Después de la reordenación semántica, Swirling Currents Hotel se mueve al primer puesto.

El clasificador semántico usa modelos de comprensión automática para evaluar el grado de coincidencia de cada resultado con la intención de la consulta. La descripción de Swirling Currents Hotel menciona , que se alinea estrechamente con la consulta de búsqueda de . La coincidencia semántica con los restaurantes y compras cercanos lo eleva por encima del Sublime Palace Hotel, que no destaca las comodidades accesibles a pie en su descripción.

Puntos clave:

  • En una búsqueda híbrida, puede integrar el vector de búsqueda con búsqueda de texto completo sobre palabras clave. Los filtros y la clasificación semántica solo se aplican al contenido textual, no a los vectores.

Limpieza de recursos

Cuando trabaja en su propia suscripción, es una buena idea finalizar un proyecto quitando los recursos que ya no necesita. Los recursos que quedan en ejecución pueden costar dinero.

En el portal de Azure, seleccione Todos los recursos o Grupos de recursos en el panel izquierdo para buscar y administrar recursos. Puede eliminar recursos individualmente o eliminar el grupo de recursos para quitar todos los recursos a la vez.

De lo contrario, puede enviar la solicitud para eliminar el índice que creó en este inicio rápido.

Contenido relacionado

  • Last updated on