Megosztás a következőn keresztül:

Azure AI Search JavaScripthez készült ügyféloldali kódtár – 12.2.0-s verzió

Az Azure AI Search (korábbi nevén "Azure Cognitive Search") egy mesterséges intelligencián alapuló információ-lekérési platform, amely segít a fejlesztőknek gazdag keresési élményeket és generatív AI-alkalmazásokat létrehozni, amelyek nagy nyelvi modelleket kombinálnak a vállalati adatokkal.

Az Azure AI Search szolgáltatás a következő alkalmazásforgatókönyvekhez alkalmas:

  • A különböző tartalomtípusok összevonása egyetlen kereshető indexbe. Index feltöltéséhez leküldheti a tartalmat tartalmazó JSON-dokumentumokat, vagy ha az adatai már az Azure-ban vannak, létrehozhat egy indexelőt az adatok automatikus lekéréséhez.
  • Képességkészleteket csatolhat egy indexelőhöz, hogy kereshető tartalmakat hozzon létre képekből és strukturálatlan dokumentumokból. A készségkészletek az Azure AI Services API-jait használják a beépített OCR-hez, az entitásfelismeréshez, a kulcskifejezés-kinyeréshez, a nyelvfelismeréshez, a szövegfordításhoz és a hangulatelemzéshez. Egyéni képességeket is hozzáadhat a tartalom külső feldolgozásának integrálásához az adatbetöltés során.
  • A keresési ügyfélalkalmazásokban a kereskedelmi webes keresőmotorokhoz és csevegőstílusú alkalmazásokhoz hasonló lekérdezési logikát és felhasználói élményeket valósíthat meg.

Az ügyféloldali kódtár használatával a következőket teheti @azure/search-documents :

  • Lekérdezések küldése vektoros, kulcsszó- és hibrid lekérdezési űrlapokkal.
  • Szűrt lekérdezések implementálása metaadatokhoz, térinformatikai kereséshez, részletes navigációhoz vagy a szűrési feltételek alapján a találatok szűkítéséhez.
  • Keresési indexek létrehozása és kezelése.
  • Dokumentumok feltöltése és frissítése a keresési indexben.
  • Olyan indexelőket hozhat létre és kezelhet, amelyek adatokat kérnek le az Azure-ból egy indexbe.
  • Olyan képességkészletek létrehozása és kezelése, amelyek AI-bővítést adnak az adatbetöltéshez.
  • Elemzők létrehozása és kezelése speciális szövegelemzéshez vagy többnyelvű tartalomhoz.
  • Optimalizálja az eredményeket szemantikai rangsorolással és pontozási profilokkal az üzleti logika vagy frissesség figyelembe viteléhez.

Főbb hivatkozások:

Kezdetekhez

Telepítse a(z) @azure/search-documents csomagot

npm install @azure/search-documents

Jelenleg támogatott környezetek

További részletekért tekintse meg támogatási szabályzatunkat.

Előfeltételek

Új keresési szolgáltatás létrehozásához használhatja a Azure Portal, a Azure PowerShell vagy az Azure CLI-t. Az alábbi példa az Azure CLI használatával hoz létre egy ingyenes példányt az első lépésekhez:

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

Az elérhető lehetőségekkel kapcsolatos további információkért tekintse meg a tarifacsomag kiválasztását .

Az ügyfél hitelesítése

A keresési szolgáltatással való interakcióhoz létre kell hoznia a megfelelő ügyfélosztály egy példányát: SearchClient indexelt dokumentumok kereséséhez, SearchIndexClient indexek kezeléséhez, adatforrások SearchIndexerClient bejárásához és keresési dokumentumok indexbe való betöltéséhez. Ügyfélobjektum példányosításához végpontra és Azure-szerepkörökre vagy API-kulcsra lesz szüksége. A keresési szolgáltatással támogatott hitelesítési módszerekkel kapcsolatos további információkért tekintse meg a dokumentációt.

API-kulcs lekérése

Az API-kulcsokkal könnyebb kezdeni, mert nem igényel meglévő szerepkör-hozzárendeléseket.

A végpontot és az API-kulcsot a keresési szolgáltatásból szerezheti be a Azure Portal. Az API-kulcs beszerzésével kapcsolatos utasításokat a dokumentációban találja.

Azt is megteheti, hogy a következő Azure CLI-paranccsal lekéri az API-kulcsot a keresési szolgáltatásból:

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

A keresési szolgáltatás eléréséhez kétféle kulcs használható: rendszergazdai(írási-olvasási) és lekérdezési(csak olvasható) kulcsok. Az ügyfélalkalmazások hozzáférésének és műveleteinek korlátozása elengedhetetlen a szolgáltatás keresési eszközeinek védelméhez. Mindig használjon lekérdezési kulcsot rendszergazdai kulcs helyett az ügyfélalkalmazásból származó lekérdezésekhez.

Megjegyzés: A fenti példa Azure CLI-kódrészlet lekér egy rendszergazdai kulcsot, így könnyebben megkezdheti az API-k feltárását, de körültekintően kell kezelni.

Miután rendelkezik api-kulccsal, az alábbiak szerint használhatja:

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

Hitelesítés nemzeti felhőben

A nemzeti felhőben való hitelesítéshez a következő kiegészítéseket kell végrehajtania az ügyfél konfigurációjában:

  • Állítsa be a AudienceSearchClientOptions
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,
});

