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

  • Artikel

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

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

  • Konsolidieren Sie verschiedene Inhaltstypen in einem einzigen durchsuchbaren Index. Um einen Index aufzufüllen, können Sie JSON-Dokumente pushen, die Ihre Inhalte enthalten. Wenn sich Ihre Daten bereits in Azure befinden, können Sie einen Indexer erstellen, um Daten automatisch zu pullen.
  • Fügen Sie Skillsets an einen Indexer an, um durchsuchbare Inhalte aus Bildern und umfangreichen Textdokumenten zu erstellen. Ein Skillset nutzt APIs aus KI-Diensten für integrierte OCR, Entitätserkennung, Schlüsselbegriffsextraktion, Spracherkennung, Textübersetzung und Stimmungsanalyse. Sie können auch benutzerdefinierte Fähigkeiten hinzufügen, um die externe Verarbeitung Ihrer Inhalte während der Datenerfassung zu integrieren.
  • Implementieren Sie in einer Suchclientanwendung Abfragelogik und Benutzeroberflächen, die kommerziellen Websuchmaschinen ähneln.

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

  • Übermitteln Sie Abfragen mithilfe von Vektor-, Schlüsselwort (keyword)- und Hybridabfrageformularen.
  • Implementieren Sie gefilterte Abfragen für Metadaten, georäumliche Suche, Facettennavigation oder zum Einschränken von Ergebnissen basierend auf Filterkriterien.
  • Erstellen und Verwalten von Suchindizes
  • Hochladen und Aktualisieren von Dokumenten im Suchindex
  • Erstellen und Verwalten von Indexern, die Daten aus Azure in einen Index abrufen.
  • Erstellen und verwalten Sie Skillsets, die der Datenerfassung KI-Anreicherung hinzufügen.
  • Erstellen und verwalten Sie Analysetools für erweiterte Textanalyse oder mehrsprachige Inhalte.
  • Optimieren Sie Ergebnisse durch Bewertungsprofile, um Geschäftslogik oder Aktualität zu berücksichtigen.

Wichtige Links:

Erste Schritte

Installieren Sie das Paket @azure/search-documents.

npm install @azure/search-documents

Die derzeitig unterstützten Umgebungen

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

Um einen neuen Suchdienst zu erstellen, können Sie die Azure-Portal, Azure PowerShell oder die Azure CLI verwenden. Hier sehen Sie ein Beispiel für die Verwendung der Azure CLI, um eine kostenlose instance für die ersten Schritte zu erstellen:

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

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

Authentifizieren des Clients

Um mit dem Suchdienst zu interagieren, müssen Sie eine instance der entsprechenden Clientklasse erstellen: SearchClient für die Suche nach indizierten Dokumenten, SearchIndexClient zum Verwalten von Indizes oder SearchIndexerClient zum Durchforsten von Datenquellen und Zum 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, da er keine bereits vorhandenen Rollenzuweisungen erfordert.

Sie können den Endpunkt und einen API-Schlüssel aus dem Suchdienst im Azure-Portal abrufen. 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 --service-name <mysearch> --resource-group <mysearch-rg>

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 nationalen Cloud zu authentifizieren, müssen Sie die folgenden Ergänzungen zu Ihrer Clientkonfiguration vornehmen:

  • Festlegen des in AudienceSearchClientOptions
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,
});

Wichtige Begriffe

Ein Azure KI-Suchdienst enthält einen oder mehrere Indizes, die eine dauerhafte Speicherung durchsuchbarer Daten in Form von JSON-Dokumenten bereitstellen. (Wenn Sie bei der Suche noch ganz neu sind, können Sie eine sehr grobe Analogie zwischen Indizes und Datenbanktabellen machen.) Die @azure/search-documents Clientbibliothek macht Vorgänge für diese Ressourcen über drei Standard Clienttypen verfügbar.

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

TypeScript/JavaScript-spezifische Konzepte

Dokumente

Ein In einem Suchindex gespeichertes Element. Die Form dieses Dokuments wird im Index mit Fields beschrieben. Jedes Feld hat einen Namen, einen Datentyp und zusätzliche Metadaten, z. B. ob es durchsuchbar oder filterbar ist.

Paginierung

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

Dokumentfeldcodierung

Unterstützte Datentypen in einem Index werden JSON-Typen in API-Anforderungen/-Antworten zugeordnet. Die JS-Clientbibliothek behält diese mit einigen Ausnahmen weitgehend bei:

  • 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, aber von der Clientbibliothek wieder in number konvertiert.

Hinweis: Datentypen werden basierend auf dem Wert konvertiert, nicht auf dem Feldtyp im Indexschema. Wenn Sie also eine ISO8601 Date-Zeichenfolge (z. B. "2020-03-06T18:48:27.896Z") als Wert eines Felds haben, wird diese unabhängig davon, wie Sie es in Ihrem Schema gespeichert haben, in ein Datum konvertiert.

Beispiele

Die folgenden Beispiele veranschaulichen die Grundlagen . Weitere Informationen finden Sie in unseren Beispielen .

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 mit seinem Primärschlüsselwert 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 innerhalb eines Batches 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

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

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-Syntax verwendet, geben Sie folgendes an queryTypefull:

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

Nimmt in TypeScript einen generischen Parameter an, SearchClient der die Modellform Ihrer Indexdokumente darstellt. Dadurch können Sie stark typisierte Suchvorgänge von Feldern durchführen, die in den 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> | 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();

Abfragen mit OData-Filtern

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

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.

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

Abfragen mit Facetten

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

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 Verfeinerung zu fördern (z. B. eine Nachverfolgungssuche, die nach größer Rating oder gleich 3 und kleiner als 4 filtert.)

Problembehandlung

Protokollierung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in der Paketdokumentation zu @azure/logger.

Nächste Schritte

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Dieses Projekt hat den Microsoft Open Source Code of Conduct übernommen. Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex , oder wenden Sie sich an opencode@microsoft.com weitere Fragen oder Kommentare.

Aufrufe