Biblioteca cliente de Azure AI Search para JavaScript: versión 12.0.0

  • Artículo

Azure AI Search (anteriormente conocido como "Azure Cognitive Search") es una plataforma de recuperación de información con tecnología de inteligencia artificial que ayuda a los desarrolladores a crear experiencias de búsqueda enriquecidas y aplicaciones de IA generativas que combinan modelos de lenguaje grandes con datos empresariales.

Azure AI Search es adecuado para los siguientes escenarios de aplicación:

  • Consolide diversos tipos de contenido en un único índice en el que se pueden realizar búsquedas. Para rellenar un índice, puede insertar documentos JSON que contengan el contenido o, si los datos ya están en Azure, cree un indexador para extraer datos automáticamente.
  • Adjunte conjuntos de aptitudes a un indexador para crear contenido que se pueda buscar a partir de imágenes y documentos de texto grandes. Un conjunto de aptitudes aprovecha las API de los servicios de inteligencia artificial para OCR integrado, reconocimiento de entidades, extracción de frases clave, detección de idioma, traducción de texto y análisis de opiniones. También puede agregar aptitudes personalizadas para integrar el procesamiento externo del contenido durante la ingesta de datos.
  • En una aplicación cliente de búsqueda, implemente la lógica de consulta y las experiencias de usuario similares a los motores de búsqueda web comerciales.

Use la @azure/search-documents biblioteca cliente para:

  • Envíe consultas mediante formularios de consulta híbrida, palabra clave y vector.
  • Implemente consultas filtradas para metadatos, búsqueda geoespacial, navegación por facetas o para restringir los resultados en función de los criterios de filtro.
  • Cree y administre índices de búsqueda.
  • Cargue y actualice documentos en el índice de búsqueda.
  • Cree y administre indizadores que extraen datos de Azure en un índice.
  • Cree y administre conjuntos de aptitudes que agregan enriquecimiento con inteligencia artificial a la ingesta de datos.
  • Cree y administre analizadores para el análisis de texto avanzado o el contenido multilingüe.
  • Optimice los resultados mediante perfiles de puntuación para factorizar la lógica de negocios o la actualización.

Vínculos principales:

Introducción

Instalar el paquete @azure/search-documents

npm install @azure/search-documents

Entornos admitidos actualmente

Para más información, consulte la directiva de compatibilidad.

Requisitos previos

Para crear un nuevo servicio de búsqueda, puede usar el Azure Portal, Azure PowerShell o la CLI de Azure. Este es un ejemplo de uso de la CLI de Azure para crear una instancia gratuita para empezar:

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

Consulte Elección de un plan de tarifa para obtener más información sobre las opciones disponibles.

Autenticar el cliente

Para interactuar con el servicio de búsqueda, deberá crear una instancia de la clase de cliente adecuada: SearchClient para buscar documentos indexados, SearchIndexClient para administrar índices o SearchIndexerClient para rastrear orígenes de datos y cargar documentos de búsqueda en un índice.

Para crear instancias de un objeto de cliente, necesitará un punto de conexión y roles de Azure o una clave de API. Puede consultar la documentación para obtener más información sobre los enfoques de autenticación admitidos con el servicio de búsqueda.

Obtención de una clave de API

Una clave de API puede ser un enfoque más fácil de empezar porque no requiere asignaciones de roles preexistentes.

Puede obtener el punto de conexión y una clave de API desde el servicio de búsqueda en Azure Portal. Consulte la documentación para obtener instrucciones sobre cómo obtener una clave de API.

Como alternativa, puede usar el siguiente comando de la CLI de Azure para recuperar la clave de API del servicio de búsqueda:

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

Una vez que tenga una clave de API, puede usarla de la siguiente manera:

const {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  AzureKeyCredential,
} = require("@azure/search-documents");

// To query and manipulate documents
const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

Autenticación en una nube nacional

Para autenticarse en una nube nacional, deberá realizar las siguientes adiciones a la configuración del cliente:

  • Establecer en AudienceSearchClientOptions
const {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  AzureKeyCredential,
  KnownSearchAudience,
} = require("@azure/search-documents");

// To query and manipulate documents
const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
  {
    audience: KnownSearchAudience.AzureChina,
  }
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
  audience: KnownSearchAudience.AzureChina,
});

// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
  audience: KnownSearchAudience.AzureChina,
});

Conceptos clave

Una servicio Search de Azure AI contiene uno o varios índices que proporcionan almacenamiento persistente de datos que se pueden buscar en forma de documentos JSON. (Si no está familiarizado con la búsqueda, puede hacer una analogía muy aproximada entre índices y tablas de base de datos). La @azure/search-documents biblioteca cliente expone operaciones en estos recursos a través de tres tipos de cliente principales.

Nota: Estos clientes no pueden funcionar en el explorador porque las API que llama no admiten el uso compartido de recursos entre orígenes (CORS).

Conceptos específicos de TypeScript/JavaScript

Documentos

Un elemento almacenado dentro de un índice de búsqueda. La forma de este documento se describe en el índice mediante Fields. Cada campo tiene un nombre, un tipo de datos y metadatos adicionales, como si se puede buscar o filtrar.

Paginación

Normalmente, solo deseará mostrar un subconjunto de resultados de búsqueda a un usuario a la vez. Para admitir esto, puede usar los topparámetros , skip y includeTotalCount para proporcionar una experiencia paginada sobre los resultados de búsqueda.

Codificación de campos de documento

Los tipos de datos admitidos en un índice se asignan a tipos JSON en solicitudes o respuestas de API. La biblioteca cliente de JS mantiene estas principalmente iguales, con algunas excepciones:

  • Edm.DateTimeOffset se convierte en un JS Date.
  • Edm.GeographyPoint se convierte en un GeographyPoint tipo exportado por la biblioteca cliente.
  • Los valores especiales del number tipo (NaN, Infinity, -Infinity) se serializan como cadenas en la API REST, pero la biblioteca cliente vuelve a convertir a number .

Nota: Los tipos de datos se convierten en función del valor, no el tipo de campo del esquema de índice. Esto significa que si tiene una cadena date de ISO8601 (por ejemplo, "2020-03-06T18:48:27.896Z") como el valor de un campo, se convertirá en una fecha independientemente de cómo lo haya almacenado en el esquema.

Ejemplos

En los ejemplos siguientes se muestran los conceptos básicos: consulte nuestros ejemplos para mucho más.

Creación de un índice

const { SearchIndexClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const result = await client.createIndex({
    name: "example-index",
    fields: [
      {
        type: "Edm.String",
        name: "id",
        key: true,
      },
      {
        type: "Edm.Double",
        name: "awesomenessLevel",
        sortable: true,
        filterable: true,
        facetable: true,
      },
      {
        type: "Edm.String",
        name: "description",
        searchable: true,
      },
      {
        type: "Edm.ComplexType",
        name: "details",
        fields: [
          {
            type: "Collection(Edm.String)",
            name: "tags",
            searchable: true,
          },
        ],
      },
      {
        type: "Edm.Int32",
        name: "hiddenWeight",
        hidden: true,
      },
    ],
  });

  console.log(result);
}

main();

Recuperar un documento específico de un índice

Un documento específico se puede recuperar mediante su valor de clave principal:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const result = await client.getDocument("1234");
  console.log(result);
}

main();

Adición de documentos a un índice

Puede cargar varios documentos en el índice dentro de un lote:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const uploadResult = await client.uploadDocuments([
    // JSON objects matching the shape of the client's index
    {},
    {},
    {},
  ]);
  for (const result of uploadResult.results) {
    console.log(`Uploaded ${result.key}; succeeded? ${result.succeeded}`);
  }
}

main();

Realizar una búsqueda en documentos

Para enumerar todos los resultados de una consulta determinada, puede usar search con una cadena de búsqueda que use la sintaxis de consulta simple:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const searchResults = await client.search("wifi -luxury");
  for await (const result of searchResults.results) {
    console.log(result);
  }
}

main();

Para una búsqueda más avanzada que use la sintaxis de Lucene, especifique queryType que sea full:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const searchResults = await client.search('Category:budget AND "recently renovated"^3', {
    queryType: "full",
    searchMode: "all",
  });
  for await (const result of searchResults.results) {
    console.log(result);
  }
}

main();

Consulta con TypeScript

En TypeScript, SearchClient toma un parámetro genérico que es la forma del modelo de los documentos de índice. Esto le permite realizar búsquedas fuertemente tipadas de campos devueltos en los resultados. TypeScript también puede comprobar los campos devueltos al especificar un select parámetro.

