MarkLLM：让大语言模型具备视觉文档理解能力的开源框架

1. 项目概述当大语言模型学会“看”文档最近在折腾文档智能处理的项目发现了一个挺有意思的开源工具——THU-BPM实验室开局的MarkLLM。简单来说它让大语言模型LLM具备了“视觉阅读”和理解复杂文档版式的能力。我们平时用ChatGPT这类纯文本模型处理文档时经常遇到一个头疼的问题你得先把PDF或扫描件里的文字、表格、公式一股脑儿地提取成纯文本再喂给模型。这个过程里文档的视觉结构——比如哪个是标题、表格的边框在哪、公式是上下标还是分式——几乎丢光了。模型看到的是一团乱麻的文字自然很难给出精准的答案尤其是涉及多模态信息文字表格图表的查询时。MarkLLM的核心思路很直接为什么不直接把文档的“样子”也告诉模型呢它通过一套视觉编码器将文档页面转换成一种保留了空间布局和视觉特征的“标记”Markup Language再与大语言模型结合。这就好比以前是让一个盲人听别人念稿子现在则是直接把排版精美的文稿摆在他面前。对于需要从技术手册、学术论文、财务报告等格式复杂的文档中精准提取信息的场景这个工具的价值就凸显出来了。它不是一个独立的模型而是一个框架旨在增强现有LLM的文档理解能力特别适合开发者集成到自己的RAG检索增强生成系统或智能问答应用里。2. 核心架构与设计思路拆解2.1 为何选择“视觉标记”而非传统OCR流水线传统的文档信息提取IE流程通常是一条流水线OCR识别文字 - 版面分析划分区域 - 信息抽取模型分类实体。这套流程的弊端在于误差会累积且每个环节都是独立的缺乏全局上下文的理解。更重要的是最终的“信息”是结构化数据如JSON丢失了文档原始的视觉语境LLM无法感知到“这个数字在表格的第三列第二行”或“这个标题用了加粗大号字体”。MarkLLM的设计哲学是“所见即所得”。它不追求在中间步骤就完成完美的信息结构化而是将整个文档页面包括文字、位置、字体、颜色等视觉属性编码成一种LLM能够理解的序列。这种序列我习惯称之为“视觉富文本”。它的优势在于信息保全保留了文档的原始视觉线索这些线索往往是理解文档语义的关键例如加粗的往往是重点或标题表格线框定了数据的归属。端到端学习模型可以直接从原始文档图像到最终答案进行端到端优化避免了流水线中多个模型误差叠加的问题。灵活性同一套视觉编码可以适配不同的下游任务如问答、摘要、信息抽取只需调整LLM的提示词Prompt即可无需为每个任务训练专门的抽取模型。2.2 MarkLLM的三层核心架构MarkLLM的架构可以清晰地分为三层理解这三层是如何协作的是掌握其用法的关键。第一层视觉编码器Vision Encoder这一层负责将文档图像“翻译”成机器能理解的密集特征。它通常基于一个强大的视觉主干网络比如Swin Transformer或ResNet。输入一张文档图片编码器会将其分割成许多小块Patch并提取每个小块的视觉特征。关键点在于这些特征不仅包含了“是什么”纹理、笔画还隐式地包含了“在哪里”空间位置。编码器输出的是一系列带有空间信息的视觉特征向量。第二层标记生成器Markup Generator这是MarkLLM最具创新性的一环。它的任务是将上一步的视觉特征序列转换成一个结构化的文本序列即“标记语言”。这个过程不是简单的OCR而是一种“视觉到文本”的翻译。例如它可能会生成类似这样的序列[HEAD] 引言 [END_HEAD] [TEXT] 本文研究了... [END_TEXT] [TABLE_START] [ROW] 年份 | 收入万元 | 增长率 [END_ROW] [ROW] 2022 | 1500 | 15% [END_ROW] [TABLE_END] [FIG_CAPTION] 图1: 收入增长趋势图 [END_FIG_CAPTION]这些特殊的标记如[TABLE_START],[ROW]明确地描述了文档的视觉结构。生成器通常是一个预训练好的模型学习了从视觉特征到标准标记语言的映射关系。第三层大语言模型LLM与提示工程经过前两层处理我们得到了一个富含视觉结构信息的文本序列。这个序列将被作为上下文Context与用户的问题Query一起构造成一个提示Prompt输入给大语言模型如GPT-4、ChatGLM、Qwen等。例如你是一个文档分析专家。请基于以下文档内容回答问题。 文档内容 [HEAD] 2023年第四季度财务报告 [END_HEAD] [TEXT] 本季度公司实现总收入... [END_TEXT] [TABLE_START] [ROW] 产品线 | Q4销售额亿 | 环比变化 [END_ROW] [ROW] 云计算 | 25.3 | 12% [END_ROW] [ROW] 软件服务 | 18.7 | 5% [END_ROW] [TABLE_END] 问题云计算产品在第四季度的销售额是多少环比增长了多少LLM在“阅读”这个包含了明确表格标记的提示后就能精准地定位并回答“25.3亿”和“12%”。整个过程中LLM本身并未被修改它只是获得了质量更高、信息更全的输入。3. 从零开始部署与基础使用实操3.1 环境准备与依赖安装MarkLLM是一个研究导向的框架其环境搭建需要一定的Python和深度学习基础。建议使用Python 3.8以上版本并优先在Linux系统或WSL2Windows下进行。首先克隆项目仓库并进入目录git clone https://github.com/THU-BPM/MarkLLM.git cd MarkLLM接下来是安装依赖。官方一般会提供requirements.txt文件。但由于深度学习库版本兼容性问题较多我建议采用更稳健的方式先创建并激活一个Conda虚拟环境conda create -n markllm python3.9 conda activate markllm然后分步安装核心依赖。先安装PyTorch请务必根据你的CUDA版本通过nvidia-smi查看去 PyTorch官网 获取正确的安装命令。例如对于CUDA 11.8pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118之后再安装项目其他依赖pip install -r requirements.txt注意requirements.txt中的包版本可能冲突。如果遇到问题可以尝试先注释掉版本号特别严格的包如transformersxxx安装完主要依赖后再手动安装兼容版本。常见的还有opencv-python、pdf2image用于PDF转图片、pytesseract备用OCR引擎等。3.2 模型下载与初始化配置MarkLLM通常不包含预训练模型权重需要单独下载。权重文件可能存放在Hugging Face Model Hub或项目提供的链接中。以使用其提供的默认视觉编码器和标记生成器为例查找模型信息查看项目README.md或configs/目录下的配置文件找到模型权重的名称或下载链接。下载权重如果托管在Hugging Face可以使用git lfs克隆或在代码中通过from_pretrained方法自动下载需配置网络。如果提供的是直接下载链接手动下载后放入pretrained/文件夹。配置文件路径在代码或配置文件中指定你下载的权重文件的本地路径。例如在推理脚本中你可能需要修改这样一行model_config_path ./configs/markllm_base.yaml # 在yaml文件内或代码中指定 checkpoint 路径 checkpoint_path ./pretrained/markllm_base.pth3.3 第一个端到端示例文档问答假设我们有一个sample.pdf文件我们想询问其中某个表格的数据。下面是一个简化的核心代码流程import torch from PIL import Image from markllm.processor import DocumentProcessor from markllm.models import MarkLLMPipeline # 假设有封装好的推理管道 from transformers import AutoTokenizer, AutoModelForCausalLM # 1. 初始化文档处理器负责视觉编码和标记生成 doc_processor DocumentProcessor.from_pretrained(./pretrained/markllm_processor) # 2. 加载你的LLM这里以ChatGLM3为例需提前安装chatglm-cpp或类似库以高效推理 # 注意MarkLLM框架通常提供与LLM对接的接口你可能需要编写一个适配层。 llm_tokenizer AutoTokenizer.from_pretrained(THUDM/chatglm3-6b, trust_remote_codeTrue) llm_model AutoModelForCausalLM.from_pretrained(THUDM/chatglm3-6b, trust_remote_codeTrue).half().cuda() # 半精度以节省显存 # 3. 构建MarkLLM管道 pipeline MarkLLMPipeline(doc_processor, llm_model, llm_tokenizer) # 4. 处理文档 pdf_path sample.pdf # 将PDF第一页转为图像 from pdf2image import convert_from_path images convert_from_path(pdf_path, first_page1, last_page1) doc_image images[0] # 5. 定义用户问题 question 请总结文档中2023年各季度的利润数据。 # 6. 运行推理 # 管道内部会a) 用doc_processor将图像转为标记序列 b) 将标记序列和问题构造成Prompt c) 调用LLM生成答案。 answer pipeline.run(doc_image, question) print(f问题{question}) print(f答案{answer})这是一个高度简化的示意。在实际项目中MarkLLMPipeline类需要你自己根据框架代码进行组装核心是正确地将视觉标记序列与LLM的提示模板结合。4. 高级应用与微调指南4.1 处理超长文档与复杂版式单页文档处理相对简单但实际场景中更多是多页PDF、扫描件或版式奇特的文档。MarkLLM框架需要扩展以适应这些情况。策略一分页处理智能聚合对于多页文档最直接的方法是逐页处理然后将每页生成的标记序列连接起来。但直接连接可能导致上下文超出LLM的窗口限制。此时需要引入“检索”思维使用嵌入模型如BGE为每一页的标记序列生成向量。将用户问题也向量化。计算问题与每一页的相似度只选取最相关的若干页如Top-3的完整标记序列送入LLM上下文窗口。 这种方法在保证信息不丢失的前提下极大地缓解了上下文长度压力。策略二自定义标记集应对复杂版式如果官方标记集如[TABLE],[TITLE]无法很好地描述你遇到的文档元素如化学结构式、电路图、乐谱你可以考虑扩展标记集。这通常涉及数据标注收集一批包含新元素的文档图片人工标注出这些元素的边界框和类别。模型微调在MarkLLM的标记生成器上用新标注的数据进行微调教会它识别并生成新的标记如[CHEM_FORMULA]。 这个过程需要一定的机器学习工程能力但能显著提升在垂直领域的效果。4.2 微调视觉编码器以适配特定领域预训练的视觉编码器在通用文档上表现良好但在某些特定领域如古籍手写体、医学胶片、工程蓝图可能效果下降。微调编码器是提升性能的有效手段。步骤简述准备数据你需要一个目标领域的数据集包含文档图片和对应的“视觉标记”真值。真值数据可以通过半自动工具标注获得。冻结部分参数通常我们会冻结编码器底层提取通用特征的参数只微调顶层负责领域特定特征的参数以防止过拟合和小数据灾难。定义损失函数损失函数需要衡量生成的标记序列与真值序列之间的差异常用的是连接主义时间分类CTC损失或交叉熵损失。训练与评估在训练集上微调在验证集上监控标记生成的准确率如精确匹配率、F1值。实操心得微调时学习率要设置得比原始训练小一个数量级例如1e-5。同时务必保留一个干净的测试集用于最终评估避免陷入对验证集的过拟合。领域数据往往稀缺巧妙使用数据增强如随机裁剪、颜色抖动、弹性形变能有效提升模型鲁棒性。5. 性能优化与生产部署考量5.1 推理速度与资源瓶颈分析将MarkLLM投入实际应用性能是必须跨过的坎。其推理流程主要存在三个瓶颈视觉编码与标记生成这是计算密集型步骤尤其在高分辨率图像上。一张A4纸300 DPI的图片分辨率约3500x2500像素直接输入网络计算量巨大。标记序列长度生成的标记序列可能非常长尤其是细节丰富的页面。这会占用大量LLM的上下文窗口并增加其生成答案的时间。LLM生成延迟这是主要延迟来源取决于所选LLM的大小和推理方式。针对性优化方案图像预处理在保证文字清晰的前提下适当降低图像分辨率如降至150 DPI。可以先尝试一个固定尺寸如将长边缩放到2048像素。标记序列压缩研究显示并非所有视觉标记对回答问题都同等重要。可以尝试用一个小型模型或规则对生成的标记序列进行“摘要”过滤掉无关的格式细节保留核心结构和内容。LLM选型与加速模型量化将LLM从FP32转换为INT8或INT4精度能大幅减少内存占用和加速推理精度损失通常可控。使用bitsandbytes或GPTQ等库可以方便实现。推理引擎使用专为推理优化的引擎如vLLM支持PagedAttention极大优化长序列吞吐、TensorRT-LLMNVIDIA GPU极致优化或llama.cppCPU/GPU混合推理。小模型在精度可接受的情况下选择参数量更小的模型如6B/7B参数其推理速度远快于百亿级模型。5.2 构建稳定的生产服务在本地跑通Demo只是第一步要提供稳定服务需要考虑以下几点服务化架构建议采用异步微服务架构。将MarkLLM Pipeline封装成一个独立的服务如使用FastAPI提供/process接口接收文档文件或URL和问题返回答案。这样可以实现水平扩展应对高并发。缓存策略对于相同的文档其视觉标记序列是固定的。可以引入缓存如Redis键为文档内容的哈希值值为生成的标记序列。当同一文档被多次查询不同问题时可以跳过耗时的视觉处理步骤直接使用缓存的标记序列与问题组合后询问LLM效率提升显著。错误处理与降级生产环境必须健壮。需要设计完善的错误处理链文档解析失败如损坏的PDF捕获异常返回友好错误并尝试备用解析库。视觉处理超时设置超时限制超时后尝试降低图像分辨率重试或降级到纯OCR文本提取流程。LLM生成异常或无响应实现重试机制或切换到备份的、更稳定的轻量级LLM。日志与监控记录每一次请求的处理时长细分视觉处理、LLM生成时间、Token消耗、缓存命中率等关键指标。这有助于定位性能瓶颈和进行成本核算。使用PrometheusGrafana等工具进行可视化监控。6. 常见问题排查与实战技巧在实际集成和调试MarkLLM的过程中我踩过不少坑这里总结几个典型问题和解决方法。6.1 显存溢出OOM问题这是最常遇到的问题尤其是在处理高分辨率图像或使用大LLM时。症状运行时报CUDA out of memory错误。排查与解决监控显存在代码开始时使用torch.cuda.memory_allocated()监控显存占用。降低输入分辨率这是最有效的方法。将输入图像的长边固定到1024或768像素。梯度检查点如果进行训练或微调在模型定义中启用梯度检查点Gradient Checkpointing用时间换空间。使用CPU卸载对于非常大的LLM可以将部分层如嵌入层放在CPU上使用accelerate库的device_map功能进行智能调度。批处理大小为1推理时确保批处理大小batch size为1。6.2 生成的标记序列混乱或缺失关键结构症状LLM基于标记序列给出的答案明显错误检查中间生成的标记发现没有正确的[TABLE]或[HEADING]标签。排查与解决检查预处理确认输入给视觉编码器的图像是清晰的、方向正确的无旋转。模糊或倾斜的图像会导致特征提取失败。验证模型权重确保下载的预训练权重完整且与代码版本兼容。可以尝试用项目提供的示例图片跑一遍看结果是否与官方示例一致。领域不匹配如果文档类型非常特殊如手写、多语言、古老印刷体预训练模型可能失效。此时需要考虑收集数据并进行微调见4.2节。阈值调整标记生成器后处理阶段可能有置信度阈值。查看代码中是否有相关参数如conf_threshold适当调低可能会召回更多结构但也可能引入噪声。6.3 LLM无法理解或正确利用标记信息症状标记序列看起来正确但LLM的答案却忽略了其中的结构化信息或者把标记当作普通文本回答。排查与解决提示词工程这是最关键的一环。你的Prompt必须明确指示LLM如何利用这些标记。例如在Prompt开头强调“以下内容包含特殊的文档结构标记如[TABLE_START]...表示表格[HEAD]...表示标题。请根据这些标记理解文档结构并精确回答问题。” 给LLM一两个小例子Few-shot Learning效果会更好。LLM能力评估不是所有LLM都能同等程度地理解这种自定义的标记语言。初步测试表明GPT-4、Claude-3、DeepSeek等顶尖模型在这方面表现优异而一些较小的开源模型可能需要更细致的调教。如果效果不佳尝试更换或升级LLM。标记序列过长如果序列太长超出了LLM的上下文窗口或者导致有效信息被挤到后面LLM可能会“遗忘”关键结构。此时需要应用第4.1节提到的分页与检索策略或者对标记序列进行压缩摘要。6.4 处理速度太慢无法满足实时性要求症状处理一页文档需要十几秒甚至更长时间。排查与解决性能剖析使用Python的cProfile模块或line_profiler工具精确找出是视觉编码、标记生成还是LLM推理哪个环节最耗时。硬件加速确保使用了GPU进行推理torch.cuda.is_available()返回True。对于视觉部分可以尝试使用TensorRT或ONNX Runtime对模型进行加速。流水线并行如果服务并发量高可以将视觉处理服务和LLM服务拆分开并部署多个实例。使用消息队列如RabbitMQ来连接它们实现异步处理和负载均衡。预热与常驻服务启动后先处理几张虚拟图片让模型完成加载和初始化。在Web服务中保持模型常驻内存而不是每次请求都加载。将MarkLLM这样的前沿研究应用到实际项目是一个充满挑战但也极具成就感的过程。它要求我们不仅是一个调包侠更要深入理解其设计理念具备扎实的工程化能力。从环境配置、模型整合到性能优化、生产部署每一步都需要仔细权衡和反复调试。我的体会是开始时不要追求大而全从一个具体的、小规模的应用场景切入比如只处理某一类固定格式的报告把流程彻底跑通、优化稳定再逐步扩展复杂度这样成功率会高很多。这个框架打开了一扇新的大门让LLM能更“直观”地理解我们的世界剩下的就看我们如何用它去解决真实的问题了。