企业官网建设流程全解析

Kosmos-2.5 模型输出案例全解析：文档级文本识别与图像转 Markdown 的实战指南

【免费下载链接】unilmLarge-scale Self-supervised Pre-training Across Tasks, Languages, and Modalities项目地址: https://gitcode.com/GitHub_Trending/un/unilm

CASES.md 是 Kosmos-2.5 多模态读写模型官方公开的模型输出案例文档，集中展示了该模型在两类核心转录任务上的真实输入输出表现：端到端文档级文本识别（Text Recognition，即带空间信息的 OCR）与图像转 Markdown 结构化文本生成（Image to Markdown）。本文以 kosmos-2.5/CASES.md 的案例为骨架，结合 kosmos-2.5/inference.py、kosmos-2.5/kosmos2_5/ 下的源码实现，逐例解读输出背后的 token 序列构造、特殊符号字典与结果后处理逻辑，并给出可复现这些案例的完整安装与推理命令，帮助读者理解 Kosmos-2.5 如何用单一生成式模型同时完成两项相互协作的文本密集图像理解任务。

CASES.md 在 Kosmos-2.5 项目中的定位

在仓库的官方首页 kosmos-2.5/README.md 中，项目通过一张"输入 / ocr prompt 输出 / markdown prompt 输出"的三联图示意模型能力，并明确注明"更多模型输出见 CASES.md"（原文为More model outputs can be found in the "CASES.md"）。因此，CASES.md 是理解 Kosmos-2.5 实际输出形态的第一手资料，它以"输入图片 vs 模型输出"对照表的形式，围绕两个任务组织案例：

1. Text Recognition Task（文本识别任务）：4 组案例，覆盖屏幕截图（screen）、演示文稿（ppt）、PDF 文档、扫描文档（CDIP）；
2. Image to Markdown Task（图像转 Markdown 任务）：2 组案例，覆盖 GitHub README 页面与 LaTeX 数学公式文档。

这两类任务对应 README 中描述的 Kosmos-2.5 两大核心能力：生成空间感知的文本块（每个文本块带图像内空间坐标）与生成捕获样式与结构的 Markdown 结构化文本。下面分别展开每一组案例的细节与源码实现。

任务一：端到端文档级文本识别（Text Recognition）

案例总览

以下完整保留 CASES.md 中 Text Recognition 任务的 4 组输入输出对照（图片均位于仓库 kosmos-2.5/assets/cases/ 目录）：

Input	Output

案例解读：从文档图像到"文本 + 空间框"

四组输入分别代表了真实世界中最常见的四类文本密集图像：

• 屏幕截图（screen）：网页界面，含导航栏、正文段落、侧边栏等混合排版；
• 演示文稿（ppt）：含标题、列表、代码示例与图形的幻灯片页面；
• PDF：正式报告页面，含标题、列表、表格与多段正文；
• CDIP 扫描件：带有手写签名的采购订单类扫描文档，文字与表格存在扫描噪声。

从输出列可以看到，Kosmos-2.5 的文本识别结果并非单纯吐出文字，而是以带空间位置信息的文本块形式呈现：每个被识别的文本块都配有一个边界框（bounding box），从而把"识别出什么字"与"字在图像哪里"统一在一个生成序列中解决。这与传统两阶段 OCR（先检测后识别）范式有本质区别——空间信息由生成式模型直接产出，无需独立的检测器。

源码级原理： 提示、 与坐标 token

文本识别任务的输出结构可以从推理源码中得到精确印证。在 inference.py 的build_data函数中，任务提示 token 的构造逻辑是：

if args.do_ocr == True: text_token = [dictionary.index("<ocr>"), dictionary.index('<bbox>')]

即当执行 OCR 任务时，模型在图像特征之后拼接<ocr>与<bbox>两个特殊 token，作为引导解码器生成"带边界框的文本"的任务提示。

生成结果如何还原为"文本 + 坐标"？见get_ocr_res（inference.py）。该函数逐行扫描生成的 token 序列：

• 以<开头的连续 token 被收集为边界框描述，其中第一个必须是<bbox>，最后一个必须是</bbox>；
• 框内恰好 4 个坐标 token，形如<x_123>、<y_45>，通过split('_')取出数字即为归一化坐标；
• 非<开头的 token 序列被tokenizer.decode还原为行文本；
• 最后在ocr_post_process中，将归一化坐标按比例映射回原始图像尺寸，并做clip截断防止越界。

