你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

创建或更新索引（预览版 REST API）

项目
06/28/2024

适用于：2023-07-01-Preview。此版本不再受支持。将立即升级到较新版本。

重要

2023-07-01-Preview 添加了矢量搜索。

“vectorSearch” 对象，这是矢量搜索设置的配置。仅适用于矢量搜索算法。
矢量字段所需的“Collection（Edm.Single）” 数据类型。表示单精度浮点数作为基元类型。
矢量字段所需的“dimensions” 属性。表示矢量嵌入的维度。
矢量字段所需的“vectorSearchConfiguration” 属性。为此字段选择算法配置。

2021-04-30-Preview 添加：

“semanticConfiguration” 用于将语义排名范围限定为特定字段。
“标识”，“encryptionKey”下，用于使用用户分配的托管标识从 Azure Key Vault 检索客户管理的加密密钥。

2020-06-30-Preview 添加：

“规范化器”，用于对排序和筛选器不区分大小写。

索引指定索引架构，包括字段集合（字段名称、数据类型和属性），以及定义其他搜索行为的构造（建议器、计分配置文件和 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）
- 添加或编辑在查询时使用的 synonymMap （synonymMaps）

若要对现有索引进行任何上述架构更改，请在请求 URI 上指定索引的名称，然后使用新的或更改的元素包括完全指定的索引定义。

添加新字段时，索引中的所有现有文档将自动具有该字段的 null 值。在发生以下两项操作之一之前，不会占用额外的存储空间：为新字段提供值（使用合并），或添加新文档。

对 suggester 的更新具有类似的约束：可以在添加字段的同时将新字段添加到 suggester，但如果没有索引重新生成，则无法从中删除现有字段，也不能添加到 suggesters。

不允许更新分析器、tokenizer、令牌筛选器或字符筛选器。可以使用所需的更改创建新索引，但添加新的分析器定义时必须使索引脱机。在索引更新请求中将 allowIndexDowntime 标志设置为 true 使索引脱机：

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

此操作至少将索引脱机几秒钟，这意味着索引和查询请求将失败，直到索引重新联机并准备好处理请求。

URI 参数

参数	描述
服务名称	必填。将此值设置为搜索服务的唯一用户定义的名称。
索引名称	如果使用 PUT，则 URI 上是必需的。名称必须是小写，以字母或数字开头，没有斜杠或点，并且少于 128 个字符。短划线不能连续。
api-version	必填。有关更多版本，请参阅 API 版本。
allowIndexDowntime	自选。默认情况下为 False。对于某些更新，设置为 true，例如添加或修改分析器、tokenizer、令牌筛选器、char 筛选器或类似属性。索引在更新期间处于脱机状态，通常不超过几秒钟。

请求标头

下表描述了必需的和可选的请求标头。

领域	描述
Content-Type	必填。将此值设置为 `application/json`
api-key	如果使用 Azure 角色，并且请求中提供了持有者令牌，则为可选，否则需要密钥。 api-key 是唯一的系统生成的字符串，用于对搜索服务的请求进行身份验证。创建请求必须包含设置为管理密钥的 `api-key` 标头（而不是查询密钥）。有关详细信息，请参阅使用密钥身份验证连接到 Azure AI 搜索。

请求正文

请求的正文包含一个架构定义，其中包括馈送到此索引的文档中的数据字段列表。

以下 JSON 是支持矢量搜索的架构的高级表示形式。架构需要键字段，并且该键字段可以搜索、可筛选、可排序和可分面。

矢量搜索字段的类型为 Collection(Edm.Single)。由于矢量字段不是文本字段，因此不能将向量字段用作键，并且不接受分析器、规范化器、建议器或同义词。它必须具有“dimensions”属性和“vectorSearchConfiguration”属性。

支持矢量搜索的架构还可以支持关键字搜索。索引中的其他非函数字段可以使用索引中包含的任何分析器、同义词和计分配置文件。

{  
  "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) { }  
}

请求包含以下属性：

