Udostępnij za pośrednictwem

Biblioteka klienta usługi Azure AI Search dla języka JavaScript — wersja 12.1.0

  • Artykuł

azure AI Search (dawniej "Azure Cognitive Search") to platforma pobierania informacji oparta na sztucznej inteligencji, która ułatwia deweloperom tworzenie zaawansowanych środowisk wyszukiwania i generowanie aplikacji sztucznej inteligencji, które łączą duże modele językowe z danymi przedsiębiorstwa.

Usługa Azure AI Search jest odpowiednia dla następujących scenariuszy aplikacji:

  • Konsolidowanie różnych typów zawartości w jeden indeks z możliwością wyszukiwania. Aby wypełnić indeks, możesz wypchnąć dokumenty JSON zawierające zawartość lub jeśli dane znajdują się już na platformie Azure, utwórz indeksator, aby automatycznie ściągać dane.
  • Dołącz zestawy umiejętności do indeksatora, aby utworzyć zawartość z możliwością wyszukiwania na podstawie obrazów i dokumentów bez struktury. Zestaw umiejętności korzysta z interfejsów API z usług Azure AI Services na potrzeby wbudowanego rozpoznawania OCR, rozpoznawania jednostek, wyodrębniania kluczowych fraz, wykrywania języka, tłumaczenia tekstu i analizy tonacji. Możesz również dodać niestandardowe umiejętności, aby zintegrować zewnętrzne przetwarzanie zawartości podczas pozyskiwania danych.
  • W aplikacji klienckiej wyszukiwania zaimplementuj logikę zapytań i środowiska użytkownika podobne do komercyjnych wyszukiwarek internetowych i aplikacji w stylu czatu.

Użyj biblioteki klienta @azure/search-documents, aby:

  • Przesyłanie zapytań przy użyciu formularzy wektorów, słów kluczowych i hybrydowych zapytań.
  • Zaimplementuj zapytania filtrowane pod kątem metadanych, wyszukiwania geoprzestrzennego, nawigacji aspektowej lub zawężaj wyniki na podstawie kryteriów filtrowania.
  • Tworzenie indeksów wyszukiwania i zarządzanie nimi.
  • Przekazywanie i aktualizowanie dokumentów w indeksie wyszukiwania.
  • Tworzenie indeksatorów ściągających dane z platformy Azure do indeksu i zarządzanie nimi.
  • Twórz zestawy umiejętności, które dodają wzbogacanie sztucznej inteligencji do pozyskiwania danych i zarządzaj nimi.
  • Tworzenie analizatorów i zarządzanie nimi na potrzeby zaawansowanej analizy tekstu lub zawartości wielojęzycznej.
  • Optymalizowanie wyników dzięki profilom klasyfikacji semantycznej i oceniania, aby uwzględnić logikę biznesową lub świeżość.

Kluczowe linki:

  • kod źródłowy
  • pakietu (NPM)
  • Dokumentacja referencyjna interfejs u API
  • dokumentacja interfejsu API REST
  • dokumentacja produktu
  • przykładów

Wprowadzenie

Instalowanie pakietu @azure/search-documents

npm install @azure/search-documents

Obecnie obsługiwane środowiska

  • wersje Node.js LTS
  • Najnowsze wersje przeglądarek Safari, Chrome, Microsoft Edge i Firefox.

Aby uzyskać więcej informacji, zobacz nasze zasad pomocy technicznej.

Warunki wstępne

  • subskrypcji platformy Azure
  • usługi wyszukiwania

Aby utworzyć nową usługę wyszukiwania, możesz użyć witryny Azure Portal, programu Azure PowerShelllub interfejsu wiersza polecenia platformy Azure . Oto przykład użycia interfejsu wiersza polecenia platformy Azure do utworzenia bezpłatnego wystąpienia na potrzeby rozpoczynania pracy:

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

Aby uzyskać więcej informacji na temat dostępnych opcji, zobacz wybieranie warstwy cenowej.

Uwierzytelnianie klienta

Aby wchodzić w interakcje z usługą wyszukiwania, należy utworzyć wystąpienie odpowiedniej klasy klienta: SearchClient do wyszukiwania indeksowanych dokumentów, SearchIndexClient do zarządzania indeksami lub SearchIndexerClient przeszukiwania źródeł danych i ładowania dokumentów wyszukiwania do indeksu. Aby utworzyć wystąpienie obiektu klienta, potrzebujesz punktu końcowego i ról platformy Azure lub klucza interfejsu API . Więcej informacji na temat obsługiwanych metod uwierzytelniania za pomocą usługi wyszukiwania można znaleźć w dokumentacji.

Uzyskiwanie klucza interfejsu API

Klucz interfejsu API może być łatwiejszym podejściem do rozpoczęcia od, ponieważ nie wymaga wstępnie istniejących przypisań ról.

Możesz pobrać punktu końcowego i klucz interfejsu API z usługi wyszukiwania w witrynie Azure Portal. Zapoznaj się z dokumentacją , aby uzyskać instrukcje dotyczące uzyskiwania klucza interfejsu API.

Alternatywnie możesz użyć następującego polecenia interfejsu wiersza polecenia platformy Azure, aby pobrać klucz interfejsu API z usługi wyszukiwania:

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

Istnieją dwa typy kluczy używanych do uzyskiwania dostępu do usługi wyszukiwania: administrator(do odczytu i zapisu) i zapytań (tylko do odczytu) kluczy. Ograniczenie dostępu i operacji w aplikacjach klienckich jest niezbędne do ochrony zasobów wyszukiwania w usłudze. Zawsze używaj klucza zapytania, a nie klucza administratora dla dowolnego zapytania pochodzącego z aplikacji klienckiej.

