Condividi tramite

Libreria client di Ricerca di Azure per intelligenza artificiale per JavaScript - versione 12.2.0

Ricerca di intelligenza artificiale di Azure (precedentemente nota come "Ricerca cognitiva di Azure") è una piattaforma di recupero delle informazioni basata sull'intelligenza artificiale che consente agli sviluppatori di creare esperienze di ricerca avanzate e app di intelligenza artificiale generativa che combinano modelli linguistici di grandi dimensioni con dati aziendali.

Il servizio Ricerca intelligenza artificiale di Azure è ideale per gli scenari di applicazione seguenti:

  • Consolidare tipi di contenuto diversi in un singolo indice ricercabile. Per popolare un indice, è possibile eseguire il push di documenti JSON che contengono il contenuto o se i dati sono già in Azure, creare un indicizzatore per eseguire automaticamente il pull dei dati.
  • Allegare set di competenze a un indicizzatore per creare contenuto ricercabile da immagini e documenti non strutturati. Un set di competenze sfrutta le API di Servizi di intelligenza artificiale di Azure per il riconoscimento ottico dei dati predefiniti, il riconoscimento delle entità, l'estrazione di frasi chiave, il rilevamento della lingua, la traduzione testuale e l'analisi del sentiment. È anche possibile aggiungere competenze personalizzate per integrare l'elaborazione esterna del contenuto durante l'inserimento dati.
  • In un'applicazione client di ricerca implementare la logica di query e le esperienze utente simili ai motori di ricerca Web commerciali e alle app in stile chat.

Utilizza la @azure/search-documents libreria client per:

  • Inviare query usando moduli di query vettoriali, parole chiave e ibridi.
  • Implementare query filtrate per i metadati, la ricerca geospaziale, la navigazione in base a facet o limitare i risultati in base ai criteri di filtro.
  • Creare e gestire gli indici di ricerca.
  • Caricare e aggiornare i documenti nell'indice di ricerca.
  • Creare e gestire indicizzatori che estraggono dati da Azure in un indice.
  • Creare e gestire set di competenze che aggiungono l'arricchimento tramite intelligenza artificiale all'inserimento dati.
  • Creare e gestire analizzatori per l'analisi avanzata del testo o il contenuto multilingue.
  • Ottimizzare i risultati tramite la classificazione semantica e i profili di punteggio per tenere conto della logica di business o dell'aggiornamento.

Collegamenti chiave:

Introduttiva

Installare il pacchetto @azure/search-documents

npm install @azure/search-documents

Ambienti attualmente supportati

Per altre informazioni, vedere i criteri di supporto.

Prerequisiti

Per creare un nuovo servizio di ricerca, è possibile usare il portale di Azure, Azure PowerShell o l'interfaccia della riga di comando di Azure. Ecco un esempio di uso dell'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 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 di 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, sono necessari un endpoint e ruoli di Azure o una chiave API. Per ulteriori informazioni sugli approcci di autenticazione supportati con il servizio di ricerca, vedere la documentazione.

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. Si prega di fare riferimento alla documentazione per istruzioni su come ottenere una chiave API.

In alternativa, è possibile usare il comando dell'interfaccia della riga di comando di Azure seguente per recuperare la chiave API dal servizio di ricerca:

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

Esistono due tipi di chiavi usate per accedere al servizio di ricerca: chiavi amministratore(lettura-scrittura) e chiavi di query(sola lettura). Limitare l'accesso e le operazioni nelle app client è essenziale per proteggere gli asset di ricerca nel servizio. Usare sempre una chiave di query anziché una chiave di amministrazione per qualsiasi query proveniente da un'app client.

Nota: il frammento di interfaccia della riga di comando di Azure di esempio precedente recupera una chiave amministratore in modo che sia più facile iniziare a esplorare le API, ma deve essere gestito con attenzione.

Dopo aver ottenuto una chiave API, è possibile usarla come segue:

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

Eseguire l'autenticazione in un cloud nazionale

Per eseguire l'autenticazione in un cloud nazionale, è necessario apportare le seguenti aggiunte alla configurazione del client:

  • Impostare il 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,
});

