Delen via

Azure AI Search-clientbibliotheek voor JavaScript - versie 12.1.0

  • Artikel

Azure AI Search (voorheen bekend als 'Azure Cognitive Search') is een op AI gebaseerd platform voor het ophalen van gegevens 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 om:

  • 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 beschikbare opties.

De client verifiëren

Als u wilt communiceren met de zoekservice, moet u een exemplaar van de juiste clientklasse maken: SearchClient voor het zoeken naar geïndexeerde documenten, SearchIndexClient voor het beheren van indexen of SearchIndexerClient voor het verkennen van gegevensbronnen en het laden van zoekdocumenten in een index. Als u een clientobject wilt instantiëren, hebt u een eindpunt nodig en Azure-rollen of een API-sleutel. Raadpleeg de documentatie 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 ophalen en een API-sleutel uit de zoekservice in de Azure Portal. Raadpleeg de documentatie voor instructies over het ophalen 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 typen sleutels die worden gebruikt voor toegang tot uw zoekservice: beheerder(lezen/schrijven) en query(alleen-lezen) sleutels. 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: met het bovenstaande Azure CLI-voorbeeldfragment wordt een beheersleutel opgehaald, zodat u gemakkelijker aan de slag kunt met het verkennen van API's, maar het moet zorgvuldig worden beheerd.

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

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

Verifiëren in een nationale cloud

Als u zich wilt verifiëren in een National Cloud, moet u de volgende toevoegingen aan uw clientconfiguratie aanbrengen:

  • De Audience instellen in 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,
});

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 niet bekend bent met 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 werken in de browser omdat de API's die worden aangeroepen geen ondersteuning hebben 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 eigenschap fields. Elke SearchField heeft een naam, een gegevenstype en aanvullende metagegevens, zoals of deze doorzoekbaar of filterbaar is.

Paginering

Normaal gesproken wilt u alleen een subset met zoekresultaten weergeven aan een gebruiker tegelijk. Ter ondersteuning hiervan kunt u de parameters top, skip en includeTotalCount gebruiken om een pagina-ervaring te bieden boven op 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 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

In de volgende voorbeelden ziet u de basisbeginselen. Bekijk onze voorbeelden voor nog veel meer.

Een index maken

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

Een specifiek document ophalen uit een index

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

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

Documenten toevoegen aan een index

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

Een zoekopdracht uitvoeren op documenten

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

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

Geef voor een geavanceerdere zoekopdracht die gebruikmaakt van Lucene-syntaxisqueryType moet worden 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();

Query's uitvoeren met TypeScript

In TypeScript gebruikt 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 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();

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.

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

Query's uitvoeren met vectoren

Tekst insluitingen kunnen worden opgevraagd met behulp van de vector zoekparameter. Zie queryvectors en filtervectorquery's voor meer informatie.

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

Query's uitvoeren met facetten

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

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

Bij het ophalen van resultaten is een eigenschap facets beschikbaar die het aantal resultaten aangeeft dat in elke facetbucket valt. Dit kan worden gebruikt om verfijning te stimuleren (bijvoorbeeld het uitgeven van een vervolgzoekopdracht die filtert op de Rating 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 meer gedetailleerde instructies over het inschakelen van logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

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 naar cla.microsoft.comvoor meer informatie.

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

indrukken