建立或更新索引 (預覽 REST API)

發行項
07/07/2023

適用于：2023-07-01-Preview、2021-04-30-Preview、2020-06-30-Preview

重要

2023-07-01-Preview 新增向量搜尋。

「vectorSearch」 物件，這是向量搜尋設定的組態。僅適用于向量搜尋演算法。
向量欄位所需的「集合 (Edm.Single) 」資料類型。表示單精確度浮點數做為基本類型。
向量欄位所需的「dimensions」屬性。表示向量內嵌的維度。
向量欄位所需的「vectorSearchConfiguration」 屬性。選取此欄位的演算法組態。

2021-04-30-Preview 新增：

「semanticConfiguration」 用於界定特定欄位的語意排名。
「identity」，在「encryptionKey」下，用來使用使用者指派的受控識別，從 Azure 金鑰保存庫擷取客戶管理的加密金鑰。

2020-06-30-Preview 新增：

「normalizers」，用於排序和篩選的不區分大小寫。

索引會指定索引架構，包括欄位集合 (功能變數名稱、資料類型和屬性) ，但其他建構也會 (建議程式、評分設定檔和 CORS 組態) 定義其他搜尋行為。

您可以在建立要求上使用 POST 或 PUT。其中一個要求主體會提供物件定義。

POST https://[servicename].search.windows.net/indexes?api-version=[api-version]  
  Content-Type: application/json
  api-key: [admin key]

針對更新要求，請使用 PUT 並在 URI 上指定索引名稱。

PUT https://[servicename].search.windows.net/indexes/[index name]?api-version=[api-version]
  Content-Type: application/json
  api-key: [admin key]

所有服務要求都需使用 HTTPS。如果索引不存在，則會建立它。如果已經存在，則會更新為新的定義。

建立索引 會建立架構和中繼資料。填入索引是一個獨立的操作。在此步驟中，您可以使用索引子 (請參閱索引子作業，適用于支援的資料來源) 、新增、更新或刪除檔。您可以建立的索引數目上限依定價層而異。在每個索引中，個別元素都有限制。如需詳細資訊，請參閱 Azure AI 搜尋的服務限制。

更新現有的索引 必須包含完整的架構定義，包括您想要保留的任何原始定義。一般而言，更新的最佳模式是使用 GET 擷取索引定義、修改它，然後使用 PUT 加以更新。

因為現有的索引包含內容，所以許多索引修改都需要索引卸載和重建。下列架構變更是此規則的例外狀況：

新增欄位
新增或變更評分設定檔
新增或變更語意設定
變更 CORS 選項
使用下列三項修改之一變更現有的欄位：
- 顯示或隱藏欄位 (retrievable ：true | false)
- 變更查詢時間所使用的分析器 (searchAnalyzer)
- 新增或編輯查詢時間使用的同義字Map (synonymMaps)

若要對現有索引進行任何上述架構變更，請在要求 URI 上指定索引的名稱，然後使用新的或變更的專案包含完整指定的索引定義。

