【TrOCR】模型预训练权重各个文件解读

原创

已于 2025-10-13 13:12:24 修改 · 1k 阅读

22 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能 #transformer #ocr #自然语言处理 #计算机视觉 #pytorch

于 2025-08-21 23:33:18 首次发布

预训练权重下载

huggingface上预训练权重trocr-base-printed
在这里插入图片描述
下载后的trocr-base-printed是一个文件夹，结构如下：

以下是对 trocr-base-printed 模型文件夹内各文件的简短分点解读，基于此前的详细分析提炼核心作用：

1. 模型结构与配置

config.json：定义模型整体架构（编码器-解码器结构、网络层数/维度等），是模型“蓝图”，决定网络结构与超参数。
generation_config.json：文本生成专属配置（起始/结束 Token、生成策略默认值），控制 model.generate() 的行为。

2. 数据预处理与分词

preprocessor_config.json：图像预处理规则（归一化、缩放尺寸、插值方法），确保输入图像与预训练逻辑一致。
tokenizer_config.json + vocab.json + merges.txt：定义文本分词规则（BPE 分词词表、合并规则），将文本转成模型可理解的 Token ID。
special_tokens_map.json：特殊 Token（如 <s>、<pad>）的映射关系，标记序列开始、结束、填充等边界。

3. 模型权重与版本管理

model.safetensors：核心权重文件（安全高效的 safetensors 格式），存储编码器、解码器的预训练参数，是模型“知识载体”。
.gitattributes：Git LFS 规则，让大文件（如 model.safetensors）被 Git LFS 管理，避免仓库膨胀。

这些文件相互配合，从 数据预处理（靠 preprocessor/tokenizer 配置）→ 模型结构定义（config.json）→ 权重加载（model.safetensors）→ 文本生成策略（generation_config.json），完整支撑了模型从“加载”到“运行”的全流程，支撑 TrOCR 完成“图像→文本”的 OCR 任务。

`README.md`

