Condividi tramite

Libreria client di Ricerca intelligenza artificiale di Azure per JavaScript - versione 12.1.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 che consente agli sviluppatori di creare esperienze di ricerca avanzate e di generare app di intelligenza artificiale 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.

Usare la libreria client @azure/search-documents 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 altri dettagli, vedere i criteri di supporto .

Prerequisiti

  • Una sottoscrizione di Azure
  • Un servizio di ricerca

Per creare un nuovo servizio di ricerca, è possibile usare il portale di Azure , Azure PowerShello 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 degli indici o SearchIndexerClient per la ricerca per indicizzazione delle origini dati e il caricamento di documenti di ricerca in un indice. Per creare un'istanza di un oggetto client, è necessario un endpoint e i ruoli di Azure o una chiave API . È possibile fare riferimento alla documentazione per altre informazioni su 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 --resource-group <your-resource-group-name> --service-name <your-resource-name>

Esistono due tipi di chiavi usate per accedere al servizio di ricerca: amministratore (lettura/scrittura) e query(sola lettura) chiavi. 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 esempio dell'interfaccia della riga di comando di Azure precedente recupera una chiave di amministrazione, quindi è più semplice iniziare a esplorare le API, ma deve essere gestito con attenzione.

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 il 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 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 creare un'analogia molto approssimativa tra indici e tabelle di database).) La libreria client @azure/search-documents espone le 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 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 proprietà fields. Ogni SearchField ha un nome, un tipo di dati e metadati aggiuntivi, ad esempio se è ricercabile o filtrabile.

Impaginazione

In genere si vuole solo mostrare un subset di risultati della ricerca a un utente contemporaneamente. A tale scopo, è possibile usare i parametri top, skip e includeTotalCount per offrire un'esperienza di paging sui risultati della ricerca.

Codifica dei campi documento

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 DateJS.
  • Edm.GeographyPoint viene convertito in un tipo GeographyPoint esportato dalla libreria client.
  • I valori speciali del tipo number (NaN, Infinity, -Infinity) vengono serializzati come stringhe nell'API REST, ma vengono convertiti nuovamente in number dalla 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

Gli esempi seguenti illustrano le nozioni di base: consultare 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 valore della 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 semplice sintassi di query:

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 sintassi Lucene, specificare queryType da 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 SearchClient accetta 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 parametro select.

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 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 parametro di query filter consente di eseguire query su un indice usando la sintassi di un'espressione $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

È possibile eseguire query sugli incorporamenti di testo usando il parametro di ricerca vector. Per altre informazioni, vedere vettori di query e query sui vettori di filtro.

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

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

async function main() {
  const queryVector = [...];
  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);
  }
}

main();

Esecuzione di query con facet

i facet vengono usati per consentire a un utente dell'applicazione di perfezionare una ricerca lungo le dimensioni preconfigurati. sintassi facet fornisce le opzioni per ordinare e raggruppare i valori dei facet.

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 proprietà facets che indicherà il numero di risultati che rientrano in ogni bucket facet. Questo può essere usato per favorire il perfezionamento (ad esempio, eseguendo una ricerca di completamento che filtra il Rating essere 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, è possibile esaminare la documentazione del pacchetto @azure/logger.

Passaggi successivi

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire 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 informazioni dettagliate, visitare cla.microsoft.com.

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

impressioni