企业官网建设流程全解析

Label Studio Pdf 标签完全指南：文档级标注与 OCR 校验的配置实战

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio

Pdf 标签用于在 Label Studio 标注界面中直接渲染并浏览 PDF 文档，是处理合同、票据、论文等 PDF 数据类型的核心对象标签。本文以 Pdf 标签文档 为主体，结合 Pdf 标签源码实现 与仓库标注模板，完整讲解其参数、文档级分类标注、Enterprise OCR 校验配置、样式控制与输出结果格式，帮助你快速搭建可复用的 PDF 标注方案。

Pdf 标签能做什么

Pdf 标签在标注界面中显示一个 PDF 文档，配合其他控制标签（如 Choices、OcrLabels 等），可以完成以下工作：

• 文档级标注：对整份 PDF 做分类（如法律 / 财务 / 技术文档）、转录、摘要等标注；
• OCR 校验（Enterprise）：在包含文本层的 PDF 上绘制边界框，读取并校验底层文本；
• 交互浏览：内置缩放（Zoom）与旋转（Rotation）能力，支持最多100 页的 PDF 文档。

该标签适用于数据字段类型为PDF（URL）的任务，即在导入数据时以 URL 形式引用 PDF 文件。

能力提示：Enterprise 版本还可以将 Pdf 标签与 Prompts 提示词工作流结合，用于 PDF 自动摘要、分类、信息抽取与文档智能（Document Intelligence）等自动标注场景。

Pdf 标签参数

Pdf 标签的核心参数定义如下（对应 includes/tags/pdf.md 中的参数表）：

• name：标签名称，用于其他标签（如 Choices）通过toName关联；
• value：指向任务数据中存放 PDF 地址的字段，例如value="$pdf"表示从任务 JSON 的pdf字段读取 URL。

从源码实现看（Pdf.jsx），Pdf 标签的类型为"pdf"，其value属性在渲染前会通过parseValue(self.value, store.task.dataObj)从当前任务的dataObj中解析出真实地址_url。换句话说，value字段名必须与任务数据 JSON 中的键保持一致。

示例一：PDF 文档级分类

最常见的用法是"看 PDF + 做分类"。下面这段标注配置对 PDF 文档应用文档级分类：

<View> <Pdf name="pdf" value="$pdf" /> <Choices name="choices" toName="pdf"> <Choice value="Legal" /> <Choice value="Financial" /> <Choice value="Technical" /> </Choices> </View>

对应示例输入数据：

{ "pdf": "https://app.humansignal.com/static/samples/opossum-cuteness.pdf" }

说明：

• <Pdf name="pdf" value="$pdf" />声明 PDF 对象，value="$pdf"读取任务 JSON 中pdf字段的 URL（示例 URL 为文档作者提供的演示地址，实际项目中请替换为你自己的 PDF 存储地址）；
• <Choices toName="pdf">将单选分类控件绑定到该 PDF 对象上，实现文档级分类标注；
• 分类、转录、摘要等文档级任务均可沿用这一模式，只需替换控制标签类型。

示例二：PDF OCR 校验（Label Studio Enterprise）

Enterprise 专属：OCR 校验功能仅在 Label Studio Enterprise 中提供。

社区版与 Starter Cloud 用户如需对 PDF 做 OCR 标注，需先将 PDF 转换为图片，再使用类似"多页文档标注"模板的配置（将每页作为图片对象进行标注）。

OCR 校验的标注配置如下：

<View> <OcrLabels name="ocr" toName="pdf"> <Label value="Typo"/> <Label value="Incorrect amount"/> <Label value="Incorrect name"/> </OcrLabels> <Pdf name="pdf" value="$pdf"/> </View>

对应示例输入数据：

{ "pdf": "https://app.humansignal.com/static/samples/opossum-cuteness.pdf" }

OcrLabels 标签说明

OcrLabels标签会在 PDF 上添加边界框（bounding box），并允许为每个边界框分配标签。其要点如下：

