如何将Azure AI Search自定义技能的列表输出映射为索引标量元素？

要把技能输出的数组字段拆分为多条标量索引记录，需在**技能集的索引投影（indexProjections）**中使用foreach遍历目标数组，并通过$index引用同位置的其他数组元素，配合字段映射完成拆分。

1. 索引字段定义 #

先确保Azure AI Search索引包含所需的标量字段：

{
  "name": "your-index-name",
  "fields": [
    { "name": "id", "type": "Edm.String", "key": true },
    { "name": "identifier", "type": "Edm.Collection(Edm.Int32)" },
    { "name": "text", "type": "Edm.String" },
    { "name": "embedding", "type": "Edm.Collection(Edm.Single)" },
    { "name": "pagenumber", "type": "Edm.Int32" }
  ]
}

2. 技能集配置（含索引投影） #

在技能集中，通过indexProjections的foreach遍历数组，用$index对齐同位置字段，同时嵌入Azure OpenAI技能处理每个拆分后的文本块：

{
  "name": "your-skillset-name",
  "skills": [
    // 自定义文本分块技能
    {
      "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
      "name": "custom-chunk-skill",
      "uri": "your-custom-skill-endpoint",
      "context": "/document",
      "inputs": [
        { "name": "content", "source": "/document/content" }
      ],
      "outputs": [
        { "name": "identifier", "targetName": "identifier" },
        { "name": "text", "targetName": "text" },
        { "name": "pagenumber", "targetName": "pagenumber" }
      ]
    },
    // Azure OpenAI 嵌入技能（针对每个拆分后的文本块）
    {
      "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
      "name": "embedding-skill",
      "context": "/document/chunks/*",
      "resourceUri": "your-azure-openai-resource-uri",
      "apiKey": "your-api-key",
      "deploymentId": "your-embedding-deployment",
      "inputs": [
        { "name": "text", "source": "/document/chunks/*/text" }
      ],
      "outputs": [
        { "name": "embedding", "targetName": "embedding" }
      ]
    }
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "your-index-name",
        "sourceContext": "/document",
        "mappings": [
          {
            "name": "chunks",
            "source": "/document/text",
            "foreach": "$",
            "mappings": [
              { "name": "id", "source": "/document/recordId + '-' + $index" },
              { "name": "identifier", "source": "/document/identifier[$index]" },
              { "name": "text", "source": "$" },
              { "name": "pagenumber", "source": "/document/pagenumber[$index]" },
              { "name": "embedding", "source": "/document/chunks/*/embedding" }
            ]
          }
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

关键配置说明 #

• foreach遍历数组：通过foreach: "$"遍历text数组的每个元素，将每个元素作为独立的子文档上下文。
• $index对齐字段：对于identifier、pagenumber等与text长度匹配的数组，用$index获取当前遍历位置对应的元素，实现字段一一对应。
• 唯一ID生成：拼接原始recordId和$index生成唯一id，避免索引记录重复。
• 嵌入技能上下文：将嵌入技能的context设为/document/chunks/*，确保每个拆分后的文本块都能生成对应的嵌入向量。

注意事项 #

• 确保自定义技能输出的所有数组字段长度一致，否则$index会导致部分字段值缺失。
• 若无需保留原始父文档，设置projectionMode: "skipIndexingParentDocuments"减少冗余数据。

内容的提问来源于stack exchange，提问作者liho