新增欄位時，索引中的所有現有檔都會自動具有該欄位的 Null 值。在發生兩件事之一之前，不會耗用額外的儲存空間：使用合併) 或新增檔，為新的欄位提供值 (。

匯報具有 suggester類似的條件約束：新欄位可以同時新增至 suggester ，但現有欄位無法從中移除，也不會在不使用索引重建的情況下新增至 suggesters 。

匯報分析器、權杖化工具、權杖篩選或字元篩選不允許。您可以使用您想要的變更來建立新的變更，但新增分析器定義時，您必須讓索引離線。在索引更新要求中將 allowIndexDowntime 旗標設定為 true，會讓索引離線：

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

此作業至少需要幾秒鐘的索引離線，這表示索引編制和查詢要求會失敗，直到索引重新上線且準備好處理要求為止。

URI 參數

參數	Description
服務名稱	必要。將此值設定為搜尋服務的唯一使用者定義名稱。
索引名稱	如果使用 PUT，則為 URI 的必要專案。名稱必須是小寫，開頭為字母或數位、沒有斜線或點，且少於 128 個字元。虛線不可連續。
api-version	必要。目前的預覽版本是 `2023-07-23-preview` 。如需更多版本，請參閱 API 版本。
allowIndexDowntime	選擇性。預設為 False。針對特定更新設定為 true，例如新增或修改分析器、Tokenizer、權杖篩選、char 篩選或相似性屬性。索引會在更新期間離線，通常不超過數秒。

要求標頭

下表說明必要及選用的要求標頭。

欄位	Description
Content-Type	必要。將此值設定為 `application/json`
api-key	如果您使用 Azure 角色，而且要求會提供持有人權杖，則為選擇性，否則需要金鑰。 API 金鑰是唯一的系統產生字串，可驗證對搜尋服務的要求。建立要求必須包含 `api-key` 設定為系統管理員金鑰的標頭 (，而不是查詢金鑰) 。如需詳細資訊，請參閱使用金鑰驗證連線到 Azure AI 搜尋服務。

要求本文

要求的本文包含架構定義，其中包含送入此索引的檔內的資料欄位清單。

下列 JSON 是支援向量搜尋之架構的高階標記法。架構需要索引鍵欄位，而且索引鍵欄位可以是可搜尋、可篩選、可排序和可 Facet。

向量搜尋欄位的類型 Collection(Edm.Single) 為。因為向量欄位不是文字欄位，所以向量欄位無法當做索引鍵使用，而且不接受分析器、正規化程式、建議工具或同義字。它必須具有「dimensions」屬性和「vectorSearchConfiguration」屬性。

支援向量搜尋的架構也可以支援關鍵字搜尋。索引中的其他非vector 欄位可以使用您包含在索引中的任何分析器、同義字和評分設定檔。

{  
  "name": (optional on PUT; required on POST) "Name of the index",
  "description": (optional) "Description of the index",  
  "fields": [  
    {  
      "name": "name_of_field",  
      "type": "Edm.String | Edm.Int32 | Edm.Int64 | Edm.Double | Edm.Boolean | Edm.DateTimeOffset | Edm.GeographyPoint | Edm.ComplexType | Collection(Edm.String) | Collection(Edm.Int32) | Collection(Edm.Int64) | Collection(Edm.Single) | Collection(Edm.Double) | Collection(Edm.Boolean) | Collection(Edm.DateTimeOffset) | Collection(Edm.GeographyPoint) | Collection(Edm.ComplexType)",
      "key": true | false (default, only Edm.String fields can be keys, enable on one field only),  
      "searchable": true (default where applicable) | false (only Edm.String and Collection(Edm.String) fields can be searchable),  
      "filterable": true (default) | false,  
      "sortable": true (default where applicable) | false (Collection(Edm.String) fields cannot be sortable),  
      "facetable": true (default where applicable) | false (Edm.GeographyPoint fields cannot be facetable),  
      "retrievable": true (default) | false,  
      "analyzer": "name_of_analyzer_for_search_and_indexing", (only if 'searchAnalyzer' and 'indexAnalyzer' are not set)
      "searchAnalyzer": "name_of_search_analyzer", (only if 'indexAnalyzer' is set and 'analyzer' is not set)
      "indexAnalyzer": "name_of_indexing_analyzer", (only if 'searchAnalyzer' is set and 'analyzer' is not set)
      "normalizer": "name_of_normalizer", (optional, applies only to filterable, facetable, or sortable Edm.String and Collection(Edm.String) fields.)
      "synonymMaps": [ "name_of_synonym_map" ], (optional, only one synonym map per field is currently supported),
      "fields" : [ ... ], (optional, a list of sub-fields if this is a field of type Edm.ComplexType or Collection(Edm.ComplexType). Must be null or empty for simple fields.)
      "dimensions": 1234, (required for vector field definitions. Prohibited for non-vector fields. Integer specifying the dimensionality of the embeddings generated by a machine learning model)
      "vectorSearchConfiguration": "name_of_algorithm_config" (required for vector field definitions. Prohibited for non-vector fields. This should reference an algorithm configuration.)
    }
  ],
  "similarity": (optional) { },
  "suggesters": (optional) [ ... ],  
  "scoringProfiles": (optional) [ ... ],  
  "semantic": (optional) { },
  "vectorSearch": (optional) {
    "algorithmConfigurations": [
        {
            "name": "name_of_algorithm_config",
            "kind": "hnsw" (algorithm type. Only "hnsw" is supported currently.),
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]},
  "normalizers":(optional) [ ... ],
  "analyzers":(optional) [ ... ],
  "charFilters":(optional) [ ... ],
  "tokenizers":(optional) [ ... ],
  "tokenFilters":(optional) [ ... ],
  "defaultScoringProfile": (optional) "Name of a custom scoring profile to use as the default",  
  "corsOptions": (optional) { },
  "encryptionKey":(optional) { }  
}

要求可包含下列屬性：

屬性	Description
NAME	必要。索引的名稱。索引名稱只能包含小寫字母、數位或破折號，不能以破折號開頭或結尾，且限制為 128 個字元。
description	選擇性的描述。
欄位	此索引的欄位集合，其中每個欄位都有名稱、符合實體資料模型支援的資料類型， (EDM) ，以及定義該欄位上允許動作的屬性。 fields 集合必須有一個類型的 `Edm.String` 欄位，且「key」設定為「true」。此欄位代表儲存索引之每個檔的唯一識別碼，有時稱為檔識別碼。 fields 集合現在接受向量欄位。
相似	選擇性。針對在 2020 年 7 月 15 日之前建立的服務，請將此屬性設定為加入宣告 BM25 排名演算法。
建議工具	指定建構，此建構會儲存在部分查詢上比對的前置詞，例如自動完成和建議。
scoringProfiles	選擇性。用於全文檢索查詢的相關性微調。
語義	選擇性。定義影響語意搜尋功能之搜尋索引的參數。語意查詢需要語意設定。如需詳細資訊，請參閱建立語意查詢。
vectorSearch	選擇性。設定各種向量搜尋設定。只能設定向量搜尋演算法。
正規化程式	選擇性。將字串的語彙排序正規化，產生不區分大小寫的排序和篩選輸出。
分析器、charFilters、tokenizers、tokenFilters	選擇性。如果您要定義自訂分析器，請指定索引的這些區段。根據預設，這些區段為 Null。
defaultScoringProfile	覆寫預設評分行為的自訂評分設定檔名稱。
corsOptions	選擇性。用於索引的跨原始來源查詢。
encryptionKey	選擇性。用於索引的額外加密，透過 Azure 金鑰保存庫中客戶管理的加密金鑰 (CMK) 。可用於在 2019-01-01 之後建立的可計費搜尋服務。

回應

如需成功的建立要求，您應該會看到狀態碼「201 Created」。根據預設，回應本文包含已建立之索引定義的 JSON。不過，如果 Prefer 要求標頭設定為 return=minimal，則回應本文是空的，而成功狀態碼為「204 No Content」，而不是「201 Created」。無論是否使用 PUT 或 POST 來建立索引，都是如此。

如需成功的更新要求，您應該會看到「204 無內容」。根據預設，回應本文是空的。不過，如果 Prefer 要求標頭設定 return=representation 為，回應本文會包含已更新之索引定義的 JSON。在此情況下，成功狀態碼為「200 OK」。

範例

範例：向量

向量搜尋會在欄位層級實作。此定義會將焦點放在向量欄位上。向量欄位的類型必須 Collection(Edm.Single) 用來儲存單精確度浮點值。向量欄位具有「維度」屬性，可保存機器學習模型用來產生內嵌支援的輸出維度數目。例如，如果您使用文字內嵌-ada-002，則每個檔的輸出維度數目上限為 1536。「algorithmConfiguration」會設定為索引中「vectorSearch」組態的名稱。您可以在索引中定義多個，然後為每個欄位指定一個。

許多屬性僅適用于非vector 欄位。向量欄位會忽略「filterable」、「sortable」、「facetable」、「analyzer」、「normalizer」和「synonymMaps」等屬性。同樣地，如果您在包含 Alpha 數值內容的欄位上設定僅限向量屬性，例如「dimensions」或「vectorSearchConfiguration」，則會忽略這些屬性。

{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "searchable": true,
            "retrievable": true,
            "filterable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "key": false,
            "searchable": true,
            "retrievable": true,
            "filterable": false,  
            "sortable": false,  
            "facetable": false,
            "analyzer": "",
            "searchAnalyzer": "",
            "indexAnalyzer": "",
            "normalizer": "",
            "synonymMaps": "", 
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "key": false,
            "searchable": true,
            "retrievable": true,
            "filterable": false,  
            "sortable": false,  
            "facetable": false,
            "analyzer": "",
            "searchAnalyzer": "",
            "indexAnalyzer": "",
            "normalizer": "",
            "synonymMaps": "", 
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        }
    ],
    "vectorSearch": {
        "algorithmConfigurations": [
            {
                "name": "my-vector-config",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ]
    }
}

範例：具有向量和非向量欄位的欄位集合

向量搜尋會在欄位層級實作。若要支援混合式查詢案例，請為向量和非向量查詢建立一對欄位。「title」、「titleVector」、「content」、「contentVector」欄位遵循此慣例。如果您也想要使用語意搜尋，則必須具有這些行為的非Vector 文字欄位。

{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "filterable": true
        },
        {
            "name": "title",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "content",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "category",
            "type": "Edm.String",
            "filterable": true,
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchConfiguration": "my-vector-config"
        }
    ],
    "corsOptions": {
        "allowedOrigins": [
            "*"
        ],
        "maxAgeInSeconds": 60
    },
    "vectorSearch": {
        "algorithmConfigurations": [
            {
                "name": "my-vector-config",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ]
    },
    "semantic": {
        "configurations": [
            {
                "name": "my-semantic-config",
                "prioritizedFields": {
                    "titleField": {
                        "fieldName": "title"
                    },
                    "prioritizedContentFields": [
                        {
                            "fieldName": "content"
                        }
                    ],
                    "prioritizedKeywordsFields": [
                        {
                            "fieldName": "category"
                        }
                    ]
                }
            }
        ]
    }
}

