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

Azure AI Search-ügyfélkódtár JavaScripthez – 12.1.0-s verzió

  • Cikk

Az Azure AI Search (korábbi nevén "Azure Cognitive Search") egy AI-alapú 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 nagyvá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.

A @azure/search-documents ügyfélkódtár használatával:

  • 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

A @azure/search-documents csomag telepítése

npm install @azure/search-documents

Jelenleg támogatott környezetek

  • Node.js LTS-verziói
  • A Safari, a Chrome, a Microsoft Edge és a Firefox legújabb verziói.

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

Előfeltételek

Új keresési szolgáltatás létrehozásához használhatja az Azure Portal, az Azure PowerShellvagy az Azure CLI. 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égekről további információt a tarifacsomag kiválasztásával kapcsolatban talál.

Az ügyfél hitelesítése

A keresési szolgáltatás használatához létre kell hoznia egy példányt a megfelelő ügyfélosztályból: SearchClient indexelt dokumentumok kereséséhez, SearchIndexClient indexek kezeléséhez, vagy SearchIndexerClient az adatforrások bejárásához és a keresési dokumentumok indexbe való betöltéséhez. Az ügyfélobjektumok példányosításához szüksége lesz egy végpontra és Azure-szerepkörökre vagy egy API-kulcsra. A keresési szolgáltatással támogatott hitelesítési megközelítésekkel 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égponti és egy API-kulcs a keresési szolgáltatásból az Azure Portal. Az API-kulcsok beszerzésére vonatkozó útmutatásért tekintse meg az dokumentációját.

Másik lehetőségként az alábbi Azure CLI paranccsal is lekérheti 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ásvédett) és lekérdezési(írásvédett) kulcsokat. 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 egy rendszergazdai kulcsot kér le, így egyszerűbb az API-k felfedezése, de körültekintően kell kezelni.

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

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

Hitelesítés nemzeti felhőben

Az nemzeti felhőbelivaló hitelesítéshez az alábbi kiegészítéseket kell elvégeznie az ügyfélkonfigurációhoz:

  • A Audience beállítása a 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,
});

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 teljesen új a keresésben, nagyon durva analógiát készíthet az indexek és az adatbázistáblák között.) Az @azure/search-documents ügyfélkódtár három fő ügyféltípuson keresztül teszi elérhetővé ezen erőforrások műveleteit.

Megjegyzés: Ezek az ügyfelek nem működnek a böngészőben, mert a hívott API-k nem támogatják a forráskö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 ismerteti a fields tulajdonság használatával. Minden SearchField rendelkezik névvel, adattípussal és további metaadatokkal, 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 használhatja a top, skip és includeTotalCount paramétereket, hogy lapozott felületet biztosítson a keresési eredmények tetején.

Dokumentummező kódolása

az indexben támogatott adattípusok 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-Datelesz konvertálva.
  • Edm.GeographyPoint az ügyfélkódtár által exportált GeographyPoint típussá konvertálja.
  • A number típusú speciális értékek (NaN, Infinity, -Infinity) sztringekként vannak szerializálva a REST API-ban, de az ügyfélkódtár visszaalakul number.

Megjegyzés: Az adattípusok az érték alapján lesznek konvertálva, nem pedig az indexsémában lévő mezőtípus 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 az alapokat mutatják be – kérjük, tekintse meg a mintákat még sok másért.

Index létrehozása

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

Adott dokumentum lekérése indexből

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

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

Dokumentumok hozzáadása indexhez

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

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

Keresés végrehajtása dokumentumokon

Egy adott lekérdezés összes eredményének listázásához használhatja a search egy olyan keresési sztringgel, amely egyszerű lekérdezési szintaxist használ:

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

Az Lucene szintaxisthasználó fejlettebb kereséshez adja meg a fullqueryType:

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

Lekérdezés TypeScript használatával

A TypeScriptben SearchClient egy általános paramétert vesz fel, amely az indexdokumentumok modellalakzata. Ez lehetővé teszi az eredményekben visszaadott mezők erősen begépelt keresését. A TypeScript egy select paraméter megadásakor 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 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();

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

A filter lekérdezési paraméter használatával indexet kérdezhet le egy OData $filter kifejezésszintaxisával.

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

Lekérdezés vektorokkal

A szövegbeágyazások lekérdezhetők a vector keresési paraméterrel. További információt és Szűrővektor-lekérdezések című témakörben talál.

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

Lekérdezés aspektusokkal

facets segítségével az alkalmazás felhasználója előre konfigurált dimenziók mentén pontosíthatja a keresést. Facet szintaxis a rendszerezés és a gyűjtőértékek beállítását biztosítja.

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

Az eredmények lekérésekor elérhető lesz egy facets tulajdonság, amely az egyes aspektusgyűjtőkbe eső eredmények számát jelzi. Ez a finomítás hajtója (például egy olyan követő keresés kiadása, amely a Rating 3-nál nagyobb vagy egyenlő, 4-nél kisebb szűrőket ad ki.)

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 AZURE_LOG_LEVEL környezeti változót info. Másik lehetőségként a naplózás futásidőben is engedélyezhető a setLogLevel meghí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.

Ez a projekt elfogadta a Microsoft nyílt forráskódú magatartási kódexének. 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.

benyomások