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

  • Articolo

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:

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

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.

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 Fields. 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 topskip 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 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 convertiti number 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.

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

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.

Impression