範例：具有簡單且複雜欄位的索引架構

第一個範例顯示具有簡單且複雜欄位的完整索引架構。至少一個字串欄位必須將「key」設定為 true。

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true, "normalizer": "lowercase" },
          { "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)", 
      "fields": [
          { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
          { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
          { "name": "Type", "type": "Edm.String", "searchable": true },
          { "name": "BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
          { "name": "BedOptions", "type": "Edm.String", "searchable": true },
          { "name": "SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
          { "name": "SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
          { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" }
        ]
    }
  ],
  "suggesters": [ ],
  "analyzers": [ ],
  "normalizers": [ ],
  "encryptionKey": [ ]
}

範例：建議工具

建議工具定義應該指定 REST API 中 (的「可搜尋」和「可擷取」字串欄位，所有簡單欄位預設都會 "retrievable": true) 。定義建議工具之後，您可以依據使用建議 API 或自動完成 API的查詢要求名稱來參考它，視您想要傳回相符專案或查詢字詞的其餘部分而定。

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },

  ],
  "suggesters": [
    {  
      "name": "sg",  
      "searchMode": "analyzingInfixMatching",  
      "sourceFields": ["HotelName", "Category", "Tags"]  
    } 
  ]
}

範例：分析器和正規化程式

分析器和正規化程式會在欄位定義上參考，而且可以預先定義或自訂。如果您使用自訂分析器或正規化程式，請在「analyzers」和「normalizers」區段中的索引中指定它們。

下列範例說明「標記」的自訂分析器和正規化程式。它也示範預先定義的正規化程式 (標準) 和分析器 (en.microsoft) ，分別適用于「HotelName」和「Description」。

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false, "normalizer": standard  },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft"},
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer", "normalizer": "tagsNormalizer" },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },

  ],
  "analyzers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
      "name": "tagsAnalyzer",
      "charFilters": [ "html_strip" ],
      "tokenizer": "standard_v2"
    }
  ],
  "normalizers": [
    {
      "@odata.type": "#Microsoft.Azure.Search.CustomNormalizer",
      "name": "tagsNormalizer",
      "tokenFilters": [ "asciifolding", "lowercase" ]
    }
  ]
}

