適用於 JavaScript 的 Azure AI 搜尋用戶端連結庫 - 12.1.0 版

發行項
08/02/2024

Azure AI 搜尋（先前稱為「Azure 認知搜尋」）是一個 AI 驅動的資訊擷取平臺，可協助開發人員建置豐富的搜尋體驗和將大型語言模型與企業數據結合的 AI 應用程式。

Azure AI 搜尋服務非常適合下列應用程式案例：

將不同的內容類型合併成單一可搜尋的索引。若要填入索引，您可以推送包含內容的 JSON 檔，或如果您的數據已在 Azure 中，請建立索引器來自動提取數據。
將技能集附加至索引器，以從影像和非結構化檔建立可搜尋的內容。技能集會利用 Azure AI Services 中的 API 進行內建 OCR、實體辨識、關鍵片語擷取、語言偵測、文字翻譯和情感分析。您也可以新增自定義技能，以在數據擷取期間整合內容的外部處理。
在搜尋用戶端應用程式中，實作類似商業 Web 搜尋引擎和聊天樣式應用程式的查詢邏輯和用戶體驗。

使用 @azure/search-documents 用戶端連結庫來：

使用向量、關鍵詞和混合式查詢表單提交查詢。
針對元數據、地理空間搜尋、多面向導覽或根據篩選準則縮小結果，實作篩選的查詢。
建立和管理搜尋索引。
在搜尋索引中上傳和更新檔。
建立和管理將數據從 Azure 提取到索引的索引器。
建立和管理將 AI 擴充新增至數據擷取的技能集。
建立及管理進階文字分析或多語種內容的分析器。
透過語意排名和評分配置檔將結果優化，以納入商業規則或新鮮度。

主要連結：

開始

安裝 `@azure/search-documents` 套件

npm install @azure/search-documents

目前支持的環境

LTS 版本的 Node.js
最新版的 Safari、Chrome、Microsoft Edge 和 Firefox。

如需詳細資訊，請參閱我們的支持原則。

先決條件

若要建立新的搜尋服務，您可以使用 Azure 入口網站、Azure PowerShell或 Azure CLI。以下是使用 Azure CLI 建立免費實例以開始使用的範例：

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

如需可用選項的詳細資訊，請參閱選擇定價層。

驗證用戶端

若要與搜尋服務互動，您必須建立適當的用戶端類別實例：SearchClient 搜尋索引檔、SearchIndexClient 管理索引，或 SearchIndexerClient 編目數據源，以及將搜尋檔載入索引。若要具現化客戶端物件，您需要端點和 Azure 角色 或 API 金鑰。如需使用搜尋服務支持驗證方法的詳細資訊，請參閱檔。

取得 API 金鑰

API 金鑰可能是一種較容易開始的方法，因為它不需要預先存在的角色指派。

您可以從 azure 入口網站中的搜尋服務取得端點和 API 金鑰。如需如何取得 API 金鑰的指示，請參閱檔。

或者，您可以使用下列 Azure CLI 命令，從搜尋服務擷取 API 金鑰：

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

有兩種類型的金鑰可用來存取您的搜尋服務：系統管理員（讀寫） 和查詢（只讀） 密鑰。限制用戶端應用程式中的存取和作業，對於保護服務上的搜尋資產至關重要。請一律針對源自用戶端應用程式的任何查詢使用查詢金鑰，而不是系統管理密鑰。

注意：上述範例 Azure CLI 代碼段會擷取管理密鑰，以便更輕鬆地開始探索 API，但應該謹慎管理。

有了 API 金鑰之後，您可以使用它，如下所示：

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

在國家雲端中驗證

若要在 National Cloud中進行驗證，您必須對客戶端設定進行下列新增：

在 SearchClientOptions 中設定 Audience

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

重要概念

Azure AI 搜尋服務包含一或多個索引，這些索引會以 JSON 檔的形式持續儲存可搜尋的數據。 （如果您不熟悉搜尋，您可以在索引和資料庫數據表之間產生非常粗略的類比。」@azure/search-documents 客戶端連結庫會透過三個主要客戶端類型公開這些資源的作業。

SearchClient 有助於：
- 使用向量查詢、關鍵詞查詢和混合式查詢搜尋索引檔
- 向量查詢篩選和文字查詢篩選
- 語意排名和評分配置檔，以提升相關性
- 根據索引中的文件自動完成部分類型搜尋字詞
- 建議檔中最有可能比對的文字作為用戶類型
- 從索引新增、更新或刪除檔案檔
SearchIndexClient 可讓您：
- 建立、刪除、更新或設定搜尋索引
- 宣告自定義同義字對應以展開或重寫查詢
SearchIndexerClient 可讓您：
- 啟動索引器以自動編目數據源
- 定義 AI 支援的技能集，以轉換和擴充您的資料

附註：這些用戶端無法在瀏覽器中運作，因為它呼叫的 API 不支援跨原始來源資源分享（CORS）。

TypeScript/JavaScript 特定概念

檔

