Bibliothèque de client Recherche d’IA Azure pour JavaScript - version 12.1.0

Article
08/03/2024

Azure AI Search (anciennement « Recherche cognitive Azure ») 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 IA génératives qui combinent des modèles de langage volumineux 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 :

code source
package (NPM)
Documentation de référence de l’API
documentation de l’API REST
documentation produit
Exemples

Commencer

Installer le package `@azure/search-documents`

npm install @azure/search-documents

Environnements actuellement pris en charge

versions LTS de Node.js
Dernières versions de Safari, Chrome, Microsoft Edge et Firefox.

Pour plus d’informations, consultez notre de stratégie de support .

Conditions préalables

Un abonnement Azure
Un service de recherche

Pour créer un service de recherche, vous pouvez utiliser ledu portail Azure , l'Azure PowerShell ou le 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

Consultez choisir un niveau tarifaire pour plus d’informations sur les options disponibles.

Authentifier le client

Pour interagir avec le service de recherche, vous devez créer une instance de la classe cliente appropriée : SearchClient pour rechercher des documents indexés, SearchIndexClient pour gérer les index ou SearchIndexerClient pour analyser les sources de données et charger des documents de recherche dans un index. Pour instancier un objet client, vous aurez besoin d’un point de terminaison et rôles Azure ou d’une clé API . Vous pouvez consulter la documentation pour plus d’informations sur 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 . Reportez-vous à la documentation pour obtenir des instructions sur l’obtention d’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és pour accéder à votre service de recherche : d’administration (en lecture-écriture) et de requête (en lecture seule) clés. 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 afin qu’il soit plus facile de commencer à explorer les API, mais il doit être géré avec soin.

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

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

S’authentifier dans un cloud national

Pour vous authentifier dans un National Cloud, vous devez effectuer les ajouts suivants à votre configuration cliente :

Définir la Audience dans 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,
});

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 êtes tout nouveau à rechercher, vous pouvez faire une analogie très approximative entre les index et les tables de base de données.) La bibliothèque cliente @azure/search-documents expose des opérations sur ces ressources via trois types de clients principaux.

SearchClient aide à :
- recherche vos documents indexés à l’aide de requêtes vectorielles , de requêtes de mots clés et de requêtes hybrides
- filtres de requête Vector et filtres de requête texte
- le classement sémantique et les profils de scoring pour améliorer la pertinence
- complétation automatique termes de recherche partiellement typés en fonction des documents de l’index
- Suggérer le texte le plus probable correspondant dans les documents en tant qu’utilisateur
- ajout, mise à jour ou suppression de documents documents à partir d’un index
SearchIndexClient vous permet de :
- Créer, supprimer, mettre à jour ou configurer un index de recherche
- Déclarer des mappages de synonymes personnalisés pour développer ou réécrire des requêtes
SearchIndexerClient vous permet de :
- indexeurs de démarrage pour analyser automatiquement les sources de données
- Définir des ensembles de compétences optimisés pour l’IA pour transformer et enrichir vos données

Remarque: ces clients ne peuvent pas fonctionner dans le navigateur, car les API qu’il appelle n’ont pas de prise en charge du partage de ressources cross-origin (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 propriété fields. Chaque SearchField a un nom, un type de données et des métadonnées supplémentaires, comme s’il est pouvant faire l’objet d’une recherche ou d’un filtrage.

Pagination

En règle générale, vous ne souhaiterez afficher un sous-ensemble de résultats de recherche à un utilisateur à la fois. Pour ce faire, vous pouvez utiliser les paramètres top, skip et includeTotalCount pour fournir une expérience paginée en plus des résultats de recherche.

Encodage de champ de document

types de données pris en charge dans un index sont mappés aux types JSON dans les requêtes/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 DateJS .
Edm.GeographyPoint est converti en type GeographyPoint exporté par la bibliothèque cliente.
Les valeurs spéciales du type number (NaN, Infinity, -Infinity) sont sérialisées en tant que chaînes dans l’API REST, mais sont converties en 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 principes de base : consultez nos exemples pour plus d’informations.

Création d’un d’index
Récupération d’un document spécifique à partir de votre d’index
Ajout de documents à votre d’index
effectuer une recherche sur les documents
- interrogation avec typeScript
- interrogation avec des filtres OData
- interrogation avec des facettes

Créer un index

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

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 :

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

Ajout de documents dans un index

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

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

Effectuer une recherche sur des documents

Pour répertorier tous les résultats d’une requête particulière, vous pouvez utiliser search avec une chaîne de recherche qui utilise syntaxe de requête 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();

Pour une recherche plus avancée qui utilise syntaxe Lucene, spécifiez queryType à 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();

Interrogation avec TypeScript

Dans TypeScript, SearchClient prend un paramètre générique qui est la forme de 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 en mesure de vérifier les champs retournés lors de la spécification d’un paramètre 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();

Interrogation avec des filtres OData

L’utilisation du paramètre de requête filter vous permet d’interroger un index à l’aide de la syntaxe d’une expression 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();

Interrogation avec des vecteurs

Les incorporations de texte peuvent être interrogées à l’aide du paramètre de recherche vector. Pour plus d’informations, consultez et requêtes de vecteurs de filtre.

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

facettes sont utilisées pour aider un utilisateur de votre application à affiner une recherche en fonction des dimensions préconfigurées. syntaxe facette fournit les options permettant de trier et de compartimenter les valeurs de facette.

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

Lors de la récupération des résultats, une propriété facets sera disponible qui indiquera le nombre de résultats qui tombent dans chaque compartiment de facettes. Cela peut être utilisé pour stimuler l’affinement (par exemple, l’émission d’une recherche de suivi qui filtre sur le Rating étant 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 d’informations, visitez cla.microsoft.com.

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

Kit de développement logiciel (SDK) Microsoft Azure pour javaScript

Impressions

Partager via

Bibliothèque de client Recherche d’IA Azure pour JavaScript - version 12.1.0

Commencer

Installer le package `@azure/search-documents`

Environnements actuellement pris en charge

Conditions préalables

Authentifier le client

Obtenir une clé API

S’authentifier dans un cloud national

Concepts clés

Concepts spécifiques de TypeScript/JavaScript

Documents

Encodage de champ de document

Exemples

Créer un index

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

Ajout de documents dans un index

Effectuer une recherche sur des documents

Interrogation avec TypeScript

Interrogation avec des filtres OData

Interrogation avec des vecteurs

Interrogation avec des facettes

Dépannage

Exploitation forestière

Étapes suivantes

Contribuant

Ressources supplémentaires

Partager via

Bibliothèque de client Recherche d’IA Azure pour JavaScript - version 12.1.0

Commencer

Installer le package @azure/search-documents

Environnements actuellement pris en charge

Conditions préalables

Authentifier le client

Obtenir une clé API

S’authentifier dans un cloud national

Concepts clés

Concepts spécifiques de TypeScript/JavaScript

Documents

Pagination

Encodage de champ de document

Exemples

Créer un index

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

Ajout de documents dans un index

Effectuer une recherche sur des documents

Interrogation avec TypeScript

Interrogation avec des filtres OData

Interrogation avec des vecteurs

Interrogation avec des facettes

Dépannage

Exploitation forestière

Étapes suivantes

Contribuant

Projets connexes

Ressources supplémentaires

Installer le package `@azure/search-documents`