範例：搜尋相關性的相似度

此屬性會設定用來在全文檢索搜尋查詢的搜尋結果中建立相關性分數的排名演算法。在 2020 年 7 月 15 日之後建立的服務中，會忽略此屬性，因為相似度演算法一律為 BM25。針對在 2020 年 7 月 15 日之前 建立的現有服務，您可以設定此建構來加入宣告 BM25，如下所示：

 "similarity": {
     "@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
 }

範例：CORS 選項

用戶端 JavaScript 預設無法呼叫任何 API，因為瀏覽器會防止所有跨原始來源的要求。若要允許對索引進行跨原始來源查詢，請藉由設定 corsOptions 屬性，啟用 CORS (跨原始來源資源分享 (Wikipedia) ) 。基於安全緣故，僅查詢 API 才能支援 CORS。

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "corsOptions": (optional) {  
       "allowedOrigins": ["*"] | ["https://docs.microsoft.com:80", "https://azure.microsoft.com:80", ...],  
       "maxAgeInSeconds": (optional) max_age_in_seconds (non-negative integer)  
     }
}

範例：具有存取認證的加密金鑰

加密金鑰是客戶管理的金鑰，用於額外的加密。如需詳細資訊，請參閱在 Azure 金鑰保存庫中使用客戶管理的金鑰進行加密。

{
    "name": "hotels",  
    "fields": [ omitted for brevity ],
    "suggesters": [ omitted for brevity ],
    "analyzers": [ omitted for brevity ],
    "encryptionKey": (optional) { 
       "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
       "keyVaultKeyVersion": "Version of the Azure Key Vault key",
       "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
       "accessCredentials": (optional, only if not using managed system identity) {
          "applicationId": "AAD Application ID that was granted access permissions to your specified Azure Key Vault",
          "applicationSecret": "Authentication key of the specified AAD application)"
        }
    }
}

範例：具有受控識別的加密金鑰

您可以使用系統指派或使用者指派的 (預覽) 受控識別，向 Azure 金鑰保存庫進行驗證。在此情況下，請省略存取認證，或設定為 null。下列範例顯示使用者指派的受控識別。若要使用系統指派的受控識別，請省略存取認證和身分識別。只要搜尋服務的系統身分識別在 Azure 金鑰保存庫中具有許可權，連線要求應該會成功。

{
  "name": "hotels",  
  "fields": [ omitted for brevity ],
  "suggesters": [ omitted for brevity ],
  "analyzers": [ omitted for brevity ],
  "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": null,
          "identity" : { 
              "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
              "userAssignedIdentity" : "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"
          }
    }
}

範例：評分設定檔

評分設定檔是架構的區段，可定義自訂評分行為，讓您影響搜尋結果中出現較高的檔。評分設定檔是由欄位權數和函式所組成。若要使用它們，您可以在查詢字串上以名稱指定設定檔。如需詳細資訊，請參閱將評分設定檔新增至搜尋索引， (Azure AI 搜尋服務 REST API) 以取得詳細資料。

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "scoringProfiles": [  
   {  
     "name": "name of scoring profile",  
     "text": (optional, only applies to searchable fields) {  
       "weights": {  
         "searchable_field_name": relative_weight_value (positive #'s),  
         ...  
       }  
     },  
     "functions": (optional) [  
       {  
         "type": "magnitude | freshness | distance | tag",  
         "boost": # (positive number used as multiplier for raw score != 1),  
         "fieldName": "...",  
         "interpolation": "constant | linear (default) | quadratic | logarithmic",  
         "magnitude": {  
           "boostingRangeStart": #,  
           "boostingRangeEnd": #,  
           "constantBoostBeyondRange": true | false (default)  
         },  
         "freshness": {  
           "boostingDuration": "..." (value representing timespan leading to now over which boosting occurs)  
         },  
         "distance": {  
           "referencePointParameter": "...", (parameter to be passed in queries to use as reference location)  
           "boostingDistance": # (the distance in kilometers from the reference location where the boosting range ends)  
         },  
         "tag": {  
           "tagsParameter": "..." (parameter to be passed in queries to specify a list of tags to compare against target fields)  
         }  
       }  
     ],  
     "functionAggregation": (optional, applies only when functions are specified)   
       "sum (default) | average | minimum | maximum | firstMatching"  
       }  
 ]
}

範例：語意設定

