如何在 Azure AI Search 中为文本分块保留原始 PDF 页面编号

本文介绍如何在 azure ai search 的文本分块（text splitter）过程中，准确捕获并存储每个文本块对应的 pdf 原始页码，通过 generatenormalizedimageperpage 配置与自定义 web api 技能协同实现页号注入。

本文介绍如何在 azure ai search 的文本分块（text splitter）过程中，准确捕获并存储每个文本块对应的 pdf 原始页码，通过 generatenormalizedimageperpage 配置与自定义 web api 技能协同实现页号注入。

在使用 Azure AI Search 对 PDF 文档进行向量化检索时，常借助 SplitSkill 按页（textSplitMode: “pages”）切分内容。但默认情况下，SplitSkill 仅输出纯文本块（/document/pages/*），不携带原始页码信息——这导致后续搜索无法定位结果来自哪一页，严重影响可追溯性与用户体验。

根本解法在于：利用 Azure 索引器内置的图像预处理能力提取页码元数据，再通过技能链将其映射到每个文本块。关键前提是启用 PDF 页面级归一化图像生成：

✅ 步骤一：配置索引器参数启用页码提取

在索引器（Indexer）的 parameters.configuration 中设置：

{
  "parameters": {
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "default",
      "imageAction": "generateNormalizedImagePerPage"
    }
  }
}

⚠️ 注意：generateNormalizedImagePerPage 仅对 PDF 文件生效（自动跳过其他格式），且会为每页生成一个归一化图像对象，并在 /document/normalized_images/*/pageNumber 字段中提供精确页码（从 1 开始计数）。

此时文档结构将包含：

"normalized_images": [
  {
    "data": "base64...",
    "width": 500,
    "height": 300,
    "pageNumber": 1
  },
  {
    "data": "base64...",
    "width": 500,
    "height": 300,
    "pageNumber": 2
  }
]

✅ 步骤二：构建自定义 Web API 技能关联页码与文本块

由于 SplitSkill 输出的 /document/pages/* 与 /document/normalized_images/* 是两个独立数组（长度一致、顺序对应），需通过自定义技能建立映射。推荐方案是部署轻量 Web API（如 Azure Functions），接收归一化图像数组，返回同长度的页码数组：

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "name": "#3",
  "description": "Map normalized image page numbers to text chunks",
  "uri": "https://your-api.azurewebsites.net/api/getPageNumbers",
  "context": "/document",
  "inputs": [
    {
      "name": "images",
      "source": "/document/normalized_images/*"
    }
  ],
  "outputs": [
    {
      "name": "pageNumbers",
      "targetName": "pageNumbers"
    }
  ]
}

该 API 的典型响应示例（JSON body）：

{
  "values": [
    { "data": { "pageNumbers": [1, 2, 3] } }
  ]
}

✅ 步骤三：在索引投影中绑定页码字段

最后，在 indexProjections 中将页码数组与文本块对齐（利用 Azure 的上下文匹配机制）：

"indexProjections": {
  "selectors": [
    {
      "targetIndexName": "vector",
      "sourceContext": "/document/pages/*",
      "mappings": [
        { "name": "chunk", "source": "/document/pages/*" },
        { "name": "page_number", "source": "/document/pageNumbers/*" }, // ← 关键：与 pages/* 同层级展开
        { "name": "vector", "source": "/document/pages/*/vector" }
      ]
    }
  ]
}

? 验证与调试建议

• 使用 Indexer Run History 查看 normalized_images 是否成功生成；
• 在技能执行后通过 search explorer 查询 select=*，确认 page_number 字段已写入索引；
• 若 PDF 含扫描件（无文本层），generateNormalizedImagePerPage 仍有效，但需配合 OCR 技能提取文字——页码元数据不受影响。

通过以上三步，您即可在向量检索结果中直接获取精准页码，支撑“跳转至原文第 X 页”等核心业务场景，显著提升 RAG 应用的可信度与可用性。