Libreria client di Ricerca intelligenza artificiale di Azure per JavaScript - versione 12.0.0
Ricerca di intelligenza artificiale di Azure (in precedenza nota come "Ricerca cognitiva di Azure") è una piattaforma di recupero delle informazioni basata sull'intelligenza artificiale basata sull'intelligenza artificiale che consente agli sviluppatori di creare esperienze di ricerca avanzate e di generare app di intelligenza artificiale che combinano modelli di linguaggio di grandi dimensioni con i dati aziendali.
Ricerca intelligenza artificiale di Azure è ideale per gli scenari dell'applicazione seguenti:
- Consolidare diversi tipi di contenuto in un singolo indice ricercabile. Per popolare un indice, è possibile eseguire il push di documenti JSON contenenti il contenuto oppure se i dati sono già in Azure, creare un indicizzatore per eseguire il pull automatico dei dati.
- Collegare i set di competenze a un indicizzatore per creare contenuto ricercabile da immagini e documenti di testo di grandi dimensioni. Un set di competenze sfrutta le API dai servizi di intelligenza artificiale per il riconoscimento delle entità predefinite, il riconoscimento delle entità, l'estrazione di frasi chiave, il rilevamento della lingua, la traduzione del testo e l'analisi del sentiment. È anche possibile aggiungere competenze personalizzate per integrare l'elaborazione esterna del contenuto durante l'inserimento dei dati.
- In un'applicazione client di ricerca implementare la logica di query e le esperienze utente simili ai motori di ricerca Web commerciali.
Usare la @azure/search-documents libreria client per:
- Inviare query usando vettori, parole chiave e moduli di query ibridi.
- Implementare query filtrate per i metadati, la ricerca geospaziale, lo spostamento in facet o per limitare i risultati in base ai criteri di filtro.
- Creare e gestire gli indici di ricerca.
- Caricare e aggiornare documenti nell'indice di ricerca.
- Creare e gestire gli indicizzatori che estraggono i dati da Azure in un indice.
- Creare e gestire set di competenze che aggiungono l'arricchimento dell'intelligenza artificiale all'inserimento dei dati.
- Creare e gestire analizzatori per l'analisi avanzata del testo o il contenuto multi-linguale.
- Ottimizzare i risultati tramite profili di assegnazione dei punteggi per tenere conto della logica di business o della freschezza.
Collegamenti principali:
- Codice sorgente
- Pacchetto (NPM)
- Documentazione di riferimento delle API
- Documentazione dell'API REST
- Documentazione del prodotto
- Esempi
Guida introduttiva
Installare il pacchetto @azure/search-documents
npm install @azure/search-documents
Ambienti attualmente supportati
- Versioni LTS di Node.js
- Ultime versioni di Safari, Chrome, Edge e Firefox.
Per altre informazioni, vedere i criteri di supporto.
Prerequisiti
Per creare un nuovo servizio di ricerca, è possibile usare la portale di Azure, la Azure PowerShell o l'interfaccia della riga di comando di Azure. Ecco un esempio che usa l'interfaccia della riga di comando di Azure per creare un'istanza gratuita per iniziare:
az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus
Per altre informazioni sulle opzioni disponibili, vedere la scelta di un piano tariffario .
Autenticare il client
Per interagire con il servizio di ricerca, è necessario creare un'istanza della classe client appropriata: SearchClient
per la ricerca di documenti indicizzati, SearchIndexClient
per la gestione degli indici o SearchIndexerClient
per la ricerca per indicizzazione di origini dati e il caricamento di documenti di ricerca in un indice.
Per creare un'istanza di un oggetto client, è necessario un endpoint e un ruolo di Azure o una chiave API. È possibile fare riferimento alla documentazione per altre informazioni sugli approcci di autenticazione supportati con il servizio di ricerca.
Ottenere una chiave API
Una chiave API può essere un approccio più semplice da iniziare perché non richiede assegnazioni di ruolo preesistenti.
È possibile ottenere l'endpoint e una chiave API dal servizio di ricerca nel portale di Azure. Per istruzioni su come ottenere una chiave API, vedere la documentazione .
In alternativa, è possibile usare il comando seguente dell'interfaccia della riga di comando di Azure per recuperare la chiave API dal servizio di ricerca:
az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>
Dopo aver ottenuto una chiave API, è possibile usarla come segue:
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>"));
Eseguire l'autenticazione in un cloud nazionale
Per eseguire l'autenticazione in un cloud nazionale, è necessario apportare le aggiunte seguenti alla configurazione client:
- Impostare l'oggetto
Audience
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,
});
Concetti chiave
Un servizio di ricerca di intelligenza artificiale di Azure contiene uno o più indici che forniscono un'archiviazione persistente di dati ricercabili sotto forma di documenti JSON. Se non si ha familiarità con la ricerca, è possibile creare un'analogia molto approssimativa tra indici e tabelle di database. La @azure/search-documents libreria client espone operazioni su queste risorse tramite tre tipi di client principali.
SearchClient
aiuta con:- Ricerca dei documenti indicizzati usando query vettoriali, query di parole chiave e query ibride
- Filtri di query vettoriali e filtri di query di testo
- Classificazione semantica e profili di assegnazione dei punteggi per aumentare la rilevanza
- Completamento automatico dei termini di ricerca parzialmente tipizzata in base ai documenti nell'indice
- Suggerimento del testo più probabile corrispondente nei documenti come tipi di utente
- Aggiunta, aggiornamento o eliminazione di documenti da un indice
SearchIndexClient
consente di:SearchIndexerClient
consente di:
Nota: questi client non possono funzionare nel browser perché le API chiamate non dispongono del supporto per la condivisione di risorse tra origini (CORS).
Concetti specifici di TypeScript/JavaScript
Documenti
Elemento archiviato all'interno di un indice di ricerca. La forma di questo documento è descritta nell'indice usando Field
s. Ogni campo ha un nome, un tipo di dati e metadati aggiuntivi, ad esempio se è ricercabile o filtrabile.
Paginazione
In genere si vuole visualizzare un sottoinsieme dei risultati della ricerca a un utente alla volta. Per supportare questa operazione, è possibile usare i parametri e includeTotalCount
per fornire un'esperienza top
skip
paginata in cima ai risultati della ricerca.
Codifica del campo documento
I tipi di dati supportati in un indice vengono mappati ai tipi JSON nelle richieste/risposte dell'API. La libreria client JS mantiene queste operazioni principalmente uguali, con alcune eccezioni:
Edm.DateTimeOffset
viene convertito in un oggetto JSDate
.Edm.GeographyPoint
viene convertito in unGeographyPoint
tipo esportato dalla libreria client.- I valori speciali del
number
tipo (NaN, Infinity, -Infinity) vengono serializzati come stringhe nell'API REST, ma vengono convertitinumber
nuovamente dalla libreria client.
Nota: i tipi di dati vengono convertiti in base al valore, non al tipo di campo nello schema di indice. Ciò significa che se si dispone di una stringa di data ISO8601 (ad esempio "2020-03-06T18:48:27.896Z") come valore di un campo, verrà convertito in una data indipendentemente dalla modalità di archiviazione nello schema.
Esempio
Gli esempi seguenti illustrano le nozioni di base: vedere i nostri esempi per molto altro.
- Creazione di un indice
- Recupero di un documento specifico dall'indice
- Aggiunta di documenti all'indice
- Eseguire una ricerca sui documenti
Creare un indice
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();
Recuperare un documento specifico da un indice
Un documento specifico può essere recuperato dal relativo valore di chiave primaria:
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();
Aggiunta di documenti in un indice
È possibile caricare più documenti nell'indice all'interno di un 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();
Eseguire una ricerca sui documenti
Per elencare tutti i risultati di una query specifica, è possibile usare search
con una stringa di ricerca che usa una sintassi di query semplice:
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();
Per una ricerca più avanzata che usa la sintassi Lucene, specificare queryType
come 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();
Esecuzione di query con TypeScript
In TypeScript accetta SearchClient
un parametro generico che rappresenta la forma del modello dei documenti di indice. In questo modo è possibile eseguire una ricerca fortemente tipizzata dei campi restituiti nei risultati. TypeScript è anche in grado di verificare la presenza di campi restituiti quando si specifica un select
parametro.
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();
Esecuzione di query con filtri OData
L'uso del filter
parametro di query consente di eseguire query su un indice usando la sintassi di un'espressione di $filter OData.
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();
Esecuzione di query con vettori
Gli incorporamenti di testo possono essere sottoposti a query usando il vector
parametro di ricerca.
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();
Esecuzione di query con facet
I facet vengono usati per aiutare un utente dell'applicazione a perfezionare una ricerca lungo le dimensioni preconfigurati. La sintassi facet fornisce le opzioni per ordinare e gestire i valori di facet del bucket.
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();
Quando si recuperano i risultati, sarà disponibile una facets
proprietà che indicherà il numero di risultati che rientrano in ogni bucket di facet. Questa operazione può essere usata per guidare la perfezionamento (ad esempio l'emissione di una ricerca di completamento che filtra sull'essere Rating
maggiore o uguale a 3 e minore di 4.)
Risoluzione dei problemi
Registrazione
L'abilitazione della registrazione consente di individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL
su info
. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel
in @azure/logger
:
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.
Passaggi successivi
- Per altre informazioni, vedere i documenti di ricerca e gli esempi
- Altre informazioni sul servizio di ricerca di intelligenza artificiale di Azure
Contributo
Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.
In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, visitare cla.microsoft.com.
Questo progetto ha adottato il codice di comportamento Microsoft Open Source. Per altre informazioni, vedere le domande frequenti sul codice di condotta o contattare opencode@microsoft.com eventuali domande o commenti aggiuntivi.
Progetti correlati
Azure SDK for JavaScript
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per