Freigeben über

Azure AI Search-Clientbibliothek für JavaScript – Version 12.2.0

Azure AI Search (ehemals als "Azure Cognitive Search" bezeichnet) ist eine KI-gestützte Plattform zum Abrufen von Informationen, mit der Entwickler umfassende Suchumgebungen und generative KI-Apps erstellen können, die große Sprachmodelle mit Unternehmensdaten kombinieren.

Der Azure AI Search-Dienst eignet sich gut für die folgenden Anwendungsszenarien:

  • Konsolidieren Sie verschiedene Inhaltstypen in einem einzigen durchsuchbaren Index. Zum Auffüllen eines Indexes können Sie JSON-Dokumente, die Ihre Inhalte enthalten, pushen, oder wenn Ihre Daten bereits in Azure vorhanden sind, einen Index erstellen, um Daten automatisch abzurufen.
  • Fügen Sie Skillsets an einen Indexer an, um durchsuchbare Inhalte aus Bildern und unstrukturierten Dokumenten zu erstellen. Ein Skillset nutzt APIs von Azure AI Services für integrierte OCR,Entitätserkennung, Schlüsselausdruckextraktion, Spracherkennung, Textübersetzung und Stimmungsanalyse. Sie können auch benutzerdefinierte Fähigkeiten hinzufügen, um die externe Verarbeitung Ihrer Inhalte während der Datenaufnahme zu integrieren.
  • Implementieren Sie in einer Suchclientanwendung Abfragelogik und Benutzeroberflächen ähnlich wie kommerzielle Websuchmaschinen und Chat-Apps.

Verwenden Sie die @azure/search-documents Clientbibliothek für folgende Zwecke:

  • Übermitteln von Abfragen mithilfe von Vektor-, Schlüsselwort- und Hybridabfrageformularen.
  • Implementieren Sie gefilterte Abfragen für Metadaten, geospatiale Suche, faceted Navigation oder einschränken Sie Ergebnisse basierend auf Filterkriterien.
  • Erstellen und Verwalten von Suchindizes.
  • Laden Sie Dokumente im Suchindex hoch und aktualisieren Sie sie.
  • Erstellen und verwalten Sie Indexer, die Daten aus Azure in einen Index abrufen.
  • Erstellen und verwalten Sie Skillsets, die KI-Anreicherung zur Datenaufnahme hinzufügen.
  • Erstellen und Verwalten von Analyzern für erweiterte Textanalyse oder mehrsprachige Inhalte.
  • Optimieren Sie Ergebnisse durch semantische Bewertungs- und Bewertungsprofile, um die Geschäftslogik oder Aktualität zu berücksichtigen.

Wichtige Links:

Erste Schritte

Installieren Sie das @azure/search-documents-Paket

npm install @azure/search-documents

Derzeit unterstützte Umgebungen

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

Um einen neuen Suchdienst zu erstellen, können Sie das Azure-Portal, Azure PowerShell oder die Azure CLI verwenden. Im Folgenden finden Sie ein Beispiel für die Verwendung der Azure CLI zum Erstellen einer kostenlosen Instanz für die ersten Schritte:

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

Weitere Informationen zu den verfügbaren Optionen finden Sie unter Auswählen eines Tarifs .

Authentifizieren des Clients

Um mit dem Suchdienst interagieren zu können, müssen Sie eine Instanz der entsprechenden Clientklasse erstellen: SearchClient zum Durchsuchen indizierter Dokumente, SearchIndexClient zum Verwalten von Indizes oder SearchIndexerClient zum Durchforsten von Datenquellen und Laden von Suchdokumenten in einen Index. Zum Instanziieren eines Clientobjekts benötigen Sie einen Endpunkt und Azure-Rollen oder einen API-Schlüssel. Weitere Informationen zu unterstützten Authentifizierungsansätzen mit dem Suchdienst finden Sie in der Dokumentation.

Abrufen eines API-Schlüssels

Ein API-Schlüssel kann ein einfacherer Ansatz sein, um damit zu beginnen, da es keine bereits vorhandenen Rollenzuweisungen erfordert.

Sie können den Endpunkt und einen API-Schlüssel über den Suchdienst im Azure-Portal abrufen. In der Dokumentation finden Sie Anweisungen, wie Sie einen API-Schlüssel erhalten.

Alternativ können Sie den folgenden Azure CLI-Befehl verwenden, um den API-Schlüssel aus dem Suchdienst abzurufen:

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

Es gibt zwei Arten von Schlüsseln, die für den Zugriff auf Ihren Suchdienst verwendet werden: admin-Schlüssel (Lese-/Schreibzugriff) und Abfrageschlüssel(schreibgeschützt). Das Einschränken des Zugriffs und der Vorgänge in Client-Apps ist unerlässlich, um die Suchressourcen in Ihrem Dienst zu schützen. Verwenden Sie immer einen Abfrageschlüssel anstelle eines Administratorschlüssels für jede Abfrage, die von einer Client-App stammt.

Hinweis: Das obige Beispiel für einen Azure CLI-Codeausschnitt ruft einen Administratorschlüssel ab, sodass der Einstieg in die Erkundung von APIs einfacher ist, aber er sollte sorgfältig verwaltet werden.

Sobald Sie über einen API-Schlüssel verfügen, können Sie ihn wie folgt verwenden:

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

Authentifizieren in einer nationalen Cloud

Um sich in einer National Cloud zu authentifizieren, müssen Sie die folgenden Ergänzungen zu Ihrer Clientkonfiguration vornehmen:

  • Legen Sie die Audience in SearchClientOptions
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,
});

Schlüsselkonzepte