财产	描述
名字	必填。索引的名称。索引名称只能包含小写字母、数字或短划线，不能以短划线开头或结尾，并且限制为 128 个字符。
描述	可选说明。
字段	此索引的字段集合，其中每个字段都有一个名称、支持的数据类型符合实体数据模型（EDM）以及定义该字段允许操作的属性。字段集合必须具有一个类型 `Edm.String` 字段，其中“key”设置为“true”。此字段表示与索引一起存储的每个文档的唯一标识符（有时称为文档 ID）。字段集合现在接受向量字段。
相似性	自选。对于在 2020 年 7 月 15 日之前创建的服务，请将此属性设置为选择 BM25 排名算法。
建议器	指定一个构造，该构造存储用于在部分查询（如自动完成和建议）上匹配的前缀。
scoringProfiles	自选。用于全文查询的相关性优化。
语义	自选。定义影响语义搜索功能的搜索索引的参数。语义查询需要语义配置。有关详细信息，请参阅创建语义查询。
vectorSearch	自选。配置各种矢量搜索设置。只能配置矢量搜索算法。
规范化程序	自选。规范化字符串的词法排序，生成不区分大小写的排序和筛选输出。
analyzers， charFilters， tokenizers， tokenFilters	自选。如果要定义自定义分析器，请指定索引的这些部分。默认情况下，这些部分为 null。
defaultScoringProfile	覆盖默认评分行为的自定义计分配置文件的名称。
corsOptions	自选。用于索引的跨域查询。
encryptionKey	自选。用于通过 Azure Key Vault 中的客户管理的加密密钥（CMK）对索引进行额外加密。可用于在 2019-01-01 之后创建的可计费搜索服务。

响应

对于成功的创建请求，应会看到状态代码“201 已创建”。默认情况下，响应正文包含已创建的索引定义的 JSON。但是，如果将 Prefer 请求标头设置为 return=minimal，则响应正文为空，成功状态代码为“204 无内容”，而不是“201 已创建”。无论使用 PUT 还是 POST 创建索引，都是如此。

对于成功的更新请求，应会看到“204 无内容”。默认情况下，响应正文为空。但是，如果 Prefer 请求标头设置为 return=representation，响应正文将包含已更新的索引定义的 JSON。在这种情况下，成功状态代码为“200 正常”。

例子

示例：矢量

矢量搜索在字段级别实现。此定义将焦点放在矢量字段上。矢量字段的类型必须为 Collection(Edm.Single)，用于存储单精度浮点值。矢量字段具有一个“dimensions”属性，该属性保存用于生成嵌入的机器学习模型支持的输出维度数。例如，如果使用 text-embedding-ada-002，则每个输出维度的最大数目为 1536。 “algorithmConfiguration”设置为索引中的“vectorSearch”配置的名称。可以在索引中定义多个，然后为每个字段指定一个。

许多属性仅适用于非函数字段。对于矢量字段，将忽略“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”字段遵循此约定。如果还想要使用语义搜索，则必须具有这些行为的非函数文本字段。

{
    "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"]  
    } 
  ]
}

示例：分析器和规范化器

分析器和规范化器在字段定义上引用，并且可以预定义或自定义。如果使用自定义分析器或规范化器，请在“分析器”和“规范化器”部分的索引中指定它们。

以下示例演示了“Tags”的自定义分析器和规范化器。它还分别演示“HotelName”和“Description”的预定义规范化器（标准）和分析器（en.microsoft）。

