Partager via

Bibliothèque cliente Azure AI Search pour JavaScript - version 12.2.0

Azure AI Search (anciennement connu sous le nom d'« Azure Cognitive Search ») est une plateforme de récupération d’informations basée sur l’IA qui aide les développeurs à créer des expériences de recherche enrichies et des applications d’IA génératives qui combinent de grands modèles de langage avec des données d’entreprise.

Le service Recherche d’IA Azure convient parfaitement aux scénarios d’application suivants :

  • Consolider des types de contenu variés en un seul index pouvant faire l’objet d’une recherche. Pour remplir un index, vous pouvez envoyer (push) des documents JSON contenant votre contenu ou, si vos données se trouvent déjà dans Azure, créez un indexeur pour extraire automatiquement des données.
  • Attachez des ensembles de compétences à un indexeur pour créer du contenu pouvant faire l’objet d’une recherche à partir d’images et de documents non structurés. Un ensemble de compétences tire parti des API d’Azure AI Services pour l’OCR intégré, la reconnaissance d’entité, l’extraction d’expressions clés, la détection de langue, la traduction de texte et l’analyse des sentiments. Vous pouvez également ajouter des compétences personnalisées pour intégrer le traitement externe de votre contenu pendant l’ingestion des données.
  • Dans une application cliente de recherche, implémentez une logique de requête et des expériences utilisateur similaires aux moteurs de recherche web commerciaux et aux applications de style conversation.

Utilisez la bibliothèque cliente @azure/search-documents pour :

  • Envoyez des requêtes à l’aide de formulaires de requête vectorielles, de mots clés et hybrides.
  • Implémentez des requêtes filtrées pour les métadonnées, la recherche géospatiale, la navigation à facettes ou pour affiner les résultats en fonction des critères de filtre.
  • Créez et gérez des index de recherche.
  • Chargez et mettez à jour des documents dans l’index de recherche.
  • Créez et gérez des indexeurs qui extrayent des données d’Azure dans un index.
  • Créez et gérez des ensembles de compétences qui ajoutent l’enrichissement par IA à l’ingestion de données.
  • Créez et gérez des analyseurs pour l’analyse de texte avancée ou le contenu multilingue.
  • Optimisez les résultats par le biais de profils de classement sémantique et de scoring pour prendre en compte la logique métier ou l’actualisation.

Liens clés :

Commencer

Installer le package @azure/search-documents

npm install @azure/search-documents

Environnements actuellement pris en charge

Pour plus d’informations, consultez notre politique de support .

Conditions préalables

Pour créer un service de recherche, vous pouvez utiliser le portail Azure, Azure PowerShell ou Azure CLI. Voici un exemple utilisant Azure CLI pour créer une instance gratuite pour commencer :

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

Pour plus d’informations sur les options disponibles, consultez la section Choix d’un niveau tarifaire .

Authentifier le client

Pour interagir avec le service de recherche, vous devez créer une instance de la classe cliente appropriée : SearchClient pour la recherche de documents indexés, SearchIndexClient pour la gestion des index ou SearchIndexerClient pour l’exploration des sources de données et le chargement des documents de recherche dans un index. Pour instancier un objet client, vous aurez besoin d’un point de terminaison et de rôles Azure ou d’une clé API. Vous pouvez vous référer à la documentation pour plus d’informations sur les approches d’authentification prises en charge avec le service de recherche.

Obtenir une clé API

Une clé API peut être une approche plus simple pour commencer, car elle ne nécessite pas d’attributions de rôles préexistantes.

Vous pouvez obtenir le point de terminaison et une clé API à partir du service de recherche dans le portail Azure. Veuillez vous référer à la documentation pour obtenir des instructions sur la façon d’obtenir une clé API.

Vous pouvez également utiliser la commande Azure CLI suivante pour récupérer la clé API à partir du service de recherche :

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

Il existe deux types de clés utilisées pour accéder à votre service de recherche : les clés admin(lecture-écriture) et query(lecture seule). La restriction de l’accès et des opérations dans les applications clientes est essentielle pour protéger les ressources de recherche sur votre service. Utilisez toujours une clé de requête plutôt qu’une clé d’administration pour toute requête provenant d’une application cliente.

Remarque : L’exemple d’extrait de code Azure CLI ci-dessus récupère une clé d’administration, ce qui facilite la prise en main de l’exploration des API, mais elle doit être gérée avec soin.

Une fois que vous disposez d’une clé API, vous pouvez l’utiliser comme suit :

import {
  SearchClient,
  AzureKeyCredential,
  SearchIndexClient,
  SearchIndexerClient,
} from "@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>"));

S’authentifier dans un cloud national

Pour vous authentifier dans un cloud national, vous devrez effectuer les ajouts suivants à la configuration de votre client :

  • Réglez l’icône AudienceSearchClientOptions
import {
  SearchClient,
  AzureKeyCredential,
  KnownSearchAudience,
  SearchIndexClient,
  SearchIndexerClient,
} from "@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,
});

Concepts clés

Un service Recherche Azure AI contient un ou plusieurs index qui fournissent un stockage persistant de données pouvant faire l’objet d’une recherche sous la forme de documents JSON. (Si vous débutez dans la recherche, vous pouvez faire une analogie très grossière entre les index et les tables de base de données.) La @azure/search-documents bibliothèque cliente expose les opérations sur ces ressources par le biais de trois principaux types de clients.

