在 Azure AI 搜尋服務中建立索引

在本文中，了解定義搜尋索引結構描述的步驟，並將其推送至搜尋服務。 建立索引時，系統會在搜尋服務上建立實體資料結構。 索引一旦存在，載入索引作為個別工作。

必要條件

• 以搜尋服務參與者身分撰寫權限，或撰寫系統管理 API 金鑰進行金鑰型驗證。

• 了解您想要編製索引的資料。 搜尋索引是以您想要進行搜尋的外部內容為基礎。 可搜尋的內容會儲存為索引中的欄位。 您應該清楚瞭解您想要在 Azure AI 搜尋服務上進行可搜尋、可擷取、可篩選、可多面向和可排序的來源字段。 如需指引， 請參閱架構檢查清單 。

• 您也必須在來源資料中具有唯一欄位，其可用於索引中的文件索引鍵 (或識別碼)。

• 穩定的索引位置。 目前不支援將現有索引移至不同的搜尋服務。 重新瀏覽應用程式需求，並確定您現有的搜尋服務（容量和區域）已足以滿足您的需求。 如果您相依於 Azure AI 服務或 Azure OpenAI， 請選擇提供所有必要資源的區域 。

• 最後，針對您所能建立的物件數目，所有服務層級都具有索引限制。 例如，如果在免費層上進行實驗，則您在任何指定時間都只能使用三個索引。 在索引本身，簡單和複雜欄位的數目具有向量限制和索引限制。

文件索引鍵

搜尋索引建立有兩個需求：索引在搜尋服務上必須有唯一的名稱，而且必須有檔索引鍵。 欄位上的布爾 key 屬性可以設定為 true，以指出哪個欄位提供檔索引鍵。

文件索引鍵是搜尋文件的唯一識別碼，而搜尋文件則是可完整描述某些內容的欄位集合。 例如，如果您要編製電影資料集的索引，則搜尋文件包含單一電影的標題、類型和持續時間。 影片名稱在此數據集中是唯一的，因此您可以使用電影名稱作為檔索引鍵。

在 Azure AI 搜尋服務中，檔索引鍵是字串，而且必須源自數據源中提供要編製索引內容的唯一值。 一般規則是，搜尋服務不會產生索引鍵值，但在某些案例中（例如 Azure 數據表索引器）會合成現有的值，為編製索引的檔建立唯一索引鍵。 另一個案例是區塊化或數據分割數據的一對多索引編製，在此情況下，會針對每個區塊產生檔索引鍵。

在累加式索引編製期間，當新和更新的內容完成索引編製，系統就會新增具有新索引鍵的內送文件，或者合併或覆寫具有現有索引鍵的內送文件，上述情形是取決於索引欄位是否已填入資料或為 Null。

檔案索引鍵的要點包括：

• 索引鍵欄位中值的最大長度為 1,024 個字元。
• 每個索引中只有一個最上層字段必須選擇為索引鍵欄位，而且必須是類型 Edm.String。
• 簡單欄位的 key 預設值為 false，複雜欄位為 null。

索引鍵欄位可用來直接查閱檔，並更新或刪除特定檔。 查閱或編製檔索引時，索引鍵欄位的值會以區分大小寫的方式處理。 如需詳細資訊，請參閱 GET 檔 （REST） 和索引檔 （REST）。

結構描述檢查清單

使用此檢查清單來協助制定搜尋索引的設計決策。

1. 請檢閱命名慣例，讓索引和欄位名稱符合命名規則。

2. 請檢閱支援的資料類型。 資料類型會影響欄位的使用方式。 例如，您可以篩選數值內容，但無法搜尋全文。 最常見的資料類型為 Edm.String，該類型用於可搜尋的文字，並使用全文搜尋引擎進行權杖化和查詢。 向量欄位最常見的資料類型是 Edm.Single，但您也可以使用其他類型。

3. 識別文件索引鍵。 文件索引鍵是索引需求。 這是從源數據欄位填入的單一字串字位，其中包含唯一值。 例如，如果您要從 Blob 儲存體編製索引，則中繼資料儲存體路徑通常會用來作為文件索引鍵，因為該路徑會唯一識別容器中的每個 Blob。

4. 在資料來源中識別特定欄位，這些欄位會提供索引中的可搜尋內容。

   可搜尋的非向量內容包括使用全文搜尋引擎所查詢的短或長字串。 如果內容較詳細 (簡短片語或較長的句構)，請使用不同的分析器進行實驗，以查看文字的權杖化方式。

   可搜尋的向量內容可以是以數學表示形式存在的影像或文字 (任何語言)。 您可以使用狹窄資料類型或向量壓縮，讓向量欄位變小。

   在或 filterable等retrievable欄位上設定的屬性會決定搜尋行為和搜尋服務上索引的實體表示法。 判斷欄位應如何屬性化，是許多開發人員的反覆程式。 若要加速流程，請使用範例資料來執行作業，以便輕鬆進行卸除和重建。

5. 識別哪些來源欄位可作為篩選。 數值內容和簡短文字欄位，特別是具有重複值的欄位都是不錯的選擇。 使用篩選時，請記得：

   • 篩選可用於向量和非vector 查詢，但篩選本身會套用至索引中的人類可讀取（非vector）字段。

   • 您可以選擇將可篩選的欄位用於多面向導覽。

   • 可篩選的欄位會依任意順序傳回，而且不會進行相關性評分，因此也請考慮將它們排序。

6. 針對向量欄位，指定向量搜尋組態，以及用來建立瀏覽路徑並填入內嵌空間的演算法。 如需詳細資訊，請參閱新增向量欄位。

   向量欄位具有非向量欄位所沒有的額外屬性，例如要使用的演算法和向量壓縮。

   向量欄位會省略向量資料上沒有用處的屬性，例如排序、篩選和 Facet。

