本文介绍如何在 Azure AI Search 的文本分块（SplitSkill）流程中准确捕获并存储每个文本块对应的 PDF 原始页码，通过 generateNormalizedImagePerPage 配合自定义 Web API 技能实现页面号注入到索引字段。
本文介绍如何在 azure ai search 的文本分块（splitskill）流程中准确捕获并存储每个文本块对应的 pdf 原始页码，通过 `generatenormalizedimageperpage` 配合自定义 web api 技能实现页面号注入到索引字段。
在 Azure AI Search 中使用 TextSplitSkill 按页（textSplitMode: "pages"）切分 PDF 文档时，系统默认不会自动保留原始页码信息——即使内容按页分割，生成的 /document/pages/* 数组中也缺乏 pageNumber 字段。这意味着检索结果无法直接关联到源 PDF 的具体页码，严重影响可追溯性与下游应用体验（如高亮定位、文档导航等）。解决该问题的关键在于：利用 Azure 索引器的图像预处理能力提取页码，并将其映射至文本块上下文。
✅ 正确做法：启用 generateNormalizedImagePerPage 并桥接页码
Azure 索引器在解析 PDF 时支持 imageAction 参数，当设为 "generateNormalizedImagePerPage"（仅适用于 PDF），它会为每一页生成一个标准化图像对象，并在 /document/normalized_images/* 中附带 pageNumber 字段。注意：此行为与 SplitSkill 的 textSplitMode: "pages" 逻辑对齐，二者页序一致，可安全建立映射关系。
首先，在索引器参数中启用该功能：
{
"parameters": {
"configuration": {
"dataToExtract": "contentAndMetadata",
"parsingMode": "default",
"imageAction": "generateNormalizedImagePerPage"
}
}
}
执行后，文档结构将包含如下字段（示例）：
"normalized_images": [
{
"data": "/9j/4AAQSkZJRg...",
"width": 500,
"height": 300,
"originalWidth": 5000,
"originalHeight": 3000,
"rotationFromOriginal": 0,
"contentOffset": 0,
"pageNumber": 1
},
{
"pageNumber": 2,
"contentOffset": 12478,
...
}
]
? 关键桥梁：自定义 Web API 技能注入页码
由于 normalized_images 和 pages 是两个独立数组（无原生嵌套关系），需借助 Custom Web API Skill 将 pageNumber 显式注入到每个文本块中。推荐设计一个轻量 Web API（如 Azure Function），接收 normalized_images 数组，返回与之顺序一致的 pageNumber 列表：
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"uri": "https://your-function-app.azurewebsites.net/api/extractPageNumbers",
"context": "/document/normalized_images/*",
"inputs": [
{
"name": "normalized_images",
"source": "/document/normalized_images/*"
}
],
"outputs": [
{
"name": "pageNumber",
"targetName": "pageNumber"
}
],
"httpMethod": "POST",
"timeout": "PT30S"
}
该技能的输出 pageNumber 将作为新字段挂载到 /document/normalized_images/*/pageNumber 路径下。随后，你可在后续技能（如 EmbeddingSkill）或索引投影中，通过 sourceContext: "/document/normalized_images/*" 将其与对应文本块关联。
? 索引投影与字段映射建议
在 indexProjections 中，确保将页码字段显式映射至目标索引：
"indexProjections": {
"selectors": [
{
"targetIndexName": "vector",
"sourceContext": "/document/pages/*",
"mappings": [
{
"name": "chunk",
"source": "/document/pages/*"
},
{
"name": "page_number",
"source": "/document/normalized_images/*/pageNumber"
},
{
"name": "vector",
"source": "/document/pages/*/vector"
}
]
}
]
}
⚠️ 注意事项：
- generateNormalizedImagePerPage 仅对 PDF 生效；其他格式（如 DOCX）需改用 OCR 或第三方解析库预处理。
- normalized_images 与 pages 的数组长度必须严格一致（否则映射错位），建议在调试阶段验证二者 count 是否相等。
- 自定义 Web API 应具备幂等性和低延迟（
- 若无需图像本身，可忽略 data 字段，仅提取 pageNumber，减少网络传输开销。
最终，搜索结果将携带 page_number 字段，支持前端精准跳转、分页过滤或按页聚合分析，真正实现“所见即所得”的语义检索体验。
