Sdílet prostřednictvím

Klientská knihovna Azure AI Search pro JavaScript – verze 12.2.0

Azure AI Search (dříve známý jako "Azure Cognitive Search") je platforma pro získávání informací využívající umělou inteligenci, která pomáhá vývojářům vytvářet bohatá vyhledávací prostředí a aplikace generativní umělé inteligence, které kombinují velké jazykové modely s podnikovými daty.

Služba Azure AI Search je vhodná pro následující scénáře aplikací:

  • Sloučit různé typy obsahu do jediného prohledávatelného indexu Pokud chcete naplnit index, můžete odeslat dokumenty JSON, které obsahují váš obsah, nebo pokud už jsou vaše data v Azure, vytvořte indexer, který automaticky načítá data.
  • Připojte sady dovedností k indexeru a vytvořte prohledávatelný obsah z obrázků a nestrukturovaných dokumentů. Sada dovedností využívá rozhraní API ze služeb Azure AI pro integrovanou technologii OCR, rozpoznávání entit, extrakci klíčových frází, rozpoznávání jazyka, překlad textu a analýzu mínění. Můžete také přidat vlastní dovednosti pro integraci externího zpracování obsahu během příjmu dat.
  • V klientské aplikaci vyhledávací služby implementujte logiku dotazů a uživatelská prostředí podobná komerčním webovým vyhledávacím webům a aplikacím ve stylu chatu.

Klientskou knihovnu @azure/search-documents můžete použít k následujícím účelům:

  • Odešlete dotazy pomocí vektorových, klíčových slov a formulářů hybridních dotazů.
  • Implementujte filtrované dotazy pro metadata, geoprostorové vyhledávání, fasetovou navigaci nebo zúžit výsledky na základě kritérií filtru.
  • Vytváření a správa indexů vyhledávání
  • Nahrajte a aktualizujte dokumenty v indexu vyhledávání.
  • Vytvářejte a spravujte indexery, které načítá data z Azure do indexu.
  • Vytvářejte a spravujte sady dovedností, které přidávají rozšiřování AI do příjmu dat.
  • Vytvářejte a spravujte analyzátory pro pokročilou analýzu textu nebo vícejazyčný obsah.
  • Optimalizujte výsledky prostřednictvím sémantických profilů hodnocení a bodování, abyste mohli využívat obchodní logiku nebo aktuálnost.

Klíčové odkazy:

Začínáme

Nainstalujte balíček @azure/search-documents.

npm install @azure/search-documents

Aktuálně podporovaná prostředí

Další podrobnosti najdete v zásadách podpory.

Požadavky

K vytvoření nové vyhledávací služby můžete použít Azure Portal, Azure PowerShell nebo Azure CLI. Tady je příklad použití Azure CLI k vytvoření bezplatné instance pro začátek:

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

Další informace o dostupných možnostech najdete v tématu Volba cenové úrovně .

Ověření klienta

Chcete-li pracovat s vyhledávací službou, budete muset vytvořit instanci příslušné třídy klienta: SearchClient pro vyhledávání v indexovaných dokumentech, SearchIndexClient pro správu indexů nebo SearchIndexerClient pro procházení zdrojů dat a načítání vyhledávacích dokumentů do indexu. K vytvoření instance objektu klienta budete potřebovat koncový bod a role Azure nebo klíč rozhraní API. Další informace o podporovaných přístupech k ověřování pomocí vyhledávací služby najdete v dokumentaci.

Získání klíče rozhraní API

Klíč rozhraní API může být jednodušším přístupem, protože nevyžaduje předem existující přiřazení rolí.

Koncový bod a klíč rozhraní API můžete získat z vyhledávací služby v Azure Portal. Pokyny k získání klíče API naleznete v dokumentaci .

Případně můžete k načtení klíče rozhraní API z vyhledávací služby použít následující příkaz Azure CLI :

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

Pro přístup k vyhledávací službě se používají dva typy klíčů: klíče admin(pro čtení i zápis) a klíče dotazu(pouze pro čtení). Omezení přístupu a operací v klientských aplikacích je nezbytné k ochraně vyhledávacích prostředků ve vaší službě. Vždy používejte klíč dotazu místo klíče správce pro jakýkoli dotaz pocházející z klientské aplikace.

Poznámka: Výše uvedený ukázkový fragment Azure CLI načte klíč správce, takže je snazší začít zkoumat rozhraní API, ale měl by být spravován pečlivě.

Jakmile máte klíč api-key, můžete ho použít následujícím způsobem:

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

Ověřování v národním cloudu

Chcete-li se ověřit v národním cloudu, budete muset do konfigurace klienta provést následující doplňky:

  • Audience Nastavit vSearchClientOptions
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,
});