原文

	---
	tags:
	- trocr
	- image-to-text
	widget:
	- src: https://layoutlm.blob.core.windows.net/trocr/dataset/SROIE2019Task2Crop/train/X00016469612_1.jpg
	  example_title: Printed 1
	- src: https://layoutlm.blob.core.windows.net/trocr/dataset/SROIE2019Task2Crop/train/X51005255805_7.jpg
	  example_title: Printed 2
	- src: https://layoutlm.blob.core.windows.net/trocr/dataset/SROIE2019Task2Crop/train/X51005745214_6.jpg
	  example_title: Printed 3
	---
	
	# TrOCR (base-sized model, fine-tuned on SROIE) 
	
	TrOCR model fine-tuned on the [SROIE dataset](https://rrc.cvc.uab.es/?ch=13). It was introduced in the paper [TrOCR: Transformer-based Optical Character Recognition with Pre-trained Models](https://arxiv.org/abs/2109.10282) by Li et al. and first released in [this repository](https://github.com/microsoft/unilm/tree/master/trocr). 
	
	Disclaimer: The team releasing TrOCR did not write a model card for this model so this model card has been written by the Hugging Face team.
	
	## Model description
	
	The TrOCR model is an encoder-decoder model, consisting of an image Transformer as encoder, and a text Transformer as decoder. The image encoder was initialized from the weights of BEiT, while the text decoder was initialized from the weights of RoBERTa.
	
	Images are presented to the model as a sequence of fixed-size patches (resolution 16x16), which are linearly embedded. One also adds absolute position embeddings before feeding the sequence to the layers of the Transformer encoder. Next, the Transformer text decoder autoregressively generates tokens.
	
	## Intended uses & limitations
	
	You can use the raw model for optical character recognition (OCR) on single text-line images. See the [model hub](https://huggingface.co/models?search=microsoft/trocr) to look for fine-tuned versions on a task that interests you.
	
	### How to use
	
	Here is how to use this model in PyTorch:
	
	```python
	from transformers import TrOCRProcessor, VisionEncoderDecoderModel
	from PIL import Image
	import requests
	
	# load image from the IAM database (actually this model is meant to be used on printed text)
	url = 'https://fki.tic.heia-fr.ch/static/img/a01-122-02-00.jpg'
	image = Image.open(requests.get(url, stream=True).raw).convert("RGB")
	
	processor = TrOCRProcessor.from_pretrained('microsoft/trocr-base-printed')
	model = VisionEncoderDecoderModel.from_pretrained('microsoft/trocr-base-printed')
	pixel_values = processor(images=image, return_tensors="pt").pixel_values
	
	generated_ids = model.generate(pixel_values)
	generated_text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
	```
	
	### BibTeX entry and citation info
	
	```bibtex
	@misc{li2021trocr,
	      title={TrOCR: Transformer-based Optical Character Recognition with Pre-trained Models}, 
	      author={Minghao Li and Tengchao Lv and Lei Cui and Yijuan Lu and Dinei Florencio and Cha Zhang and Zhoujun Li and Furu Wei},
	      year={2021},
	      eprint={2109.10282},
	      archivePrefix={arXiv},
	      primaryClass={cs.CL}

这份 README.md 是 Hugging Face Hub 上 microsoft/trocr-base-printed 模型的说明文档，详细介绍了模型的基本信息、用途、使用方法等，是快速上手该模型的核心参考。以下是逐部分解读：

一、头部元信息（模型标签与示例）

tags:
- trocr
- image-to-text
widget:
- src: https://layoutlm.blob.core.windows.net/trocr/dataset/SROIE2019Task2Crop/train/X00016469612_1.jpg
  example_title: Printed 1
- src: https://layoutlm.blob.core.windows.net/trocr/dataset/SROIE2019Task2Crop/train/X51005255805_7.jpg
  example_title: Printed 2
- src: https://layoutlm.blob.core.windows.net/trocr/dataset/SROIE2019Task2Crop/train/X51005745214_6.jpg
  example_title: Printed 3

tags：模型标签，用于分类和检索。trocr 表明属于 TrOCR 系列，image-to-text 说明其核心功能是“图像到文本”转换（即 OCR）。
widget：交互式示例，展示模型的典型输入（印刷体文本图像）。在 Hugging Face 模型页面中，用户可直接上传类似图像测试模型输出，直观了解模型效果。

二、模型基本信息

# TrOCR (base-sized model, fine-tuned on SROIE) 

TrOCR model fine-tuned on the [SROIE dataset](https://rrc.cvc.uab.es/?ch=13). It was introduced in the paper [TrOCR: Transformer-based Optical Character Recognition with Pre-trained Models](https://arxiv.org/abs/2109.10282) by Li et al. and first released in [this repository](https://github.com/microsoft/unilm/tree/master/trocr). 

Disclaimer: The team releasing TrOCR did not write a model card for this model so this model card has been written by the Hugging Face team.

模型名称：trocr-base-printed 是基础版（base-sized）TrOCR 模型，专门针对印刷体文本优化，并在 SROIE 数据集（收据识别数据集）上进行了微调。
来源：模型源自 2021 年论文《TrOCR: Transformer-based Optical Character Recognition with Pre-trained Models》，由微软团队开发，首次发布于 unilm 仓库。
免责声明：原团队未提供官方模型卡片，此文档由 Hugging Face 团队补充，确保用户能获取关键信息。

三、模型结构说明（`Model description`）

The TrOCR model is an encoder-decoder model, consisting of an image Transformer as encoder, and a text Transformer as decoder. The image encoder was initialized from the weights of BEiT, while the text decoder was initialized from the weights of RoBERTa.

Images are presented to the model as a sequence of fixed-size patches (resolution 16x16), which are linearly embedded. One also adds absolute position embeddings before feeding the sequence to the layers of the Transformer encoder. Next, the Transformer text decoder autoregressively generates tokens.

核心架构：TrOCR 是“编码器-解码器”结构：
- 编码器：基于图像 Transformer（源自 BEiT 模型的预训练权重），负责将图像转换为特征序列。
- 解码器：基于文本 Transformer（源自 RoBERTa 模型的预训练权重），负责将图像特征生成为文本序列。
图像处理流程：
1. 图像被分割为 16x16 像素的固定大小“补丁（patch）”；
2. 每个补丁通过线性嵌入转换为向量，并添加绝对位置嵌入（标记补丁在图像中的位置）；
3. 嵌入后的序列输入 Transformer 编码器，输出图像特征；
4. 解码器以自回归方式（逐词生成）基于图像特征生成文本。

四、用途与限制（`Intended uses & limitations`）

You can use the raw model for optical character recognition (OCR) on single text-line images. See the [model hub](https://huggingface.co/models?search=microsoft/trocr) to look for fine-tuned versions on a task that interests you.

主要用途：适用于单行文本图像的 OCR 任务（如扫描文档中的单行文字、街景中的单行招牌等）。
限制：
- 对多行文本、复杂布局的图像识别效果较差（需额外的文本检测模型先分割单行）；
- 主要优化印刷体，对手写体或低质量（模糊、倾斜、噪声）图像的识别可能不准确；
- 如需针对特定场景（如收据、车牌）使用，建议寻找在对应数据集上微调过的版本（可通过 Hugging Face 模型 hub 搜索）。

五、使用示例（`How to use`）

提供了 PyTorch 环境下的最小化使用代码，核心步骤包括：

加载处理器（TrOCRProcessor）和模型（VisionEncoderDecoderModel）；
读取图像并转换为模型可接受的格式（pixel_values）；
生成文本（model.generate()）并解码为可读字符串（processor.batch_decode()）。

示例代码简洁展示了从“加载模型”到“输出结果”的完整流程，方便用户快速测试。

六、引用信息（`BibTeX entry`）

提供了论文的 BibTeX 引用格式，方便用户在学术研究中引用该模型时使用，确保合规性。

总结

这份 README.md 是 trocr-base-printed 模型的“使用说明书”，核心价值在于：

明确模型的适用场景（单行印刷体 OCR）和结构（编码器-解码器架构）；
提供直观的使用示例，降低上手门槛；
提示模型的局限性和扩展方向（如寻找特定场景的微调版本）。

对于使用者而言，可通过此文档快速判断模型是否符合需求，并直接复用示例代码进行测试或集成到项目中。

`vocab.json`

在这里插入图片描述
用Pycharm快捷键Ctrl+Alt+L，格式化一下：

在这里插入图片描述
以下为你详细解读 vocab.json 中各类 Token 的含义、作用，以及背后的分词逻辑（结合 TrOCR 这类基于 BPE 分词的模型场景），帮你理解文本是如何被“拆”成模型能懂的单元：

一、核心特殊 Token（模型运行的基础标记）

Token	ID	含义与作用
`<s>`	0	一般是序列开始标记（Sentence Start），文本生成任务中，常作为解码器的“起始信号”。比如用 `model.generate` 时，解码器会先拿到 `<s>`，再逐步生成后续内容。
`<pad>`	1	填充标记（Padding），用来对齐一个 batch 中长度不一的文本。短文本会用 `<pad>` 填充到最大长度，模型会忽略这些位置的损失（或特殊处理）。
`</s>`	2	序列结束标记（Sentence End），文本生成时，模型输出 `</s>` 就表示生成结束；也用于区分不同文本片段（比如多句子输入时）。
`<unk>`	3	未知标记（Unknown），遇到分词器不认识的字符/子词时，会替换成 `<unk>`，避免因词表外内容报错，不过也会损失一些语义信息。

二、标点与常见词 Token（文本内容的基础单元）

标点符号：如 .:4、,:6、-:12
这些是文本中常见的标点，会被单独拆分为 Token（或和前后子词结合，取决于 BPE 规则）。作用是保留文本的语法结构，让模型理解句子停顿、断句等。
常见英文单词/子词：如 Ġthe:5、Ġto:7、Ġand:8
- 前面的 Ġ（实际是一个特殊的空白符号，可能显示为 Ġ 或 ## 类似标记），表示这个 Token 是词的开头（或独立词）。
- 比如 Ġthe 就是完整的单词 the，而如果有 ##e 这样的 Token（假设存在），则表示它是某个词中间的子词（比如 another 可能被拆成 an + ##other ）。
- 这类常见词的 Token，是预训练时统计高频出现的结果，让模型能高效处理日常文本。

三、特殊字符与缩写 Token（覆盖多样文本场景）

特殊字符：如 âĢ:17（可能是文本编码问题，或原始数据中的特殊符号）
预训练数据中如果包含特殊符号、小众语言字符、emoji 等，会被编码成对应的 Token 存入词表，确保模型能“看见”这些内容（虽然可能出现频率低，语义难捕捉）。
缩写/词缀：如 's:18（英文里的所有格缩写，如 Virgil's 可能拆成 ĠVirgil + 's ）
这类 Token 处理语言中的“紧凑表达”，让分词器不用生硬拆分 ' 和 s，保留语义完整性。

四、分词逻辑与 `merges.txt` 的关联（BPE 分词的关键）

vocab.json 里的 Token 是 BPE 分词的“终点”——预训练时，先统计所有可能的字符对，按频率合并成子词，直到达到预设词表大小。而 merges.txt 就记录了合并的步骤（比如先合并 e 和 s 成 es，再合并 the 和 es 成 thees 等，不过实际是更细的字符对合并）。

举个流程示例：
原始文本 → 拆成字符（t, h, e, , w, o, r, l, d…）→ 按 merges.txt 合并高频对 → 最终得到 vocab.json 里的 Ġthe、Ġworld 等 Token。

所以，vocab.json 里的每个 Token，都是 BPE 算法“合并到不能再合并（或达到词表限制）”的产物，平衡了词表大小和语义表达力。

五、对模型训练/推理的影响

训练阶段：模型学习的是这些 Token 之间的关联（比如看到 Ġthe 后，更可能接 Ġworld 还是 Ġof ），通过预测下一个 Token 学习文本规律。
推理阶段：输入文本会先经分词器，按 vocab.json 和 merges.txt 拆成对应 Token ID，再喂给模型；模型输出的 ID，也会通过 vocab.json 转回文本（比如 ID5 对应 Ġthe，最终去掉 Ġ 显示为 the ）。

简单说，vocab.json 就是模型的“字典”——所有输入输出都要通过这个“字典”转成数字 ID 才能被模型理解，而背后的 merges.txt 则是“字典是怎么造出来的”规则书。理解这套逻辑，调参（比如词表大小）、处理未登录词（Out-of-Vocabulary）时就更清晰啦

`merges.txt`

在这里插入图片描述
merges.txt文件在基于字节对编码（Byte - Pair Encoding，BPE）的分词算法中起着关键作用，以下是对该merges.txt文件的详细解读：

1. 文件头信息

#version: 0.2
这是一个注释行，表明当前merges.txt文件的版本信息。注释行以#开头，在BPE算法执行过程中，解析器会忽略这些注释行。它主要用于记录和区分不同版本的合并规则文件，方便管理和追溯。

2. 合并规则解析

每一行代表一次合并操作，格式为token1 token2，表示将这两个相邻的token合并成一个新的token。以下举例说明：

Ġ t：
- Ġ是一个特殊的前缀符号，在很多基于BPE的分词系统中，用于表示词的开头。这一行规则表示将词开头符号Ġ和字符t合并。在实际应用中，可能会出现以t开头的单词，通过这样的合并，能够在分词时将词开头和首字符作为一个整体处理。例如，对于单词the，在后续的合并步骤中，结合其他规则可以将其正确分词。
r e：
- 将字符r和e合并，这可能用于处理如re开头的词缀（如return、rebuild等）或者一些常见的双字符组合。
o n：
- 合并字符o和n，on是常见的介词，通过此规则将其作为一个token处理。
e r：
- 合并字符e和r，这对于处理以er结尾的单词（如teacher、worker等）或者一些常见的双字符组合很有帮助。
a t：
- 合并字符a和at，at是常用的介词，通过此规则将其作为一个token。

3. BPE算法执行过程简述

在执行BPE算法时，初始状态下，文本会被拆分成最细粒度的单元，通常是字符或字节。然后，根据merges.txt中的合并规则，从频率最高的字符对（在训练过程中统计得出）开始，逐步进行合并操作。每次合并后，更新文本中的token表示，直到达到预设的词表大小或者没有可合并的token对为止。

4. 对分词和模型的影响

分词效果：通过这些合并规则，BPE分词算法能够生成更符合语言习惯和文本统计规律的词表。对于高频词，如the、and、in等，会被完整地作为一个token，减少了分词后的token数量，提高了模型对常见语言模式的捕捉能力。同时，对于一些不常见的单词或词缀，也能通过合并规则进行合理的切分和表示。
模型训练：在模型训练阶段，使用基于BPE分词后的token作为输入，模型能够学习到这些token之间的语义和语法关系。由于BPE词表的构建考虑了文本的统计特性，模型可以更高效地学习到语言的规律，提高训练效率和模型性能。在推理阶段，输入文本按照相同的BPE规则进行分词，然后输入到模型中进行处理，从而得到准确的预测结果。

总之，merges.txt文件中的合并规则是BPE分词算法的核心，它决定了词表的构建和文本的分词方式，对基于该分词算法的自然语言处理模型有着重要的影响。

`special_tokens_map.json`

{
   
   
  "bos_token": {
   
   
    "content": "<s>",
    "single_word": false,
    "lstrip": false,
    "rstrip": false,
    "normalized": true
  },
  "eos_token": {
   
   
    "content": "</s>",
    "single_word": false,
    "lstrip": false,
    "rstrip": false,
    "normalized": true
  },
  "unk_token": {
   
   
    "content": "<unk>",
    "single_word": false,
    "lstrip": false,
    "rstrip": false,
    "normalized": true
  },
  "sep_token": {
   
   
    "content": "</s&g