Ein Azure AI Search-Dienst enthält einen oder mehrere Indizes, die beständigen Speicher durchsuchbarer Daten in Form von JSON-Dokumenten bereitstellen. (Wenn Sie ganz neu in der Suche sind, können Sie eine sehr grobe Analogie zwischen Indizes und Datenbanktabellen herstellen.) Die @azure/search-documents Clientbibliothek macht Vorgänge für diese Ressourcen über drei Hauptclienttypen verfügbar.

Hinweis: Diese Clients können im Browser nicht funktionieren, da die APIs, die sie aufrufen, keine Unterstützung für Cross-Origin Resource Sharing (CORS) bieten.

TypeScript/JavaScript-spezifische Konzepte

Urkunden

Ein Element, das in einem Suchindex gespeichert ist. Die Form dieses Dokuments wird im Index mit der Eigenschaft beschrieben fields . Jeder SearchField verfügt über einen Namen, einen Datentyp und zusätzliche Metadaten, z. B. ob er durchsuchbar oder filterbar ist.

Paginierung

In der Regel möchten Sie einem Benutzer jeweils nur eine Teilmenge der Suchergebnisse anzeigen . Um dies zu unterstützen, können Sie die topParameter und skip verwenden, includeTotalCount um eine ausgelagerte Benutzeroberfläche über den Suchergebnissen bereitzustellen.

Dokumentfeldcodierung

Unterstützte Datentypen in einem Index werden JSON-Typen in API-Anfragen/-Antworten zugeordnet. Die JS-Clientbibliothek hält diese meist gleich, mit einigen Ausnahmen:

  • Edm.DateTimeOffset wird in ein JS Datekonvertiert.
  • Edm.GeographyPoint wird in einen GeographyPoint Typ konvertiert, der von der Clientbibliothek exportiert wird.
  • Spezielle Werte des number Typs (NaN, Infinity -Infinity) werden in der REST-API als Zeichenfolgen serialisiert, aber von der Clientbibliothek wieder number konvertiert.

Hinweis: Datentypen werden basierend auf dem Wert und nicht auf dem Feldtyp im Indexschema konvertiert. Dies bedeutet: Wenn Sie über eine ISO8601 Datumszeichenfolge (z. B. "2020-03-06T18:48:27.896Z") als Wert eines Felds verfügen, wird sie unabhängig davon, wie Sie es in Ihrem Schema gespeichert haben, in ein Datum konvertiert.

Beispiele

Die folgenden Beispiele zeigen die Grundlagen - schauen Sie sich unsere Beispiele an, um mehr zu erfahren.

Erstellen eines Indexes

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}`);

Abrufen eines bestimmten Dokuments aus einem Index

Ein bestimmtes Dokument kann anhand seines Primärschlüsselwerts abgerufen werden:

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

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

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

Hinzufügen von Dokumenten zu einem Index

Sie können mehrere Dokumente in einen Index in einem Batch hochladen:

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}`);
}

Durchführen einer Suche nach Dokumenten

Um alle Ergebnisse einer bestimmten Abfrage aufzulisten, können Sie eine Suchzeichenfolge verwenden search , die eine einfache Abfragesyntax verwendet:

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

Für eine erweiterte Suche, die die Lucene-Syntax verwendet, geben Sie Folgendes anqueryType: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);
}

Abfragen mit TypeScript

In TypeScript wird ein generischer Parameter verwendet, SearchClient der die Modellform Ihrer Indexdokumente darstellt. Auf diese Weise können Sie stark typierte Nachschlagevorgänge von Feldern ausführen, die in Ergebnissen zurückgegeben werden. TypeScript ist auch in der Lage, nach Feldern zu suchen, die beim Angeben eines select Parameters zurückgegeben werden.

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

Abfragen mit OData-Filtern

Mit dem filter query-Parameter können Sie einen Index mit der Syntax eines OData-$filter-Ausdrucks abfragen.

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

Abfragen mit Vektoren

Texteinbettungen können über den vector Suchparameter abgefragt werden. Weitere Informationen finden Sie unter Abfragevektoren und Filtern von Vektorabfragen .

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

Abfragen mit Facets

Facetten werden verwendet, um einem Benutzer Ihrer Anwendung zu helfen, eine Suche entlang vorkonfigurierter Dimensionen zu verfeinern. Die Facettensyntax bietet die Optionen zum Sortieren und Zuordnen von Facettenwerten.

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

Beim Abrufen von Ergebnissen ist eine facets Eigenschaft verfügbar, die die Anzahl der Ergebnisse angibt, die in die einzelnen Facetten-Buckets fallen. Dies kann verwendet werden, um die Verfeinerung voranzutreiben (z. B. indem eine Folgesuche durchgeführt wird, die danach filtert, ob sie Rating größer oder gleich 3 und kleiner als 4 ist).

Fehlerbehebung

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Nächste Schritte

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den Beitragsleitfaden , um mehr über das Erstellen und Testen des Codes zu erfahren.

Dieses Projekt begrüßt Beiträge und Vorschläge. Die meisten Beiträge erfordern, dass Sie einem Mitwirkenden-Lizenzvertrag (CLA) zustimmen, der erklärt, dass Sie das Recht haben, uns tatsächlich die Rechte zur Nutzung Ihres Beitrags zu gewähren. Weitere Informationen finden Sie unter cla.microsoft.com.

Dieses Projekt hat den Microsoft Open Source Code of Conductübernommen. Weitere Informationen finden Sie im Code of Conduct FAQ oder wenden Sie sich an opencode@microsoft.com mit weiteren Fragen oder Kommentaren.

  • Last updated on