Azure AI Search-klientbibliotek för JavaScript – version 12.0.0

  • Artikel

Azure AI Search (tidigare kallat "Azure Cognitive Search") är en AI-baserad plattform för informationshämtning som hjälper utvecklare att skapa omfattande sökupplevelser och generativa AI-appar som kombinerar stora språkmodeller med företagsdata.

Azure AI Search passar bra för följande programscenarier:

  • Konsolidera olika innehållstyper till ett enda sökbart index. Om du vill fylla i ett index kan du skicka JSON-dokument som innehåller ditt innehåll, eller om dina data redan finns i Azure skapar du en indexerare som hämtar data automatiskt.
  • Koppla kompetensuppsättningar till en indexerare för att skapa sökbart innehåll från bilder och stora textdokument. En kompetensuppsättning utnyttjar API:er från AI-tjänster för inbyggd OCR, entitetsigenkänning, extrahering av nyckelfraser, språkidentifiering, textöversättning och attitydanalys. Du kan också lägga till anpassade kunskaper för att integrera extern bearbetning av ditt innehåll under datainmatning.
  • I ett sökklientprogram implementerar du frågelogik och användarupplevelser som liknar kommersiella webbsökmotorer.

@azure/search-documents Använd klientbiblioteket för att:

  • Skicka frågor med hjälp av vektor-, nyckelords- och hybridfrågeformulär.
  • Implementera filtrerade frågor för metadata, geospatial sökning, aspektbaserad navigering eller för att begränsa resultaten baserat på filterkriterier.
  • Skapa och hantera sökindex.
  • Ladda upp och uppdatera dokument i sökindexet.
  • Skapa och hantera indexerare som hämtar data från Azure till ett index.
  • Skapa och hantera kompetensuppsättningar som lägger till AI-berikande för datainmatning.
  • Skapa och hantera analysverktyg för avancerad textanalys eller flerspråkigt innehåll.
  • Optimera resultaten genom att bedöma profiler för att ta hänsyn till affärslogik eller färskhet.

Nyckellänkar:

Komma igång

Installera @azure/search-documents-paketet

npm install @azure/search-documents

Miljöer som stöds för närvarande

Mer information finns i vår supportprincip .

Förutsättningar

Om du vill skapa en ny söktjänst kan du använda Azure Portal, Azure PowerShell eller Azure CLI. Här är ett exempel som använder Azure CLI för att skapa en kostnadsfri instans för att komma igång:

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

Mer information om tillgängliga alternativ finns i Välja prisnivå .

Autentisera klienten

För att interagera med söktjänsten måste du skapa en instans av lämplig klientklass: SearchClient för att söka i indexerade dokument, SearchIndexClient hantera index eller SearchIndexerClient crawla datakällor och läsa in sökdokument i ett index.

För att instansiera ett klientobjekt behöver du en slutpunkt och Azure-roller eller en API-nyckel. Mer information om autentiseringsmetoder som stöds med söktjänsten finns i dokumentationen.

Hämta en API-nyckel

En API-nyckel kan vara en enklare metod att börja med eftersom den inte kräver befintliga rolltilldelningar.

Du kan hämta slutpunkten och en API-nyckel från söktjänsten i Azure Portal. Se dokumentationen för anvisningar om hur du hämtar en API-nyckel.

Du kan också använda följande Azure CLI-kommando för att hämta API-nyckeln från söktjänsten:

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

När du har en API-nyckel kan du använda den på följande sätt:

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

Autentisera i ett nationellt moln

Om du vill autentisera i ett nationellt moln måste du göra följande tillägg i klientkonfigurationen:

  • Audience Ange iSearchClientOptions
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,
});

Viktiga begrepp

En Azure AI-tjänsten Search innehåller ett eller flera index som ger beständig lagring av sökbara data i form av JSON-dokument. (Om du är helt ny att söka i kan du göra en mycket grov analogi mellan index och databastabeller.) Klientbiblioteket @azure/search-documents exponerar åtgärder för dessa resurser via tre huvudsakliga klienttyper.

Obs! Dessa klienter kan inte fungera i webbläsaren eftersom DE API:er som anropas inte har stöd för resursdelning mellan ursprung (CORS).

TypeScript/JavaScript-specifika begrepp

Dokument

Ett objekt som lagras i ett sökindex. Formen på det här dokumentet beskrivs i indexet med hjälp av Fields. Varje fält har ett namn, en datatyp och ytterligare metadata, till exempel om det är sökbart eller filterbart.

Sidnumrering

Vanligtvis vill du bara visa en delmängd av sökresultaten för en användare samtidigt. För att stödja detta kan du använda parametrarna topoch includeTotalCountskip för att tillhandahålla en växlingsupplevelse ovanpå sökresultaten.

Kodning av dokumentfält

Datatyper som stöds i ett index mappas till JSON-typer i API-begäranden/svar. JS-klientbiblioteket behåller dessa mestadels på samma sätt, med vissa undantag:

  • Edm.DateTimeOffset konverteras till en JS Date.
  • Edm.GeographyPoint konverteras till en GeographyPoint typ som exporteras av klientbiblioteket.
  • Specialvärden av number typen (NaN, Infinity, -Infinity) serialiseras som strängar i REST-API:et, men konverteras tillbaka till number av klientbiblioteket.

Obs! Datatyper konverteras baserat på värde, inte fälttypen i indexschemat. Det innebär att om du har en ISO8601 datumsträng (t.ex. "2020-03-06T18:48:27.896Z") som värde för ett fält konverteras det till ett datum oavsett hur du lagrade det i schemat.

Exempel

Följande exempel visar grunderna – läs våra exempel för mycket mer.

Skapa ett index

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

Hämta ett specifikt dokument från ett index

Ett specifikt dokument kan hämtas med dess primära nyckelvärde:

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

Lägga till dokument i ett index

Du kan ladda upp flera dokument till index i en batch:

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

Utföra en sökning i dokument

Om du vill visa en lista över alla resultat för en viss fråga kan du använda search med en söksträng som använder enkel frågesyntax:

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

För en mer avancerad sökning som använder Lucene-syntax anger du queryType till 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();

Fråga med TypeScript

I TypeScript SearchClient tar en generisk parameter som är modellformen för dina indexdokument. På så sätt kan du utföra starkt typifierad sökning av fält som returneras i resultat. TypeScript kan också söka efter fält som returneras när du anger en select parameter.

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

Fråga med OData-filter

filter Med frågeparametern kan du köra frågor mot ett index med syntaxen för ett OData-$filter uttryck.

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

Fråga med vektorer

Textinbäddningar kan efterfrågas med hjälp av sökparametern vector .

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

Fråga med fasetter

Fasetter används för att hjälpa en användare av ditt program att förfina en sökning längs förkonfigurerade dimensioner. Fasetteringssyntaxen innehåller alternativ för sortering och bucketfasetteringsvärden.

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

När du hämtar resultat blir en facets egenskap tillgänglig som anger antalet resultat som hamnar i varje fasetteringsbucket. Detta kan användas för att driva förfining (t.ex. genom att utfärda en uppföljningssökning som filtrerar på Rating att vara större än eller lika med 3 och mindre än 4.)

Felsökning

Loggning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg över HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Loggning kan också aktiveras vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokumentationen om @azure-/loggningspaket.

Nästa steg

Bidra

Om du vill bidra till det här biblioteket kan du läsa bidragsguiden om du vill veta mer om hur du skapar och testar koden.

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns i cla.microsoft.com.

Det här projektet har antagit Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.

Visningar