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

  • Artikel

Azure AI Search (früher als "Azure Cognitive Search" bezeichnet) ist eine KI-basierte Informationsempfangsplattform, die Entwicklern hilft, umfangreiche Sucherfahrungen und generative KI-Apps zu erstellen, 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, um:

  • Ü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 des @azure/search-documents-Pakets

npm install @azure/search-documents

Derzeit unterstützte Umgebungen

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Voraussetzungen

Zum Erstellen eines neuen Suchdiensts 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 verfügbaren Optionen finden Sie unter Auswahl einer Preisstufe.

Authentifizieren des Clients

Um mit dem Suchdienst zu interagieren, müssen Sie eine Instanz der entsprechenden Clientklasse erstellen: SearchClient zum Suchen indizierte 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 abrufen, aus dem Suchdienst im Azure-Portal. Anweisungen zum Abrufen eines API-Schlüssels finden Sie in der Dokumentation.

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 für den Zugriff auf Ihren Suchdienst: Administrator-(Lese-/Schreibzugriff) und Abfrage-(schreibgeschützt) Schlüssel. 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: Der oben beschriebene Azure CLI-Codeausschnitt ruft einen Administratorschlüssel ab, sodass es einfacher ist, APIs zu erkunden, aber es sollte sorgfältig verwaltet werden.

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

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

Authentifizieren in einer nationalen Cloud

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

  • Festlegen der Audience in 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,
});

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 völlig neu für die Suche sind, können Sie eine sehr grobe Analogie zwischen Indizes und Datenbanktabellen erstellen.) Die @azure/search-documents-Clientbibliothek macht Vorgänge für diese Ressourcen über drei Hauptclienttypen verfügbar.

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

TypeScript/JavaScript-spezifische Konzepte

Urkunden

Ein Element, das in einem Suchindex gespeichert ist. Die Form dieses Dokuments wird im Index mithilfe der fields-Eigenschaft beschrieben. Jede SearchField hat einen Namen, einen Datentyp und zusätzliche Metadaten, z. B. ob sie durchsuchbar oder gefiltert werden kann.

Paginierung

In der Regel möchten Sie nur eine Teilmenge von Suchergebnissen für einen Benutzer gleichzeitig anzeigen. Um dies zu unterstützen, können Sie die Parameter top, skip und includeTotalCount verwenden, um eine seitenseitige Erfahrung über suchergebnisse bereitzustellen.

Dokumentfeldcodierung

Unterstützten Datentypen in einem Index werden JSON-Typen in API-Anforderungen/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 als Zeichenfolgen in der REST-API serialisiert, werden jedoch von der Clientbibliothek zurück in number konvertiert.

Hinweis: Datentypen werden basierend auf dem Wert und nicht 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 veranschaulichen die Grundlagen - bitte sehen Sie sich unsere Beispiele für vieles mehr an.

Erstellen eines Indexes

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

Abrufen eines bestimmten Dokuments aus einem Index

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

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

Hinzufügen von Dokumenten zu einem Index

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

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

Durchführen einer Suche nach Dokumenten

Zum Auflisten aller Ergebnisse einer bestimmten Abfrage können Sie search mit einer Suchzeichenfolge verwenden, die einfache Abfragesyntaxverwendet:

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

Für eine erweiterte Suche, die Lucene-Syntaxverwendet, geben Sie queryType an, die fullwerden sollen:

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

Abfragen mit TypeScript

In TypeScript akzeptiert SearchClient einen generischen Parameter, der die Modellform Ihrer Indexdokumente ist. Auf diese Weise können Sie stark typierte Nachschlagevorgänge von Feldern ausführen, die in Ergebnissen zurückgegeben werden. TypeScript kann auch nach Feldern 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 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();

Abfragen mit OData-Filtern

Mithilfe des filter Abfrageparameters können Sie einen Index mithilfe der Syntax eines OData-$filter Ausdrucksabfragen.

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

Abfragen mit Vektoren

Texteinbettungen können mithilfe des vector Suchparameters abgefragt werden. Weitere Informationen finden Sie unter Abfragevektoren und Filtervektorabfragen.

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

Abfragen mit Facets

Facets- werden verwendet, um einem Benutzer Ihrer Anwendung zu helfen, eine Suche entlang vordefinierter Dimensionen zu verfeinern. Facetsyntax bietet die Optionen zum Sortieren und Bucket-Facetwert.

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

Beim Abrufen von Ergebnissen ist eine facets-Eigenschaft verfügbar, die die Anzahl der Ergebnisse angibt, die in jeden Facet-Bucket fallen. Dies kann verwendet werden, um die Einschränkung zu fördern (z. B. das Ausgeben einer Nachverfolgungssuche, die nach dem 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 mitwirkenden Leitfaden, 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.

Aufrufe