Sdílet prostřednictvím

Klientská knihovna Azure AI Search pro JavaScript – verze 12.1.0

  • Článek

azure AI Search (dříve označované jako Azure Cognitive Search) je platforma pro načítání informací využívající AI, která vývojářům pomáhá vytvářet bohatá vyhledávací prostředí a generovat aplikace AI, 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.

Pomocí klientské knihovny @azure/search-documents můžete:

  • 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:

  • zdrojového kódu
  • balíčku (NPM)
  • Referenční dokumentace k rozhraní API
  • Dokumentace k rozhraní REST API
  • dokumentace k produktu
  • ukázky

Začínáme

Instalace balíčku @azure/search-documents

npm install @azure/search-documents

Aktuálně podporovaná prostředí

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

Požadavky

  • Předplatné Azure
  • vyhledávací služby

K vytvoření nové vyhledávací služby můžete použítwebu Azure Portal, Azure PowerShellu 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 výběru cenové úrovně.

Ověření klienta

Pokud chcete pracovat s vyhledávací službou, budete muset vytvořit instanci příslušné třídy klienta: SearchClient pro vyhledávání indexovaných dokumentů, 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 ověřování vyhledávací službou 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 můžete získat a klíč rozhraní API z vyhledávací služby na webu Azure Portal. Pokyny k získání klíče rozhraní API najdete v dokumentaci.

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

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

Pro přístup ke vyhledávací službě se používají dva typy klíčů: správce(pro čtení i zápis) a dotazu (jen pro čtení) klíče. 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 kódu Azure CLI načte klíč správce, aby bylo snazší začít zkoumat rozhraní API, ale mělo by se spravovat pečlivě.

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

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

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

Pokud se chcete ověřit vnárodního cloudu , budete muset do konfigurace klienta provést následující doplňky:

  • Nastavení Audience v 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,
});

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 vyhledávání začínáte, můžete vytvořit velmi přibližnou analogii mezi indexy a databázovými tabulkami.) Klientská knihovna @azure/search-documents zveřejňuje operace s těmito prostředky prostřednictvím tří hlavních typů klientů.

Poznámka: Tito klienti nemůžou v prohlížeči fungovat, protože rozhraní API, která volá, nemají podporu 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 indexu pomocí vlastnosti fields. Každý SearchField má název, datový typ a další metadata, například pokud je prohledávatelná nebo filtrovatelná.

Stránkování

Obvykle budete chtít zobrazit podmnožinu výsledků hledání uživateli najednou. K tomu můžete použít parametry top, skip a includeTotalCount k zajištění stránkovaného prostředí nad výsledky hledání.

Kódování pole dokumentu

podporované datové typy v indexu se mapují na typy JSON v požadavcích a 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 JS Date.
  • Edm.GeographyPoint se převede na typ GeographyPoint exportovaný klientskou knihovnou.
  • Speciální hodnoty typu number (NaN, Infinity, -Infinity) jsou serializovány jako řetězce v rozhraní REST API, ale jsou převedeny zpět na number klientskou knihovnou.

Poznámka: Datové typy jsou převedeny na základě hodnoty, nikoli na typ 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 – si projděte naše ukázky mnohem více.

Vytvoření indexu

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

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

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

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

Přidání dokumentů do indexu

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

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

Hledání dokumentů

Pokud chcete zobrazit seznam všech výsledků konkrétního dotazu, můžete použít search s vyhledávacím řetězcem, který používá jednoduchou syntaxi dotazu:

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

Pokud chcete pokročilejší vyhledávání, které používá syntaxi Lucene, zadejte queryType, které se mají full:

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

Dotazování pomocí TypeScriptu

V TypeScriptu SearchClient přebírá obecný parametr, který je tvarem modelu dokumentů indexu. 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 kontrolovat 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 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();

Dotazování pomocí filtrů OData

Pomocí parametru dotazu umožňuje dotazování indexu pomocí syntaxevýrazu OData $filter výrazu .

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

Dotazování pomocí vektorů

Vkládání textu se dá dotazovat pomocí parametru vector vyhledávání. Další informace najdete v tématu vektory dotazů a vektorové dotazy filtru.

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

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

facets slouží k tomu, aby uživatel vaší aplikace upřesňuje hledání podle předem nakonfigurovaných dimenzí. syntaxe omezující vlastnosti poskytuje možnosti řazení a rozdělení hodnot omezujících vlastností do kbelíku.

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

Při načítání výsledků bude k dispozici vlastnost facets, která bude indikovat počet výsledků, které spadají do každého kontejneru omezující vlastnosti. Dá se použít k upřesnění (např. vydání následného vyhledávání, které filtruje Rating větší než nebo rovno 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 přispívání a přečtěte si další informace o vytváření a testování kódu.

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 najdete v cla.microsoft.com.

Tento projekt přijal pravidla chování microsoftu 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.

imprese