Delen via

Azure AI Search-clientbibliotheek voor JavaScript - versie 12.2.0

Azure AI Search (voorheen bekend als 'Azure Cognitive Search') is een AI-gebaseerd platform voor het ophalen van informatie waarmee ontwikkelaars uitgebreide zoekervaringen en generatieve AI-apps kunnen bouwen die grote taalmodellen combineren met bedrijfsgegevens.

De Azure AI Search-service is geschikt voor de volgende toepassingsscenario's:

  • Voeg verschillende inhoudstypen samen in één doorzoekbare index. Als u een index wilt vullen, kunt u JSON-documenten pushen die uw inhoud bevatten, of als uw gegevens zich al in Azure bevindt, een indexeerfunctie maken om automatisch gegevens op te halen.
  • Koppel vaardighedensets aan een indexeerfunctie om doorzoekbare inhoud te maken op basis van afbeeldingen en ongestructureerde documenten. Een vaardighedenset maakt gebruik van API's van Azure AI Services voor ingebouwde OCR, entiteitsherkenning, sleuteltermextractie, taaldetectie, tekstomzetting en sentimentanalyse. U kunt ook aangepaste vaardigheden toevoegen om externe verwerking van uw inhoud te integreren tijdens gegevensopname.
  • Implementeer in een zoekclienttoepassing querylogica en gebruikerservaringen die vergelijkbaar zijn met commerciële webzoekprogramma's en chat-apps.

Gebruik de @azure/search-documents clientbibliotheek voor het volgende:

  • Verzend query's met vector-, trefwoord- en hybride queryformulieren.
  • Filterquery's implementeren voor metagegevens, georuimtelijke zoekopdrachten, facetnavigatie of om resultaten te beperken op basis van filtercriteria.
  • Zoekindexen maken en beheren.
  • Documenten uploaden en bijwerken in de zoekindex.
  • Indexeerfuncties maken en beheren die gegevens uit Azure in een index ophalen.
  • Vaardighedensets maken en beheren die AI-verrijking toevoegen aan gegevensopname.
  • Analyses maken en beheren voor geavanceerde tekstanalyse of meertalige inhoud.
  • Optimaliseer de resultaten door middel van semantische classificatie- en scoreprofielen om rekening te houden met bedrijfslogica of nieuwheid.

Sleutelkoppelingen:

Slag

Het @azure/search-documents-pakket installeren

npm install @azure/search-documents

Momenteel ondersteunde omgevingen

Zie ons ondersteuningsbeleid voor meer informatie.

Voorwaarden

Als u een nieuwe zoekservice wilt maken, kunt u de Azure Portal, Azure PowerShell of de Azure CLI gebruiken. Hier volgt een voorbeeld van het gebruik van de Azure CLI om een gratis exemplaar te maken om aan de slag te gaan:

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

Zie Een prijscategorie kiezen voor meer informatie over de beschikbare opties.

De client verifiëren

Als u met de zoekservice wilt communiceren, moet u een exemplaar van de juiste clientklasse maken: SearchClient voor het doorzoeken van geïndexeerde documenten, SearchIndexClient voor het beheren van indexen of SearchIndexerClient voor het doorzoeken van gegevensbronnen en het laden van zoekdocumenten in een index. Als u een clientobject wilt instantiëren, hebt u een eindpunt en Azure-rollen of een API-sleutel nodig. U kunt de documentatie raadplegen voor meer informatie over ondersteunde verificatiemethoden met de zoekservice.

Een API-sleutel ophalen

Een API-sleutel kan een eenvoudigere benadering zijn om mee te beginnen, omdat hiervoor geen vooraf bestaande roltoewijzingen nodig zijn.

U kunt het eindpunt en een API-sleutel ophalen bij de zoekservice in de Azure Portal. Raadpleeg de documentatie voor instructies over het verkrijgen van een API-sleutel.

U kunt ook de volgende Azure CLI-opdracht gebruiken om de API-sleutel op te halen uit de zoekservice:

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

Er zijn twee soorten sleutels die worden gebruikt om toegang te krijgen tot uw zoekservice: admin-toetsen (lezen-schrijven) en query-toetsen (alleen-lezen). Het beperken van de toegang en bewerkingen in client-apps is essentieel voor het beveiligen van de zoekassets op uw service. Gebruik altijd een querysleutel in plaats van een beheersleutel voor elke query die afkomstig is van een client-app.

Opmerking: In het bovenstaande voorbeeld van een Azure CLI-fragment wordt een beheerderssleutel opgehaald, zodat u gemakkelijker aan de slag kunt gaan met het verkennen van API's, maar deze moet zorgvuldig worden beheerd.

Zodra u een API-sleutel hebt, kunt u deze als volgt gebruiken:

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

Verifiëren in een nationale cloud

Om u te authenticeren in een nationale cloud, moet u de volgende toevoegingen aan uw clientconfiguratie doen:

  • Stel de Audience in SearchClientOptions
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,
});

Sleutelbegrippen