Concetti chiave

Un servizio Ricerca intelligenza artificiale di Azure contiene uno o più indici che forniscono un archivio permanente di dati ricercabili sotto forma di documenti JSON. Se non si ha familiarità con la ricerca, è possibile fare un'analogia molto approssimativa tra indici e tabelle di database. La @azure/search-documents libreria client espone le operazioni su queste risorse tramite tre tipi di client principali.

Nota: questi client non possono funzionare nel browser perché le API che chiamano non supportano la condivisione di risorse tra le 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 utilizzando la fields proprietà. Ognuno SearchField di essi dispone di un nome, di un tipo di dati e di metadati aggiuntivi, ad esempio se è ricercabile o filtrabile.

Impaginazione

In genere, si desidera mostrare a un utente solo un sottoinsieme di risultati di ricerca alla volta. A tale scopo, è possibile utilizzare i parametri e topskip per fornire un'esperienza includeTotalCountdi paging sopra i risultati della ricerca.

Codifica dei campi documento

I tipi di dati supportati in un indice vengono mappati ai tipi JSON nelle richieste/risposte API. La libreria client JS mantiene le stesse per lo più, con alcune eccezioni:

  • Edm.DateTimeOffset viene convertito in un JS Date.
  • Edm.GeographyPoint viene convertito in un GeographyPoint tipo esportato dalla libreria client.
  • I valori speciali del number tipo (NaN, Infinity, -Infinity) vengono serializzati come stringhe nell'API REST, ma vengono riconvertiti dalla number libreria client.

Nota: I tipi di dati vengono convertiti in base al valore, non al tipo di campo nello schema dell'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.

Esempi

I seguenti esempi illustrano le basi: dai un'occhiata ai nostri esempi per molto di più.

Creare un indice

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

Recuperare un documento specifico da un indice

Un documento specifico può essere recuperato dal valore della chiave primaria:

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

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

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

Aggiunta di documenti in un indice

È possibile caricare più documenti nell'indice all'interno di un 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}`);
}

Eseguire una ricerca sui documenti

Per elencare tutti i risultati di una determinata query, è possibile utilizzare search una stringa di ricerca che utilizza una sintassi di query semplice:

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

Per una ricerca più avanzata che utilizza la sintassi Lucene, specificare queryType di essere 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);
}

Esecuzione di query con TypeScript

In TypeScript, SearchClient accetta un parametro generico che è 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>;
  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);
}

Esecuzione di query con filtri OData

L'utilizzo del filter parametro query consente di eseguire una query su un indice utilizzando la sintassi di un'espressione OData $filter.

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

Esecuzione di query con vettori

Gli incorporamenti di testo possono essere interrogati utilizzando il vector parametro search. Per ulteriori informazioni, vedere Vettori di query e Filtrare le query vettoriali .

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

Esecuzione di query con facet

I facet vengono utilizzati per aiutare un utente dell'applicazione a perfezionare una ricerca in base a dimensioni preconfigurate. La sintassi dei facet fornisce le opzioni per ordinare e suddividere i valori dei facet.

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

Quando si recuperano i risultati, sarà disponibile una facets proprietà che indicherà il numero di risultati che rientrano in ogni bucket di facet. Questo può essere utilizzato per guidare il perfezionamento (ad esempio, emettendo una ricerca di follow-up che filtra in base all'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 nel @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, vedere la documentazione del pacchetto @azure/logger.

Passaggi successivi

Contribuire

Per contribuire a questa libreria, leggere la guida per i contributi per altre informazioni su come compilare e testare il codice.

Questo progetto accoglie contributi e suggerimenti. La maggior parte dei contributi richiede l'accettazione di un Contratto di licenza collaboratore (CLA) che dichiara di avere il diritto e, in realtà, concedere a Microsoft i diritti per l'uso del contributo. Per ulteriori informazioni, visitare il sito cla.microsoft.com.

Questo progetto ha adottato il codice di comportamento open source Microsoft. Per altre informazioni, vedere domande frequenti sul codice di comportamento o contattare opencode@microsoft.com con eventuali domande o commenti aggiuntivi.

  • Last updated on