Azure AI Search-clientbibliotheek voor JavaScript - versie 12.0.0
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:
- Broncode
- Pakket (NPM)
- API-referentiedocumentatie
- REST API-documentatie
- Productdocumentatie
- Voorbeelden
Aan de slag
Installeer het pakket @azure/search-documents
npm install @azure/search-documents
Momenteel ondersteunde omgevingen
- LTS-versies van Node.js
- Nieuwste versies van Safari, Chrome, Edge en Firefox.
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 inSearchClientOptions
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.
SearchClient
helpt bij:- Uw geïndexeerde documenten doorzoeken met vectorquery's, trefwoordquery's en hybride query's
- Vectorqueryfilters en Tekstqueryfilters
- Semantische classificatie - en scoreprofielen voor het vergroten van de relevantie
- Gedeeltelijk getypte zoektermen automatisch aanvullen op basis van documenten in de index
- De meest waarschijnlijke overeenkomende tekst in documenten voorstellen terwijl een gebruiker typt
- Documenten toevoegen, bijwerken of verwijderen uit een index
SearchIndexClient
hiermee kunt u het volgende doen:SearchIndexerClient
hiermee kunt u het volgende doen:
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 Field
s. 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 top
skip
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 JSDate
.Edm.GeographyPoint
wordt geconverteerd naar eenGeographyPoint
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 weernumber
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
- Een specifiek document ophalen uit de index
- Documenten toevoegen aan uw index
- Een zoekopdracht uitvoeren op documenten
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.
Verwante projecten
Azure SDK for JavaScript
Feedback
https://aka.ms/ContentUserFeedback.
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie:Feedback verzenden en weergeven voor