語意設定是索引定義的一部分，用來設定語意搜尋使用排名、標題、醒目提示和答案的欄位。若要使用語意搜尋，您必須在查詢時指定語意組態的名稱。如需詳細資訊，請參閱建立語意查詢。

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "semantic": {
     "configurations": [
       {
         "name": "my-semantic-config",
         "prioritizedFields": {
           "titleField": {
                 "fieldName": "hotelName"
               },
           "prioritizedContentFields": [
             {
               "fieldName": "description"
             },
             {
               "fieldName": "description_fr"
             }
           ],
           "prioritizedKeywordsFields": [
             {
               "fieldName": "tags"
             },
             {
               "fieldName": "category"
             }
           ]
         }
       }
     ]
   }
}

定義

連結	描述
corsOptions	列出授與您的索引的網域或來源。
defaultScoringProfile	覆寫預設評分行為的自訂評分設定檔名稱。
encryptionKey	針對客戶管理的加密，設定與 Azure 金鑰保存庫的連線。
欄位	設定搜尋索引中欄位的定義和屬性。
正規化程式	設定自訂正規化程式。將字串的語彙排序正規化，產生不區分大小寫的排序、Facet 和篩選輸出。
語義	設定語意搜尋用於排名、標題、醒目提示和答案的欄位。
scoringProfiles	用於全文檢索查詢的相關性微調。
相似
建議工具	設定內部前置詞儲存體，以在部分查詢上進行比對，例如自動完成和建議。
vectorSearch	設定用於向量欄位的演算法。

corsOptions

用戶端 JavaScript 預設無法呼叫任何 API，因為瀏覽器會防止所有跨原始來源的要求。若要允許對索引進行跨原始來源查詢，請藉由設定「corsOptions」屬性，啟用 CORS (跨原始來源資源分享) 。基於安全緣故，僅查詢 API 才能支援 CORS。

屬性描述

allowedOrigins 必要。被授與索引存取權的逗號分隔來源清單，其中每個來源通常是格式 protocol:// fully-qualified-domain-name > ： < port > (，不過 <> 通常省 < 略埠) 。這表示允許從這些來源提供的任何 JavaScript 程式碼查詢您的索引， (假設它提供有效的 API 金鑰) 。如果您想要允許存取所有來源，請在「allowedOrigins」陣列中指定 * 為單一專案。不建議用於生產環境，但對於開發或偵錯可能很有用。

maxAgeInSeconds 選擇性。瀏覽器會使用此值來判斷快取 CORS 預檢回應的持續期間 (以秒為單位)。這必須是非負數的整數。如果此值較大，效能會改善，但這些提升會因 CORS 原則變更生效所需的時間量而位移。如果未設定，則會使用預設持續時間 5 分鐘。

屬性	描述
allowedOrigins	必要。被授與索引存取權的逗號分隔來源清單，其中每個來源通常是格式 protocol:// fully-qualified-domain-name > ： < port > (，不過 <> 通常省 < 略埠) 。這表示允許從這些來源提供的任何 JavaScript 程式碼查詢您的索引， (假設它提供有效的 API 金鑰) 。如果您想要允許存取所有來源，請在「allowedOrigins」陣列中指定 `*` 為單一專案。不建議用於生產環境，但對於開發或偵錯可能很有用。
maxAgeInSeconds	選擇性。瀏覽器會使用此值來判斷快取 CORS 預檢回應的持續期間 (以秒為單位)。這必須是非負數的整數。如果此值較大，效能會改善，但這些提升會因 CORS 原則變更生效所需的時間量而位移。如果未設定，則會使用預設持續時間 5 分鐘。

defaultScoringProfile

選擇性。字串，此字串是索引中定義的自訂評分設定檔名稱。每當查詢字串上未明確指定自訂設定檔時，就會叫用預設設定檔。如需詳細資訊，請參閱將評分設定檔新增至搜尋索引。

encryptionKey

設定與 Azure 金鑰保存庫的連線，以補充客戶管理的加密金鑰， (CMK) 。適用于在 2019 年 1 月 1 日或之後建立的可計費搜尋服務。

必須驗證金鑰保存庫的連線。您可以針對此目的使用「accessCredentials」或受控識別。

受控識別可以是系統或使用者指派 (預覽) 。如果搜尋服務同時具有系統指派的受控識別，以及授與金鑰保存庫讀取權限的角色指派，您可以省略「身分識別」和「accessCredentials」，而要求將會使用受控識別進行驗證。如果搜尋服務具有使用者指派的身分識別和角色指派，請將「identity」屬性設定為該身分識別的資源識別碼。

屬性	Description
keyVaultKeyName	必要。用於加密的 Azure 金鑰保存庫金鑰名稱。
keyVaultKeyVersion	必要。 Azure 金鑰保存庫金鑰的版本。
keyVaultUri	必要。 Azure 金鑰保存庫 (的 URI 也稱為提供金鑰的 DNS 名稱) 。範例 URI 可能是 `https://my-keyvault-name.vault.azure.net`
accessCredentials	選擇性。如果您使用受控識別，請省略此屬性。否則，「accessCredentials」的屬性包括：「applicationId」 (具有指定 Azure 金鑰保存庫) 存取權限的 Azure Active Directory 應用程式識別碼。「applicationSecret」 (指定之 Azure AD 應用程式的驗證金鑰) 。
身分識別	除非您使用使用者指派的受控識別來連線至 Azure 金鑰保存庫，否則為選擇性。格式為 `"/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"`。

