Share via

Klientská knihovna Azure AI Search pro JavaScript – verze 12.0.0

  • Článek

Azure AI Search (dříve označovaná jako "Azure Cognitive Search") je platforma pro načítání informací využívající umělou inteligenci, 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čení různých typů obsahu do jednoho 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řit indexer pro automatické načítání dat.
  • Připojte sady dovedností k indexeru a vytvořte prohledávatelný obsah z obrázků a velkých textových dokumentů. Sada dovedností využívá rozhraní API ze služeb AI k integrovanému rozpoznávání OCR, rozpoznávání entit, extrakci klíčových frází, rozpoznávání jazyka, překladu textu a analýze mínění. Můžete také přidat vlastní dovednosti pro integraci externího zpracování obsahu během příjmu dat.
  • Ve vyhledávací klientské aplikaci implementujte logiku dotazů a uživatelská prostředí podobná komerčním webovým vyhledávacím webům.

Klientská @azure/search-documents knihovna slouží k:

  • Odešlete dotazy pomocí vektorů, klíčových slov a hybridních formulářů dotazů.
  • Implementujte filtrované dotazy pro metadata, geoprostorové vyhledávání, fasetovou navigaci nebo zúžení výsledků na základě kritérií filtru.
  • Vytváření a správa indexů vyhledávání
  • Nahrajte a aktualizujte dokumenty ve vyhledávacím indexu.
  • Vytvořte a spravujte indexery, které přetahují data z Azure do indexu.
  • Vytvářejte a spravujte sady dovedností, které přidávají rozšíření AI k příjmu dat.
  • Vytváření a správa analyzátorů pro pokročilou analýzu textu nebo vícejazyčný obsah
  • Optimalizujte výsledky prostřednictvím profilů bodování, abyste mohli zohlednit 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í

  • LtS verze Node.js
  • Nejnovější verze prohlížečů Safari, Chrome, Edge a Firefox.

Další podrobnosti najdete v našich 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

Abyste mohli pracovat s vyhledávací službou, budete muset vytvořit instanci příslušné klientské třídy: SearchClient pro vyhledávání indexovaných dokumentů, SearchIndexClient pro správu indexů nebo SearchIndexerClient pro procházení zdrojů dat a načítání hledaný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í pomocí vyhledávací služby najdete v dokumentaci.

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

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

Koncový bod a klíč rozhraní API můžete získat 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 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 --service-name <mysearch> --resource-group <mysearch-rg>

Jakmile budete mít 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 v národním cloudu, musíte do konfigurace klienta přidat následující doplňky:

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

Klíčové koncepty

Search Azure AI obsahuje jeden nebo více indexů, které poskytují trvalé úložiště prohledávatelných dat ve formě dokumentů JSON. (Pokud s vyhledáváním začínáte, můžete vytvořit velmi přibližnou analogii mezi indexy a databázovými tabulkami.) Klientská @azure/search-documents knihovna 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á, nepodporují sdílení prostředků mezi zdroji (CORS).

Koncepty specifické pro TypeScript nebo JavaScript

dokumenty.

Položka uložená ve vyhledávacím indexu. Tvar tohoto dokumentu je popsán v indexu pomocí s Field. Každé pole má název, datový typ a další metadata, například jestli se dá prohledávat nebo filtrovat.

Stránkování

Obvykle budete chtít uživateli zobrazit jenom podmnožinu výsledků hledání najednou. K tomu můžete použít topparametry a, skip které includeTotalCount poskytují stránkované prostředí nad výsledky hledání.

Kódování pole dokumentu

Podporované datové typy v indexu se v požadavcích a odpovědích rozhraní API mapují na typy JSON. V klientské knihovně JS jsou tyto soubory většinou stejné, s některými výjimkami:

  • Edm.DateTimeOffset se převede na 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 typu pole ve schématu indexu. To znamená, že pokud máte jako hodnotu pole ISO8601 řetězec data (např. "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 demonstrují základní informace – podívejte se prosím na naše ukázky , kde najdete 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í určitého dokumentu z indexu

Konkrétní dokument je možné načíst podle hodnoty 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();

Vyhledávání v dokumentech

Pokud chcete zobrazit seznam všech výsledků konkrétního dotazu, můžete použít s search 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();

Pro pokročilejší vyhledávání, které používá syntaxi Lucene, zadejte queryType hodnotu 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 indexových dokumentů. To umožňuje 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> | 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();

Dotazování pomocí filtrů OData

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

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 je možné dotazovat pomocí parametru vector vyhledávání.

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

Dotazování s omezujícími vlastnostmi

Omezující vlastnosti pomáhají uživateli vaší aplikace upřesnit vyhledávání podle předem nakonfigurovaných dimenzí. Syntaxe fazety poskytuje možnosti řazení a rozdělení hodnot omezující vlastnosti.

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 udávat počet výsledků, které spadají do jednotlivých kontejnerů omezujících vlastností. Můžete ho použít ke zpřesnění (například k následnému hledání, které filtruje Rating hodnotu větší nebo rovnou 3 a menší než 4).

Poradce při potížích

protokolování

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné 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 balíčkům @azure/protokolovacího nástroje.

Další kroky

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete 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á stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete v cla.microsoft.com.

Tento projekt přijal pravidla chování pro Open Source společnosti Microsoft. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.

Imprese