Bagikan melalui

Pustaka klien Azure AI Search untuk JavaScript - versi 12.1.0

  • Artikel

Azure AI Search (sebelumnya dikenal sebagai "Azure Cognitive Search") adalah platform pengambilan informasi yang didukung AI yang membantu pengembang membangun pengalaman pencarian yang kaya dan aplikasi AI generatif yang menggabungkan model bahasa besar dengan data perusahaan.

Layanan Pencarian Azure AI sangat cocok untuk skenario aplikasi berikut:

  • Mengonsolidasikan berbagai jenis konten ke dalam satu indeks yang dapat dicari. Untuk mengisi indeks, Anda dapat mendorong dokumen JSON yang berisi konten Anda, atau jika data Anda sudah ada di Azure, buat pengindeks untuk menarik data secara otomatis.
  • Lampirkan set keterampilan ke pengindeks untuk membuat konten yang dapat dicari dari gambar dan dokumen yang tidak terstruktur. Skillset memanfaatkan API dari Azure AI Services untuk OCR bawaan, pengenalan entitas, ekstraksi frasa kunci, deteksi bahasa, terjemahan teks, dan analisis sentimen. Anda juga dapat menambahkan keterampilan kustom untuk mengintegrasikan pemrosesan eksternal konten Anda selama penyerapan data.
  • Dalam aplikasi klien pencarian, terapkan logika kueri dan pengalaman pengguna yang mirip dengan mesin pencari web komersial dan aplikasi gaya obrolan.

Gunakan pustaka klien @azure/search-documents untuk:

  • Kirim kueri menggunakan formulir kueri vektor, kata kunci, dan hibrid.
  • Terapkan kueri yang difilter untuk metadata, pencarian geospasial, navigasi tersaring, atau untuk mempersempit hasil berdasarkan kriteria filter.
  • Membuat dan mengelola indeks pencarian.
  • Unggah dan perbarui dokumen di indeks pencarian.
  • Buat dan kelola pengindeks yang menarik data dari Azure ke dalam indeks.
  • Membuat dan mengelola set keterampilan yang menambahkan pengayaan AI ke penyerapan data.
  • Membuat dan mengelola penganalisis untuk analisis teks tingkat lanjut atau konten multibahasa.
  • Optimalkan hasil melalui peringkat semantik dan profil penilaian untuk memperhitungkan logika bisnis atau kesegaran.

Tautan kunci:

Persiapan

Menginstal paket @azure/search-documents

npm install @azure/search-documents

Lingkungan yang saat ini didukung

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

  • langganan Azure
  • layanan Pencarian

Untuk membuat layanan pencarian baru, Anda dapat menggunakan portal Azure , Azure PowerShell, atau Azure CLI. Berikut adalah contoh menggunakan Azure CLI untuk membuat instans gratis untuk memulai:

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

Lihat memilih tingkat harga untuk informasi selengkapnya tentang opsi yang tersedia.

Mengautentikasi klien

Untuk berinteraksi dengan layanan pencarian, Anda harus membuat instans kelas klien yang sesuai: SearchClient untuk mencari dokumen terindeks, SearchIndexClient untuk mengelola indeks, atau SearchIndexerClient untuk merayapi sumber data dan memuat dokumen pencarian ke dalam indeks. Untuk membuat instans objek klien, Anda memerlukan titik akhir dan peran Azure atau kunci API . Anda dapat merujuk ke dokumentasi untuk informasi selengkapnya tentang pendekatan autentikasi yang didukung dengan layanan pencarian.

Mendapatkan Kunci API

Kunci API dapat menjadi pendekatan yang lebih mudah untuk memulai karena tidak memerlukan penetapan peran yang sudah ada sebelumnya.

Anda bisa mendapatkan titik akhir dan kunci API dari layanan pencarian di portal Microsoft Azure . Silakan lihat dokumentasi untuk petunjuk tentang cara mendapatkan kunci API.

Atau, Anda dapat menggunakan perintah Azure CLI berikut untuk mengambil kunci API dari layanan pencarian:

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

Ada dua jenis kunci yang digunakan untuk mengakses layanan pencarian Anda: admin (baca-tulis) dan kueri (baca-saja) kunci. Membatasi akses dan operasi di aplikasi klien sangat penting untuk melindungi aset pencarian pada layanan Anda. Selalu gunakan kunci kueri daripada kunci admin untuk kueri apa pun yang berasal dari aplikasi klien.

Catatan: Contoh cuplikan Azure CLI di atas mengambil kunci admin sehingga lebih mudah untuk mulai menjelajahi API, tetapi harus dikelola dengan hati-hati.

Setelah Anda memiliki kunci api, Anda dapat menggunakannya sebagai berikut:

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

Mengautentikasi di Cloud Nasional