儲存在搜尋索引內的專案。本文件的形狀會使用 fields 屬性在索引中描述。每個 SearchField 都有名稱、數據類型和其他元數據，例如可搜尋或可篩選。

分頁

一般而言，您只想要一次向用戶顯示搜尋結果的子集。若要支援此功能，您可以使用 top、skip 和 includeTotalCount 參數，在搜尋結果上提供分頁體驗。

檔欄位編碼

索引中支援的數據類型會對應至 API 要求/回應中的 JSON 類型。 JS 用戶端連結庫會保留這些大部分相同，但有一些例外：

Edm.DateTimeOffset 會轉換成 JS Date。
Edm.GeographyPoint 會轉換成用戶端連結庫所匯出 GeographyPoint 類型。
number 類型的特殊值（NaN、Infinity、-Infinity）會串行化為 REST API 中的字串，但會由客戶端連結庫轉換成 number。

附註：數據類型會根據值轉換，而不是索引架構中的欄位類型。這表示如果您有ISO8601 Date 字串（例如“2020-03-06T18：48：27.896Z”）作為字段的值，則不論您儲存在架構中的方式為何，都會轉換成 Date。

例子

下列範例示範基本概念 - 請查看我們的範例，深入瞭解。

建立索引
從索引擷取特定檔
將檔新增至索引
對檔執行搜尋
- 使用 TypeScript 進行查詢
- 使用 OData 篩選查詢
- 使用facet進行查詢

建立索引

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

從索引擷取特定檔

特定檔案可以透過其主鍵值來擷取：

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

將檔新增至索引

您可以將多個檔案上傳至批次內的索引：

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

對文件執行搜尋

若要列出特定查詢的所有結果，您可以使用 search 搭配使用簡單查詢語法的搜尋字串：

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

如需使用 Lucene 語法的更進階搜尋，請指定要 full的 queryType：

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

使用 TypeScript 進行查詢

在 TypeScript 中，SearchClient 採用索引檔的模型圖形的泛型參數。這可讓您對結果中傳回的字段執行強型別查閱。 TypeScript 也可以在指定 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();

使用 OData 篩選進行查詢

使用 filter 查詢參數可讓您使用 OData $filter 表達式語法來查詢索引。

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

使用向量查詢

您可以使用搜尋參數 vector 查詢文字內嵌。如需詳細資訊，請參閱查詢向量和篩選向量查詢。

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

Facet 可用來協助應用程式的使用者沿著預先設定的維度精簡搜尋。 Facet 語法提供排序和貯體 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();

擷取結果時，可以使用 facets 屬性，指出落入每個Facet貯體的結果數目。這可用來推動精簡搜尋（例如發出後續搜尋，篩選 Rating 大於或等於 3 且小於 4。

故障排除

伐木

啟用記錄有助於找出有關失敗的實用資訊。若要查看 HTTP 要求和回應的記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，您可以在運行時間啟用記錄，方法是在 @azure/logger中呼叫 setLogLevel：

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

setLogLevel("info");

如需如何啟用記錄的詳細指示，請參閱@azure/記錄器套件檔。

後續步驟

貢獻

如果您想要參與此連結庫，請閱讀參與指南，以深入瞭解如何建置和測試程序代碼。

此項目歡迎參與和建議。大部分的捐款都要求您同意「參與者許可協定」（CLA），宣告您有權，而且實際上確實會授與我們使用您貢獻的許可權。如需詳細資訊，請造訪 cla.microsoft.com。

此項目已採用 Microsoft 開放原始碼程式代碼。如需詳細資訊，請參閱《行為規範》常見問題或連絡 opencode@microsoft.com，以取得任何其他問題或意見。

Microsoft Azure SDK for JavaScript

共用方式為

適用於 JavaScript 的 Azure AI 搜尋用戶端連結庫 - 12.1.0 版

開始

安裝 `@azure/search-documents` 套件

目前支持的環境

先決條件

驗證用戶端

取得 API 金鑰

在國家雲端中驗證

重要概念

TypeScript/JavaScript 特定概念

檔

檔欄位編碼

例子

建立索引

從索引擷取特定檔

將檔新增至索引

對文件執行搜尋

使用 TypeScript 進行查詢

使用 OData 篩選進行查詢

使用向量查詢

使用Facet進行查詢

故障排除

伐木

後續步驟

貢獻

其他資源

共用方式為

適用於 JavaScript 的 Azure AI 搜尋用戶端連結庫 - 12.1.0 版

開始

安裝 @azure/search-documents 套件

目前支持的環境

先決條件

驗證用戶端

取得 API 金鑰

在國家雲端中驗證

重要概念

TypeScript/JavaScript 特定概念

檔

分頁

檔欄位編碼

例子

建立索引

從索引擷取特定檔

將檔新增至索引

對文件執行搜尋

使用 TypeScript 進行查詢

使用 OData 篩選進行查詢

使用向量查詢

使用Facet進行查詢

故障排除

伐木

後續步驟

貢獻

相關專案

其他資源

安裝 `@azure/search-documents` 套件