Pustaka klien Azure AI Search untuk JavaScript - versi 12.0.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.

Pencarian Azure AI sangat cocok untuk skenario aplikasi berikut:

  • Mengonsolidasikan jenis konten yang bervariasi 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 teks besar. Skillset memanfaatkan API dari layanan AI 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.

@azure/search-documents Gunakan pustaka klien 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 dalam indeks pencarian.
  • Buat dan kelola pengindeks yang menarik data dari Azure ke dalam indeks.
  • Buat dan kelola set keterampilan yang menambahkan pengayaan AI ke penyerapan data.
  • Membuat dan mengelola penganalisis untuk analisis teks tingkat lanjut atau konten multibahasa.
  • Optimalkan hasil melalui profil penilaian untuk memperhitungkan logika bisnis atau kesegaran.

Tautan utama:

Memulai

Pasang paket @azure/search-documents

npm install @azure/search-documents

Lingkungan yang didukung saat ini

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

Untuk membuat layanan pencarian baru, Anda bisa 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 --service-name <mysearch> --resource-group <mysearch-rg>

Setelah 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 di National Cloud, Anda harus membuat tambahan berikut ke konfigurasi klien Anda:

  • Atur di AudienceSearchClientOptions
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

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

Catatan: Klien ini tidak dapat berfungsi di browser karena API yang dipanggilnya 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 Fields. Setiap Bidang memiliki nama, jenis data, dan metadata tambahan seperti jika dapat dicari atau dapat difilter.

Paginasi

Biasanya Anda hanya ingin menampilkan subset hasil pencarian kepada pengguna pada satu waktu. Untuk mendukung ini, Anda dapat menggunakan topparameter , dan includeTotalCountskip 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 sebagian besar hal yang sama, dengan beberapa pengecualian:

  • Edm.DateTimeOffset dikonversi ke JS Date.
  • Edm.GeographyPoint dikonversi ke jenis yang GeographyPoint diekspor oleh pustaka klien.
  • Nilai khusus dari number jenis (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 lihat 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 menggunakan sintaks Lucene, tentukan queryType menjadi 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();

Mengkueri dengan TypeScript

Di TypeScript, SearchClient ambil 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 select parameter.

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

Mengkueri dengan filter OData

filter Menggunakan parameter kueri 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 vector parameter pencarian.

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

Mengkueri dengan faset

Faset digunakan untuk membantu pengguna aplikasi Anda memperbaiki 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, facets properti 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 Rating yang lebih besar dari atau sama dengan 3 dan kurang dari 4.)

Pemecahan Masalah

Pencatatan

Mengaktifkan pengelogan dapat membantu menemukan 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 baik 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 kontak opencode@microsoft.com dengan pertanyaan atau komentar tambahan apa pun.

Tayangan