Bibliothèque de client Azure AI Search pour JavaScript - version 12.0.0

  • Article

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 d’IA génératives qui combinent des modèles de langage volumineux avec des données d’entreprise.

Azure AI Search est bien adapté aux scénarios d’application suivants :

  • Regroupez les types de contenu variés dans un seul index pouvant faire l’objet d’une recherche. Pour remplir un index, vous pouvez envoyer (push) des documents JSON qui contiennent votre contenu ou, si vos données sont déjà dans Azure, créer un indexeur pour extraire automatiquement les données.
  • Joignez 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 texte volumineux. Un ensemble de compétences tire parti des API des services d’IA pour l’OCR intégrée, 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.

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

  • Envoyer des requêtes à l’aide de formulaires de requête vectoriels, mot clé 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 de critères de filtre.
  • Créer et gérer des index de recherche.
  • Charger et mettre à 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 des données.
  • Créez et gérez des analyseurs pour l’analyse de texte avancée ou le contenu multilingue.
  • Optimisez les résultats via des profils de scoring pour prendre en compte la logique métier ou l’actualisation.

Liens clés :

Prise en main

Installez le package @azure/search-documents

npm install @azure/search-documents

Environnements actuellement pris en charge

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

Prérequis

Pour créer un service de recherche, vous pouvez utiliser le Portail Azure, Azure PowerShell ou Azure CLI. Voici un exemple d’utilisation d’Azure CLI pour créer un instance gratuit pour la prise en main :

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

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

Authentifier le client

Pour interagir avec le service de recherche, vous devez créer un instance de la classe client appropriée : SearchClient pour la recherche de documents indexés, SearchIndexClient pour la gestion des index ou SearchIndexerClient pour l’analyse des sources de données et le chargement de documents de recherche dans un index.

Pour instancier un objet client, vous avez besoin d’un point de terminaison et de rôles Azure ou d’une clé API. Vous pouvez consulter 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 facile 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 --service-name <mysearch> --resource-group <mysearch-rg>

Une fois que vous avez 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 cloud national, vous devez effectuer les ajouts suivants à votre configuration client :

  • Définir le 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 Search Azure AI contient un ou plusieurs index qui fournissent un stockage persistant de données pouvant faire l’objet d’une recherche sous forme de documents JSON. (Si vous débutez dans la recherche, vous pouvez faire une analogie très approximative 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 via trois types de clients main.

Remarque : Ces clients ne peuvent pas fonctionner dans le navigateur, car les API qu’il appelle ne prennent pas en charge CORS (Cross-Origin Resource Sharing).

Concepts spécifiques à TypeScript/JavaScript

Documents

Élément stocké dans un index de recherche. La forme de ce document est décrite dans l’index à l’aide Fieldde . Chaque champ a un nom, un type de données et des métadonnées supplémentaires, comme s’il peut faire l’objet d’une recherche ou d’un filtre.

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 prendre en charge cela, vous pouvez utiliser les topparamètres et skipincludeTotalCount pour fournir une expérience paginée au-dessus des résultats de la recherche.

Encodage des champs de document

Les 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 cliente JS conserve ces éléments pour la plupart identiques, avec quelques exceptions :

  • Edm.DateTimeOffset est converti en JS Date.
  • Edm.GeographyPoint est converti en type GeographyPoint 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 reconvertes number en 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 est 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 : veuillez case activée nos exemples pour bien plus.

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 une 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 la syntaxe Lucene, spécifiez queryType comme suit 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 des champs retournés dans les résultats. TypeScript peut également case activée pour les champs retourné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> | 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();

Interrogation avec des filtres OData

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

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 vector paramètre de recherche.

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

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 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 facets propriété est disponible qui indique le nombre de résultats qui se trouvent dans chaque compartiment de facettes. Cela peut être utilisé pour améliorer l’affinement (par exemple, émettre une recherche de suivi qui filtre sur l’être Rating supérieur ou égal à 3 et inférieur à 4.)

Résolution des problèmes

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir 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 @azure/logger :

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Étapes suivantes

Contribution

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 accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Ce projet a adopté le code de conduite Open Source de Microsoft. Pour plus d’informations, consultez le FAQ sur le code de conduite ou contactez-nous opencode@microsoft.com pour toute question ou commentaire supplémentaire.

Impressions