Főbb fogalmak

Az Azure AI Search szolgáltatás egy vagy több olyan indexet tartalmaz, amelyek JSON-dokumentumok formájában biztosítják a kereshető adatok állandó tárolását. (Ha még nem ismeri a keresést, nagyon durva analógiát hozhat létre az indexek és az adatbázistáblák között.) Az @azure/search-documents ügyféloldali kódtár három fő ügyféltípuson keresztül teszi elérhetővé az erőforrások műveleteit.

Megjegyzés: Ezek az ügyfelek nem működnek a böngészőben, mert az általa meghívott API-k nem támogatják az eredetközi erőforrás-megosztást (CORS).

TypeScript-/JavaScript-specifikus fogalmak

Dokumentumok

Egy keresési indexben tárolt elem. A dokumentum alakját az index írja le a fields tulajdonság használatával. Mindegyiknek SearchField van neve, adattípusa és további metaadatai, például kereshető vagy szűrhető.

Tördelés

Általában csak a keresési eredmények egy részhalmazát szeretné megjeleníteni egy felhasználónak egyszerre. Ennek támogatásához a , top és skip paraméterekkel includeTotalCountlapozható élményt biztosíthat a keresési eredmények tetején.

Dokumentummező kódolása

Az indexek támogatott adattípusai JSON-típusokra vannak leképezve az API-kérésekben/-válaszokban. A JS-ügyfélkódtár ezeket többnyire változatlanul tartja, néhány kivétellel:

  • Edm.DateTimeOffset JS-sé Datealakul át.
  • Edm.GeographyPoint az ügyféloldali könyvtár által exportált típussá GeographyPoint alakul át.
  • A speciális típusú értékek number (NaN, Infinity -Infinity) sztringekként vannak szerializálva a REST API, de az ügyféloldali kódtár visszakonvertálja number őket.

Megjegyzés: Az adattípusok konvertálása az érték alapján történik, nem pedig az indexséma mezőtípusa alapján. Ez azt jelenti, hogy ha ISO8601 Dátum sztringet (például "2020-03-06T18:48:27.896Z") tartalmaz egy mező értékeként, a rendszer dátummá alakítja, függetlenül attól, hogy hogyan tárolta azt a sémában.

Példák

Az alábbi példák bemutatják az alapokat - kérjük, tekintse meg mintáinkat még sok másért.

Index létrehozása

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

Adott dokumentum lekérése indexből

Egy adott dokumentum lekérhető az elsődleges kulcs értéke alapján:

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

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

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

Dokumentumok hozzáadása indexhez

Egy kötegen belül több dokumentumot is feltölthet az indexbe:

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

Keresés végrehajtása dokumentumokon

Egy adott lekérdezés összes eredményének listázásához használhatja search egy egyszerű lekérdezési szintaxist használó keresési sztringet:

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

A Lucene szintaxist használó speciálisabb keresés esetén adja meg a queryType következőtfull:

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

Lekérdezés TypeScript használatával

A TypeScriptben egy általános paramétert vesz fel, SearchClient amely az indexdokumentumok modellalakja. Ez lehetővé teszi az eredményekben visszaadott mezők erősen begépelt keresését. A TypeScript a paraméter megadásakor select visszaadott mezőket is képes ellenőrizni.

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

Lekérdezés OData-szűrőkkel

A lekérdezési filter paraméter használatával lekérdezhet egy indexet egy OData $filter-kifejezés szintaxisával.

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

Lekérdezés vektorokkal

A szövegbeágyazások a vector search paraméterrel kérdezhetők le. További információ: Lekérdezési vektorok és Vektoros lekérdezések szűrése .

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

Lekérdezés aspektusokkal

A dimenziók segítségével az alkalmazás felhasználója finomíthatja a keresést az előre konfigurált dimenziók mentén. A dimenziószintaxis lehetővé teszi az értékek rendezését és csoportosítását.

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

Az eredmények lekérésekor elérhető lesz egy facets tulajdonság, amely jelzi az egyes dimenziógyűjtőkbe eső eredmények számát. Ez felhasználható a finomítás ösztönzésére (pl. egy olyan utólagos keresés kiadása, amely a Rating 3-nál nagyobb vagy egyenlő és a 4-nél kisebb értékre szűr.)

Hibaelhárítás

Fakitermelés

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a környezeti változót a AZURE_LOG_LEVEL következőre info: . Alternatívaként a naplózás futásidőben is engedélyezhető a setLogLevel hívásával a @azure/logger.

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

setLogLevel("info");

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentációit.

Következő lépések

Hozzájárulás

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót , amelyből többet is megtudhat a kód összeállításáról és teszteléséről.

Ez a projekt üdvözli a hozzájárulásokat és javaslatokat. A legtöbb hozzájárulás megköveteli, hogy elfogadja a közreműködői licencszerződést (CLA), amely kimondja, hogy önnek joga van a hozzájárulás használatára, és valóban meg kell adnia nekünk a jogosultságokat a hozzájárulás használatára. A részletekért látogasson el a cla.microsoft.com oldalra.

Ez a projekt a Microsoft nyílt forráskóddal kapcsolatos viselkedési szabályzata alapján működik. További információkért lásd a magatartási kódexével kapcsolatos gyakori kérdéseket, vagy további kérdésekkel vagy megjegyzésekkel forduljon opencode@microsoft.com.

  • Last updated on