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

  • Artykuł

Usługa Azure AI Search (wcześniej znana jako "Azure Cognitive Search") to oparta na sztucznej inteligencji platforma pobierania informacji, 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 dobrze odpowiednia dla następujących scenariuszy aplikacji:

  • Skonsoliduj różne typy 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 są 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 dużych dokumentów tekstowych. Zestaw umiejętności korzysta z interfejsów API z usług sztucznej inteligencji na potrzeby wbudowanego rozpoznawania jednostek, rozpoznawania jednostek, wyodrębniania kluczowych fraz, wykrywania języka, tłumaczenia tekstu i analizy tonacji. Możesz również dodać umiejętności niestandardowe, 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.

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

  • Przesyłanie zapytań przy użyciu formularzy wektorów, słów kluczowych i hybrydowych zapytań.
  • Zaimplementuj przefiltrowane zapytania dotyczące metadanych, wyszukiwania geoprzestrzennego, nawigacji aspektowej lub zawężenia wyników na podstawie kryteriów filtrowania.
  • Tworzenie indeksów wyszukiwania i zarządzanie nimi.
  • Przekazywanie i aktualizowanie dokumentów w indeksie wyszukiwania.
  • Tworzenie indeksatorów, które ściągają dane z platformy Azure do indeksu i zarządzaj nimi.
  • Tworzenie zestawów umiejętności, które dodają wzbogacanie sztucznej inteligencji do pozyskiwania danych i zarządzanie nimi.
  • Tworzenie analizatorów i zarządzanie nimi na potrzeby zaawansowanej analizy tekstu lub zawartości wielojęzycznej.
  • Zoptymalizuj wyniki za pomocą profilów oceniania, aby uwzględnić logikę biznesową lub świeżość.

Kluczowe linki:

Wprowadzenie

Instalowanie pakietu @azure/search-documents

npm install @azure/search-documents

Obecnie obsługiwane środowiska

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

Wymagania wstępne

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

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

Aby uzyskać więcej informacji o dostępnych opcjach, zobacz wybieranie warstwy cenowej .

Uwierzytelnianie klienta

Aby korzystać z usługi wyszukiwania, musisz utworzyć wystąpienie odpowiedniej klasy klienta: SearchClient do wyszukiwania indeksowanych dokumentów, SearchIndexClient 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 pracy, ponieważ nie wymaga wstępnie istniejących przypisań ról.

Punkt końcowy i klucz interfejsu API można uzyskać 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 --service-name <mysearch> --resource-group <mysearch-rg>

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 chmurze krajowej, należy wprowadzić następujące dodatki do konfiguracji klienta:

  • Ustaw wartość 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 usługa wyszukiwania 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 i tabelami bazy danych). Biblioteka @azure/search-documents kliencka udostępnia 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 przez nią interfejsy API nie obsługują współużytkowania zasobów między źródłami (CORS).

Pojęcia specyficzne dla języka TypeScript/JavaScript

Dokumenty

Element przechowywany wewnątrz indeksu wyszukiwania. Kształt tego dokumentu został opisany w indeksie przy użyciu języka Fields. Każde pole ma nazwę, typ danych i dodatkowe metadane, takie jak wyszukiwanie lub filtrowanie.

Dzielenie na strony

Zazwyczaj chcesz wyświetlić tylko podzbiór wyników wyszukiwania użytkownikowi jednocześnie. Aby to umożliwić, możesz użyć parametrów topi includeTotalCount , skip 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 zachowuje te same zasady, z pewnymi wyjątkami:

  • Edm.DateTimeOffset jest konwertowany na js Date.
  • Edm.GeographyPoint jest konwertowany na GeographyPoint typ wyeksportowany przez bibliotekę klienta.
  • Specjalne wartości number typu (NaN, Infinity, -Infinity) są serializowane jako ciągi w interfejsie API REST, ale są konwertowane z powrotem do number biblioteki 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 przekonwertowany na datę niezależnie od sposobu jego przechowywania w schemacie.

Przykłady

W poniższych przykładach przedstawiono podstawy — zapoznaj się z naszymi przykładami , aby uzyskać znacznie 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żna pobrać według jego wartości 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

Wiele dokumentów można przekazać do indeksu w 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 w dokumentach

Aby wyświetlić listę wszystkich wyników określonego zapytania, można użyć z search 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 ze składni Lucene, określ wartość 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> | 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();

Wykonywanie zapytań za pomocą filtrów OData

Użycie parametru filter zapytania 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 vector wyszukiwania.

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

Wykonywanie zapytań za pomocą aspektów

Aspekty służą do ułatwienia użytkownikowi aplikacji uściślinia wyszukiwania we wstępnie skonfigurowanych wymiarach. Składnia aspektu udostępnia opcje sortowania i wartości aspektów zasobnika.

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 dostępna będzie właściwość wskazująca facets liczbę wyników, które należą do każdego zasobnika aspektów. Może to służyć do zwiększania uściślenia (np. wystawiania wyszukiwania monitującego, które filtruje Rating , gdy wartość jest większa lub równa 3 i mniejsza niż 4).

Rozwiązywanie problemów

Rejestrowanie

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel polecenie w pliku @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

Współtworzenie

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

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź cla.microsoft.com.

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

Wrażenia