Uwaga: powyższy fragment kodu interfejsu wiersza polecenia platformy Azure pobiera klucz administratora, dzięki czemu łatwiej jest rozpocząć eksplorowanie interfejsów API, ale powinno być starannie zarządzane.

Po utworzeniu klucza api-key możesz go użyć w następujący sposób:

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

Uwierzytelnianie w chmurze krajowej

Aby uwierzytelnić się w chmury krajowej, należy wprowadzić następujące dodatki do konfiguracji klienta:

  • Ustawianie Audience w 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,
});

Kluczowe pojęcia

Usługa Azure AI Search zawiera co najmniej jeden indeks, który zapewnia trwały magazyn danych z możliwością wyszukiwania w postaci dokumentów JSON. (Jeśli dopiero zaczynasz wyszukiwanie, możesz utworzyć bardzo szorstką analogię między indeksami a tabelami baz danych). Biblioteka klienta @azure/search-documents uwidacznia operacje na tych zasobach za pośrednictwem trzech głównych typów klientów.

Uwaga: ci klienci nie mogą działać w przeglądarce, ponieważ wywoływane interfejsy API nie obsługują udostępniania zasobów między źródłami (CORS).

Pojęcia specyficzne dla języka TypeScript/JavaScript

Dokumentów

Element przechowywany wewnątrz indeksu wyszukiwania. Kształt tego dokumentu jest opisany w indeksie przy użyciu właściwości fields. Każda SearchField ma nazwę, typ danych i dodatkowe metadane, takie jak możliwość wyszukiwania lub filtrowania.

Paginacja

Zazwyczaj chcesz wyświetlić tylko podzbiór wyników wyszukiwania użytkownikowi jednocześnie. Aby to umożliwić, możesz użyć parametrów top, skip i includeTotalCount, aby zapewnić stronicowane środowisko na podstawie wyników wyszukiwania.

Kodowanie pól dokumentu

Obsługiwane typy danych w indeksie są mapowane na typy JSON w żądaniach/odpowiedziach interfejsu API. Biblioteka klienta JS przechowuje te same elementy, z pewnymi wyjątkami:

  • Edm.DateTimeOffset jest konwertowany na DateJS.
  • Edm.GeographyPoint jest konwertowany na typ GeographyPoint wyeksportowany przez bibliotekę klienta.
  • Specjalne wartości typu number (NaN, Infinity, -Infinity) są serializowane jako ciągi w interfejsie API REST, ale są konwertowane z powrotem na number przez bibliotekę klienta.

Uwaga: typy danych są konwertowane na podstawie wartości, a nie typu pola w schemacie indeksu. Oznacza to, że jeśli masz ciąg daty ISO8601 (np. "2020-03-06T18:48:27.896Z") jako wartość pola, zostanie on przekonwertowany na datę niezależnie od sposobu jego przechowywania w schemacie.

Przykłady

W poniższych przykładach przedstawiono podstawowe informacje — zapoznać się z naszymi przykładami, aby uzyskać więcej informacji.

Tworzenie indeksu

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

Pobieranie określonego dokumentu z indeksu

Określony dokument może zostać pobrany przez jego wartość klucza podstawowego:

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

Dodawanie dokumentów do indeksu

Możesz przekazać wiele dokumentów do indeksu wewnątrz partii:

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

Wyszukiwanie dokumentów

Aby wyświetlić listę wszystkich wyników określonego zapytania, możesz użyć search z ciągiem wyszukiwania, który używa prostej składni zapytania:

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

Aby uzyskać bardziej zaawansowane wyszukiwanie korzystające z składni Lucene, określ 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();

Wykonywanie zapytań za pomocą języka TypeScript

W języku TypeScript SearchClient przyjmuje ogólny parametr, który jest kształtem modelu dokumentów indeksu. Dzięki temu można wykonywać silnie typizowane wyszukiwanie pól zwracanych w wynikach. Język TypeScript jest również w stanie sprawdzić, czy pola są zwracane podczas określania parametru 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();

Wykonywanie zapytań za pomocą filtrów OData

Użycie parametru zapytania filter umożliwia wykonywanie zapytań względem indeksu przy użyciu składni wyrażenia 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();

Wykonywanie zapytań za pomocą wektorów

Zapytania dotyczące osadzania tekstu można wykonywać przy użyciu parametru wyszukiwania vector. Aby uzyskać więcej informacji, zobacz wektory zapytań i filtru wektorów.

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

Wykonywanie zapytań za pomocą aspektów

aspekty ułatwiają użytkownikowi aplikacji uściślenie wyszukiwania we wstępnie skonfigurowanych wymiarach. składnia aspektu udostępnia opcje sortowania i zasobnika wartości aspektów.

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

Podczas pobierania wyników będzie dostępna właściwość facets, która będzie wskazywać liczbę wyników, które należą do każdego zasobnika aspektu. Może to służyć do kierowania uściśleniem (np. wystawianie wyszukiwania monitującego, które filtruje na Rating jest większe lub równe 3 i mniejsze niż 4).

Rozwiązywanie problemów

Wyrąb

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietów @azure/rejestratora.

Następne kroki

Przyczyniając się

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

Ten projekt z zadowoleniem przyjmuje wkład i sugestie. Większość kontrybucja wymaga zgody na umowę licencyjną współautora (CLA), deklarując, że masz prawo, a w rzeczywistości przyznaj nam prawa do korzystania z twojego wkładu. Aby uzyskać szczegółowe informacje, odwiedź stronę cla.microsoft.com.

Ten projekt przyjął kodeks postępowania firmy Microsoft typu open source. Aby uzyskać więcej informacji, zobacz Kodeks postępowania — często zadawane pytania lub skontaktuj się z opencode@microsoft.com z dodatkowymi pytaniami lub komentarzami.

wrażenia