如何用自有数据微调 Surya OCR 定制模型从判断到落地的完整实战指南【免费下载链接】suryaOCR, layout analysis, reading order, table recognition in 90 languages项目地址: https://gitcode.com/GitHub_Trending/su/suryaSurya 是一个覆盖 90 语言、支持 OCR、版面分析、阅读顺序与表格识别的文档理解工具链本文基于 Surya OCR用你自己的文档数据微调一个自定义模型并把它接回现有推理管线。先说一个真实会遇到的翻车现场把一批税务表格和医疗报告丢给通用 OCR纯数字字段里0/O、1/l混读摊销、门诊这类行业词错成同音字生僻药名直接整词丢行同一批页面换成普通印刷文本又几乎全对。问题的根源不是模型不行而是通用预训练模型没见过你的版式与词表——这类错误集中在特定字体与领域术语上靠提示词和分辨率调参救不回来需要用自己的数据做一次微调。下面的内容按先判断、再投入的顺序展开每一步都尽量给你可直接复制的最小命令。先判断再投入哪些文档值得微调结论错误集中在少数字符集、领域术语或特殊版式时微调收益明显目标语言在官方 91 语种清单内且版式属于通用类型报纸、教科书、公文、表单时预训练模型通常够用。Surya 官方多语言基准整体通过率 87.2%其中 38 个语种超过 90%完整 91 语种对照表在 static/docs/multilingual.md。如果你的文档落在这些高分区里先别急着训练。判断标准可以很简单随机抽 10 页真实数据跑一遍预训练模型人工统计每页字符级错误率——错误率持续低于 3%~5% 就直接用现成的错误率高且集中在固定模式某类符号、某套字体、某个业务的专有名词再走微调路线。用 10 页自有数据跑冒烟测试安装环境只需要三步依赖版本约束都在 pyproject.toml 里uv sync会一次性解析好避免手工装包踩版本冲突git clone https://gitcode.com/GitHub_Trending/su/surya cd surya uv sync --group dev然后拿你的真实文档跑一次全页 OCRuv run surya_ocr /path/to/sample_docs/ --images --output_dir results--images会把带标注框的页面图一并存下来肉眼比对 3 页最差的输出就能得到两个信息错在哪识别错 / 检测漏 / 阅读顺序错以及值不值得为它训练。这一步几乎零成本但能帮你省掉后面所有不必要的投入。上图这类手写笔记属于预训练模型已经覆盖的场景而你的私有版式、内部术语才是微调该发力的地方。数据工程标注格式先定对结论训练样本的目标文本必须和模型推理时实际收到的提示词prompt严格一致否则训练出来的模型接回管线会说不通。Surya 的 OCR/版面/表格能力由同一个视觉语言模型约 650M 参数承担靠不同的 prompt 输出不同格式版面识别输出 JSON全页 OCR 输出 HTML公式包在math里、表格包在table里。提示词模板集中在 surya/inference/prompts.py做标注时先把它读一遍。标注格式怎么定目标文本跟着 prompt 走每条样本是一个 chat 对话用户侧是图像 任务 prompt助手侧是人工确认过的目标输出。落成 JSONL每页一条{ messages: [ {role: user, content: image\n全页OCR提示词与prompts.py保持一致}, {role: assistant, content: 目标输出全页HTML公式用math包裹} ], images: [train/page_0001.png] }标注规范建议写进团队文档至少包含三条文本按页内阅读顺序排列数字、日期、编号逐字符核对这是微调收益最大的一类字段拿不准的目标文本标出来双人复核而不是猜一个填上——错误标注会被模型当成事实学走比噪声更危险。私有数据怎么转成训练 JSONLPDF 用仓库已有的依赖pypdfium2渲染成图片即可渲染分辨率对齐推理侧的设置识别与表格识别默认 192 DPIsurya/settings.py 里的IMAGE_DPI_HIGHRES训练图和推理图分辨率差太多会让模型不适应。转换脚本本身没有技术含量关键是保证三件事文件名与 JSONL 中images字段一一对应按 8:2 随机划分训练/验证集且同一文档的页面不跨集防止页与页之间信息泄漏验证集只做评估、不参与任何处理。数据增强取舍何时开、验证集怎么留增强的取舍可以这样定数据少于 2000 页时开轻度增强小幅旋转、亮度抖动、轻度模糊模拟扫描质量波动数据量充足时优先保证真实分布少做增强因为你的真实文档长什么样比看起来更多样重要。无论哪种情况验证集一律不加增强——它是你模拟上线后真实输入的唯一标尺被增强污染了就失去评估资格。表单是典型的微调场景字段固定、数字密集、版式重复几百页标注数据通常就能把数字字段错误率压下去。一次跑通的训练配置完整命令与逐项解释结论仓库本身不附带现成的微调入口脚本官方建议需要微调支持时联系维护方见 README.md 的 Training 一节联系方式 hidatalab.to自建路线则用任意支持 VLM SFT 的训练框架按下面这套配置先跑通再调优。以 LLaMA-Factory 为例ms-swift、verl 等框架同理概念一一对应第一次跑通用这套保守配置llamafactory-cli train \ --stage sft \ --model_name_or_path /path/to/surya_base_vlm \ --dataset ocr_finetune \ --finetuning_type lora \ --lora_rank 32 \ --per_device_train_batch_size 1 \ --gradient_accumulation_steps 8 \ --learning_rate 1e-4 \ --max_steps 2000逐项解释为什么这么设sft阶段是监督微调不需要强化学习那一套LoRA低秩适配只训练少量旁路权重而非全部参数把显存需求压到单卡可承受范围且 32 的秩对文档域微调已经足够batch size 设为 1 加梯度累积 8 步等效批量 8这是显存不够还能稳定训练的标准做法学习率 1e-4 是 LoRA 微调的常用量级全参数微调时应降到 1e-5 左右max_steps 2000先给一个明确终点避免不知道要跑多久。显存不够怎么调 batch顺序是batch 降到 1 → 开梯度累积等效批量不变→ 降低图像输入分辨率192 DPI 改 96 DPI像素量降约 75%但注意识别精度会随之下降建议只用于中间试验→ 仍不够就上多卡或 LoRA 降秩。判断显存是否够用看两个信号loss 前 50 步应明显下降若前 100 步内 loss 几乎不动多半是批量等效太小或学习率不对先查配置再怀疑数据。多语言混合数据怎么办按语言分层抽样别让高频语言把样本池占满给每个目标语言单独统计验证集错误率低于整体均值最多的那个语言再补数据而不是按总量平均加。验证各语言表现可对照官方 static/docs/multilingual.md 的 91 语种表格先看预训练模型在你目标语言上的基线——基线 90% 以上的语言基本不用额外投数据。单页文字太多怎么办全页 OCR 的输出 token 预算默认 12288settings 里的SURYA_MAX_TOKENS_FULL_PAGE。如果你的文档单页文本超过这个量级训练时把序列长度上限放宽推理侧同步调整否则长页会被截断SURYA_MAX_TOKENS_FULL_PAGE16384 VLLM_MAX_MODEL_LEN24576 \ uv run surya_ocr long_doc.pdf把训练好的 checkpoint 指回现有管线微调产出的模型必须能说 Surya 的提示词方言输出 layout JSON / 全页 HTML这样接回管线不需要改任何代码——只需把 surya/settings.py 里的SURYA_MODEL_CHECKPOINT指到你本地目录SURYA_MODEL_CHECKPOINT/path/to/custom_ocr uv run surya_ocr doc.png推理后端GPU 用 vllm、CPU/Apple Silicon 用 llama.cpp会自动探测并拉起服务这一步和用官方模型完全一致。用结果说话基准指标与可视化对比结论评估先看四个数——文本相似度、框级 IoU、阅读顺序正确率、单页耗时四个里任何一个明显劣于预训练基线都要回头查对应环节。基准测试该看哪四个指标文本相似度 / 编辑距离对验证集每页的识别文本与标注文本算归一化 Levenshtein 距离越低越好这是识别准不准的核心指标官方 olmOCR-bench 也是同一思路。框级 IoU检测框与标注框的交并比均值反映找没找对位置。IoU 差而相似度高说明漏检或错并行。阅读顺序正确率块序列与标注顺序一致的比例多栏版面报纸、双栏报告重点看它。单页耗时微调后不应明显变慢如果变慢多半是 checkpoint 没合并或量化没做。上表是官方给出的模型规模-分数对照你的自定义模型评估时基线一列填官方预训练模型在同验证集上的成绩两列并排才看得出微调的净收益。识别结果怎么可视化对比用仓库自带的绘制工具把识别块画回页面预训练 vs 微调各存一张并排看from PIL import Image from surya.debug.draw import draw_polys_on_image img Image.open(page.png).convert(RGB) page rec([img])[0] out draw_polys_on_image( [b.polygon for b in page.blocks], img, labels[b.label for b in page.blocks]) out.save(annotated.png)draw_polys_on_image定义在 surya/debug/draw.pyblocks的字段结构label、polygon、html、confidence见 surya/recognition/schema.py。对比时重点看之前错的那几类字段数字是否还混读、专有名词是否还丢行。定制模型怎么接入应用CLI 一条命令即可批量出结果--images附带可视化results.json为最终输出SURYA_MODEL_CHECKPOINT/path/to/custom_ocr \ uv run surya_ocr ./docs/ --images --output_dir resultsPython 侧则是标准的预测器写法SuryaInferenceManager负责拉起后端进程内构造一次即可from PIL import Image from surya.inference import SuryaInferenceManager from surya.recognition import RecognitionPredictor rec RecognitionPredictor(SuryaInferenceManager()) blocks rec([Image.open(doc.png)])[0].blocks print(blocks[0].html, blocks[0].confidence)三条可选进阶路线按需自选以下三条都不是必做对应三种不同的后续诉求对号入座即可。多任务联合训练如果你的痛点同时包含识别和版面例如表格区域漏检导致整块丢失就把版面 JSON 样本和全页 HTML 样本混进同一个 SFT 数据集。Surya 的训练输出本来就是这两类layout JSON / full-page HTML见 README.md Training 一节的描述混合比例从 5:5 起步按两类指标各自的退化方向微调。知识蒸馏与量化部署目标是边缘设备或小显存服务器时先量化再谈别的仓库自带 surya/scripts/build_gguf.py 可以把模型转成 llama.cpp 能直接加载的 GGUF 格式CPU 和 Apple Silicon 上都能跑llama.cpp 后端在 surya/inference/backends/llamacpp.py。想要更聪明的小模型可以让一个更大的 VLM 对你验证不了的难样本批量生成标注人工抽检后并入训练集——这比堆算力更实际。增量学习新业务上线新增一种文档类型时从已有自定义 checkpoint 继续 SFT而不是从基座重训学习率降到 1e-5 量级、LoRA 只挂语言侧参数视觉编码器保持冻结小数据量几百页下 200~500 步即可收敛原有能力回退最小。下一步微调只是把识别这一段做对完整的文档数字化链路还包括版面与表格surya_layout和surya_table命令、以及 surya/scripts/ 下的命令行入口都值得逐个跑一遍确认你的管线里每一环都达标。更多细节看 README.md 的 Usage 与 Benchmarks 章节多语言完整表格在 static/docs/multilingual.md回归测试在 tests/ 下改动管线前后跑一遍能兜住意外。需要微调支持或托管训练时README 的 Training 一节留有官方联系方式hidatalab.to贡献与许可相关问题见 CLA.md。【免费下载链接】suryaOCR, layout analysis, reading order, table recognition in 90 languages项目地址: https://gitcode.com/GitHub_Trending/su/surya创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何用自有数据微调 Surya OCR 定制模型从判断到落地的完整实战指南【免费下载链接】suryaOCR, layout analysis, reading order, table recognition in 90 languages项目地址: https://gitcode.com/GitHub_Trending/su/suryaSurya 是一个覆盖 90 语言、支持 OCR、版面分析、阅读顺序与表格识别的文档理解工具链本文基于 Surya OCR用你自己的文档数据微调一个自定义模型并把它接回现有推理管线。先说一个真实会遇到的翻车现场把一批税务表格和医疗报告丢给通用 OCR纯数字字段里0/O、1/l混读摊销、门诊这类行业词错成同音字生僻药名直接整词丢行同一批页面换成普通印刷文本又几乎全对。问题的根源不是模型不行而是通用预训练模型没见过你的版式与词表——这类错误集中在特定字体与领域术语上靠提示词和分辨率调参救不回来需要用自己的数据做一次微调。下面的内容按先判断、再投入的顺序展开每一步都尽量给你可直接复制的最小命令。先判断再投入哪些文档值得微调结论错误集中在少数字符集、领域术语或特殊版式时微调收益明显目标语言在官方 91 语种清单内且版式属于通用类型报纸、教科书、公文、表单时预训练模型通常够用。Surya 官方多语言基准整体通过率 87.2%其中 38 个语种超过 90%完整 91 语种对照表在 static/docs/multilingual.md。如果你的文档落在这些高分区里先别急着训练。判断标准可以很简单随机抽 10 页真实数据跑一遍预训练模型人工统计每页字符级错误率——错误率持续低于 3%~5% 就直接用现成的错误率高且集中在固定模式某类符号、某套字体、某个业务的专有名词再走微调路线。用 10 页自有数据跑冒烟测试安装环境只需要三步依赖版本约束都在 pyproject.toml 里uv sync会一次性解析好避免手工装包踩版本冲突git clone https://gitcode.com/GitHub_Trending/su/surya cd surya uv sync --group dev然后拿你的真实文档跑一次全页 OCRuv run surya_ocr /path/to/sample_docs/ --images --output_dir results--images会把带标注框的页面图一并存下来肉眼比对 3 页最差的输出就能得到两个信息错在哪识别错 / 检测漏 / 阅读顺序错以及值不值得为它训练。这一步几乎零成本但能帮你省掉后面所有不必要的投入。上图这类手写笔记属于预训练模型已经覆盖的场景而你的私有版式、内部术语才是微调该发力的地方。数据工程标注格式先定对结论训练样本的目标文本必须和模型推理时实际收到的提示词prompt严格一致否则训练出来的模型接回管线会说不通。Surya 的 OCR/版面/表格能力由同一个视觉语言模型约 650M 参数承担靠不同的 prompt 输出不同格式版面识别输出 JSON全页 OCR 输出 HTML公式包在math里、表格包在table里。提示词模板集中在 surya/inference/prompts.py做标注时先把它读一遍。标注格式怎么定目标文本跟着 prompt 走每条样本是一个 chat 对话用户侧是图像 任务 prompt助手侧是人工确认过的目标输出。落成 JSONL每页一条{ messages: [ {role: user, content: image\n全页OCR提示词与prompts.py保持一致}, {role: assistant, content: 目标输出全页HTML公式用math包裹} ], images: [train/page_0001.png] }标注规范建议写进团队文档至少包含三条文本按页内阅读顺序排列数字、日期、编号逐字符核对这是微调收益最大的一类字段拿不准的目标文本标出来双人复核而不是猜一个填上——错误标注会被模型当成事实学走比噪声更危险。私有数据怎么转成训练 JSONLPDF 用仓库已有的依赖pypdfium2渲染成图片即可渲染分辨率对齐推理侧的设置识别与表格识别默认 192 DPIsurya/settings.py 里的IMAGE_DPI_HIGHRES训练图和推理图分辨率差太多会让模型不适应。转换脚本本身没有技术含量关键是保证三件事文件名与 JSONL 中images字段一一对应按 8:2 随机划分训练/验证集且同一文档的页面不跨集防止页与页之间信息泄漏验证集只做评估、不参与任何处理。数据增强取舍何时开、验证集怎么留增强的取舍可以这样定数据少于 2000 页时开轻度增强小幅旋转、亮度抖动、轻度模糊模拟扫描质量波动数据量充足时优先保证真实分布少做增强因为你的真实文档长什么样比看起来更多样重要。无论哪种情况验证集一律不加增强——它是你模拟上线后真实输入的唯一标尺被增强污染了就失去评估资格。表单是典型的微调场景字段固定、数字密集、版式重复几百页标注数据通常就能把数字字段错误率压下去。一次跑通的训练配置完整命令与逐项解释结论仓库本身不附带现成的微调入口脚本官方建议需要微调支持时联系维护方见 README.md 的 Training 一节联系方式 hidatalab.to自建路线则用任意支持 VLM SFT 的训练框架按下面这套配置先跑通再调优。以 LLaMA-Factory 为例ms-swift、verl 等框架同理概念一一对应第一次跑通用这套保守配置llamafactory-cli train \ --stage sft \ --model_name_or_path /path/to/surya_base_vlm \ --dataset ocr_finetune \ --finetuning_type lora \ --lora_rank 32 \ --per_device_train_batch_size 1 \ --gradient_accumulation_steps 8 \ --learning_rate 1e-4 \ --max_steps 2000逐项解释为什么这么设sft阶段是监督微调不需要强化学习那一套LoRA低秩适配只训练少量旁路权重而非全部参数把显存需求压到单卡可承受范围且 32 的秩对文档域微调已经足够batch size 设为 1 加梯度累积 8 步等效批量 8这是显存不够还能稳定训练的标准做法学习率 1e-4 是 LoRA 微调的常用量级全参数微调时应降到 1e-5 左右max_steps 2000先给一个明确终点避免不知道要跑多久。显存不够怎么调 batch顺序是batch 降到 1 → 开梯度累积等效批量不变→ 降低图像输入分辨率192 DPI 改 96 DPI像素量降约 75%但注意识别精度会随之下降建议只用于中间试验→ 仍不够就上多卡或 LoRA 降秩。判断显存是否够用看两个信号loss 前 50 步应明显下降若前 100 步内 loss 几乎不动多半是批量等效太小或学习率不对先查配置再怀疑数据。多语言混合数据怎么办按语言分层抽样别让高频语言把样本池占满给每个目标语言单独统计验证集错误率低于整体均值最多的那个语言再补数据而不是按总量平均加。验证各语言表现可对照官方 static/docs/multilingual.md 的 91 语种表格先看预训练模型在你目标语言上的基线——基线 90% 以上的语言基本不用额外投数据。单页文字太多怎么办全页 OCR 的输出 token 预算默认 12288settings 里的SURYA_MAX_TOKENS_FULL_PAGE。如果你的文档单页文本超过这个量级训练时把序列长度上限放宽推理侧同步调整否则长页会被截断SURYA_MAX_TOKENS_FULL_PAGE16384 VLLM_MAX_MODEL_LEN24576 \ uv run surya_ocr long_doc.pdf把训练好的 checkpoint 指回现有管线微调产出的模型必须能说 Surya 的提示词方言输出 layout JSON / 全页 HTML这样接回管线不需要改任何代码——只需把 surya/settings.py 里的SURYA_MODEL_CHECKPOINT指到你本地目录SURYA_MODEL_CHECKPOINT/path/to/custom_ocr uv run surya_ocr doc.png推理后端GPU 用 vllm、CPU/Apple Silicon 用 llama.cpp会自动探测并拉起服务这一步和用官方模型完全一致。用结果说话基准指标与可视化对比结论评估先看四个数——文本相似度、框级 IoU、阅读顺序正确率、单页耗时四个里任何一个明显劣于预训练基线都要回头查对应环节。基准测试该看哪四个指标文本相似度 / 编辑距离对验证集每页的识别文本与标注文本算归一化 Levenshtein 距离越低越好这是识别准不准的核心指标官方 olmOCR-bench 也是同一思路。框级 IoU检测框与标注框的交并比均值反映找没找对位置。IoU 差而相似度高说明漏检或错并行。阅读顺序正确率块序列与标注顺序一致的比例多栏版面报纸、双栏报告重点看它。单页耗时微调后不应明显变慢如果变慢多半是 checkpoint 没合并或量化没做。上表是官方给出的模型规模-分数对照你的自定义模型评估时基线一列填官方预训练模型在同验证集上的成绩两列并排才看得出微调的净收益。识别结果怎么可视化对比用仓库自带的绘制工具把识别块画回页面预训练 vs 微调各存一张并排看from PIL import Image from surya.debug.draw import draw_polys_on_image img Image.open(page.png).convert(RGB) page rec([img])[0] out draw_polys_on_image( [b.polygon for b in page.blocks], img, labels[b.label for b in page.blocks]) out.save(annotated.png)draw_polys_on_image定义在 surya/debug/draw.pyblocks的字段结构label、polygon、html、confidence见 surya/recognition/schema.py。对比时重点看之前错的那几类字段数字是否还混读、专有名词是否还丢行。定制模型怎么接入应用CLI 一条命令即可批量出结果--images附带可视化results.json为最终输出SURYA_MODEL_CHECKPOINT/path/to/custom_ocr \ uv run surya_ocr ./docs/ --images --output_dir resultsPython 侧则是标准的预测器写法SuryaInferenceManager负责拉起后端进程内构造一次即可from PIL import Image from surya.inference import SuryaInferenceManager from surya.recognition import RecognitionPredictor rec RecognitionPredictor(SuryaInferenceManager()) blocks rec([Image.open(doc.png)])[0].blocks print(blocks[0].html, blocks[0].confidence)三条可选进阶路线按需自选以下三条都不是必做对应三种不同的后续诉求对号入座即可。多任务联合训练如果你的痛点同时包含识别和版面例如表格区域漏检导致整块丢失就把版面 JSON 样本和全页 HTML 样本混进同一个 SFT 数据集。Surya 的训练输出本来就是这两类layout JSON / full-page HTML见 README.md Training 一节的描述混合比例从 5:5 起步按两类指标各自的退化方向微调。知识蒸馏与量化部署目标是边缘设备或小显存服务器时先量化再谈别的仓库自带 surya/scripts/build_gguf.py 可以把模型转成 llama.cpp 能直接加载的 GGUF 格式CPU 和 Apple Silicon 上都能跑llama.cpp 后端在 surya/inference/backends/llamacpp.py。想要更聪明的小模型可以让一个更大的 VLM 对你验证不了的难样本批量生成标注人工抽检后并入训练集——这比堆算力更实际。增量学习新业务上线新增一种文档类型时从已有自定义 checkpoint 继续 SFT而不是从基座重训学习率降到 1e-5 量级、LoRA 只挂语言侧参数视觉编码器保持冻结小数据量几百页下 200~500 步即可收敛原有能力回退最小。下一步微调只是把识别这一段做对完整的文档数字化链路还包括版面与表格surya_layout和surya_table命令、以及 surya/scripts/ 下的命令行入口都值得逐个跑一遍确认你的管线里每一环都达标。更多细节看 README.md 的 Usage 与 Benchmarks 章节多语言完整表格在 static/docs/multilingual.md回归测试在 tests/ 下改动管线前后跑一遍能兜住意外。需要微调支持或托管训练时README 的 Training 一节留有官方联系方式hidatalab.to贡献与许可相关问题见 CLA.md。【免费下载链接】suryaOCR, layout analysis, reading order, table recognition in 90 languages项目地址: https://gitcode.com/GitHub_Trending/su/surya创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
