Dela via

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

  • Artikel

Azure AI Search- (kallades tidigare "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-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.

Använd @azure/search-documents-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-portalen, Azure PowerShelleller 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 du väljer en 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 för att hantera index eller SearchIndexerClient för crawlning av datakällor och inläsning av sökdokument till 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 slutpunkt och en API-nyckel från söktjänsten i Azure-portalen. Mer information om hur du hämtar en API-nyckel finns i dokumentationen.

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ör(skrivskyddad) och fråga(skrivskyddad) nycklar. 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.

Obs! Azure CLI-exempelfragmentet 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:

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 en National Cloudmåste du göra följande tillägg i klientkonfigurationen:

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

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 att söka efter 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 egenskapen fields. Varje SearchField har ett namn, en datatyp och ytterligare metadata, till exempel om det är sökbart eller filterbart.

Paginering

Vanligtvis vill du bara visa en delmängd sökresultat till en användare i taget. För att stödja detta kan du använda parametrarna top, skip och includeTotalCount för att ge en sidsidig upplevelse 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 den 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 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

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

Om du vill ha en mer avancerad sökning som använder Lucene-syntaxanger du queryType som ska 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 tar SearchClient en allmän 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 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

Med frågeparametern filter kan du fråga ett index med hjälp av 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. Mer information finns i Frågevektorer och Filtervektorfrågor.

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

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. Fasetteringssyntax 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 kommer en facets egenskap att vara tillgänglig som anger antalet resultat som hamnar i varje fasetterings bucket. Detta kan användas för att driva förfining (t.ex. genom att utfärda en uppföljningssökning som filtrerar på Rating är 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 @azure/logger-paketdokumenten.

Nästa steg

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide 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 i cla.microsoft.com.

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

visningar