在 Azure AI 搜索中创建索引

本文介绍定义搜索索引架构并将其推送至搜索服务的步骤。 创建索引会在搜索服务上建立物理数据结构。 一旦索引存在，将在单独的任务中加载索引。

先决条件

• 以搜索服务参与者或管理员 API 密钥的身份写入权限，以进行基于密钥的身份验证。

• 了解要编制索引的数据。 搜索索引基于要使其可搜索的外部内容。 可搜索内容以字段形式存储在索引中。 应该清楚了解要使哪些源字段在 Azure AI 搜索上可搜索、可检索、可筛选、可查找和可排序。 有关指南，请参阅架构清单。

• 还必须在源数据中具有唯一字段，该字段可用作索引中的文档键（或 ID）。

• 稳定的索引位置。 目前不支持将现有索引移到其他搜索服务。 回顾应用程序要求，并确保现有的搜索服务（容量和区域）足以满足你的需求。 如果依赖于 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. 标识数据源中参与索引中可搜索内容的字段。

   可搜索的非矢量内容包括使用全文搜索引擎查询的短字符串或长字符串。 如果内容十分冗长（少量短语或长段内容），请试用不同的分析器来查看文本是如何被标记的。

   可搜索的矢量内容可以是以数学表示形式存在的图像或文本（任何语言）。 可以使用窄数据类型或矢量压缩来缩小矢量字段。

   在 retrievable 或 filterable 字段上设置的属性决定搜索行为和索引在搜索服务上的物理表示形式。 对于许多开发人员来说，确定应如何属性化字段是一个迭代过程。 若要加快迭代速度，请从示例数据开始，这样就可以轻松删除和重新生成索引。

5. 确定哪些源字段可用作筛选器。 数值内容和短文本字段（尤其是那些具有重复值的字段）是不错的选择。 使用筛选器时，请记住：

   • 筛选器可用于矢量和非矢量查询，但筛选器本身应用于索引中的字母数字（非矢量）字段。

   • 可以选择在分面导航中使用可筛选字段。

   • 可筛选字段以任意顺序返回，并且不进行相关性评分，因此请考虑也对其进行排序。

6. 对于矢量字段，请指定矢量搜索配置以及用于创建导航路径和填充嵌入空间的算法。 有关更多信息，请参阅添加矢量字段。

   矢量字段具有非矢量字段所没有的额外属性，例如要使用哪些算法和矢量压缩。

   矢量字段会忽略对矢量数据无用的属性，例如排序、筛选和查找。

7. 对于非矢量字段，确定是使用默认分析器 ("analyzer": null) 还是其他分析器。 分析器用于在索引和执行查询期间标记文本字段。

   对于多语言字符串，请考虑语言分析器。

   对于带连字符的字符串或特殊字符，请考虑专用分析器。 例如，将整个字段内容视为单个令牌的关键字。 此行为可用于邮政编码、ID 和某些产品名称等数据。 有关详细信息，请参阅部分字词搜索和包含特殊字符的模式。

配置字段定义

字段集合定义搜索文档的结构。 所有字段都具有名称、数据类型和属性。

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

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

REST API 具有基于数据类型的默认归因，导入向导也在 Azure 门户中使用。 Azure SDK 没有默认值，但它们具有包含属性和行为的字段子类，例如用于字符串的 SearchableField，用于基元的 SimpleField。

下表汇总了 REST API 的默认字段属性。

还可以选择与分析器和同义词映射关联字符串字段。 Edm.String 类型的可筛选、可排序或可查找字段的长度最多可以是 32 千字节。 这是因为，此类字段的值将被视为单个搜索词，而在 Azure AI 搜索中，一个字词的最大长度为 32 KB。 如果需要在单个字符串字段中存储多于此大小的文本，则应在索引定义中将可筛选、可排序和分面显式设置为 false。

矢量字段必须与维度和矢量配置文件相关联。 如果使用导入和矢量化向导在门户中添加矢量字段，则可检索默认值为 true，否则如果使用 REST API，则为 false。

下表描述了字段属性。

创建索引

准备好创建索引时，请使用可发送请求的搜索客户端。 可以使用 Azure 门户或 REST API 进行早期开发和概念验证测试，否则通常使用 Azure SDK。

在开发过程中，规划频繁的重新生成。 由于物理结构是在服务中创建的，因此许多修改都需要删除和重新创建索引。 可以考虑使用一部分数据来加快重新生成的速度。

POST https://[servicename].search.azure.cn/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>。

  若要允许访问所有来源，请将 * 作为单个项目包含在 allowedOrigins 数组中。 不建议对生产搜索服务采用这种做法，但它在开发和调试中却很有用。

• maxAgeInSeconds（可选）：浏览器使用此值确定缓存 CORS 预检响应的持续时间（以秒为单位）。 此值必须是非负整数。 较长的缓存周期可提供更好的性能，但它延长了 CORS 策略生效所需的时间。 如果未设置此值，则使用默认持续时间为 5 分钟。

允许更新现有索引

创建索引会在搜索服务上创建物理数据结构（文件和倒排索引）。 创建索引后，能否使用创建或更新索引进行更改取决于修改是否会使这些物理结构无效。 在索引中创建了字段后，大多数字段属性就无法更改。

若要最大程度地减少应用程序代码中的改动，可以创建一个索引别名，用作搜索索引的稳定引用。 可以更新索引别名以指向较新的索引版本，而不是使用索引名称更新代码。

为了最大限度地减少设计过程中的流失，下表描述了架构中哪些元素是固定的以及哪些元素是灵活的。 更改固定元素需要重新生成索引，而灵活元素可以在不影响物理实现的情况下随时更改。 有关详细信息，请参阅更新或重新生成索引。

后续步骤

使用以下链接了解可添加到索引的专用功能：

• 添加矢量字段和矢量配置文件

• 添加评分配置文件

• 添加建议器

• 添加同义词映射

• 添加分析器

• 添加加密

使用这些链接加载或更新索引：

• 数据导入概述
• 加载文档
• 更新或重新生成索引