在 Azure AI 搜尋服務（預覽）中為查詢新增拼字檢查

你可以在查詢單字進入搜尋引擎前，先修正拼字來提升回憶能力。 speller參數（預覽）支援所有文字（非向量）查詢類型，並可透過 Azure 入口網站、預覽版 REST API 及 Azure SDK 函式庫的測試版取得。

先決條件

• 位於任何區域、Basic 層級或更高層級的搜尋服務。

• 一個現有的搜尋索引，內容以 支援語言呈現。

• 將 和 speller=lexicon 設定為queryLanguage的 查詢要求。 拼字檢查會對在參數中傳遞的 search 字串進行。 它不支援篩選器、模糊搜尋、通配符搜尋、正則表達式或向量查詢。

使用支援預覽 API 的搜尋客戶端來處理查詢請求。 你可以使用 REST 客戶端 或是 Azure SDK 的測試版。

使用簡單搜尋來進行拼寫校正

以下範例使用 hotels-sample index 來示範簡單文字查詢的拼寫修正。 若不進行拼寫修正，查詢會回傳零個結果。 更正後，查詢會回傳一個 Johnson 所擁有並以家庭為導向的度假村的結果。

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
    "search": "famly acitvites",
    "speller": "lexicon",
    "queryLanguage": "en-us",
    "queryType": "simple",
    "select": "HotelId,HotelName,Description,Category,Tags",
    "count": true
}

使用完整 Lucene 進行拼寫校正

拼寫修正發生在經過文字分析的個別查詢詞上，因此你可以在某些 Lucene 查詢中使用拼字器參數，而其他則不行。

• 不相容的查詢形式會繞過文字分析，包括：萬用符、正則表達式、模糊
• 相容的查詢表單包括：欄位搜尋、接近度、詞彙提升

此範例使用完整 Lucene 語法，針對 Category 欄位進行欄位搜尋，並包含拼錯的查詢詞彙。 加入拼字檢查工具後，「Suiite」中的錯字被修正，查詢成功。

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
    "search": "Category:(Resort and Spa) OR Category:Suiite",
    "queryType": "full",
    "speller": "lexicon",
    "queryLanguage": "en-us",
    "select": "Category",
    "count": true
}

語意排序的拼寫修正

此查詢除了一個詞外，其他詞彙都有錯字，並會進行拼字修正以返回相關結果。 欲了解更多，請參閱 「設定語意排名器」。

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
    "search": "hisotoric hotell wiht great restrant nad wiifi",
    "queryType": "semantic",
    "speller": "lexicon",
    "queryLanguage": "en-us",
    "searchFields": "HotelName,Tags,Description",
    "select": "HotelId,HotelName,Description,Category,Tags",
    "count": true
}

支援語言

有效值 queryLanguage 可在下表中找到，該表是從 支援語言列表（REST API 參考）複製而來。

語言分析器的考量

包含非英語內容的索引通常會使用語言 分析 器來套用母語的語言規則。

在同時進行語言分析的內容中加入拼字檢查時，使用相同語言在每個索引和查詢處理步驟中都能獲得更好的結果。 例如，如果某欄位的內容是用「fr.microsoft」語言分析器索引的，那麼查詢和拼字檢查都應該使用某種形式的法語詞典或語言庫。

回顧一下 Azure AI 搜尋服務 中語言函式庫的使用情況：

• 語言分析器可在索引與查詢執行時被調用，分別為 Apache Lucene（例如「de.lucene」）或 Microsoft（「de.microsoft）。

• 在拼字檢查中調用的語言詞彙表，是透過 支援語言 表中的語言代碼之一來指定。

在查詢請求中，分配給 的 queryLanguage 值適用於 speller。

雖然搜尋索引中的內容可以用多種語言組合，但查詢輸入最有可能以一種語言呈現。 搜尋引擎不會檢查 queryLanguage、語言分析器及內容撰寫語言的相容性，因此務必相應調整查詢範圍，以避免產生錯誤結果。

下一步

• 建立一個基本查詢
• 使用完整的 Lucene 查詢語法
• 使用簡單的查詢語法