• 必须包含一个或多个Label子标签（如上例中的 Typo、Incorrect amount、Incorrect name）；
• 支持标准参数，例如maxUsages（限制某个标签的最大使用次数），用法可参考 RectangleLabels 等标签；
• 绘制边界框后，工具会尝试读取该区域下方文本层中的文字并高亮显示。

支持的 PDF：文本层是关键

OCR 校验对 PDF 的类型有明确要求：

• 最适合的 PDF：已包含可选中的文本层（text overlay / text layer）的 PDF。这类 PDF 中绘制边界框时，工具可以直接读取并高亮底层文本；
• 不适合的 PDF：仅含图片的 PDF（如扫描件、手机拍照件）没有文本层，不会返回文本，需要先用外部 OCR 工具为 PDF 添加文本层；
• 质量风险提示：如果 PDF 的文本层错位或质量较差，捕获到的文本可能不完整或不准确——该功能恰好可用于审计和改进这些文本层覆盖质量。

控制 PDF 显示高度

默认情况下，PDF 会渲染为当前页面的完整高度。若需限制高度，可对.htx-pdf类应用样式设置高度。一个良好的默认值是calc(100vh - 250px)，具体像素值可根据你标注配置中额外元素的高度微调：

<Style> .htx-pdf { height: calc(100vh - 250px); } </Style>

补充源码细节：从 Pdf.jsx 的渲染组件看，Pdf 标签最终通过<embed src={item._url} style={{ width: "100%", height: "600px", border: "none" }} type="application/pdf" />内嵌方式加载 PDF（即浏览器原生 PDF 查看器），默认高度为 600px、宽度占满容器。因此在实际使用中，建议结合.htx-pdf样式类或容器布局调整高度，以匹配你的标注界面整体设计。

OCR 校验结果输出格式

使用 OcrLabels 进行 OCR 校验后，每个标注区域会输出如下结果字段：

注意旋转原点的细节：在界面上旋转时，视觉上看起来是围绕区域的中心旋转；但数据存储时，原点记录为区域的左上角(x, y)。理解这一差异，有助于你在后处理坐标或解析导出结果时正确还原标注区域。

从源码理解 Pdf 标签的注册与渲染

在开源仓库的前端编辑器中，Pdf 标签的实现位于 web/libs/editor/src/tags/object/Pdf.jsx：

• 模型定义（L21-L32）：通过 MobX State Tree 定义type: "pdf"与可空的value/_url字段；updateValue动作在渲染前从任务数据中解析 URL；
• 组合与注册（L34-L46）：PdfModel组合了 Base、ProcessAttrsMixin、AnnotationMixin 等基础能力，并通过Registry.addTag("pdf", PdfModel, HtxPdf)与Registry.addObjectType(PdfModel)注册为对象类型标签，从而可以成为 Choices 等控制标签的toName关联目标；
• 渲染组件（L36-L41）：若_url未解析成功则返回空，否则渲染浏览器原生 PDF embed 视图。

这意味着：只要任务数据字段能正确提供可访问的 PDF URL，Pdf 标签即可直接工作；value字段解析失败（如字段名拼写错误或 URL 不可达）时，界面不会渲染 PDF 内容，因此请务必核对导入数据中的字段名与value="$xxx"一致。

使用建议与限制汇总

• 数据类型：仅适用于字段类型为 PDF URL 的任务数据；
• 页数上限：最多支持 100 页的 PDF；
• 交互能力：缩放与旋转已内置，无需额外配置；
• OCR 前置条件：Enterprise 的 OCR 校验依赖 PDF 文本层，扫描件需先经外部 OCR 工具补层；
• 样式控制：通过.htx-pdf样式类调整显示高度，默认渲染高度为 600px（源码内联样式）；
• 社区版替代方案：文档级分类/转录/摘要可直接使用 Pdf 标签；OCR 类标注需将 PDF 转图片后按多页图片标注模板处理。

掌握 Pdf 标签的参数与三种典型用法（文档级分类、Enterprise OCR 校验、高度样式控制），即可在 Label Studio 中快速搭建适用于合同审阅、票据校验、论文批注等场景的 PDF 标注流程。

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio