关于LayoutLMv3的中文图片识别项目运行环境配置问题

一、问题背景

      最近打算入门中文文档的布局分析，由于是新手，第一条路当然是找个经典项目练练手。LayoutLM这个工具可以说是文档处理领域绕不开的经典模型，虽然现在有了更好的，但是用这个练手准没错。官方的教程过于复杂，因为有源码在里面，大概是想什么功能都讲，集成功能比较多，而且python版本也老了，还是3.7的。然而我只想看怎么应用而已，而且目标是中文的识别，于是我遍寻github，找到一个功能简洁，注释完整的应用代码，整个工程就三个文件，分别是训练、推理和图像处理，而且就是中国人作的，每行都有中文注释，数据集是XFUNDv1.0的中文图片。工程链接在这里中文LayouLMv3应用。

      当真正去运行的时候，才发现每这么简单。哪怕每一句代码都有注释，写得也不复杂，就是运行不起来，一堆错误。想想也难怪，现在机械学习的模型后浪推前浪，一个模型还没捂热乎，就被另一些性能效果更好的模型抢了风头，然后网上留下了一堆烂尾材料，都没有能把教程讲全乎的。各个AI工具包为了能兼容最新的模型，隔段时间就更新，留下的就是一堆相互依赖的兼容性问题。制作这个中文LayoutLMV3工程的哥们儿留得最大的坑就是没把环境配置讲清楚，连requirements.txt都没有，实在是要命。我一开始按照官方的依赖安装工具包，结果到处报错，为了搞清楚安装包我试了好几天，才算整出来一个能用的环境。

二、环境配置

（1）以我的ubuntu系统为例，首先本工程依赖环境是python3.9，可以先用conda创建一个虚拟环境，然后再进行下一步。

（2）系统还需要安装tesseract-ocr工具，这个是layoutLMv3会调用到的，我的是ubuntu系统，所以用下面命令安装，windows则使用官方推荐的安装方式。

sudo apt install tesseract-ocr

（3）激活虚拟环境，按下面的安装包版本去安装pip包，也可以一起制作成requirements文件, 用pip安装。不一定每个包都能用到，但是可以对照下面版本进行选择。

Package                  Version
------------------------ ------------------
absl-py                  2.1.0
aiohappyeyeballs         2.4.6
aiohttp                  3.11.12
aiosignal                1.3.2
antlr4-python3-runtime   4.9.3
appdirs                  1.4.4
async-timeout            5.0.1
attrs                    25.1.0
black                    21.4b2
cachetools               5.5.1
certifi                  2025.1.31
charset-normalizer       3.4.1
click                    8.1.8
cloudpickle              3.1.1
contourpy                1.3.0
cycler                   0.12.1
datasets                 2.2.2
deepspeed                0.5.7
detectron2               0.6+cu111
dill                     0.3.4
einops                   0.8.1
evaluate                 0.1.2
filelock                 3.17.0
fonttools                4.56.0
frozenlist               1.5.0
fsspec                   2025.2.0
future                   1.0.0
fvcore                   0.1.5.post20221221
google-auth              2.38.0
google-auth-oauthlib     0.4.6
grpcio                   1.70.0
hjson                    3.1.0
huggingface-hub          0.29.0
hydra-core               1.3.2
idna                     3.10
importlib_metadata       8.6.1
importlib_resources      6.5.2
iopath                   0.1.9
Jinja2                   3.1.5
joblib                   1.4.2
kiwisolver               1.4.7
Markdown                 3.7
MarkupSafe               3.0.2
matplotlib               3.9.4
mpmath                   1.3.0
multidict                6.1.0
multiprocess             0.70.12.2
mypy-extensions          1.0.0
networkx                 3.2.1
ninja                    1.11.1.3
numpy                    1.23.1
nvidia-cublas-cu12       12.4.5.8
nvidia-cuda-cupti-cu12   12.4.127
nvidia-cuda-nvrtc-cu12   12.4.127
nvidia-cuda-runtime-cu12 12.4.127
nvidia-cudnn-cu12        9.1.0.70
nvidia-cufft-cu12        11.2.1.3
nvidia-curand-cu12       10.3.5.147
nvidia-cusolver-cu12     11.6.1.9
nvidia-cusparse-cu12     12.3.1.170
nvidia-cusparselt-cu12   0.6.2
nvidia-nccl-cu12         2.21.5
nvidia-nvjitlink-cu12    12.4.127
nvidia-nvtx-cu12         12.4.127
oauthlib                 3.2.2
omegaconf                2.3.0
opencv-python            4.11.0.86
packaging                24.2
pandas                   2.2.3
pathspec                 0.12.1
pillow                   11.1.0
pip                      25.0.1
portalocker              3.1.1
propcache                0.2.1
protobuf                 3.20.0
psutil                   7.0.0
pyarrow                  14.0.2
pyasn1                   0.6.1
pyasn1_modules           0.4.1
pycocotools              2.0.8
pydot                    3.0.4
pyparsing                3.2.1
pytesseract              0.3.13
python-dateutil          2.9.0.post0
pytz                     2025.1
PyYAML                   6.0.2
regex                    2024.11.6
requests                 2.32.3
requests-oauthlib        2.0.0
response                 0.5.0
responses                0.18.0
rsa                      4.9
sacremoses               0.1.1
safetensors              0.5.2
scikit-learn             1.6.1
scipy                    1.13.1
sentencepiece            0.2.0
seqeval                  1.2.2
setuptools               59.5.0
shapely                  2.0.7
six                      1.17.0
sympy                    1.13.1
tabulate                 0.9.0
tensorboard              2.7.0
tensorboard-data-server  0.6.1
tensorboard-plugin-wit   1.8.1
termcolor                2.5.0
textdistance             4.6.3
threadpoolctl            3.5.0
timm                     0.4.12
tokenizers               0.12.1
toml                     0.10.2
torch                    1.10.1+cu111
torchvision              0.11.2+cu111
tqdm                     4.67.1
transformers             4.27.1
triton                   3.2.0
typing_extensions        4.12.2
tzdata                   2025.1
urllib3                  2.3.0
Werkzeug                 3.1.3
wheel                    0.45.1
xxhash                   3.5.0
yacs                     0.1.8
yarl                     1.18.3
zipp                     3.21.0

三、代码调整

      环境按照上面进行安装应该能解决99%的问题，即使是按照上面环境进行搭建，程序中还是会有报错，我所遇到的一个就是下面的问题。

processor = LayoutLMv3Processor(tokenizer=tokenizer, image_processor=image_processor, apply_ocr=False)

      系统会提示tokenizer的类型不支持。这本质上也是个兼容问题，但是我不想再费劲试下去了，所以按照网上人的留言，把这句代码进行了了改进。

class LayoutLMv3ChineseProcessor(LayoutLMv3Processor):
    tokenizer_class = ("LayoutLMv3Tokenizer", "LayoutLMv3TokenizerFast",'XLMRobertaTokenizer','XLMRobertaTokenizerFast','LayoutXLMTokenizer')
    
processor = LayoutLMv3ChineseProcessor(image_processor=image_processor,tokenizer=tokenizer,apply_ocr=False)

    这样就能运行下去。

    运行效果还有待测试，如再遇到问题会修改此文章。