更新或重建 Azure AI 搜尋服務中的索引

發行項
10/16/2024

本文說明如何透過累加式索引編製，使用結構描述變更或內容變更來更新 Azure AI 搜尋服務中的現有索引。包含需要重建的情況，並提供可降低重建對進行中查詢要求影響的建議。

在活躍開發期間，當您在反覆設計索引時，通常會卸載並重建索引。大部分的開發人員會使用其資料的小型代表性範例，以便加快重新編製索引的速度。

若要變更生產環境中既有應用程式的結構描述，建議您建立並測試會與現有索引並存執行的新索引。使用索引別名來交換新索引，同時避免變更應用程式的程式碼。

更新內容

對大多數搜尋應用程式來說，以累加方式對來源資料的變更進行索引編製和同步處理是很重要的操作。本節會說明在搜尋索引中更新欄位內容的工作流程。

使用相同的技術來載入文件：文件 - 索引 (REST)，或 Azure SDK 中的對等 API。如需索引編製技術的詳細資訊，請參閱載入文件。

設定 @search.action 參數以判斷對現有文件的影響：

動作	效果
delete	從索引中移除整份文件。如果想要移除個別欄位，請改用 merge，將有問題的欄位設定為 null。已刪除的文件和欄位不會立即釋放索引中的空間。每隔幾分鐘，背景程序就會執行實體刪除。無論您使用入口網站還是 API 來傳回索引統計資料，系統應該都會延遲一會，才會在入口網站中和透過 API 反映刪除操作。
合併	更新已經存在的文件，並讓找不到的文件失效。合併會取代現有的值。基於這個原因，請務必檢查包含多個值的集合欄位，例如類型為 `Collection(Edm.String)` 的欄位。例如，如果 `tags` 欄位以 `["budget"]` 的值開始，而且使用 `["economy", "pool"]` 執行合併，則 `tags` 欄位的最終值為 `["economy", "pool"]`。其不會是 `["budget", "economy", "pool"]`。
mergeOrUpload	如果文件存在，行為會和合併一樣，如果是新文件，則會上傳。這是累加式更新最常見的動作。
上傳	類似 "upsert"，如果是新文件，就會插入該文件，如果文件已經存在，則會更新或取代該文件。如果文件遺漏索引所需的值，則文件欄位的值會設定為 null。

發佈更新。

查詢會繼續執行，但如果您要更新或移除現有欄位，則應該會有混合的結果，並且有較高的機會發生節流。

累加式索引編製的秘訣

索引子會自動進行累加式索引編製。如果可以使用索引子，而且資料來源支援變更追蹤，便可以對週期性排程執行索引子，以新增、更新或覆寫可搜尋的內容，使其同步處理至外部資料。
如果您要直接透過推送 API 進行索引呼叫，請使用 mergeOrUpload 作為搜尋動作。
承載必須包含您要新增、更新或刪除之每個文件的索引或識別碼。
如果您的索引包含向量欄位，並將 stored 屬性設定為 false，請確定您在部分文件更新中提供向量，即使值未變更也一樣。將 stored 設定為 false 的副作用，是在重新編製索引作業時卸除向量。在文件承載中提供向量可防止這種情況發生。
若要更新複雜類型中簡單欄位和子欄位的內容，請只列出您想要變更的欄位。例如，如果您只需要更新描述欄位，承載應該包含文件索引鍵和修改後的描述。省略其他欄位會保留那些欄位現有的值。
若要將內嵌變更合併到字串集合中，請提供整個值。回想上一節的 tags 欄位範例。新的值會覆寫整個欄位舊的值，而且欄位的內容中沒有合併。

以下是示範這些秘訣的 REST API 範例：

### Get Secret Point Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

### Change the description, city, and tags for Secret Point Hotel
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Secret Point Hotel.",
            "Tags": ["my old item", "my new item"],
            "Address": {
                "City": "Gotham City"
                }
            }
        ]
    }
       
### Retrieve the same document, confirm the overwrites and retention of all other values
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

變更索引結構描述

索引結構描述會定義在搜尋服務上建立的實體資料結構，因此，不進行完整重建就很難進行許多結構描述變更。下列清單會列舉可順暢地引入到現有索引的結構描述變更。一般而言，清單中會包含查詢執行期間所使用的新欄位和新功能。

新增欄位
對現有欄位設定 retrievable 屬性
對具有現有 indexAnalyzer 的欄位更新 searchAnalyzer
在索引中新增分析器定義 (可套用至新欄位)
新增、更新或刪除評分設定檔
新增、更新或刪除 CORS 設定
新增、更新或刪除 synonymMaps
新增、更新或刪除語意設定

作業順序為：

取得索引定義。
使用上一個清單中的更新來修訂結構描述。
在搜尋服務上更新索引結構描述。
如果您增加了新的欄位，請更新索引內容以符合修訂後的結構描述。至於所有其他變更，則會依現狀使用現有編制的內容。

當您更新索引結構描述以包含新欄位時，索引中的現有文件會針對欄位獲得 null 值。在執行下一個編制作業時，來自外部來源資料的值便會取代 Azure AI 搜尋服務所新增的 null。

更新期間應該不會有查詢中斷的情況，但查詢結果會隨著更新的生效而不同。

卸除並重建索引

某些修改需要索引卸除和重建，以新的索引取代目前的索引。

動作	描述
刪除欄位	若要實體上移除欄位的所有追蹤，您必須重建索引。若無法立即重建，您可以修改應用程式的程式碼以重新導向對於已淘汰欄位的存取，或使用 searchFields 並選取查詢參數來選擇要搜尋和傳回的欄位。實體上，在您下次套用省略問題欄位的結構描述重建之前，欄位定義和內容都會保留在索引中。
變更欄位定義	修改欄位名稱、資料類型或特定索引屬性 (可搜尋、可篩選、可排序、可面向化) 需要完整重建。
將分析器指派給欄位	分析器會在索引中定義、指派給欄位，然後在編製索引期間叫用以指示令牌的建立方式。您可以隨時將新分析器定義新增至索引，但當欄位建立後，您只能指派分析器。這適用於 analyzer 和 indexAnalyzer 屬性。 searchAnalyzer 屬性是例外狀況 (您可以將此屬性指派給現有欄位)。
更新或刪除索引中的分析器定義	您無法刪除或變更索引中的現有分析器組態 (分析器、權杖化工具、權杖篩選器或 char 篩選器)，除非您重建整個索引。
將欄位新增至建議工具	如果已有欄位存在，且您想要將它新增至建議工具建構中，請重建索引。
切換階層	不支援就地升級。如果您需要更多容量，請建立新的服務，並徹底重建您的索引。為了協助將此程序自動化，您可以使用這個 Azure AI 搜尋服務 .NET 範例存放庫中的 index-backup-restore 範例程式碼。此應用程式會將您的索引備份到一系列 JSON 檔案，然後在您指定的搜尋服務中重新建立索引。

作業順序為：

如果您需要索引定義以供日後參考，或作為新版本基礎使用，請取得索引定義。
考慮使用備份與還原解決方案來保留索引內容的複本。有 C# 和 Python 版本的解決方案。建議使用 Python 版本，因為這個版本比較新。

如果您有搜尋服務的容量，請在建立和測試新索引時保留現有的索引。
卸除現有索引。目標是該索引的查詢會立即卸除。請記住，刪除索引是無法復原的動作，這樣會終結欄位集合和其他建構的實體儲存體。
發佈經過修訂的索引，讓要求的本文包含經過變更或修改的欄位定義和設定。
使用來自外部來源的文件載入索引 $英文$。系統便會使用新結構描述的欄位定義和設定為文件編製索引。

當您建立索引時，系統會針對索引結構描述中的每個欄位配置實體儲存體，並為每個可搜尋欄位建立反向索引，以及為每個向量欄位建立向量索引。不可搜尋的欄位可用於篩選條件或運算式中，但不會有反向索引且不是可全文或模糊搜尋。在重建索引時，這些反向索引和向量索引會被刪除並根據您提供的索引結構描述來重新建立。

平衡工作負載

索引不會在背景中執行，但搜尋服務會針對進行中的查詢平衡任何索引編製作業。在索引編製期間，您可以在入口網站中監視查詢要求，以確保查詢會及時完成。

如果為工作負載編製索引會產生令人無法接受的查詢延遲程度，請進行效能分析，並檢閱這些效能秘訣以便能降低風險。

檢查更新

第一個文件載入之後，您就可以開始查詢索引。如果您知道文件的別碼，查閱文件 REST API $英文$ 可傳回特定文件。若要進行更廣泛的測試，您應該等到索引完全載入，然後使用查詢來確認您預期會看到的內容。

您可以使用搜尋總管或 REST 用戶端來檢查更新後的內容。

如果您已新增或重新命名欄位，請使用 $select 來傳回該欄位：search=*&$select=document-id,my-new-field,some-old-field&$count=true。

Azure 入口網站會提供索引大小和向量索引大小。您可以在更新索引之後檢查這些值，但請記住，服務在處理變更時應該會有稍微延遲的情形，也請記得考慮入口網站的重新整理速率，時間可能是幾分鐘。

刪除孤立文件

Azure AI 搜尋服務支援文件層級的作業，以便您可以單獨查閱、更新和刪除特定文件。下列範例說明如何刪除文件。

刪除文件並不會立即釋放索引中的空間。每隔幾分鐘，背景程序就會執行實體刪除。無論您使用入口網站還是 API 來傳回索引統計資料，系統應該都會延遲一會，才會在入口網站和 API 計量中反映刪除操作。

識別哪一個欄位是文件索引鍵。在入口網站中，您可以檢視每個索引的欄位。文件索引鍵是字串欄位，會以鑰匙圖示表示，使其更容易找到。
檢查文件索引鍵欄位的值：search=*&$select=HotelId。簡單的字串是直接易懂的，但如果索引使用 base-64 編碼欄位，或是從 parsingMode 設定中產生搜尋文件，則您可能會使用您不熟悉的值。

查閱文件以確認文件 ID 的值，並在刪除之前檢閱其內容。在要求中指定索引鍵或文件 ID。下列範例說明旅館範例索引的一個簡單字串，以及 cog-search-demo 索引之metadata_storage_path 索引鍵的 base-64 編碼字串。

GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2024-07-01

GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2024-07-01

使用 delete @search.action 刪除文件，以將文件從搜尋索引中移除。

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/index?api-version=2024-07-01
Content-Type: application/json   
api-key: [admin key] 
{  
  "value": [  
    {  
      "@search.action": "delete",  
      "id": "1111"  
    }  
  ]  
}

共用方式為