Remarque : Ces clients ne peuvent pas fonctionner dans le navigateur, car les API qu’ils appellent ne prennent pas en charge le partage de ressources d’origine croisée (CORS).

Concepts spécifiques de TypeScript/JavaScript

Documents

Élément stocké dans un index de recherche. La forme de ce document est décrite dans l’index à l’aide de la fields propriété. Chacun SearchField a un nom, un type de données et des métadonnées supplémentaires, par exemple s’il peut faire l’objet d’une recherche ou d’un filtrage.

Pagination

En règle générale, vous ne souhaiterez afficher qu’un sous-ensemble de résultats de recherche à un utilisateur à la fois. Pour ce faire, vous pouvez utiliser les topparamètres et skipincludeTotalCount pour fournir une expérience paginée au-dessus des résultats de recherche.

Encodage de champ de document

Les types de données pris en charge dans un index sont mappés aux types JSON dans les demandes/réponses d’API. La bibliothèque de client JS les conserve principalement de la même façon, avec certaines exceptions :

  • Edm.DateTimeOffset est converti en JS Date.
  • Edm.GeographyPoint est converti en un GeographyPoint type exporté par la bibliothèque cliente.
  • Les valeurs spéciales du number type (NaN, Infinity -Infinity) sont sérialisées en tant que chaînes dans l’API REST, mais sont reconverties number par la bibliothèque cliente.

Remarque : Les types de données sont convertis en fonction de la valeur, et non du type de champ dans le schéma d’index. Cela signifie que si vous avez une chaîne date ISO8601 (par exemple, « 2020-03-06T18:48:27.896Z ») comme valeur d’un champ, elle sera convertie en date, quelle que soit la façon dont vous l’avez stockée dans votre schéma.

Exemples

Les exemples suivants illustrent les bases - veuillez consulter nos échantillons pour en savoir plus.

Créer un index

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

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

const result = await indexClient.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(`Index created with name ${result.name}`);

Récupérer un document spécifique à partir d’un index

Un document spécifique peut être récupéré par sa valeur de clé primaire :

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

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

const result = await searchClient.getDocument("1234");

Ajout de documents dans un index

Vous pouvez charger plusieurs documents dans un index à l’intérieur d’un lot :

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

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

const uploadResult = await searchClient.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}`);
}

Effectuer une recherche sur des documents

Pour répertorier tous les résultats d’une requête particulière, vous pouvez utiliser search une chaîne de recherche qui utilise une syntaxe de requête simple :

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

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

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

Pour une recherche plus poussée qui utilise la syntaxe Lucene, spécifiez queryType à :full

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

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

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

Interrogation avec TypeScript

Dans TypeScript, SearchClient prend un paramètre générique qui est la forme du modèle de vos documents d’index. Cela vous permet d’effectuer une recherche fortement typée de champs retournés dans les résultats. TypeScript est également capable de vérifier les champs renvoyés lors de la spécification d’un select paramètre.

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 searchClient = new SearchClient<Hotel>(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
);

const searchResults = await searchClient.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);
}

Interrogation avec des filtres OData

L’utilisation du filter paramètre query vous permet d’interroger un index à l’aide de la syntaxe d’une expression $filter OData.

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

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

const baseRateMax = 200;
const ratingMin = 4;
const searchResults = await searchClient.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);
}

Interrogation avec des vecteurs

Les plongements de texte peuvent être interrogés à l’aide du vector paramètre de recherche. Pour plus d’informations, consultez Vecteurs de requête et Requêtes de vecteur de filtre.

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

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

const queryVector: number[] = [
  // Embedding of the query "What are the most luxurious hotels?"
];
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);
}

Interrogation avec des facettes

Les facettes sont utilisées pour aider un utilisateur de votre application à affiner une recherche selon des dimensions préconfigurées. La syntaxe Facet fournit les options permettant de trier et de regrouper les valeurs de facette.

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

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

const searchResults = await searchClient.search("WiFi", {
  facets: ["category,count:3,sort:count", "rooms/baseRate,interval:100"],
});
console.log(searchResults.facets);

Lors de la récupération des résultats, une facets propriété sera disponible qui indiquera le nombre de résultats qui tombent dans chaque compartiment de facettes. Cela peut être utilisé pour favoriser le raffinement (par exemple, en émettant une recherche de suivi qui filtre sur l’être Rating supérieur ou égal à 3 et inférieur à 4).

Dépannage

Exploitation forestière

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentationdu package @azure/enregistreur d’événements.

Étapes suivantes

Contribuant

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Ce projet accueille les contributions et suggestions. La plupart des contributions vous obligent à accepter un contrat de licence contributeur (CLA) déclarant que vous avez le droit, et en fait, de nous accorder les droits d’utilisation de votre contribution. Pour plus de détails, visitez cla.microsoft.com.

Ce projet a adopté le Code de conduite Open Source Microsoft. Pour plus d’informations, consultez le forum aux questions du Code de conduite ou contactez avec des questions ou commentaires supplémentaires.

  • Last updated on