Untuk mengautentikasi diNational Cloud, Anda harus membuat tambahan berikut untuk konfigurasi klien Anda:

  • Mengatur Audience di 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,
});

Konsep utama

Layanan Pencarian Azure AI berisi satu atau beberapa indeks yang menyediakan penyimpanan persisten data yang dapat dicari dalam bentuk dokumen JSON. (Jika Anda baru mencari, Anda dapat membuat analogi yang sangat kasar antara indeks dan tabel database.) Pustaka klien @azure/search-documents mengekspos operasi pada sumber daya ini melalui tiga jenis klien utama.

Catatan: Klien ini tidak dapat berfungsi di browser karena API yang disebutnya tidak memiliki dukungan untuk Berbagi Sumber Daya Lintas Asal (CORS).

Konsep spesifik TypeScript/JavaScript

Dokumen

Item yang disimpan di dalam indeks pencarian. Bentuk dokumen ini dijelaskan dalam indeks menggunakan properti fields. Setiap SearchField memiliki nama, jenis data, dan metadata tambahan seperti jika dapat dicari atau dapat difilter.

Pagination

Biasanya Anda hanya ingin menampilkan subset hasil pencarian kepada pengguna pada satu waktu. Untuk mendukung hal ini, Anda dapat menggunakan parameter top, skip, dan includeTotalCount untuk memberikan pengalaman halaman di atas hasil pencarian.

Pengodean bidang dokumen

Jenis data yang didukung dalam indeks dipetakan ke jenis JSON dalam permintaan/respons API. Pustaka klien JS menyimpan ini sebagian besar sama, dengan beberapa pengecualian:

  • Edm.DateTimeOffset dikonversi ke JS Date.
  • Edm.GeographyPoint dikonversi ke jenis GeographyPoint yang diekspor oleh pustaka klien.
  • Nilai khusus dari jenis number (NaN, Infinity, -Infinity) diserialisasikan sebagai string di REST API, tetapi dikonversi kembali ke number oleh pustaka klien.

Catatan: Jenis data dikonversi berdasarkan nilai, bukan jenis bidang dalam skema indeks. Ini berarti bahwa jika Anda memiliki string Tanggal ISO8601 (misalnya, "2020-03-06T18:48:27.896Z") sebagai nilai bidang, itu akan dikonversi ke Tanggal terlepas dari bagaimana Anda menyimpannya dalam skema Anda.

Contoh

Contoh berikut menunjukkan dasar-dasarnya - silakan memeriksa sampel kami untuk lebih banyak lagi.

Membuat Indeks

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

Mengambil dokumen tertentu dari indeks

Dokumen tertentu dapat diambil oleh nilai kunci utamanya:

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

Menambahkan dokumen ke dalam indeks

Anda dapat mengunggah beberapa dokumen ke dalam indeks di dalam 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();

Melakukan pencarian pada dokumen

Untuk mencantumkan semua hasil kueri tertentu, Anda bisa menggunakan search dengan string pencarian yang menggunakan sintaks kueri sederhana :

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

Untuk pencarian yang lebih canggih yang menggunakansintaks Lucene , tentukan menjadi :

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

Mengkueri dengan TypeScript

Di TypeScript, SearchClient mengambil parameter generik yang merupakan bentuk model dokumen indeks Anda. Ini memungkinkan Anda untuk melakukan pencarian bidang yang ditik dengan kuat yang dikembalikan dalam hasil. TypeScript juga dapat memeriksa bidang yang dikembalikan saat menentukan parameter 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();

Mengkueri dengan filter OData

Menggunakan parameter kueri filter memungkinkan Anda mengkueri indeks menggunakan sintaks ekspresi $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();

Mengkueri dengan vektor

Penyematan teks dapat dikueri menggunakan parameter pencarian vector. Lihat Kueri vektor dan Filter kueri vektor untuk informasi selengkapnya.

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

Mengkueri dengan faset

Faset digunakan untuk membantu pengguna aplikasi Anda menyempurnakan pencarian di sepanjang dimensi yang telah dikonfigurasi sebelumnya. sintaks Faset menyediakan opsi untuk mengurutkan dan menyimpan nilai faset.

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

Saat mengambil hasil, properti facets akan tersedia yang akan menunjukkan jumlah hasil yang termasuk dalam setiap wadah faset. Ini dapat digunakan untuk mendorong penyempurnaan (misalnya mengeluarkan pencarian tindak lanjut yang memfilter pada Rating lebih besar dari atau sama dengan 3 dan kurang dari 4.)

Pemecahan masalah

Penebangan

Mengaktifkan pengelogan dapat membantu mengungkap informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.

Langkah berikutnya

Berkontribusi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

Proyek ini menyambut kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi cla.microsoft.com.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Kode Etik atau hubungi opencode@microsoft.com dengan pertanyaan atau komentar tambahan apa pun.

Tayangan