Dela via

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

Azure AI Search (tidigare känt som "Azure Cognitive Search") är en AI-driven 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-tjänsten 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, skapa en indexerare för att hämta data automatiskt.
  • Koppla kompetensuppsättningar till en indexerare för att skapa sökbart innehåll från bilder och ostrukturerade dokument. En kompetensuppsättning utnyttjar API:er från Azure AI Services 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 och chattappar.

@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, fasetterad navigering eller för att begränsa resultaten baserat på filtervillkor.
  • 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 semantisk rangordning och bedömningsprofiler 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

Se välja en prisnivå för mer information om tillgängliga alternativ.

Autentisera klienten

Om du vill 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 för att hantera index eller SearchIndexerClient för att crawla datakällor och läsa in sökdokument i ett index. Om du vill instansiera ett klientobjekt behöver du en slutpunkt och Azure-roller eller en API-nyckel. I dokumentationen finns mer information om vilka autentiseringsmetoder som stöds med söktjänsten.

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 instruktioner om hur du skaffar 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 --resource-group <your-resource-group-name> --service-name <your-resource-name>

Det finns två typer av nycklar som används för att komma åt söktjänsten: administratörsnycklar(läs- och skrivnycklar) och frågenycklar(skrivskyddade). Det är viktigt att begränsa åtkomst och åtgärder i klientappar för att skydda söktillgångarna i din tjänst. Använd alltid en frågenyckel i stället för en administratörsnyckel för frågor som kommer från en klientapp.

Exemplet på Azure CLI-kodfragmentet ovan hämtar en administratörsnyckel så att det är enklare att komma igång med att utforska API:er, men det bör hanteras noggrant.

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

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

Autentisera i ett nationellt moln

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

  • Ställ in in 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,
});

Viktiga begrepp

En Azure AI Search-tjänst 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 på att söka kan du göra en mycket grov analogi mellan index och databastabeller.) Klientbiblioteket @azure/search-documents exponerar åtgärder på dessa resurser via tre huvudsakliga klienttyper.

Dessa klienter kan inte fungera i webbläsaren eftersom de API:er som anropas inte har stöd för CORS (Cross-Origin Resource Sharing).

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 egenskapen fields . Var SearchField och en har ett namn, en datatyp och ytterligare metadata, till exempel om den är sökbar eller filtrerbar.

Paginering

Vanligtvis vill du bara visa en delmängd av sökresultaten för en användare åt gången. För att stödja detta kan du använda parametrarna topoch skipincludeTotalCount för att ge 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.
  • Särskilda värden av typen number (NaN, Infinity -Infinity) serialiseras som strängar i REST API, 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 den till ett datum oavsett hur du lagrade den i schemat.

Exempel

Följande exempel visar grunderna – kolla in våra exempel för mycket mer.

Skapa ett index

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

Hämta ett specifikt dokument från ett index

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

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

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

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

Lägga till dokument i ett index

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

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

Utföra en sökning i dokument

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

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

Om du vill ha en mer avancerad sökning som använder Lucene-syntax anger du queryType att vara full:

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

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

Fråga med OData-filter

filter Med hjälp av frågeparametern kan du fråga ett index med hjälp av syntaxen för ett OData-$filter uttryck.

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

Fråga med vektorer

Textinbäddningar kan efterfrågas med hjälp av sökparametern vector . Mer information finns i Frågevektorer och Filtrera vektorfrågor .

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

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. Fasettsyntax ger alternativ för att sortera och bucketa fasettvärden.

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

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

Felsökning

Skogsavverkning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning 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 dokument för @azure/logger-paket.

Nästa steg

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguiden för att lära dig mer om hur du skapar och testar koden.

Det här projektet välkomnar bidrag och förslag. De flesta bidrag kräver att du godkänner ett licensavtal för deltagare (CLA) som förklarar att du har rätt att, och faktiskt gör det, ge oss rätten att använda ditt bidrag. Mer information finns på cla.microsoft.com.

Det här projektet har antagit Microsoft Open Source Code of Conduct (Microsofts regler för uppförande för öppen källkod). Mer information finns i vanliga frågor och svar om uppförandekod eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.