{
  "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 日 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 Key Vault中使用客户管理的密钥加密。

{
    "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 Key Vault 进行身份验证。在这种情况下，省略访问凭据或设置为 null。以下示例显示了用户分配的托管标识。若要使用系统分配的托管标识，请省略访问凭据和标识。只要搜索服务的系统标识在 Azure Key Vault 中具有权限，连接请求应成功。

{
  "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 Key Vault 的连接，以便进行客户管理的加密。
字段	设置搜索索引中字段的定义和属性。
规范化程序	配置自定义规范化程序。规范化字符串的字典顺序，生成不区分大小写的排序、分面和筛选输出。
语义	配置语义搜索用于排名、标题、突出显示和答案的字段。
scoringProfiles	用于全文查询的相关性优化。
相似性
建议器	配置内部前缀存储以匹配部分查询，例如自动完成和建议。
vectorSearch	配置用于向量字段的算法。

corsOptions

默认情况下，客户端 JavaScript 无法调用任何 API，因为浏览器会阻止所有跨域请求。若要允许跨域查询索引，请通过设置“corsOptions”属性来启用 CORS（跨域资源共享）。出于安全原因，只有查询 API 支持 CORS。

属性描述

allowedOrigins 必填。授予对索引访问权限的源的逗号分隔列表，其中每个源通常是格式 protocol://<完全限定的域名>：<端口>（尽管通常省略 <端口>）。这意味着允许从这些源提供的任何 JavaScript 代码查询索引（假设它提供有效的 API 密钥）。如果要允许访问所有源，请将 * 指定为“allowedOrigins”数组中的单个项。不建议将其用于生产，但对于开发或调试可能很有用。

maxAgeInSeconds 自选。浏览器使用此值来确定缓存 CORS 预检响应的持续时间（以秒为单位）。这必须是非负整数。如果此值较大，则性能会提高，但这些增益将抵消 CORS 策略更改生效所需的时间。如果未设置，则使用默认持续时间 5 分钟。

属性	描述
allowedOrigins	必填。授予对索引访问权限的源的逗号分隔列表，其中每个源通常是格式 protocol://<完全限定的域名>：<端口>（尽管通常省略 <端口>）。这意味着允许从这些源提供的任何 JavaScript 代码查询索引（假设它提供有效的 API 密钥）。如果要允许访问所有源，请将 `*` 指定为“allowedOrigins”数组中的单个项。不建议将其用于生产，但对于开发或调试可能很有用。
maxAgeInSeconds	自选。浏览器使用此值来确定缓存 CORS 预检响应的持续时间（以秒为单位）。这必须是非负整数。如果此值较大，则性能会提高，但这些增益将抵消 CORS 策略更改生效所需的时间。如果未设置，则使用默认持续时间 5 分钟。

defaultScoringProfile

自选。一个字符串，该字符串是索引中定义的自定义计分配置文件的名称。只要查询字符串上未显式指定自定义配置文件，就会调用默认配置文件。有关详细信息，请参阅将计分配置文件添加到搜索索引。

encryptionKey

配置与 Azure Key Vault 的连接，以补充客户管理的加密密钥（CMK）。可用于在 2019 年 1 月 1 日或之后创建的计费搜索服务。

必须对与密钥保管库的连接进行身份验证。为此，可以使用“accessCredentials”或托管标识。

托管标识可以是系统或用户分配的（预览版）。如果搜索服务同时具有系统分配的托管标识和授予对密钥保管库的读取访问权限的角色分配，则可以省略“标识”和“accessCredentials”，并且请求将使用托管标识进行身份验证。如果搜索服务具有用户分配的标识和角色分配，请将“identity”属性设置为该标识的资源 ID。

属性	描述
keyVaultKeyName	必填。用于加密的 Azure Key Vault 密钥的名称。
keyVaultKeyVersion	必填。 Azure Key Vault 密钥的版本。
keyVaultUri	必填。提供密钥的 Azure Key Vault 的 URI（也称为 DNS 名称）。示例 URI 可能是 `https://my-keyvault-name.vault.azure.net`
accessCredentials	自选。如果使用托管标识，请省略此属性。否则，“accessCredentials”的属性包括： “applicationId”（有权访问指定 Azure Key Vault 的 Azure Active Directory 应用程序 ID）。 “applicationSecret”（指定的 Azure AD 应用程序的身份验证密钥）。
身份	可选，除非使用用户分配的托管标识连接到 Azure Key Vault 的搜索服务。格式为 `"/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"`。

领域

包含有关字段定义的属性的信息。

属性	描述
名字	必填。设置字段的名称，该名称在索引或父字段的字段集合中必须唯一。
类型	必填。设置字段的数据类型。字段可以是简单或复杂的。简单字段是基元类型，例如文本 `Edm.String` 或整数 `Edm.Int32`。复杂字段可以具有简单或复杂的子字段。这样，便可以对对象和对象的数组进行建模，这样就可以将大多数 JSON 对象结构上传到索引。 `Collection(Edm.Single)` 容纳单精度浮点值。它仅用于矢量字段，并且是必需的。有关支持类型的完整列表，请参阅支持的数据类型。
钥匙	必填。将此属性设置为 true 以指定字段的值唯一标识索引中的文档。键字段中值的最大长度为 1024 个字符。每个索引中的一个顶级字段必须选择为键字段，并且必须 `Edm.String`类型。对于简单字段，默认值为 `false`，复杂字段的 `null`。键字段可用于直接查找文档，并更新或删除特定文档。查找或索引文档时，键字段的值以区分大小写的方式进行处理。有关详细信息，请参阅查找文档和添加、更新或删除文档。
检索	指示是否可以在搜索结果中返回字段。如果要使用字段（例如页边距）作为筛选器、排序或评分机制，但不希望字段对最终用户可见，请将此属性设置为 `false`。此属性必须为键字段 `true`，并且必须为复杂字段 `null`。可以在现有字段上更改此属性。将可检索设置为 `true` 不会导致索引存储要求增加。对于简单字段，默认值为 `true`，复杂字段的 `null`。
搜索	指示字段是否可全文搜索，并且可以在搜索查询中引用。这意味着它经历了词法分析，例如索引编制期间的断字。如果将可搜索字段设置为“Sunny day”等值，则从内部将它规范化为单个标记“sunny”和“day”。这将启用全文搜索这些术语。默认情况下，可搜索 `Edm.String` 或 `Collection(Edm.String)` 类型的字段。此属性必须 `false` 其他非字符串数据类型的简单字段，并且必须为复杂字段 `null`。可搜索字段在索引中占用额外的空间，因为 Azure AI 搜索处理这些字段的内容，并在辅助数据结构中组织这些字段以执行性能搜索。如果要在索引中节省空间，并且不需要在搜索中包含字段，请将可搜索设置为 `false`。有关详细信息，请参阅 Azure AI 搜索全文搜索的工作原理。
filterable	指示是否启用 `$filter` 查询中引用的字段。可筛选不同于可搜索的字符串的处理方式。可筛选的 `Edm.String` 或 `Collection(Edm.String)` 类型的字段不会进行词法分析，因此仅针对完全匹配项进行比较。例如，如果将此类字段 `f` 设置为“Sunny day”，则 `$filter=f eq 'sunny'` 找不到匹配项，但 `$filter=f eq 'Sunny day'`。对于复杂字段，此属性必须 `null`。对于简单字段，默认值为 `true`，复杂字段的 `null`。若要减小索引大小，请将此属性设置为 `false` 不会筛选的字段。
可排序	指示是否启用 `$orderby` 表达式中引用的字段。默认情况下，Azure AI 搜索按分数对结果进行排序，但在很多体验中，用户希望按文档中的字段进行排序。仅当简单字段是单值字段（父文档的作用域中具有单个值）时，才能进行排序。简单集合字段无法进行排序，因为它们是多值。复杂集合的简单子字段也是多值，因此无法排序。无论是直接父字段还是上级字段，都是复杂的集合，都是如此。复杂字段不能可排序，并且必须为此类字段 `null` 可排序属性。可排序的默认值为单值简单字段 `true`，`false` 多值简单字段，以及复杂字段的 `null`。
facetable	指示是否允许在分面查询中引用字段。通常用于按类别显示的搜索结果（例如，按品牌搜索、按百万像素、按价格等）搜索数字摄像头并查看命中次数）。对于复杂字段，此属性必须 `null`。无法分面 `Edm.GeographyPoint` 或 `Collection(Edm.GeographyPoint)` 类型的字段。对于所有其他简单字段，默认值为 `true`。若要减小索引大小，请将此属性设置为 `false` 不会分面的字段。
分析器	设置用于在索引和查询操作期间标记字符串的词法分析器。此属性的有效值包括语言分析器、内置分析器，以及自定义分析器。默认值为 `standard.lucene`。此属性只能与可搜索字段一起使用，不能与 searchAnalyzer 或 indexAnalyzer 一起使用。选择分析器并在索引中创建字段后，无法更改该字段。必须为复杂字段`null`。
searchAnalyzer	将此属性与 indexAnalyzer 一起设置为指定索引和查询的不同词法分析器。如果使用此属性，请将分析器设置为 `null` 并确保 indexAnalyzer 设置为允许的值。此属性的有效值包括内置分析器和自定义分析器。此属性只能与可搜索字段一起使用。可以在现有字段上更新搜索分析器，因为它仅在查询时使用。必须为复杂字段`null`。
indexAnalyzer	将此属性与 searchAnalyzer 一起设置为指定索引和查询的不同词法分析器。如果使用此属性，请将分析器设置为 `null` 并确保 searchAnalyzer 设置为允许的值。此属性的有效值包括内置分析器和自定义分析器。此属性只能与可搜索字段一起使用。选择索引分析器后，无法更改字段。必须为复杂字段`null`。
normalizer	设置用于筛选、排序和分面操作的规范化器。它可以是预定义规范化器的名称，也可以是索引中定义的自定义规范化器的名称。默认值为 `null`，这会导致逐字、未分析的文本完全匹配。此属性只能与 `Edm.String` 和 `Collection(Edm.String)` 字段一起使用，这些字段至少有一个可筛选、可排序或可分面设置为 true。规范化程序只能在添加到索引时在字段上设置，以后无法更改。必须为复杂字段`null`。预定义规范化器的有效值包括： `standard`- 小写后跟 asciifolding 的文本。 `lowercase`- 将字符转换为小写。 `uppercase` - 将字符转换为大写。 `asciifolding` - 将不在基本拉丁文 Unicode 块中的字符转换为其 ASCII 等效字符（如果存在）。例如，将“à”更改为“a”。 `elision`- 从令牌开头移除 elision。
synonymMaps	要与此字段关联的同义词的名称列表。此属性只能与可搜索字段一起使用。目前每个字段仅支持一个同义词映射。将同义词映射分配给字段可确保使用同义词映射中的规则在查询时扩展针对该字段的查询词。可以在现有字段上更改此属性。必须为复杂字段 `null` 或空集合。
领域	如果这是 `Edm.ComplexType` 或 `Collection(Edm.ComplexType)`类型的字段，则为子字段的列表。对于简单字段，必须为 `null` 或为空。有关如何使用子字段的详细信息，请参阅如何在 Azure AI 搜索中为复杂数据类型建模。
尺寸	整数。矢量字段是必需的。 **这必须与嵌入模型的输出嵌入大小匹配。例如，对于常用的 Azure OpenAI 模型 `text-embedding-ada-002`，其输出维度为 1536，因此，这将是为该向量字段设置的维度。维度属性至少有 2 个，每个浮点值最多为 2048 个。
vectorSearchConfiguration	矢量字段定义是必需的。指定矢量字段使用的 “vectorSearch”算法配置的名称。创建字段后，无法更改 vectorSearchConfiguration 的名称，但可以更改索引中算法配置的属性。这允许调整算法类型和参数。

注意

可筛选、可排序或可分面类型 Edm.String 字段的长度最多可以为 32 KB。这是因为此类字段的值被视为单个搜索词，Azure AI 搜索中字词的最大长度为 32 KB。如果需要在单个字符串字段中存储多于此文本，则需要在索引定义中显式设置可筛选、可排序和可分面 false。

将字段设置为可搜索、可筛选、可排序或可分面对索引大小和查询性能产生影响。不要在查询表达式中不打算引用的字段上设置这些属性。

如果字段未设置为可搜索、可筛选、可排序或可分面，则不能在任何查询表达式中引用该字段。这对于查询中未使用的字段非常有用，但在搜索结果中是必需的。

normalizers

定义自定义规范化程序，该规范化程序具有用户定义的字符筛选器和令牌筛选器的组合。在索引中定义自定义规范化器后，可以在字段定义按名称指定它。

属性	描述
名字	必填。指定用户定义的自定义规范化器的字符串字段。
charFilters	在自定义规范化器中使用。它可以是支持在自定义规范化器中使用的一个或多个可用字符筛选器：映射 pattern_replace
tokenFilters	在自定义规范化器中使用。它可以是一个或多个可用的令牌倾斜器，支持在自定义规范化器中使用： arabic_normalization asciifolding cjk_width elision german_normalization hindi_normalization indic_normalization persian_normalization scandinavian_normalization scandinavian_folding sorani_normalization 小写大写

scoringProfiles

计分配置文件适用于全文搜索。配置文件在索引中定义，并指定自定义逻辑，这些逻辑可授予更高的搜索分数，以匹配符合配置文件中定义的条件的文档。可以创建多个计分配置文件，然后分配要查询的计分配置文件。

如果创建自定义配置文件，可以通过设置 defaultScoringProfile将其设置为默认设置。有关详细信息，请参阅将计分配置文件添加到搜索索引。

语义

语义配置是索引定义的一部分，用于配置语义搜索对排名、标题、突出显示和答案使用哪些字段。语义配置由标题字段、优先级内容字段和优先级关键字字段组成。至少需要为三个子属性（titleField、prioritizedKeywordsFields 和 prioritizedContentFields）中的每个子属性指定一个字段。类型为 Edm.String 或 Collection(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": "..."
             }
           ]
         }
       }
     ]
   }
}