fields

包含欄位定義上屬性的相關資訊。

屬性	Description
NAME	必要。設定功能變數名稱，此欄位在索引或父欄位的欄位集合內必須是唯一的。
類型	必要。設定欄位的資料類型。欄位可以是簡單或複雜。簡單欄位屬於基本類型，例如 `Edm.String` 文字或 `Edm.Int32` 整數。複雜欄位可以有本身為簡單或複雜的子欄位。這可讓您建立物件和物件的陣列模型，進而讓您將大部分的 JSON 物件結構上傳至索引。 `Collection(Edm.Single)` 容納單精確度浮點值。它僅適用于向量欄位，而且是必要的。如需支援型別的完整清單，請參閱支援的資料類型。
索引鍵	必要。將此屬性設定為 true，以指定欄位的值可唯一識別索引中的檔。索引鍵欄位中值的最大長度為 1024 個字元。每個索引中的最上層欄位都必須選擇為索引鍵欄位，而且其類型必須為 `Edm.String` 。預設為 `false` 簡單欄位和 `null` 複雜欄位。索引鍵欄位可用來直接查閱檔，並更新或刪除特定檔。查閱或編制檔索引時，索引鍵欄位的值會以區分大小寫的方式處理。如需詳細資訊，請參閱查閱檔及新增、更新或刪除檔。
可擷取	指出欄位是否可以在搜尋結果中傳回。如果您想要使用欄位 (，請將此屬性 `false` 設定為，例如邊界) 做為篩選、排序或評分機制，但不想讓使用者看到欄位。此屬性必須 `true` 適用于索引鍵欄位，而且必須為 `null` 複雜欄位。這個屬性可以在現有的欄位上變更。將 [可擷取] 設定為 `true` 不會造成索引儲存體需求增加。預設值為 `true` 簡單欄位和 `null` 複雜欄位。
可搜尋	指出欄位是否為全文檢索搜尋，而且可以在搜尋查詢中參考。這表示它會在編制索引期間進行語彙分析，例如斷詞。如果您將可搜尋的欄位設定為類似「Sunny day」的值，則會在內部將它正規化為個別的標記「ny」和「day」。這樣就能針對這些字詞進行全文檢索搜尋。類型 `Edm.String` 為或 `Collection(Edm.String)` 的欄位預設為可搜尋。此屬性必須 `false` 適用于其他非字串資料類型的簡單欄位，而且它必須 `null` 適用于複雜欄位。可搜尋的欄位會耗用索引的額外空間，因為 Azure AI 搜尋服務會處理這些欄位的內容，並將其組織在輔助資料結構中，以進行高效能搜尋。如果您想要節省索引的空間，而且不需要在搜尋中包含欄位，請將 [可搜尋] 設定為 `false` 。如需詳細資訊，請參閱全文檢索搜尋如何在 Azure AI 搜尋服務中運作。
可篩選	指出是否要在查詢中 `$filter` 參考欄位。 Filterable 與可搜尋的字串處理方式不同。類型 `Edm.String` 或 `Collection(Edm.String)` 可篩選的欄位不會進行語彙分析，因此比較僅適用于完全相符專案。例如，如果您將這類欄位 `f` 設定為「Sunny day」， `$filter=f eq 'sunny'` 則找不到相符專案，但 `$filter=f eq 'Sunny day'` 會。此屬性必須 `null` 適用于複雜欄位。預設值為 `true` 簡單欄位和 `null` 複雜欄位。若要減少索引大小，請在您不會篩選的欄位上，將此屬性設定為 `false` 。
sortable	指出是否要在運算式中 `$orderby` 參考欄位。根據預設，Azure AI 搜尋服務會依分數排序結果，但在許多體驗中，使用者想要依檔中的欄位排序。只有在單一值 (在父檔範圍中有單一值時，才能排序簡單欄位) 。簡單集合欄位無法排序，因為它們是多重值。複雜集合的簡單子欄位也是多重值，因此無法排序。不論其為即時父欄位或上階欄位，都是複雜的集合，都是如此。複雜欄位無法排序，而且可排序屬性必須 `null` 適用于這類欄位。可排序的預設值為 `true` 單一值簡單欄位、 `false` 多重值簡單欄位，以及 `null` 複雜欄位。
可面向化	指出是否要在 Facet 查詢中參考欄位。通常用於搜尋結果的呈現中，包括依類別 (的點擊計數，例如搜尋數位相機，並依品牌查看點擊數、依 mbpixels、價格等) 。此屬性必須 `null` 適用于複雜欄位。類型 `Edm.GeographyPoint` 或 `Collection(Edm.GeographyPoint)` 無法進行 Facet 的欄位。預設值為 `true` 所有其他簡單欄位。若要減少索引大小，請將這個屬性設定為您 `false` 不會進行 Facet 的欄位。
分析儀	設定在編制索引和查詢作業期間標記字串的語彙分析器。此屬性的有效值包括語言分析器、內建分析器和自訂分析器。預設為 `standard.lucene`。此屬性只能與可搜尋的欄位搭配使用，而且不能與 searchAnalyzer 或 indexAnalyzer 一起設定。選擇分析器並在索引中建立欄位之後，就無法變更欄位。必須為 `null`複雜欄位。
searchAnalyzer	將此屬性與 indexAnalyzer 一起設定，以指定索引和查詢的不同語彙分析器。如果您使用此屬性，請將分析器設定為 `null` ，並確定 indexAnalyzer 設定為允許的值。此屬性的有效值包括內建分析器和自訂分析器。此屬性只能與可搜尋的欄位搭配使用。搜尋分析器可以在現有欄位上更新，因為它只在查詢時間使用。必須為 `null`複雜欄位。
indexAnalyzer	將此屬性與 searchAnalyzer 一起設定，以指定索引和查詢的不同語彙分析器。如果您使用此屬性，請將分析器設定為 `null` ，並確定 searchAnalyzer 設定為允許的值。此屬性的有效值包括內建分析器和自訂分析器。此屬性只能與可搜尋的欄位搭配使用。選擇索引分析器之後，就無法變更欄位。必須為 `null`複雜欄位。
normalizer	設定用於篩選、排序和 Facet 作業的正規化程式。它可以是預先定義的正規化程式名稱，或是在索引內定義的自訂正規化程式名稱。預設值為 `null` ，這會導致逐字、未分析的文字完全相符。此屬性只能與至少一個可篩選、可排序或可 Facet 設定為 true 的欄位 `Collection(Edm.String)` 搭配 `Edm.String` 使用。只有在新增至索引且稍後無法變更時，才能在欄位上設定正規化程式。必須為 `null`複雜欄位。預先定義的正規化程式的有效值包括： `standard` - 小寫文字後面接著 asciifolding。 `lowercase`- 將字元轉換成小寫。 `uppercase` - 將字元轉換成大寫。 `asciifolding` - 如果存在的話，將不在基本拉丁 Unicode 區塊中的字元轉換為其 ASCII 對等的字元。例如，將「à」變更為「a」。 `elision`- 從權杖開頭移除 elision。
synonymMaps	要與此欄位產生關聯的同義字名稱清單。此屬性只能與可搜尋的欄位搭配使用。目前每個欄位只支援一個同義字對應。將同義字對應指派給欄位可確保以該欄位為目標的查詢詞彙會在查詢階段使用同義字對應中的規則來展開。這個屬性可以在現有的欄位上變更。必須是 `null` 或複雜欄位的空白集合。
fields	如果這是類型 `Edm.ComplexType` 為或 `Collection(Edm.ComplexType)` 的欄位，則為子欄位的清單。簡單欄位必須是 `null` 或空白。如需如何使用子欄位的詳細資訊，請參閱如何在 Azure AI 搜尋服務中建立複雜資料類型模型。
dimensions	整數。向量欄位的必要專案。 **這必須符合內嵌模型的輸出內嵌大小。例如，針對熱門的 Azure OpenAI 模型 `text-embedding-ada-002` ，其輸出維度為 1536，因此這會是針對該向量欄位設定的維度。維度屬性的最小值為 2，每個浮點數上限為 2048 個。
vectorSearchConfiguration	向量欄位定義的必要專案。指定向量欄位所使用的「vectorSearch」演算法組態名稱。建立欄位之後，您無法變更 vectorSearchConfiguration 的名稱，但您可以變更索引中演算法組態的屬性。這可讓您調整演算法類型和參數。