这些坐标 token 的字典来源见 kosmos-2.5/kosmos2_5/data/utils.py：SPECIAL_SYMBOLS中除<ocr>、<image>、</image>、<bbox>、</bbox>、<md>等语义符号外，还批量注册了<x_0>~<x_4095>与<y_0>~<y_4095>共 8192 个坐标 token，作为空间位置的离散化表示。

输出 JSON 结构

OCR 结果最终以 JSON 文件保存（默认输出到--out_dir），其结构与get_json_format（inference.py）一致：

{ "model": "kosmos 2.5", "task": "ocr", "width": 原图宽度, "height": 原图高度, "results": [ { "text": "识别出的文本行", "bounding box": {"x0": 0, "y0": 0, "x1": 100, "y1": 50} } ] }

任务二：图像转 Markdown（Image to Markdown）

案例总览

以下完整保留 CASES.md 中 Image to Markdown 任务的 2 组输入输出对照：

Input	Output

案例解读：从版面图像到结构化 Markdown

• README 案例：输入是一个 GitHub 仓库的 README 页面（含标题、Install / Physical Setup / Configure / Update 等章节、代码块、超链接），输出保留了标题层级、代码块与链接结构的 Markdown 文本，说明模型不仅识别文字，还理解了版面结构与样式语义；
• LaTeX 案例：输入是含数学公式与数据表格的学术论文页面（如分支比表格、B_s \to \gamma \mu^+ \mu^-类公式），输出保留了表格的列对齐、上下标数值与 LaTeX 公式语法，验证了模型对复杂版面（表格、公式）的结构化转录能力。

源码级原理： 提示与 Markdown 后处理

与 OCR 不同，Markdown 任务的任务提示只有一个 token。build_data中（inference.py）：

else: text_token = [dictionary.index("<md>")]

生成完成后，get_markdown_res（inference.py）执行后处理：

• 截取</image>之后到</s>之前的 token 段；
• 用tiktoken的cl100k_base编码器解码为原始 Markdown 文本；
• 将模型输出的<br>标记替换为真实换行\n；
• 逐行去除首尾空白，并把连续空行压缩为单个空行，得到整洁的 Markdown。

输出 JSON 结构同样固定（task字段为"markdown"）：

{ "model": "kosmos 2.5", "task": "markdown", "width": 原图宽度, "height": 原图高度, "results": "# 转换后的 Markdown 正文" }

案例背后的统一架构：一个模型如何同时完成两项任务

CASES.md 展示的两个任务看似不同，实际共享同一套生成式架构，这正是 Kosmos-2.5 设计的关键：共享的 decoder-only 自回归 Transformer + 任务提示（prompt）+ 灵活的文本表示。源码可以完整还原这条链路：

输入序列的构造

在build_data（inference.py）中，送入模型的 token 序列依次为：

1. bos（序列起始）；
2. <image>+ 2048 个图像特征占位 token +</image>（图像区域，配合img_gpt_input_mask将视觉特征注入 GPT）；
3. 任务提示 token：<ocr> <bbox>（OCR）或<md>（Markdown）。

图像本身通过AutoProcessor.from_pretrained("google/pix2struct-large", is_vqa=False)处理为flattened_patches与attention_mask（inference.py），最多支持 4096 个 patch（见 kosmos2_5/tasks/generation.py 的MAX_PATHES=4096）。

模型主体：视觉编码器 + 连接器 + GPT 解码器

模型定义在 kosmos2_5/models/unigpt.py 的UniGPTmodel中：

• 视觉编码器：Pix2StructVisionModel（load_image_model中从args.image_encoder加载）；
• 连接器：XConnector（kosmos2_5/models/connector.py），先做线性投影，再引入可学习的latent_query，通过一层 cross-attention 把视觉特征压缩对齐到 GPT 的隐空间；
• GPT 解码器：自回归语言模型主体，注册的架构unigptmodel_large（unigpt.py）为 24 层、隐维度 1536、16 个注意力头、约 1.3B 参数规模。

训练与推理阶段的字典由 kosmos2_5/tasks/generation.py 的GenerationTask.setup_dictionary加载dict.txt，并将SPECIAL_SYMBOLS（含<ocr>、<md>、<bbox>、坐标 token 等）追加为字典符号，保证提示 token 与坐标 token 均可被生成。

推理默认配置（inference.py）为贪心解码：beam=1、max_len_b=4000、min_len=1、lenpen=1.0，并在init中开启 FP16、加载 checkpoint 到 GPU。整个main流程对每张图片走一遍"构造输入 →task.inference_step生成 → 按任务后处理 → 写 JSON"，与 CASES.md 中每组案例的产出路径完全一致。

复现案例：安装、模型下载与推理实战

环境与安装