属性	描述
名字	必填。语义配置的名称。
prioritizedFields	必填。描述要用于语义排名、标题、突出显示和答案的标题、内容和关键字字段。至少需要设置三个子属性（titleField、优先级为KeywordsFields 和优先级的ContentFields）中的一个。
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 搜索中的排名算法。

建议器

指定一个构造，该构造存储用于在部分查询（如自动完成和建议）上匹配的前缀。

属性	描述
名字	必填。建议器的名称。
sourceFields	必填。要为其启用自动完成或建议结果的一个或多个字符串字段。
searchMode	必需，并且始终设置为 `analyzingInfixMatching`。它指定匹配发生在查询字符串中的任何术语上。

vectorSearch

vectorSearch 对象允许配置矢量搜索属性。目前只能配置算法配置。这允许配置用于向量字段的算法类型和算法参数。可以有多个配置。无法修改和删除矢量字段引用的任何配置。任何未引用的配置都可以修改或删除。矢量字段定义（在字段集合中）必须指定字段正在使用的矢量搜索算法配置（通过 vectorSearchConfiguration 属性）。

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

属性	描述
名字	必填。算法配置的名称。
类	要使用的算法类型。仅支持“hnsw”，这是分层导航小型世界（HNSW）算法。
hnswParameters	自选。 “hnsw”算法的参数。如果省略此对象，则使用默认值。