Een Azure AI Search-service bevat een of meer indexen die permanente opslag van doorzoekbare gegevens bieden in de vorm van JSON-documenten. (Als u helemaal nieuw bent in het zoeken, kunt u een zeer ruwe analogie maken tussen indexen en databasetabellen.) De @azure/search-documents clientbibliotheek maakt bewerkingen op deze resources beschikbaar via drie hoofdclienttypen.

Opmerking: Deze clients kunnen niet functioneren in de browser omdat de API's die worden aangeroepen, geen ondersteuning bieden voor Cross-Origin Resource Sharing (CORS).

TypeScript-/JavaScript-specifieke concepten

Documenten

Een item dat is opgeslagen in een zoekindex. De vorm van dit document wordt beschreven in de index met behulp van de fields eigenschap. Elk SearchField heeft een naam, een gegevenstype en aanvullende metagegevens, bijvoorbeeld of het doorzoekbaar of filterbaar is.

Paginering

Meestal wilt u slechts een subset van zoekresultaten tegelijk aan een gebruiker laten zien . Om dit te ondersteunen, kunt u de parameters en topskip gebruiken includeTotalCountom een pagina-ervaring te bieden boven aan de zoekresultaten.

Documentveldcodering

Ondersteunde gegevenstypen in een index worden toegewezen aan JSON-typen in API-aanvragen/-antwoorden. De JS-clientbibliotheek houdt deze meestal hetzelfde, met enkele uitzonderingen:

  • Edm.DateTimeOffset wordt geconverteerd naar een JS Date.
  • Edm.GeographyPoint wordt geconverteerd naar een GeographyPoint type dat door de clientbibliotheek wordt geëxporteerd.
  • Speciale waarden van het number type (NaN, Infinity, -Infinity) worden geserialiseerd als tekenreeksen in de REST API, maar worden weer geconverteerd naar number door de clientbibliotheek.

Opmerking: Gegevenstypen worden geconverteerd op basis van waarde, niet op basis van het veldtype in het indexschema. Dit betekent dat als u een ISO8601 datumtekenreeks hebt (bijvoorbeeld '2020-03-06T18:48:27.896Z') als de waarde van een veld, deze wordt geconverteerd naar een datum, ongeacht hoe u deze hebt opgeslagen in uw schema.

Voorbeelden

De volgende voorbeelden demonstreren de basisprincipes - bekijk onze voorbeelden voor nog veel meer.

Een index maken

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

Een specifiek document ophalen uit een index

Een specifiek document kan worden opgehaald met de primaire-sleutelwaarde:

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

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

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

Documenten toevoegen aan een index

U kunt meerdere documenten uploaden naar index in een 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}`);
}

Een zoekopdracht uitvoeren op documenten

Als u alle resultaten van een bepaalde query wilt weergeven, kunt u deze gebruiken search met een zoekreeks die gebruikmaakt van een eenvoudige querysyntaxis:

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

Voor een meer geavanceerde zoekopdracht die gebruikmaakt van Lucene-syntaxis, geeft u queryType op :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);
}

Query's uitvoeren met TypeScript

Neemt in TypeScript SearchClient een algemene parameter die de modelvorm van uw indexdocumenten is. Hiermee kunt u sterk getypte opzoekacties uitvoeren van velden die worden geretourneerd in de resultaten. TypeScript kan ook controleren op velden die worden geretourneerd bij het opgeven van een 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);
}

Query's uitvoeren met OData-filters

Met behulp van de filter queryparameter kunt u een query uitvoeren op een index met behulp van de syntaxis van een OData-$filter expressie.

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

Query's uitvoeren met vectoren

Tekstinbeddingen kunnen worden opgevraagd met behulp van de vector zoekparameter. Zie Queryvectoren en Vectorquery's filteren voor meer informatie.

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

Query's uitvoeren met facetten

Facetten worden gebruikt om een gebruiker van uw toepassing te helpen bij het verfijnen van een zoekopdracht op basis van vooraf geconfigureerde dimensies. Facetsyntaxis biedt de opties voor het sorteren en bucketen van facetwaarden.

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

Bij het ophalen van resultaten is er een facets eigenschap beschikbaar die het aantal resultaten aangeeft dat in elke facetbucket valt. Dit kan worden gebruikt om verfijning te stimuleren (bijvoorbeeld het uitvoeren van een vervolgzoekopdracht die filtert op het Rating feit dat het groter is dan of gelijk is aan 3 en kleiner dan 4).

Probleemoplossing

Logboekregistratie

Als u logboekregistratie inschakelt, kunt u nuttige informatie over fouten ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Voor gedetailleerdere instructies over het inschakelen van logboeken, kunt u de documentatie over het @azure/logger-pakket bekijken.

Volgende stappen

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

Dit project verwelkomt bijdragen en suggesties. Voor de meeste bijdragen moet u akkoord gaan met een Licentieovereenkomst voor inzenders (CLA) waarin wordt aangegeven dat u het recht hebt om, en daadwerkelijk, ons de rechten te verlenen om uw bijdrage te gebruiken. Ga voor meer informatie naar cla.microsoft.com.

Dit project onderschrijft de Microsoft Open Source gedragscode. Zie de Veelgestelde vragen over gedragscodes voor meer informatie of neem contact op met opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.