Compartir a través de

Biblioteca cliente de Azure AI Search para JavaScript: versión 12.1.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 inteligencia artificial generativas que combinan modelos de lenguaje grandes con datos empresariales.

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

  • Consolide los tipos de contenido variados 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 no estructurados. Un conjunto de aptitudes aprovecha las API de Azure AI Services para el OCR integrado, el reconocimiento de entidades, la extracción de frases clave, la detección de idioma, la traducción de texto y el análisis de sentimiento. 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 y las aplicaciones de estilo de chat.

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

  • Envíe consultas mediante formularios de consulta vectorial, palabra clave e híbrida.
  • 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 IA a la ingesta de datos.
  • Cree y administre analizadores para el análisis de texto avanzado o el contenido multilingüe.
  • Optimice los resultados a través de perfiles de clasificación semántica y puntuación para factorizar la lógica de negocios o la actualización.

Vínculos clave:

  • código fuente
  • paquete de (NPM)
  • documentación de referencia de api de
  • documentación de la API REST de
  • documentación del producto de
  • ejemplos de

Empezar

Instalación del paquete @azure/search-documents

npm install @azure/search-documents

Entornos admitidos actualmente

Consulte nuestra de directiva de soporte técnico de para obtener más información.

Prerrequisitos

  • Un de suscripción de Azure de
  • Una del servicio Search

Para crear un nuevo servicio de búsqueda, puede usar Azure Portal, azure PowerShello la CLI de Azure . Este es un ejemplo del 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 elegir un plan de tarifa para obtener más información sobre las opciones disponibles.

Autenticación del 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 de y roles de Azure o una clave de API de . Puede consultar la documentación para obtener más información sobre 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 de punto de conexión de y una clave de API de desde el servicio de búsqueda en Azure Portal. Consulte la documentación de para obtener instrucciones sobre cómo obtener una clave de API.

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

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

Hay dos tipos de claves que se usan para acceder al servicio de búsqueda: de administración (lectura y escritura) y de consulta (solo lectura) claves. Restringir el acceso y las operaciones en las aplicaciones cliente es esencial para proteger los recursos de búsqueda en el servicio. Use siempre una clave de consulta en lugar de una clave de administrador para cualquier consulta que se origine en una aplicación cliente.

Nota: El fragmento de código de la CLI de Azure de ejemplo anterior recupera una clave de administrador para que sea más fácil empezar a explorar las API, pero debe administrarse cuidadosamente.

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 National Cloud, deberá realizar las siguientes adiciones a la configuración del cliente:

  • Establecer el Audience en SearchClientOptions
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

Un servicio Azure AI Search 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 biblioteca cliente de @azure/search-documents 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 a las que llama no admiten el uso compartido de recursos entre orígenes (CORS).

Conceptos específicos de TypeScript y JavaScript

Documentos

Un elemento almacenado dentro de un índice de búsqueda. La forma de este documento se describe en el índice mediante la propiedad fields. Cada SearchField 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 parámetros top, skip y includeTotalCount para proporcionar una experiencia paginada sobre los resultados de búsqueda.

Codificación de campos de documento

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

  • Edm.DateTimeOffset se convierte en un Datede JS.
  • Edm.GeographyPoint se convierte en un tipo GeographyPoint exportado por la biblioteca cliente.
  • Los valores especiales del tipo de number (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 en 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 valor de un campo, se convertirá a una fecha independientemente de cómo lo almacene en el esquema.

Ejemplos

En los ejemplos siguientes se muestran los conceptos básicos, por favor 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();

Recuperación de un documento específico de un índice

Su valor de clave principal puede recuperar un documento específico:

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

Agregar 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 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 obtener una búsqueda más avanzada que use sintaxis de Lucene, especifique queryType que se 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 una búsqueda fuertemente tipada de campos devueltos en los resultados. TypeScript también puede comprobar los campos devueltos al especificar un parámetro select.

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>;
  parkingIncluded?: boolean | null;
  lastRenovationDate?: Date | null;
  rating?: number | null;
  rooms?: Array<{
    beds?: number | null;
    description?: string | 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 OData

El uso del parámetro de consulta filter 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 parámetro de búsqueda vector. Consulte Consultas de vectores y consultas de vectores de filtro de para obtener más información.

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

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

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

main();

Consulta con facetas

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

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, estará disponible una propiedad facets que indicará el número de resultados que se encuentran en cada cubo de facetas. Esto se puede usar para impulsar el refinamiento (por ejemplo, emitir una búsqueda de seguimiento que filtre por la Rating sea 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 el @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Pasos siguientes

Contribuyendo

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

Este proyecto da la bienvenida a las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia de colaborador (CLA) declarando que tiene derecho a, y en realidad, concedanos los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Este proyecto ha adoptado el código abierto de conducta de Microsoft. Para obtener más información, consulte el de preguntas más frecuentes sobre el código de conducta de o póngase en contacto con con preguntas o comentarios adicionales.

impresiones