hnswParameters

此对象包含用于 hnsw 算法参数的自定义项。所有属性都是可选的，如果省略任何属性，则使用默认值。

属性	描述
度量	字符串。用于矢量比较的相似性指标。对于 `hnsw`，允许的值为“余弦”、“euclidean”和“dotProduct”。默认值为“余弦”。
m	整数。在构造过程中为每个新元素创建的双向链接数。默认值为 4。允许的范围为 4 到 10。较大的值会导致更密集的图形，从而提高查询性能，但需要更多的内存和计算。
efConstruction	整数。索引期间使用的最近邻居的动态列表的大小。默认值为 400。允许的范围为 100 到 1000。较大的值会导致索引质量更好，但需要更多的内存和计算。
efSearch	整数。包含最近邻居的动态列表的大小，该列表在搜索期间使用。默认值为 500。允许的范围为 100 到 1000。增加此参数可能会改善搜索结果，但会降低查询性能。

由于 efSearch 是查询时参数，因此即使现有字段正在使用算法配置，也可以更新此值。

通过

创建或更新索引（预览版 REST API）

URI 参数

请求标头

请求正文

响应

例子

定义

corsOptions

defaultScoringProfile

encryptionKey

领域

normalizers

scoringProfiles

语义

相似

建议器

vectorSearch

hnswParameters

另请参阅

其他资源

通过

创建或更新索引 （预览版 REST API）

URI 参数

请求标头

请求正文

响应

例子

定义

corsOptions

defaultScoringProfile

encryptionKey

领域

normalizers

scoringProfiles

语义

相似

建议器

vectorSearch

hnswParameters

另请参阅

其他资源

创建或更新索引（预览版 REST API）