Azure AI Search-clientbibliotheek voor JavaScript - versie 12.0.0

  • Artikel

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

Azure AI Search is goed 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. Als uw gegevens zich al in Azure bevinden, kunt u een indexeerfunctie maken om automatisch gegevens op te halen.
  • Koppel vaardighedensets aan een indexeerfunctie om doorzoekbare inhoud te maken op basis van afbeeldingen en grote tekstdocumenten. Een vaardighedenset maakt gebruik van API's van AI-services voor ingebouwde OCR, entiteitsherkenning, sleuteltermextractie, taaldetectie, tekstomzetting en sentimentanalyse. U kunt ook aangepaste vaardigheden toevoegen om externe verwerking van uw inhoud tijdens gegevensopname te integreren.
  • Implementeer in een zoekclienttoepassing querylogica en gebruikerservaringen die vergelijkbaar zijn met commerciële webzoekprogramma's.

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

  • Dien query's in met behulp van vector-, trefwoord- en hybride queryformulieren.
  • Implementeer gefilterde query's voor metagegevens, georuimtelijke zoekopdrachten, facetnavigatie of om resultaten te beperken op basis van filtercriteria.
  • Zoekindexen maken en beheren.
  • Documenten in de zoekindex uploaden en bijwerken.
  • Indexeerfuncties maken en beheren die gegevens uit Azure in een index ophalen.
  • Vaardighedensets maken en beheren die AI-verrijking toevoegen aan gegevensopname.
  • Analyseprogramma's maken en beheren voor geavanceerde tekstanalyse of meertalige inhoud.
  • Resultaten optimaliseren met scoreprofielen om rekening te houden met bedrijfslogica of nieuwheid.

Belangrijke koppelingen:

Aan de slag

Installeer het pakket @azure/search-documents

npm install @azure/search-documents

Momenteel ondersteunde omgevingen

Zie ons ondersteuningsbeleid voor meer informatie.

Vereisten

Als u een nieuwe zoekservice wilt maken, kunt u de Azure Portal, Azure PowerShell of de Azure CLI gebruiken. Hier volgt een voorbeeld met behulp 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 en Azure-rollen of een API-sleutel nodig. Raadpleeg de documentatie voor meer informatie over ondersteunde verificatiemethoden met de zoekservice.

Een API-sleutel ophalen

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

U kunt het eindpunt en een API-sleutel ophalen uit de zoekservice in 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 --service-name <mysearch> --resource-group <mysearch-rg>

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 nationale cloud, moet u de volgende toevoegingen aan uw clientconfiguratie aanbrengen:

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

Belangrijkste concepten

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 nog geen ervaring hebt 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 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 Fields. Elk veld heeft een naam, een gegevenstype en aanvullende metagegevens, bijvoorbeeld of het doorzoekbaar of filterbaar is.

Paginering

Normaal gesproken wilt u slechts een subset met zoekresultaten tegelijk aan een gebruiker weergeven. Om dit te ondersteunen, kunt u de topskip parameters en includeTotalCount gebruiken om een gepaginade ervaring boven op de zoekresultaten te bieden.

Documentveldcodering

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

  • Edm.DateTimeOffset wordt geconverteerd naar een JS Date.
  • Edm.GeographyPoint wordt geconverteerd naar een GeographyPoint type dat is geëxporteerd door de clientbibliotheek.
  • Speciale waarden van het number type (NaN, Infinity, -Infinity) worden geserialiseerd als tekenreeksen in de REST API, maar worden weer number geconverteerd 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 (bijvoorbeeld '2020-03-06T18:48:27.896Z') als waarde van een veld hebt, deze wordt geconverteerd naar een datum, ongeacht hoe u deze in uw schema hebt opgeslagen.

Voorbeelden

De volgende voorbeelden laten de basisprincipes zien. 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 een index binnen 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 gebruiken search 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();

Voor een geavanceerdere zoekopdracht die gebruikmaakt van lucene-syntaxis, geeft u queryType op als 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 SearchClient gebruikt u een algemene parameter die de modelvorm van uw indexdocumenten is. Hierdoor kunt u sterk getypte opzoekacties uitvoeren van velden die in de resultaten worden geretourneerd. 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> | 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();

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 insluiten kan worden opgevraagd met behulp van de vector zoekparameter.

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

Query's uitvoeren met facetten

Facetten worden gebruikt om een gebruiker van uw toepassing te helpen bij het verfijnen van een zoekopdracht langs vooraf geconfigureerde dimensies. Facetsyntaxis biedt de opties voor het sorteren en bucket 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 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 de Rating waarde groter dan of gelijk aan 3 en kleiner dan 4.)

Problemen oplossen

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen bij het ontdekken van nuttige informatie over fouten. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de AZURE_LOG_LEVEL omgevingsvariabele in op info. Logboekregistratie kan ook worden ingeschakeld tijdens runtime door aan te roepen setLogLevel in de @azure/logger:

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken kunt u de @azure-/loggerpakketdocumenten bekijken.

Volgende stappen

Bijdragen

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

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar cla.microsoft.com voor meer informatie.

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

Weergaven