Kosmos-2.5 的代码依赖 Flash Attention 2（见 kosmos-2.5/requirements.txt），因此仅支持 Ampere、Ada 或 Hopper 架构 GPU（如 A100、RTX 3090、RTX 4090、H100）。安装步骤：

git clone https://github.com/microsoft/unilm.git cd unilm/kosmos-2.5 pip install -r requirements.txt

requirements.txt 中除tiktoken、tqdm、omegaconf<=2.1.0、numpy==1.22、scipy==1.10、fairscale==0.4、flash-attn、triton等常规依赖外，还从外部源码安装了 fairseq、infinibatch、torchscale、transformers 等工具包，请确保按清单完整安装。

下载模型权重

按 README 说明，可通过以下命令下载官方发布的 checkpoint（该权重比论文报告版本训练了更多步数）：

wget -O ckpt.pt https://huggingface.co/microsoft/kosmos-2.5/resolve/main/ckpt.pt?download=true

推理命令

执行 OCR（对应 CASES.md 的 Text Recognition 案例）：

python inference.py \ --do_ocr \ --image path/to/image \ --ckpt path/to/checkpoint

执行图像转 Markdown（对应 CASES.md 的 Image to Markdown 案例），仅需将--do_ocr换成--do_md：

python inference.py \ --do_md \ --image path/to/image \ --ckpt path/to/checkpoint

命令行约束在 inference.py 中校验：--image指向的文件必须存在；--do_ocr与--do_md必须二选一且不能同时开启（assert (args.do_ocr and not args.do_md) or (args.do_md and not args.do_ocr)）。结果按原图片名.json保存到--out_dir（默认./）。

针对极端宽高比图片的预处理

对于宽高比极端的图片（例如超长截图、超宽表格），README 建议先做宽高比规整再推理，以获得更稳定的效果：

python inference.py \ --do_ocr \ --image path/to/image \ --ckpt path/to/checkpoint \ --use_preprocess \ --hw_ratio_adj_upper_span "[1.5, 5]" \ --hw_ratio_adj_lower_span "[0.5, 1.0]"

参数含义（README 原文说明，同时与 inference.py 的实现一一对应）：

• --hw_ratio_adj_upper_span "[1.5, 5]"：当图片宽高比（高/宽）落在 1.5 到 5 之间时，将图片等比缩放到宽高比为 1.5（即把过高的图压缩到合理比例）；
• --hw_ratio_adj_lower_span "[0.5, 1.0]"：当宽高比落在 0.5 到 1.0 之间时，将图片等比缩放到宽高比为 1.0（即把过宽的图拉伸到接近正方形）。

两个参数均通过parse_list解析为 Python list（inference.py），请按实际图片分布调整区间；预处理后的图片再交给image_processor切 patch，因此该参数只影响送入模型的图像比例，不改变输出 JSON 中记录的原始宽高。

注意事项与适用边界

由于 Kosmos-2.5 本质上是生成式模型（generative model），README 明确警示：生成过程中存在幻觉（hallucination）风险，无法保证图片中所有 OCR / Markdown 结果的绝对准确。因此在实际应用中，对结果可结合人工抽检或下游规则进行校验，尤其在高精度要求的票据、合同等场景。

若希望量化了解该模型在各类文档上的水平，可参考 kosmos-2.5/README.md 中的评测表：Text Recognition 在 Handwritten / Design / Receipt / General / Academic / Web Image 六类数据集上的 F1、IOU、NED 指标，以及 Image to Markdown 在 Docx / README / Arxiv / Tables / Math Equation / CROHME Math 上的 NED 与 NTED 指标。CASES.md 的定性案例与 README 的定量指标互为印证，共同勾勒出 Kosmos-2.5 在文本密集图像理解上的能力边界。

小结

CASES.md 用六组输入输出对照，直观呈现了 Kosmos-2.5 的两项核心转录能力。结合 inference.py 的 token 构造与后处理逻辑、kosmos2_5/data/utils.py 的特殊符号字典、kosmos2_5/models/unigpt.py 的统一架构，可以看出：OCR 输出"文本 + 边界框"，Markdown 输出"结构化文本"，二者均由同一 decoder-only 模型通过不同任务提示驱动。读者可依照上文安装、下载权重并运行推理命令，在自己的屏幕截图、PPT、PDF、扫描件与学术文档上复现这些案例，进而将 Kosmos-2.5 应用到文档解析、知识库构建等文本密集图像理解场景中。

【免费下载链接】unilmLarge-scale Self-supervised Pre-training Across Tasks, Languages, and Modalities项目地址: https://gitcode.com/GitHub_Trending/un/unilm