7. 對於非向量欄位，決定是否要使用預設分析器 ("analyzer": null) 或不同的分析器。 分析器可用來在索引編製和查詢執行期間將文字欄位權杖化。

   若為多語言字串，請考慮語言分析器。

   若為連字號連接的字串或特殊字元，請考慮特製化分析器。 其中一個範例是關鍵字，其會將欄位的整個內容視為單一語彙基元。 此行為適合用於郵遞區號、識別碼和產品名稱等資料。 如需詳細資訊，請參閱部分字詞搜尋和具有特殊字元的模式。

設定欄位定義

fields 集合會定義搜尋文件的結構。 所有欄位都有名稱、數據類型和屬性。

將欄位設定為可搜尋、可篩選、可排序或可 Facet，對索引大小和查詢效能有影響。 請勿在查詢表達式中未參考的欄位上設定這些屬性。

如果欄位未設定為可搜尋、可篩選、可排序或可多面向，則無法在任何查詢表達式中參考字段。 對於查詢中未使用的欄位而言，這是理想的做法，但在搜尋結果中是必要的。

REST API 具有以數據類型為基礎的預設屬性，匯入精靈也會使用 Azure 入口網站。 Azure SDK 沒有預設值，但它們有包含屬性和行為的字段子類別，例如 字串的 SearchableField 和 基本類型的 SimpleField 。

下表摘要說明 REST API 的預設欄位屬性。

字串欄位也可以選擇性地與分析器和同義字對應相關聯。 可篩選、可排序或可多面向類型的 Edm.String 欄位最多可以有 32 KB 的長度。 這是因為這類欄位的值會被視為單一搜尋字詞，而 Azure AI 搜尋中字詞的最大長度為 32 KB。 如果您需要將比這更多的文字儲存在單一字串字位中，您應該在索引定義中明確地將可篩選、可排序和可 Facet 設定為 false 。

向量欄位必須與維度和向量配置文件相關聯。 如果您在 Azure 入口網站 中使用匯入和向量化精靈新增向量字段，則可擷取的預設值為 true，否則如果您使用 REST API，則為 false。

下表說明欄位屬性。

建立索引

當您準備好建立索引時，請使用可傳送要求的搜尋用戶端。 您可使用 Azure 入口網站或 REST API 進行早期開發和概念證明測試，否則通常會使用 Azure SDK。

進行開發時，請考量頻繁進行的重建作業。 由於實體結構是在服務中建立，因此許多修改作業都需要卸除和重新建立索引。 您可以考慮處理部份的資料，讓重建更快速。

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "hotels",
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "StateProvince", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    }
  ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "analyzers":(optional)[ ... ]
}

// Create the index
string indexName = "hotels";
SearchIndex index = new SearchIndex(indexName)
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("descriptionFr") { AnalyzerName = LexicalAnalyzerName.FrLucene }
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { SynonymMapNames = new[] { synonymMapName }, IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    }
};

await indexClient.CreateIndexAsync(index);

針對跨來源查詢來設定 corsOptions

索引結構描述包含設定 corsOptions 的區段。 根據預設，用戶端 JavaScript 無法呼叫任何 API，因為瀏覽器會阻止所有跨原始來源的要求。 若要允許對索引進行跨原始來源查詢，請設定 corsOptions 屬性來啟用 CORS (跨原始來源資源共用)。 基於安全緣故，僅查詢 API 才能支援 CORS。

"corsOptions": {
  "allowedOrigins": [
    "*"
  ],
  "maxAgeInSeconds": 300

您可以為 CORS 設定下列屬性：

• allowedOrigins (必要)：這是被允許存取索引的原始來源清單。 允許從這些原始來源提供的 JavaScript 程式碼查詢您的索引 (假設呼叫者提供有效的金鑰或具有權限)。 每個原始來源的形式通常是 protocol://<fully-qualified-domain-name>:<port> (儘管經常會忽略 <port>)。 如需詳細資訊，請參閱 跨原始來源資源共用 (Wikipedia)。

  如果您想要允許所有原始來源進行存取，請在 allowedOrigins 陣列中包含 * 作為單一項目。 「此做法並不建議用於實際執行環境搜尋服務」，但對於開發和偵錯作業通常很有幫助。

• maxAgeInSeconds (選用)：瀏覽器會使用這個值，來判斷快取 CORS 預檢回應的持續期間 (以秒為單位)。 這必須是非負數的整數。 快取期間越長可提供越好的效能，但其會延長 CORS 原則需要生效的時間量。 如果未設定此值，則會使用預設持續時間 (5 分鐘)。

現有索引上允許的更新

建立索引會在搜尋服務上建立實體資料結構 (檔案和反轉的索引)。 一旦建立索引，您就能夠使用建立或更新索引來影響變更，這是取決於修改內容是否會讓這些實體結構無效。 在索引中建立欄位之後，就無法變更大部分的欄位屬性。

若要將應用程式程式代碼中的變換降到最低，您可以 建立索引別名 ，做為搜尋索引的穩定參考。 您可以更新索引別名以指向較新的索引版本，而不是使用索引名稱更新程序代碼。

為了將設計程序中的流失情形最小化，下表說明結構描述中固定和彈性的元素。 變更固定元素需要重建索引，而彈性元素則可以隨時變更，不會影響實體實作。 如需詳細資訊，請參閱 更新或重建索引。

下一步

使用下列連結來瞭解可新增至索引的特殊功能：

• 新增向量欄位和向量配置檔
• 新增評分配置檔
• 新增語意排名
• 新增建議工具
• 新增同義字對應
• 新增分析器
• 新增加密

使用這些連結來載入或更新索引：

• 資料匯入概觀
• 載入文件
• 更新或重建索引