注意

可篩選、可排序或可面向的型 Edm.String 別欄位長度最多可以是 32 KB。這是因為這類欄位的值會被視為單一搜尋字詞，而 Azure AI 搜尋服務中字詞的最大長度是 32 KB。如果您需要在單一字串欄位中儲存超過此文字，您必須在索引定義中明確設定可篩選、可排序和可 false 面向的。

將欄位設定為可搜尋、可篩選、可排序或多面向，對索引大小和查詢效能造成影響。請勿在未在查詢運算式中參考的欄位上設定這些屬性。

如果欄位未設定為可搜尋、可篩選、可排序或可多面向，則無法在任何查詢運算式中參考欄位。這適用于查詢中未使用的欄位，但在搜尋結果中是必要的。

正規化程式

定義自訂正規化程式，其中包含字元篩選和權杖篩選準則的使用者定義組合。在索引中定義自訂正規化程式之後，您可以在欄位定義上依名稱加以指定。

屬性	Description
NAME	必要。指定使用者定義自訂正規化程式的字串欄位。
charFilters	用於自訂正規化程式。它可以是自訂正規化程式中支援的一或多個可用字元篩選器：對應 pattern_replace
tokenFilters	用於自訂正規化程式。它可以是自訂正規化程式支援的一或多個可用權杖傾斜器： arabic_normalization asciifolding cjk_width elision german_normalization hindi_normalization indic_normalization persian_normalization scandinavian_normalizationscandinavian_folding sorani_normalization 小寫大寫

scoringProfiles

評分設定檔適用于全文檢索搜尋。設定檔是在索引中定義，並指定自訂邏輯，可授與較高的搜尋分數，以比對符合設定檔中所定義準則的檔。您可以建立多個評分設定檔，然後將您想要的設定檔指派給查詢。

如果您建立自訂設定檔，您可以藉由設定 defaultScoringProfile 來將其設為預設值。如需詳細資訊，請參閱將評分設定檔新增至搜尋索引。

語義