Klíčové koncepty

Služba Azure AI Search obsahuje jeden nebo více indexů, které poskytují trvalé úložiště prohledávatelných dat ve formě dokumentů JSON. (Pokud jste ve vyhledávání úplným nováčkem, můžete vytvořit velmi přibližnou analogii mezi indexy a databázovými tabulkami.) Klientská @azure/search-documents knihovna zpřístupňuje operace s těmito prostředky prostřednictvím tří hlavních typů klientů.

Poznámka: Tito klienti nemohou v prohlížeči fungovat, protože rozhraní API, která volá, nepodporují sdílení prostředků mezi zdroji (CORS).

Koncepty specifické pro TypeScript nebo JavaScript

Dokumenty

Položka uložená v indexu vyhledávání. Tvar tohoto dokumentu je popsán v rejstříku pomocí fields vlastnosti. Každý z nich SearchField má název, datový typ a další metadata, například zda je možné v něm vyhledávat nebo filtrovat.

Stránkování

Obvykle budete chtít uživateli zobrazit pouze podmnožinu výsledků vyhledávání najednou. Chcete-li to podpořit, můžete použít topparametry a skipincludeTotalCount k poskytnutí stránkovaného prostředí nad výsledky hledání.

Kódování pole dokumentu

Podporované datové typy v indexu jsou mapovány na typy JSON v požadavcích/odpovědích rozhraní API. Klientská knihovna JS udržuje tyto převážně stejné, s některými výjimkami:

  • Edm.DateTimeOffset je převeden na soubor JS Date.
  • Edm.GeographyPoint se převede na GeographyPoint typ exportovaný klientskou knihovnou.
  • Speciální hodnoty number typu (NaN, Infinity, -Infinity) jsou serializovány jako řetězce v rozhraní REST API, ale jsou převedeny zpět klientskou number knihovnou.

Poznámka: Datové typy se převádějí na základě hodnoty, nikoli na základě typu pole ve schématu indexu. To znamená, že pokud máte jako hodnotu pole ISO8601 řetězec data (například 2020-03-06T18:48:27.896Z), převede se na datum bez ohledu na to, jak jste ho uložili ve schématu.

Příklady

Následující příklady ukazují základy - podívejte se prosím na naše ukázky pro mnohem více.

Vytvoření indexu

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

Načtení konkrétního dokumentu z indexu

Konkrétní dokument lze načíst hodnotou primárního klíče:

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

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

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

Přidání dokumentů do indexu

Do indexu v dávce můžete nahrát více dokumentů:

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

Hledání dokumentů

Chcete-li vypsat všechny výsledky konkrétního dotazu, můžete použít search s vyhledávacím řetězcem, který používá jednoduchou syntaxi dotazu:

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

Pro pokročilejší vyhledávání, které používá syntaxi Lucene, zadejte queryType jako :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);
}

Dotazování pomocí TypeScriptu

V TypeScriptu přebírá obecný parametr, SearchClient který je tvarem modelu vašich indexových dokumentů. To umožňuje provádět vyhledávání polí vrácených ve výsledcích se silnými typy. TypeScript také dokáže zkontrolovat pole vrácená při zadávání 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 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);
}

Dotazování pomocí filtrů OData

Použití parametru filter query umožňuje dotazovat se na index pomocí syntaxe výrazu OData $filter.

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

Dotazování pomocí vektorů

Na vkládání textu je možné dotazovat pomocí parametru vector search. Další informace najdete v tématech Vektorové dotazy a Vektorové dotazy filtrů .

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

Dotazování pomocí omezujících vlastností

Fasety se používají k tomu, aby pomohly uživateli vaší aplikace zpřesnit vyhledávání podle předem nakonfigurovaných dimenzí. Syntaxe fazet poskytuje možnosti pro řazení a kbelík hodnot faset.

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

Při načítání výsledků bude k dispozici vlastnost, facets která bude označovat počet výsledků, které spadají do každého kontejneru omezujících vlastností. To lze použít k upřesnění (např. vydání následného vyhledávání, které filtruje Rating bytost větší nebo rovnou 3 a menší než 4).

Řešení problémů

Protokolování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Další kroky

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce pro přispívání a přečtěte si další informace o tom, jak sestavit a otestovat kód.

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která deklaruje, že máte právo a ve skutečnosti nám udělíte práva k používání vašeho příspěvku. Podrobnosti naleznete na cla.microsoft.com.

Tento projekt se řídí Pravidly chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k kodexu chování nebo kontaktujte opencode@microsoft.com s dalšími dotazy nebo komentáři.

  • Last updated on