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

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

  • Cikk

Az Azure AI Search (korábbi nevén "Azure Cognitive Search") egy AI-alapú információlekérési platform, amellyel a fejlesztők gazdag keresési szolgáltatásokat és generatív AI-alkalmazásokat hozhatnak létre, amelyek nagy nyelvi modelleket kombinálnak vállalati adatokkal.

Az Azure AI Search a következő alkalmazásforgatókönyvekhez ideális:

  • A különböző tartalomtípusok összevonása egyetlen kereshető indexbe. Az index feltöltéséhez leküldheti a tartalmat tartalmazó JSON-dokumentumokat, vagy ha az adatok már az Azure-ban vannak, hozzon létre egy indexelőt az adatok automatikus lekéréséhez.
  • Képességcsoportokat csatolhat egy indexelőhöz, hogy kereshető tartalmat hozzon létre képekből és nagyméretű szöveges dokumentumokból. A képességcsoportok az AI-szolgáltatások API-jait használják a beépített OCR-hez, az entitásfelismeréshez, a kulcskifejezések kinyeréséhez, 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 hasonló lekérdezési logikát és felhasználói élményt valósíthat meg.

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

  • Lekérdezések küldése vektoros, kulcsszós és hibrid lekérdezési űrlapokkal.
  • Szűrt lekérdezések implementálása metaadatokhoz, térinformatikai kereséshez, aspektusalapú navigációhoz vagy az eredmények szűrési feltételek alapján történő 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.
  • Indexelők létrehozása és kezelése, amelyek adatokat kérnek le az Azure-ból egy indexbe.
  • Olyan képességcsoportokat hozhat létre és kezelhet, 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 pontozási profilok segítségével az üzleti logika vagy a frissesség figyelembe vételéhez.

Főbb hivatkozások:

Első lépések

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, Azure PowerShell vagy az Azure CLI-t. Íme egy példa, amely 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ása című témakörben talál.

Az ügyfél hitelesítése

A keresési szolgáltatás használatá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, SearchIndexerClient adatforrások 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 van szükség. 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 egyszerűbben lehet kezdeni, mert nem igényel meglévő szerepkör-hozzárendeléseket.

A végpontot és egy API-kulcsot az Azure Portal keresési szolgáltatásából szerezheti be. Az API-kulcs beszerzésére vonatkozó útmutatásért tekintse meg a dokumentációt .

Másik lehetőségként a következő Azure CLI-paranccsal is lekérheti az API-kulcsot a keresési szolgáltatásból:

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

Ha már 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

A nemzeti felhőben való hitelesítéshez a következő kiegészítéseket kell elvégeznie az ügyfélkonfigurációhoz:

  • Állítsa be a következőt Audience : 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ő fogalmak

Az Azure AI-Search szolgáltatás egy vagy több olyan indexet tartalmaznak, amelyek JSON-dokumentumok formájában biztosítják a kereshető adatok állandó tárolását. (Ha még csak most ismerkedik a kereséssel, nagyon durva hasonlatot 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 az eltérő eredetű erőforrások megosztását (CORS).

TypeScript-/JavaScript-specifikus fogalmak

Dokumentumok

Egy keresési indexben tárolt elem. A dokumentum alakját az index az s használatával Fieldismerteti. Minden mező rendelkezik névvel, adattípussal és további metaadatokkal, például kereshető vagy szűrhető.

Oldalra 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 és skipincludeTotalCount a topparamétereket, hogy lapozott felületet biztosítson a keresési eredményeken.

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

Megjegyzés: Az adattípusok az érték alapján lesznek konvertálva, nem az indexsémában lévő mezőtípus alapján. Ez azt jelenti, hogy ha egy ISO8601 Date sztringgel (például "2020-03-06T18:48:27.896Z") rendelkezik 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 – további információért tekintse meg a mintákat .

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

Több dokumentumot is feltölthet indexbe egy kötegen belül:

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álhat search egy egyszerű lekérdezési szintaxist használó keresési sztringet:

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

A Lucene szintaxist használó speciálisabb kereséshez adja meg queryType a következőt 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();

Lekérdezés TypeScripttel

A TypeScriptben egy általános paramétert használ, SearchClient amely az indexdokumentumok modellalakzata. 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> | 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();

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

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

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.

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

Lekérdezés aspektusokkal

Az aspektusok segítségével az alkalmazás felhasználója előre konfigurált dimenziók mentén pontosíthatja a keresést. Az arculati szintaxis a rendezési és gyűjtői szemponté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 pontosítás ösztönzésére használható (például egy olyan nyomon követési keresés kiadása, amely a 3-nál nagyobb vagy 4-nél kisebb szűrőt szűri Rating .)

Hibaelhárítás

Naplózá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 értékre info. A naplózás futásidőben is engedélyezhető a következő hívással setLogLevel@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ót.

Következő lépések

Közreműködé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.

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. 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ét. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.

Megjelenések