語意設定是索引定義的一部分，用來設定語意搜尋使用排名、標題、醒目提示和答案的欄位。語意設定是由標題欄位、優先順序內容欄位和已設定優先順序的關鍵字欄位所組成。每個子屬性至少必須指定一個欄位， (titleField、優先順序為KeywordsFields，以及優先順序為ContentFields) 。類型 Edm.StringCollection(Edm.String) 或的任何欄位都可以當做語意設定的一部分使用。

若要使用語意搜尋，您必須在查詢時指定語意組態的名稱。如需詳細資訊，請參閱建立語意查詢。

{
   "name": "hotels",  
   "fields": [ omitted for brevity ],
   "suggesters": [ omitted for brevity ],
   "analyzers": [ omitted for brevity ],
   "semantic": {
     "configurations": [
       {
         "name": "name of the semantic configuration",
         "prioritizedFields": {
           "titleField": {
                 "fieldName": "..."
               },
           "prioritizedContentFields": [
             {
               "fieldName": "..."
             },
             {
               "fieldName": "..."
             }
           ],
           "prioritizedKeywordsFields": [
             {
               "fieldName": "..."
             },
             {
               "fieldName": "..."
             }
           ]
         }
       }
     ]
   }
}

屬性	Description
NAME	必要。語意設定的名稱。
prioritizedFields	必要。描述要用於語意排名、標題、醒目提示和答案的標題、內容和關鍵字欄位。必須設定至少三個子屬性的其中一個 (titleField、優先順序的KeywordsFieldsFields 和 prioritizedContentFields) 。
prioritizedFields.titleField	定義要用於語意排名、標題、醒目提示和答案的標題欄位。如果您的索引中沒有標題欄位，請將此欄位保留空白。
prioritizedFields.prioritizedContentFields	定義要用於語意排名、標題、醒目提示和答案的內容欄位。為了獲得最佳結果，選取的欄位應該包含自然語言格式的文字。陣列中欄位的順序代表其優先順序。如果內容很長，則具有較低優先順序的欄位可能會遭到截斷。
prioritizedFields.prioritizedKeywordsFields	定義要用於語意排名、標題、醒目提示和答案的關鍵字欄位。為了獲得最佳結果，選取的欄位應該包含關鍵字清單。陣列中欄位的順序代表其優先順序。如果內容很長，則具有較低優先順序的欄位可能會遭到截斷。

相似度

選擇性屬性，適用于 2020 年 7 月 15 日之前建立的服務。針對這些服務，您可以將此屬性設定為使用 2020 年 7 月引進的 BM25 排名演算法。有效值包括 "#Microsoft.Azure.Search.ClassicSimilarity" (先前的預設) 或 "#Microsoft.Azure.Search.BM25Similarity" 。

針對在 2020 年 7 月之後建立的所有服務，設定此屬性沒有任何作用。所有較新的服務都會使用 BM25 作為全文檢索搜尋的唯一排名演算法。如需詳細資訊，請參閱 Azure AI 搜尋中的排名演算法。

建議工具

指定建構，此建構會儲存在部分查詢上比對的前置詞，例如自動完成和建議。

屬性	Description
NAME	必要。建議工具的名稱。
sourceFields	必要。您要啟用自動完成或建議結果的一或多個字串欄位。
searchMode	必要，且一律設定為 `analyzingInfixMatching` 。它會指定比對發生在查詢字串中的任何字詞上。

vectorSearch

vectorSearch 物件允許設定向量搜尋屬性。目前只能設定演算法組態。這允許設定用於向量欄位的演算法類型和演算法參數。您可以有多個組態。無法修改或刪除向量欄位所參考的任何組態。任何未參考的組態都可以修改或刪除。欄位) 集合中的向量欄位定義 (必須透過欄位所使用的屬性) 指定哪些向量搜尋演算法組態 vectorSearchConfiguration (。

"vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "my-vector-config",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]
}

屬性	Description
NAME	必要。演算法組態的名稱。
kind	要使用的演算法類型。僅支援 '「hnsw」'，這是階層式導覽小型世界 (HNSW) 演算法。
hnswParameters	選擇性。「hnsw」演算法的參數。如果省略此物件，則會使用預設值。

hnswParameters

這個物件包含演算法參數的 hnsw 自訂。如果省略任何屬性，則所有屬性都是選擇性的，而且會使用預設值。

屬性	描述
計量	字串。用於向量比較的相似度計量。針對 `hnsw` ，允許的值為「cosine」、「euclidean」和「dotProduct」。預設值為「cosine」。
m	整數。建構期間為每個新專案建立的雙向連結數目。預設值為 4。允許的範圍是 4 到 10。較大的值會導致更密集的圖形、改善查詢效能，但需要更多記憶體和計算。
efConstruction	整數。索引編制期間所使用最接近芳鄰的動態清單大小。預設值為 400。允許的範圍是 100 到 1000。較大的值會導致更好的索引品質，但需要更多記憶體和計算。
efSearch	整數。包含最接近鄰的動態清單大小，在搜尋期間使用。預設值為 500。允許的範圍是 100 到 1000。增加此參數可能會改善搜尋結果，但會降低查詢效能。

因為 efSearch 是查詢時間參數，所以即使現有的欄位正在使用演算法組態，也可以更新此值。