Hugging Face Transformers 中的 LightOnOcr轻量级端到端 OCR 与文档理解视觉语言模型全解析【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformersLightOnOcr是 Transformers 于 2026-01-14 合入的一个紧凑型端到端视觉语言模型VLM专为 OCR光学字符识别与文档理解设计它用基于 Pixtral 的 Vision Transformer 编码器提取版面感知的图像特征再交给一个由高质量开放 VLM 蒸馏而来的轻量 Qwen3 文本解码器生成结构化文本。本文基于官方模型文档 model_doc/lighton_ocr.md 与仓库源码完整覆盖其使用方式、配置结构、Processor 工作原理与模型前向流程并给出可运行示例与验证路径。1. 模型概览架构与定位官方文档给出的模型定位如下LightOnOcris a compact, end-to-end vision–language model for Optical Character Recognition (OCR) and document understanding. It achieves state-of-the-art accuracy in its weight class while being several times faster and cheaper than larger general-purpose VLMs.从源码结构看LightOnOcr 是一个典型的视觉编码器 多模态投影器 文本解码器三件套。模型定义文件 中LightOnOcrModel的构造函数清晰地展示了这一组合class LightOnOcrModel(LightOnOcrPreTrainedModel): def __init__(self, config: LightOnOcrConfig): super().__init__(config) self.vision_encoder AutoModel.from_config(config.vision_config) # Pixtral 视觉编码器 self.vision_projection LightOnOcrMultiModalProjector(config) # 多模态投影器 self.language_model AutoModel.from_config(config.text_config) # Qwen3 语言模型 self.post_init()三个关键组件与文档描述一一对应组件实现默认模型族说明vision_encoderPixtral 视觉编码器pixtral24 层 ViTpatch_size14hidden_size1024vision_projectionLightOnOcrMultiModalProjector—RMSNorm PatchMerger 两层线性映射GELU 激活language_modelQwen3 解码器qwen328 层GQA16 头 / 8 KV 头vocab_size151936模型通过model_type lighton_ocr注册可在 Auto 映射 中被AutoModel等自动类识别并映射到image-text-to-text管线见 测试中的 pipeline_model_mapping。2. 快速上手官方 Usage 示例以下是官方文档给出的完整用法核心路径是Processor.apply_chat_template→model.generate→processor.decode三步from transformers import LightOnOcrForConditionalGeneration, LightOnOcrProcessor # 加载模型与处理器官方模型卡权重lightonai/LightOnOCR-1B-1025 model LightOnOcrForConditionalGeneration.from_pretrained(lightonai/LightOnOCR-1025.replace(LightOnOCR, LightOnOCR), device_mapauto) model LightOnOcrForConditionalGeneration.from_pretrained(lightonai/LightOnOCR-1B-1025, device_mapauto) processor LightOnOcrProcessor.from_pretrained(lightonai/LightOnOCR-1B-1025) # 一张收据图片 URLSROIE 数据集样例 url https://huggingface.co/datasets/hf-internal-testing/fixtures_ocr/resolve/main/SROIE-receipt.jpeg # 以对话形式构造输入user 消息中只放图片 conversation [{role: user, content: [{type: image, url: url}]}] inputs processor.apply_chat_template( conversation, add_generation_promptTrue, tokenizeTrue, return_dictTrue, return_tensorspt, ).to(model.device) output_ids model.generate(**inputs, max_new_tokens1024) # 切掉 prompt 部分只保留新生成的 token generated_ids output_ids[0, inputs[input_ids].shape[1]:] output_text processor.decode(generated_ids, skip_special_tokensTrue) print(output_text)几点实操说明结合源码与测试确认输入张量键名Processor 输出的模型输入名为input_ids、attention_mask、pixel_values、image_sizes四件套模型输入名校验测试。其中image_sizes记录每张图缩放后的 (height, width)模型用它来切分每张图的视觉 token。生成参数官方集成测试 test_lightonocr_ocr_integration 使用max_new_tokens50, do_sampleFalse, num_beams1做贪心解码并把输出与期望文本做SequenceMatcher相似度比对要求 95%期望输出形如Document No : TD01167104\n\nDate : 25/12/2018 8:13:39 PM...——说明模型直接产出带换行、保留版式的纯文本。可纯文本生成test_model_can_generate_without_images 验证了不提供图片时model.generate(input_ids...)同样可用因此它本质上仍是一个可自回归的 LM。精度提示集成测试在加载后使用dtypetorch.bfloat16做前向文档示例未显式指定精度按 Hub 权重的 dtype 默认加载即可。3. LightOnOcrConfig配置结构与默认参数LightOnOcrConfig定义于 configuration_lighton_ocr.py是一个复合配置sub_configs {text_config: AutoConfig, vision_config: AutoConfig}顶层只保留少量共享字段字段默认值含义spatial_merge_size2空间合并倍数每2×24个视觉 patch 合并为 1 个图像 token图像 token 数降为 1/4image_token_id151655文本序列中标记图像占位符的 token idimgtie_word_embeddingsTruelm_head与embed_tokens共享权重vision_configNone自动补全为 pixtral视觉编码器配置text_configNone自动补全为 qwen3文本解码器配置__post_init__的逻辑值得注意当vision_config/text_config未提供时会自动实例化一套完整的默认配置源码 L70-L98这正是1B规格参数的来源视觉侧pixtralhidden_size1024、num_hidden_layers24、num_attention_heads16、head_dim64、patch_size14、rope_theta10000、hidden_actsilu文本侧qwen3hidden_size1024、num_hidden_layers28、num_attention_heads16、num_key_value_heads8GQA、head_dim128、intermediate_size3072、max_position_embeddings40960、rope_theta1000000、vocab_size151936。如果你要基于该模型微调或自定义尺寸只需传入一个text_config/vision_config字典会按model_type自动映射到对应 Config 类例如测试中就用小尺寸配置快速构建模型测试配置示例。文档中[[autodoc]]引用的完整 API 面为LightOnOcrConfig、LightOnOcrProcessor含__call__、LightOnOcrModel含forward、get_image_features、LightOnOcrForConditionalGeneration含forward、get_image_features全部由 modular_lighton_ocr.py 生成configuration_lighton_ocr.py等文件头部的注释表明 CI 会强制 modular 与生成文件保持一致。4. LightOnOcrProcessor图像 token 的展开机制这是 LightOnOcr 使用中最容易踩坑的部分——一张图在文本序列里到底占多少个 token。答案在 processing_lighton_ocr.py 中def __init__(self, image_processorNone, tokenizerNone, patch_size: int 14, spatial_merge_size: int 2, ...): self.patch_size patch_size self.spatial_merge_size spatial_merge_size # 有效 patch 尺寸 14 × 2 28 self.effective_patch_size patch_size * spatial_merge_size # 特殊 token 直接取自 tokenizer 属性 self.image_token tokenizer.image_token # img self.image_break_token tokenizer.image_break_token # im_start self.image_end_token tokenizer.image_end_token # im_end有效 patch 为 28×28视觉编码器的patch_size14与spatial_merge_size2相乘得到每个图像 token 对应原图 28×28 像素区域。token 展开规则replace_image_tokenL132-L136把单张图的占位符替换为num_height_tokens × num_width_tokens个imgtoken其中num_*_tokens 图像尺寸 // effective_patch_size。例如一张 112×112 的图会产生(112/28)² 16个图像 token——这与 测试中的 token 计数推导num_patches // spatial_merge_size**2完全一致。缩放对齐_get_num_multimodal_tokensL138-L174在预计算占位 token 数时复用 Pixtral 的get_resize_output_image_size先按size[longest_edge]等比缩小再把边长向下取整到 patch 的整数倍最后除以effective_patch_size得到 token 数。这保证了处理器算出的占位 token 数与视觉编码器实际输出的特征数严格相等。默认参数LightOnOcrProcessorKwargs._defaults规定文本侧paddingFalse、输出默认return_tensorspt。特殊 token 的具体取值img/im_start/im_end由 测试 明确断言。验证test_processor_image_token_expansion验证了单图场景下imgtoken 会被展开为多个1test_processor_batch_processing验证了批量多图输入下pixel_values与input_ids的 batch 维度对齐。5. LightOnOcrModel 前向流程视觉特征如何注入文本序列LightOnOcrModel.forwardmodeling_lighton_ocr.py L211-L254的流程可以分为四步第一步文本嵌入。input_ids通过get_input_embeddings()转为inputs_embeds若调用方直接传了inputs_embeds则跳过二者必须恰好给一个否则抛ValueError。第二步提取并投影图像特征。若pixel_values非空调用get_image_featuresL168-L183def get_image_features(self, pixel_values, image_sizes, **kwargs): image_outputs self.vision_encoder(pixel_values, image_sizesimage_sizes, return_dictTrue) image_features image_outputs.last_hidden_state image_features self.vision_projection(image_features.squeeze(0), image_sizes) # 按有效 patch 尺寸把特征切回每张图一段 downsample_ratio self.config.vision_config.patch_size * self.config.spatial_merge_size split_sizes [(h // downsample_ratio) * (w // downsample_ratio) for h, w in image_sizes] image_features torch.split(image_features, split_sizes) image_outputs.pooler_output image_features return image_outputs投影器LightOnOcrMultiModalProjectorL97-L113内部为RMSNorm(vision_hidden)→PatchMerger用unfold做 2×2 空间合并后接一个无偏置线性层把4×hidden压回hidden→Linear(1024→1024, biasFalse)→GELU→Linear(1024→1024, biasFalse)。最终pooler_output是一个list每个元素是一张图的 token 特征shape 为[num_tokens_of_image_i, text_hidden_size]。第三步占位符对齐校验。get_placeholder_maskL185-L207统计input_ids中等于image_token_id默认 151655的位置数并与图像特征总数比对不一致时抛出Image features and image tokens do not match, tokens: {n_image_tokens}, features: {n_image_features}对应的测试test_mismatching_num_image_tokens专门验证了三种情形少给一张图报错、一条 prompt 里两张图但只给一个图像特征报错、两张图配两段文本正常通过——即同一 prompt 可以包含多张图。第四步masked_scatter注入。把图像特征cat成一维后通过inputs_embeds.masked_scatter(special_image_mask, image_features)原样填入所有img位置然后整个嵌入序列送入language_model输出LightOnOcrModelOutputWithPast额外携带image_hidden_states字段见 输出 dataclass。6. LightOnOcrForConditionalGeneration生成头与权重绑定生成模型类 在LightOnOcrModel之上只加了 lm_head 与GenerationMixinclass LightOnOcrForConditionalGeneration(LightOnOcrPreTrainedModel, GenerationMixin): _tied_weights_keys {lm_head.weight: model.language_model.embed_tokens.weight} def __init__(self, config): super().__init__(config) self.model LightOnOcrModel(config) self.lm_head nn.Linear(config.text_config.hidden_size, config.text_config.vocab_size, biasFalse) self.post_init()要点lm_head为无偏置线性层输出维度vocab_size151936由于tie_word_embeddingsTrue它默认与embed_tokens共享权重因此1B级权重非常紧凑。forward支持labels用self.loss_function计算 next-token 预测 loss可用于微调/SFT、logits_to_keep只计算末尾部分位置的 logits 以省显存等标准参数签名见 forward 定义。基类 LightOnOcrPreTrainedModel 声明了能力位input_modalities (image, text)、supports_gradient_checkpointing True、_supports_flash_attn / _supports_sdpa True、_can_compile_fullgraph True——即支持 FlashAttention-2 与 SDPA 注意力后端、梯度检查点以及torch.compile全图编译。一个值得留意的实现细节测试文件注释指出 LightOnOcr uses a PixtralVisionModel, which merges batch_size and num_patches in index 1, with index 0 hardcoded to 1因此该测试类跳过了图像特征输出 shape 的通用断言skip_test_image_features_output_shape True并因多模态占位 mask 依赖数据而关闭了 torch.export测试 L228-L232。7. 测试与验证路径关注点测试说明OCR 端到端效果test_lightonocr_ocr_integration用 Hub 上的lightonai/LightOnOCR-1B-1025 SROIE 收据图贪心解码 50 token与期望文本做 95% 相似度断言图像/文本 token 数不一致test_mismatching_num_image_tokens覆盖单图缺失、多图缺特征、多图匹配三种情况不同 spatial_merge_sizetest_spatial_merge_size1/2/4 均可构建模型投影器参数随之变化变尺寸图像test_forward_pass_with_image_sizes同 batch 内不同图像尺寸的前向投影器维度test_vision_projection输出最后一维等于text_config.hidden_sizeProcessor 行为test_processing_lighton_ocr.pytoken 展开、batch 处理、特殊 token、image_sizes输出等运行方式transformers的模型测试均为标准 pytest/unittest 套件集成测试标记slow需要联网拉取 Hub 权重快测如LightOnOcrForConditionalGenerationModelTest则用随机初始化的迷你配置本地跑通。8. 小结与适用边界适用场景文档/票据/扫描件类页面的结构化文本抽取版式感知的 OCR以及需要低成本多模态理解的其他图像问答任务从源码结构看它也保留了纯文本自回归能力。关键约束输入图像会被缩放到longest_edge以内并对齐到 28 的整数倍超长页面的 token 数会随分辨率增长max_new_tokens需要按页面长度调大官方示例取 1024处理器展开的imgtoken 数必须与视觉特征数严格一致手动构造输入时务必带上image_sizes且不要改动占位 token 数量否则触发 Image features and image tokens do not match官方示例使用apply_chat_template的对话式输入格式[{role: user, content: [{type: image, url: ...}]}]图片 URL 或本地 PIL 图均可。代码入口索引配置 configuration_lighton_ocr.py、建模 modeling_lighton_ocr.py、处理器 processing_lighton_ocr.py、modular 源 modular_lighton_ocr.py、测试 tests/models/lighton_ocr/。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hugging Face Transformers 中的 LightOnOcr：轻量级端到端 OCR 与文档理解视觉语言模型全解析
Hugging Face Transformers 中的 LightOnOcr轻量级端到端 OCR 与文档理解视觉语言模型全解析【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformersLightOnOcr是 Transformers 于 2026-01-14 合入的一个紧凑型端到端视觉语言模型VLM专为 OCR光学字符识别与文档理解设计它用基于 Pixtral 的 Vision Transformer 编码器提取版面感知的图像特征再交给一个由高质量开放 VLM 蒸馏而来的轻量 Qwen3 文本解码器生成结构化文本。本文基于官方模型文档 model_doc/lighton_ocr.md 与仓库源码完整覆盖其使用方式、配置结构、Processor 工作原理与模型前向流程并给出可运行示例与验证路径。1. 模型概览架构与定位官方文档给出的模型定位如下LightOnOcris a compact, end-to-end vision–language model for Optical Character Recognition (OCR) and document understanding. It achieves state-of-the-art accuracy in its weight class while being several times faster and cheaper than larger general-purpose VLMs.从源码结构看LightOnOcr 是一个典型的视觉编码器 多模态投影器 文本解码器三件套。模型定义文件 中LightOnOcrModel的构造函数清晰地展示了这一组合class LightOnOcrModel(LightOnOcrPreTrainedModel): def __init__(self, config: LightOnOcrConfig): super().__init__(config) self.vision_encoder AutoModel.from_config(config.vision_config) # Pixtral 视觉编码器 self.vision_projection LightOnOcrMultiModalProjector(config) # 多模态投影器 self.language_model AutoModel.from_config(config.text_config) # Qwen3 语言模型 self.post_init()三个关键组件与文档描述一一对应组件实现默认模型族说明vision_encoderPixtral 视觉编码器pixtral24 层 ViTpatch_size14hidden_size1024vision_projectionLightOnOcrMultiModalProjector—RMSNorm PatchMerger 两层线性映射GELU 激活language_modelQwen3 解码器qwen328 层GQA16 头 / 8 KV 头vocab_size151936模型通过model_type lighton_ocr注册可在 Auto 映射 中被AutoModel等自动类识别并映射到image-text-to-text管线见 测试中的 pipeline_model_mapping。2. 快速上手官方 Usage 示例以下是官方文档给出的完整用法核心路径是Processor.apply_chat_template→model.generate→processor.decode三步from transformers import LightOnOcrForConditionalGeneration, LightOnOcrProcessor # 加载模型与处理器官方模型卡权重lightonai/LightOnOCR-1B-1025 model LightOnOcrForConditionalGeneration.from_pretrained(lightonai/LightOnOCR-1025.replace(LightOnOCR, LightOnOCR), device_mapauto) model LightOnOcrForConditionalGeneration.from_pretrained(lightonai/LightOnOCR-1B-1025, device_mapauto) processor LightOnOcrProcessor.from_pretrained(lightonai/LightOnOCR-1B-1025) # 一张收据图片 URLSROIE 数据集样例 url https://huggingface.co/datasets/hf-internal-testing/fixtures_ocr/resolve/main/SROIE-receipt.jpeg # 以对话形式构造输入user 消息中只放图片 conversation [{role: user, content: [{type: image, url: url}]}] inputs processor.apply_chat_template( conversation, add_generation_promptTrue, tokenizeTrue, return_dictTrue, return_tensorspt, ).to(model.device) output_ids model.generate(**inputs, max_new_tokens1024) # 切掉 prompt 部分只保留新生成的 token generated_ids output_ids[0, inputs[input_ids].shape[1]:] output_text processor.decode(generated_ids, skip_special_tokensTrue) print(output_text)几点实操说明结合源码与测试确认输入张量键名Processor 输出的模型输入名为input_ids、attention_mask、pixel_values、image_sizes四件套模型输入名校验测试。其中image_sizes记录每张图缩放后的 (height, width)模型用它来切分每张图的视觉 token。生成参数官方集成测试 test_lightonocr_ocr_integration 使用max_new_tokens50, do_sampleFalse, num_beams1做贪心解码并把输出与期望文本做SequenceMatcher相似度比对要求 95%期望输出形如Document No : TD01167104\n\nDate : 25/12/2018 8:13:39 PM...——说明模型直接产出带换行、保留版式的纯文本。可纯文本生成test_model_can_generate_without_images 验证了不提供图片时model.generate(input_ids...)同样可用因此它本质上仍是一个可自回归的 LM。精度提示集成测试在加载后使用dtypetorch.bfloat16做前向文档示例未显式指定精度按 Hub 权重的 dtype 默认加载即可。3. LightOnOcrConfig配置结构与默认参数LightOnOcrConfig定义于 configuration_lighton_ocr.py是一个复合配置sub_configs {text_config: AutoConfig, vision_config: AutoConfig}顶层只保留少量共享字段字段默认值含义spatial_merge_size2空间合并倍数每2×24个视觉 patch 合并为 1 个图像 token图像 token 数降为 1/4image_token_id151655文本序列中标记图像占位符的 token idimgtie_word_embeddingsTruelm_head与embed_tokens共享权重vision_configNone自动补全为 pixtral视觉编码器配置text_configNone自动补全为 qwen3文本解码器配置__post_init__的逻辑值得注意当vision_config/text_config未提供时会自动实例化一套完整的默认配置源码 L70-L98这正是1B规格参数的来源视觉侧pixtralhidden_size1024、num_hidden_layers24、num_attention_heads16、head_dim64、patch_size14、rope_theta10000、hidden_actsilu文本侧qwen3hidden_size1024、num_hidden_layers28、num_attention_heads16、num_key_value_heads8GQA、head_dim128、intermediate_size3072、max_position_embeddings40960、rope_theta1000000、vocab_size151936。如果你要基于该模型微调或自定义尺寸只需传入一个text_config/vision_config字典会按model_type自动映射到对应 Config 类例如测试中就用小尺寸配置快速构建模型测试配置示例。文档中[[autodoc]]引用的完整 API 面为LightOnOcrConfig、LightOnOcrProcessor含__call__、LightOnOcrModel含forward、get_image_features、LightOnOcrForConditionalGeneration含forward、get_image_features全部由 modular_lighton_ocr.py 生成configuration_lighton_ocr.py等文件头部的注释表明 CI 会强制 modular 与生成文件保持一致。4. LightOnOcrProcessor图像 token 的展开机制这是 LightOnOcr 使用中最容易踩坑的部分——一张图在文本序列里到底占多少个 token。答案在 processing_lighton_ocr.py 中def __init__(self, image_processorNone, tokenizerNone, patch_size: int 14, spatial_merge_size: int 2, ...): self.patch_size patch_size self.spatial_merge_size spatial_merge_size # 有效 patch 尺寸 14 × 2 28 self.effective_patch_size patch_size * spatial_merge_size # 特殊 token 直接取自 tokenizer 属性 self.image_token tokenizer.image_token # img self.image_break_token tokenizer.image_break_token # im_start self.image_end_token tokenizer.image_end_token # im_end有效 patch 为 28×28视觉编码器的patch_size14与spatial_merge_size2相乘得到每个图像 token 对应原图 28×28 像素区域。token 展开规则replace_image_tokenL132-L136把单张图的占位符替换为num_height_tokens × num_width_tokens个imgtoken其中num_*_tokens 图像尺寸 // effective_patch_size。例如一张 112×112 的图会产生(112/28)² 16个图像 token——这与 测试中的 token 计数推导num_patches // spatial_merge_size**2完全一致。缩放对齐_get_num_multimodal_tokensL138-L174在预计算占位 token 数时复用 Pixtral 的get_resize_output_image_size先按size[longest_edge]等比缩小再把边长向下取整到 patch 的整数倍最后除以effective_patch_size得到 token 数。这保证了处理器算出的占位 token 数与视觉编码器实际输出的特征数严格相等。默认参数LightOnOcrProcessorKwargs._defaults规定文本侧paddingFalse、输出默认return_tensorspt。特殊 token 的具体取值img/im_start/im_end由 测试 明确断言。验证test_processor_image_token_expansion验证了单图场景下imgtoken 会被展开为多个1test_processor_batch_processing验证了批量多图输入下pixel_values与input_ids的 batch 维度对齐。5. LightOnOcrModel 前向流程视觉特征如何注入文本序列LightOnOcrModel.forwardmodeling_lighton_ocr.py L211-L254的流程可以分为四步第一步文本嵌入。input_ids通过get_input_embeddings()转为inputs_embeds若调用方直接传了inputs_embeds则跳过二者必须恰好给一个否则抛ValueError。第二步提取并投影图像特征。若pixel_values非空调用get_image_featuresL168-L183def get_image_features(self, pixel_values, image_sizes, **kwargs): image_outputs self.vision_encoder(pixel_values, image_sizesimage_sizes, return_dictTrue) image_features image_outputs.last_hidden_state image_features self.vision_projection(image_features.squeeze(0), image_sizes) # 按有效 patch 尺寸把特征切回每张图一段 downsample_ratio self.config.vision_config.patch_size * self.config.spatial_merge_size split_sizes [(h // downsample_ratio) * (w // downsample_ratio) for h, w in image_sizes] image_features torch.split(image_features, split_sizes) image_outputs.pooler_output image_features return image_outputs投影器LightOnOcrMultiModalProjectorL97-L113内部为RMSNorm(vision_hidden)→PatchMerger用unfold做 2×2 空间合并后接一个无偏置线性层把4×hidden压回hidden→Linear(1024→1024, biasFalse)→GELU→Linear(1024→1024, biasFalse)。最终pooler_output是一个list每个元素是一张图的 token 特征shape 为[num_tokens_of_image_i, text_hidden_size]。第三步占位符对齐校验。get_placeholder_maskL185-L207统计input_ids中等于image_token_id默认 151655的位置数并与图像特征总数比对不一致时抛出Image features and image tokens do not match, tokens: {n_image_tokens}, features: {n_image_features}对应的测试test_mismatching_num_image_tokens专门验证了三种情形少给一张图报错、一条 prompt 里两张图但只给一个图像特征报错、两张图配两段文本正常通过——即同一 prompt 可以包含多张图。第四步masked_scatter注入。把图像特征cat成一维后通过inputs_embeds.masked_scatter(special_image_mask, image_features)原样填入所有img位置然后整个嵌入序列送入language_model输出LightOnOcrModelOutputWithPast额外携带image_hidden_states字段见 输出 dataclass。6. LightOnOcrForConditionalGeneration生成头与权重绑定生成模型类 在LightOnOcrModel之上只加了 lm_head 与GenerationMixinclass LightOnOcrForConditionalGeneration(LightOnOcrPreTrainedModel, GenerationMixin): _tied_weights_keys {lm_head.weight: model.language_model.embed_tokens.weight} def __init__(self, config): super().__init__(config) self.model LightOnOcrModel(config) self.lm_head nn.Linear(config.text_config.hidden_size, config.text_config.vocab_size, biasFalse) self.post_init()要点lm_head为无偏置线性层输出维度vocab_size151936由于tie_word_embeddingsTrue它默认与embed_tokens共享权重因此1B级权重非常紧凑。forward支持labels用self.loss_function计算 next-token 预测 loss可用于微调/SFT、logits_to_keep只计算末尾部分位置的 logits 以省显存等标准参数签名见 forward 定义。基类 LightOnOcrPreTrainedModel 声明了能力位input_modalities (image, text)、supports_gradient_checkpointing True、_supports_flash_attn / _supports_sdpa True、_can_compile_fullgraph True——即支持 FlashAttention-2 与 SDPA 注意力后端、梯度检查点以及torch.compile全图编译。一个值得留意的实现细节测试文件注释指出 LightOnOcr uses a PixtralVisionModel, which merges batch_size and num_patches in index 1, with index 0 hardcoded to 1因此该测试类跳过了图像特征输出 shape 的通用断言skip_test_image_features_output_shape True并因多模态占位 mask 依赖数据而关闭了 torch.export测试 L228-L232。7. 测试与验证路径关注点测试说明OCR 端到端效果test_lightonocr_ocr_integration用 Hub 上的lightonai/LightOnOCR-1B-1025 SROIE 收据图贪心解码 50 token与期望文本做 95% 相似度断言图像/文本 token 数不一致test_mismatching_num_image_tokens覆盖单图缺失、多图缺特征、多图匹配三种情况不同 spatial_merge_sizetest_spatial_merge_size1/2/4 均可构建模型投影器参数随之变化变尺寸图像test_forward_pass_with_image_sizes同 batch 内不同图像尺寸的前向投影器维度test_vision_projection输出最后一维等于text_config.hidden_sizeProcessor 行为test_processing_lighton_ocr.pytoken 展开、batch 处理、特殊 token、image_sizes输出等运行方式transformers的模型测试均为标准 pytest/unittest 套件集成测试标记slow需要联网拉取 Hub 权重快测如LightOnOcrForConditionalGenerationModelTest则用随机初始化的迷你配置本地跑通。8. 小结与适用边界适用场景文档/票据/扫描件类页面的结构化文本抽取版式感知的 OCR以及需要低成本多模态理解的其他图像问答任务从源码结构看它也保留了纯文本自回归能力。关键约束输入图像会被缩放到longest_edge以内并对齐到 28 的整数倍超长页面的 token 数会随分辨率增长max_new_tokens需要按页面长度调大官方示例取 1024处理器展开的imgtoken 数必须与视觉特征数严格一致手动构造输入时务必带上image_sizes且不要改动占位 token 数量否则触发 Image features and image tokens do not match官方示例使用apply_chat_template的对话式输入格式[{role: user, content: [{type: image, url: ...}]}]图片 URL 或本地 PIL 图均可。代码入口索引配置 configuration_lighton_ocr.py、建模 modeling_lighton_ocr.py、处理器 processing_lighton_ocr.py、modular 源 modular_lighton_ocr.py、测试 tests/models/lighton_ocr/。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考