import { SearchClient, AzureKeyCredential, SelectFields } from "@azure/search-documents";

// An example schema for documents in the index
interface Hotel {
  hotelId?: string;
  hotelName?: string | null;
  description?: string | null;
  descriptionVector?: Array<number> | null;
  parkingIncluded?: boolean | null;
  lastRenovationDate?: Date | null;
  rating?: number | null;
  rooms?: Array<{
    beds?: number | null;
    description?: string | null;
  } | null>;
}

const client = new SearchClient<Hotel>(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

async function main() {
  const searchResults = await client.search("wifi -luxury", {
    // Only fields in Hotel can be added to this array.
    // TS will complain if one is misspelled.
    select: ["hotelId", "hotelName", "rooms/beds"],
  });

  // These are other ways to declare the correct type for `select`.
  const select = ["hotelId", "hotelName", "rooms/beds"] as const;
  // This declaration lets you opt out of narrowing the TypeScript type of your documents,
  // though the AI Search service will still only return these fields.
  const selectWide: SelectFields<Hotel>[] = ["hotelId", "hotelName", "rooms/beds"];
  // This is an invalid declaration. Passing this to `select` will result in a compiler error
  // unless you opt out of including the model in the client constructor.
  const selectInvalid = ["hotelId", "hotelName", "rooms/beds"];

  for await (const result of searchResults.results) {
    // result.document has hotelId, hotelName, and rating.
    // Trying to access result.document.description would emit a TS error.
    console.log(result.document.hotelName);
  }
}

main();

Consulta con filtros de OData

El uso del filter parámetro de consulta permite consultar un índice mediante la sintaxis de una expresión de OData $filter.

const { SearchClient, AzureKeyCredential, odata } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const baseRateMax = 200;
  const ratingMin = 4;
  const searchResults = await client.search("WiFi", {
    filter: odata`Rooms/any(room: room/BaseRate lt ${baseRateMax}) and Rating ge ${ratingMin}`,
    orderBy: ["Rating desc"],
    select: ["hotelId", "hotelName", "rating"],
  });
  for await (const result of searchResults.results) {
    // Each result will have "HotelId", "HotelName", and "Rating"
    // in addition to the standard search result property "score"
    console.log(result);
  }
}

main();

Consulta con vectores

Las incrustaciones de texto se pueden consultar mediante el vector parámetro de búsqueda.

const { SearchClient, AzureKeyCredential, odata } = require("@azure/search-documents");

const searchClient = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const queryVector = [...]
  const searchResults = await searchClient.search("*", {
    vector: {
      fields: ["descriptionVector"],
      kNearestNeighborsCount: 3,
      value: queryVector,
    },
  });
  for await (const result of searchResults.results) {
    // These results are the nearest neighbors to the query vector
    console.log(result);
  }
}

main();

Consulta con facetas

Las facetas se usan para ayudar a un usuario de la aplicación a refinar una búsqueda a lo largo de dimensiones preconfiguradas. La sintaxis de faceta proporciona las opciones para ordenar y ordenar los valores de faceta del cubo.

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const searchResults = await client.search("WiFi", {
    facets: ["category,count:3,sort:count", "rooms/baseRate,interval:100"],
  });
  console.log(searchResults.facets);
  // Output will look like:
  // {
  //   'rooms/baseRate': [
  //     { count: 16, value: 0 },
  //     { count: 17, value: 100 },
  //     { count: 17, value: 200 }
  //   ],
  //   category: [
  //     { count: 5, value: 'Budget' },
  //     { count: 5, value: 'Luxury' },
  //     { count: 5, value: 'Resort and Spa' }
  //   ]
  // }
}

main();

Al recuperar los resultados, una facets propiedad estará disponible que indicará el número de resultados que entran en cada cubo de facetas. Esto se puede usar para impulsar el refinamiento (por ejemplo, emitir una búsqueda de seguimiento que filtre por ser Rating mayor o igual que 3 y menor que 4).

Solución de problemas

Registro

La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

Pasos siguientes

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más información, visite cla.microsoft.com.

Este proyecto ha adoptado el código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes sobre el código de conducta o póngase en contacto con opencode@microsoft.com cualquier pregunta o comentario adicional.

Impresiones