本文介绍如何在 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 应用的可信度与可用性。
