簡(jiǎn)介OCR技術(shù)廣泛用于文檔掃描、車牌識(shí)別、身份證信息提取等場(chǎng)景PPOCRLabel則是PaddleOCR生態(tài)中專門用于制作文字識(shí)別訓(xùn)練數(shù)據(jù)的半自動(dòng)標(biāo)注工具。這份exe包將工具源碼編譯封裝用戶無需預(yù)裝PaddlePaddle或Python環(huán)境即可在Windows上直接運(yùn)行顯著降低OCR數(shù)據(jù)標(biāo)注的入門門檻。壓縮包共2000個(gè)文件包含py源碼、pyc編譯文件、exe主程序、dll動(dòng)態(tài)庫、pyd擴(kuò)展及whl依賴包等整體大小355.43MB解壓后即可啟動(dòng)圖形化標(biāo)注界面。工具支持在圖片上拖拽創(chuàng)建文字框、錄入與修改文本內(nèi)容并提供撤銷、重做、保存和導(dǎo)出JSON標(biāo)注數(shù)據(jù)功能導(dǎo)出的標(biāo)準(zhǔn)格式可方便接入PaddleOCR或其他主流深度學(xué)習(xí)框架進(jìn)行模型訓(xùn)練適用于證件識(shí)別、票據(jù)識(shí)別、文檔數(shù)字化等任務(wù)。目前已有6445人瀏覽學(xué)習(xí)對(duì)需要快速構(gòu)建自定義OCR數(shù)據(jù)集的數(shù)據(jù)標(biāo)注人員、算法工程師和初學(xué)者而言是一款實(shí)用且易上手的效率工具。 做數(shù)據(jù)標(biāo)注的朋友應(yīng)該都遇到過這種情況自己電腦上PPOCRLabel跑得好好的OCR識(shí)別、手動(dòng)修正、結(jié)果導(dǎo)出一條龍但換到同事電腦上就傻眼了——要么沒裝Python環(huán)境要么PaddleOCR版本對(duì)不上要么缺各種依賴庫光是把環(huán)境搭明白就得折騰一下午。我早期做標(biāo)注項(xiàng)目時(shí)就經(jīng)常被這種事卡住后來干脆把PPOCRLabel打成了exe雙擊就能跑省掉了大量環(huán)境糾紛。今天這篇就專門聊聊打包PPOCRLabel的完整過程從工具選型、打包腳本、模型資源配置到常見坑位排查全是我實(shí)際跑過的路徑照著操作基本能一次成功。先說結(jié)論P(yáng)POCRLabel打包exe并不是單純執(zhí)行一句pyinstaller -F main.py那么簡(jiǎn)單因?yàn)镻addleOCR的依賴樹很深PaddlePaddle框架、opencv、shapely、pyclipper這些庫都有大量動(dòng)態(tài)鏈接和隱式導(dǎo)入直接打包出來的exe大概率會(huì)報(bào)缺模塊、缺DLL或者模型路徑找不到。所以整個(gè)打包過程的核心就是三件事選對(duì)打包工具、補(bǔ)齊隱藏依賴、規(guī)劃好模型文件的存放路徑。下面我從頭到尾拆開講。1. 項(xiàng)目拆解PPOCRLabel是什么打包要解決什么問題1.1 工具本質(zhì)與典型使用場(chǎng)景PPOCRLabel是PaddleOCR生態(tài)里官方維護(hù)的半自動(dòng)標(biāo)注工具本質(zhì)是“OCR模型預(yù)標(biāo)注 人工確認(rèn)修正”的工作流。它先調(diào)用訓(xùn)練好的檢測(cè)模型和識(shí)別模型把圖片里的文字區(qū)域框出來并識(shí)別出內(nèi)容再由人工檢查、調(diào)整文本框位置、修改識(shí)別結(jié)果最后導(dǎo)出成可訓(xùn)練的數(shù)據(jù)格式默認(rèn)是JSON格式。如果你要做一個(gè)新場(chǎng)景的OCR識(shí)別模型第一步永遠(yuǎn)是用它來產(chǎn)出一批高質(zhì)量標(biāo)注數(shù)據(jù)這一步做得好不好直接影響后面模型訓(xùn)練的精度上限。這個(gè)工具在實(shí)際項(xiàng)目里解決的是純?nèi)斯?biāo)注效率太低的問題。舉個(gè)例子如果一批單據(jù)里有1000張圖片純手動(dòng)框出每個(gè)文字區(qū)域再錄入內(nèi)容平均每張要花兩三分鐘熟練工一天也就標(biāo)200張出頭但用PPOCRLabel先讓模型自動(dòng)跑一遍人工只需要修正錯(cuò)框、漏框和識(shí)別錯(cuò)的字每張耗時(shí)能壓縮到二三十秒效率至少提升三四倍。這也是為什么它在OCR數(shù)據(jù)生產(chǎn)流程里幾乎是標(biāo)配。1.2 為什么非打包exe不可從GitHub拉源碼跑python PPOCRLabel.py --lang ch其實(shí)不難難的是讓不懂技術(shù)的標(biāo)注員也跑起來。標(biāo)注團(tuán)隊(duì)的成員很多不是開發(fā)背景他們不會(huì)配conda環(huán)境不會(huì)裝CUDA遇到報(bào)錯(cuò)也不知道怎么處理。如果每次都讓工程師去給每個(gè)人的機(jī)器裝環(huán)境時(shí)間成本會(huì)高到懷疑人生。打包成exe后標(biāo)注員拿到的就是一個(gè)普通的Windows程序雙擊圖標(biāo)就能用所有依賴都封裝在程序內(nèi)部跟裝個(gè)QQ一樣簡(jiǎn)單。從團(tuán)隊(duì)管理的角度統(tǒng)一exe版本還能避免環(huán)境不一致帶來的標(biāo)注結(jié)果差異。之前出現(xiàn)過同一個(gè)模型在A同事電腦上識(shí)別效果正常、在B同事電腦上因?yàn)镻addleOCR版本不同導(dǎo)致效果打折的情況打包后所有客戶端都固定使用同一套依賴環(huán)境這類問題從根上就消失了。1.3 打包方案選型思路市面上給Python程序打包exe的主流工具就那幾個(gè)PyInstaller、Nuitka、cx_Freeze、py2exe。對(duì)于PPOCRLabel這個(gè)項(xiàng)目我的建議是無腦選PyInstaller后面再考慮用Nuitka做性能優(yōu)化。原因有三點(diǎn)PyInstaller對(duì)PaddlePaddle全家桶的兼容性在社區(qū)里驗(yàn)證得最多坑位少遇到問題搜一下基本都有答案它支持目錄模式打包-D可以讓模型文件獨(dú)立在exe外后續(xù)更新模型不用重新打包配置相對(duì)簡(jiǎn)單一個(gè).spec文件就能精確控制打包內(nèi)容包括隱藏導(dǎo)入、數(shù)據(jù)文件、資源路徑Nuitka的優(yōu)勢(shì)是轉(zhuǎn)成C代碼后啟動(dòng)速度和內(nèi)存占用有一定優(yōu)化但它的打包配置更復(fù)雜對(duì)Paddle這種大型框架的支持也不如PyInstaller成熟容易在編譯階段卡住。我的實(shí)際經(jīng)驗(yàn)是除非對(duì)性能有極致要求否則PyInstaller的產(chǎn)物在實(shí)際使用中差異并不明顯沒必要為了優(yōu)化那幾秒啟動(dòng)時(shí)間增加大量排錯(cuò)成本。1.4 打包前后用戶體感對(duì)比對(duì)比維度源碼運(yùn)行方式exe打包方式環(huán)境要求需手動(dòng)安裝Python3.8、PaddlePaddle、PaddleOCR等超過20個(gè)依賴僅需Windows 10/11系統(tǒng)無需Python安裝耗時(shí)首次環(huán)境搭建30~60分鐘取決于網(wǎng)絡(luò)和編譯情況解壓即用約1分鐘模型部署手動(dòng)下載模型文件放到指定目錄易搞錯(cuò)路徑模型與程序自動(dòng)關(guān)聯(lián)定位或放固定目錄出錯(cuò)概率依賴版本沖突、缺失DLL、路徑錯(cuò)誤等高頻問題低主要問題是殺毒軟件誤報(bào)多人分發(fā)每個(gè)人都要配環(huán)境改版本還要逐個(gè)升發(fā)一份壓縮包即可版本統(tǒng)一這一對(duì)比就清楚了打包不是可選項(xiàng)而是把工具推給非技術(shù)團(tuán)隊(duì)使用的必選項(xiàng)。2. 打包前置工作環(huán)境準(zhǔn)備與依賴梳理2.1 建議在干凈的conda環(huán)境里構(gòu)建我打包PPOCRLabel踩過的第一個(gè)坑就是在自己的主環(huán)境里直接打包。那個(gè)環(huán)境為了做其他項(xiàng)目裝了各種亂七八糟的包PyInstaller會(huì)把這些不相干的庫也掃描分析一遍導(dǎo)致生成的exe體積巨大甚至出現(xiàn)模塊互相干擾。所以打包前一定要新建一個(gè)干凈的conda環(huán)境只裝PPOCRLabel運(yùn)行所需的依賴。conda create -n ppocrlabel_pkg python3.9 conda activate ppocrlabel_pkg pip install paddlepaddle2.5.2 pip install paddleocr2.7.0 pip install PPOCRLabel pip install pyinstaller這里要說明一下版本選擇的邏輯。Python的版本我固定在3.9因?yàn)镻addlePaddle官方對(duì)3.10及以上版本的支持有段時(shí)間不太穩(wěn)定3.9是最穩(wěn)妥的選擇。PaddlePaddle沒裝GPU版因?yàn)闃?biāo)注工具對(duì)推理速度要求不高CPU版體積更小、兼容性更好打出來的exe在別人的機(jī)器上不會(huì)因?yàn)槿盋UDA運(yùn)行庫而跑不起來。等后面需要大批量跑預(yù)標(biāo)注的時(shí)候再單獨(dú)用GPU環(huán)境跑而不是讓標(biāo)注員的客戶端依賴顯卡算力。2.2 確認(rèn)依賴樹完整且無沖突啟動(dòng)PPOCRLabel主程序前建議先用命令行方式把程序完整跑一遍確認(rèn)所有依賴都能正常導(dǎo)入和調(diào)用。有一個(gè)很關(guān)鍵的點(diǎn)PPOCRLabel在啟動(dòng)時(shí)不會(huì)立即加載所有模塊有些依賴是點(diǎn)擊某個(gè)功能按鈕才動(dòng)態(tài)導(dǎo)入的。如果只驗(yàn)證到“能打開界面”就認(rèn)為環(huán)境沒問題打包后大概率會(huì)在運(yùn)行時(shí)崩。我的做法是逐項(xiàng)把核心功能手動(dòng)過一遍打開圖像、自動(dòng)標(biāo)注、手動(dòng)改框、導(dǎo)出標(biāo)注結(jié)果。每操作一步觀察控制臺(tái)有沒有報(bào)導(dǎo)入錯(cuò)誤或警告。這個(gè)過程本質(zhì)上就是在幫PyInstaller提前暴露那些只能在運(yùn)行時(shí)才能發(fā)現(xiàn)的隱式依賴。python PPOCRLabel.py --lang ch執(zhí)行后界面正常彈出再依次操作圖片加載、自動(dòng)標(biāo)注、保存和導(dǎo)出所有環(huán)節(jié)都沒有異常輸出依賴樹才算驗(yàn)證通過。2.3 找出PPOCRLabel的入口腳本和資源清單進(jìn)入PPOCRLabel的安裝目錄你會(huì)看到它的核心代碼文件主要包括PPOCRLabel.py主程序入口負(fù)責(zé)啟動(dòng)Qt界面和事件循環(huán)libs/包含自繪的標(biāo)注畫布、標(biāo)簽管理、配置文件讀寫等resources/存放圖標(biāo)、樣式表、字體等界面資源configs/存放默認(rèn)配置模板打包前一定要摸清這些資源文件的路徑和用途特別是libs文件夾里的內(nèi)容它不是在import語句里直接體現(xiàn)的PyInstaller默認(rèn)不會(huì)收集這種目錄。我在第一次打包時(shí)就漏掉了libs結(jié)果exe啟動(dòng)能出界面但一加載圖片就報(bào)“module libs.shape not found”非常典型的隱式導(dǎo)入問題。2.4 自己實(shí)測(cè)下來的依賴清單參考依賴庫版本參考打包時(shí)易發(fā)問題paddlepaddle2.5.2缺少paddle內(nèi)部DLLCPU版比GPU版更易打包成功paddleocr2.7.0隱式導(dǎo)入paddleocr.cv_utils等子模塊需加hidden-importPyQt55.15.9Qt插件目錄需收集完整不同機(jī)器缺MSVC運(yùn)行時(shí)opencv-python4.8.x需收集opencv_videoio_ffmpeg*.dll等動(dòng)態(tài)庫shapely2.0.x依賴geos_c.dll需binary方式收集pyclipper1.3.0.post5純Python實(shí)現(xiàn)基本無問題pyinstaller5.13.x版本過低不支持Python3.9新特性過高存在依賴變更風(fēng)險(xiǎn)這些版本號(hào)是我反復(fù)試過能穩(wěn)定運(yùn)行的組合直接搬過去用可以減少很多兼容性排查時(shí)間。3. 核心實(shí)操手工編寫spec文件實(shí)現(xiàn)精準(zhǔn)打包3.1 不推薦一條命令直接打包的原因網(wǎng)上很多教程告訴你執(zhí)行pyinstaller -F -w PPOCRLabel.py就完事了但這條命令對(duì)PPOCRLabel絕對(duì)行不通。原因在于PaddleOCR和PyQt5的包結(jié)構(gòu)都極其復(fù)雜PyInstaller在自動(dòng)分析階段無法完整識(shí)別所有動(dòng)態(tài)導(dǎo)入的模塊和二進(jìn)制依賴。即便你用--hidden-import一個(gè)一個(gè)補(bǔ)也會(huì)陷入“補(bǔ)了A缺B補(bǔ)了B缺C”的死亡循環(huán)。更合理的做法是先用PyInstaller生成一個(gè)spec文件然后手工編輯spec把所有的數(shù)據(jù)文件、隱藏導(dǎo)入項(xiàng)、二進(jìn)制庫都顯式寫進(jìn)去。spec文件是PyInstaller的構(gòu)建配置文件它的核心作用就是告訴打包器我要把哪些Python模塊、哪些數(shù)據(jù)文件、哪些動(dòng)態(tài)庫放進(jìn)最終產(chǎn)物。3.2 我的完整spec配置內(nèi)容# -*- mode: python ; coding: utf-8 -*- block_cipher None hidden_imports [ paddleocr, paddleocr.cv_utils, paddleocr.utils, paddle.nn.functional, paddle.tensor, paddle.fluid.core_avx, pyclipper, shapely.geometry, shapely.ops, PIL._tkinter_finder, PyQt5.sip, ] datas [ (libs, libs), (resources, resources), (configs, configs), ] a Analysis( [PPOCRLabel.py], pathex[], binaries[], hiddenimportshidden_imports, hookspath[], hooksconfig{}, runtime_hooks[], excludes[], noarchiveFalse, optimize0, ) pyz PYZ(a.pure) exe EXE( pyz, a.scripts, a.binaries, a.datas, [], namePPOCRLabel, debugFalse, bootloader_ignore_signalsFalse, stripFalse, upxFalse, iconresources/icon.ico, consoleFalse, disable_windowed_tracebackFalse, argv_emulationFalse, target_archNone, codesign_identityNone, entitlements_fileNone, )注意上面用的不是EXE(..., a.binaries, a.datas)那種onepackage寫法而是把加a.binaries和a.datas直接打進(jìn)了單文件EXE。這種方式叫“onefile”產(chǎn)出一個(gè)獨(dú)立exe但內(nèi)部自解壓到臨時(shí)目錄運(yùn)行。如果你更在意啟動(dòng)穩(wěn)定性和排查問題方便可以用目錄模式onedirEXE只保留pyz和a.scripts把a(bǔ).binaries和a.datas放到同目錄的_internal文件夾里。兩種模式各有取舍onefile分發(fā)方便但啟動(dòng)慢且容易被殺毒軟件盯上onedir啟動(dòng)快、排錯(cuò)方便但要發(fā)一整個(gè)文件夾。3.3 每個(gè)關(guān)鍵配置項(xiàng)背后的邏輯先看datas部分我把libs、resources、configs三個(gè)目錄都整體拷進(jìn)了打包產(chǎn)物。libs是PPOCRLabel自帶的輔助模塊集合包含畫布交互、形狀編輯、標(biāo)簽管理等邏輯這些文件不是以標(biāo)準(zhǔn)包名存在PyInstaller分析時(shí)會(huì)漏掉必須手動(dòng)指定。resources里有Qt的樣式表、圖標(biāo)資源和中文字體漏了它界面會(huì)嚴(yán)重變形甚至文字全變方塊。configs里是默認(rèn)的OCR配置模板程序初始化時(shí)會(huì)讀取。再看hiddenimports這個(gè)列表里的每一項(xiàng)都是我實(shí)打?qū)嵅瘸鰜淼?。paddleocr.cv_utils是PaddleOCR在預(yù)處理圖像時(shí)動(dòng)態(tài)導(dǎo)入的漏掉它會(huì)在點(diǎn)擊自動(dòng)標(biāo)注時(shí)直接拋ModuleNotFoundErrorshapely.geometry和shapely.ops是文本框的旋轉(zhuǎn)、裁剪等幾何運(yùn)算依賴漏了報(bào)錯(cuò)更隱蔽程序不退出但功能靜默失效paddle.fluid.core_avx這行是Paddle在部分CPU上運(yùn)行時(shí)需要的雖然新版本Paddle已經(jīng)開始轉(zhuǎn)向新的執(zhí)行體系但為了兼容老版本依賴加上它更安全。3.4 UPX壓縮選項(xiàng)的取舍配置里我特意寫了upxFalse原因很實(shí)際。UPX確實(shí)能把exe體積壓縮20%到30%但經(jīng)過UPX壓縮的Paddle框架類程序偶爾會(huì)出現(xiàn)解壓失敗或動(dòng)態(tài)庫加載報(bào)錯(cuò)而且Windows Defender對(duì)UPX殼的誤殺率會(huì)明顯升高。PPOCRLabel打包出來本身就有300MB以上壓縮到260MB對(duì)分發(fā)體驗(yàn)提升有限卻引入穩(wěn)定性和報(bào)毒風(fēng)險(xiǎn)不劃算。3.5 執(zhí)行打包并驗(yàn)證產(chǎn)物spec文件改好后執(zhí)行構(gòu)建命令pyinstaller PPOCRLabel.spec --noconfirm構(gòu)建過程可能持續(xù)5到10分鐘期間控制臺(tái)會(huì)輸出大量分析日志看到completed successfully就說明打包成功。重點(diǎn)檢查dist目錄下生成的exe或文件夾先雙擊啟動(dòng)再走一遍完整的標(biāo)注流程加載圖片、自動(dòng)標(biāo)注、修正文本框、導(dǎo)出JSON。全部流程跑完沒報(bào)錯(cuò)這個(gè)exe才真正可用于分發(fā)。4. 模型資源的兩種管理策略內(nèi)置與外部文件夾4.1 為什么模型不能簡(jiǎn)單隨包打進(jìn)去PPOCRLabel運(yùn)行起來要調(diào)用兩個(gè)模型一個(gè)是文字檢測(cè)模型默認(rèn)是ch_PP-OCRv4_det一個(gè)是文字識(shí)別模型默認(rèn)是ch_PP-OCRv4_rec。這兩個(gè)模型文件加起來通常在20MB到80MB之間看起來不大但PaddleOCR加載模型時(shí)會(huì)檢查路徑、解壓配置、校驗(yàn)結(jié)構(gòu)如果模型放在自解壓臨時(shí)目錄里每次程序啟動(dòng)都要重新解壓一遍拖慢啟動(dòng)速度不說還可能遇到臨時(shí)目錄被殺毒軟件鎖定的情況。更關(guān)鍵的是模型文件是有可能更新的。比如你后面微調(diào)了一個(gè)更好用的檢測(cè)模型或者換了一個(gè)針對(duì)特定票據(jù)領(lǐng)域的識(shí)別模型如果模型內(nèi)置在exe里就需要重新打包整個(gè)exe發(fā)給所有標(biāo)注員如果模型放在exe外部的目錄里只需要替換模型文件就好客戶端代碼一行都不用改。4.2 推薦的外部模型目錄方案我的實(shí)操方案是在exe同級(jí)目錄下創(chuàng)建一個(gè)inference文件夾里面放PPOCRLabel所需的檢測(cè)模型和識(shí)別模型目錄結(jié)構(gòu)OCR標(biāo)注工具/ ├── PPOCRLabel.exe └── inference/ ├── ch_PP-OCRv4_det/ │ ├── inference.pdmodel │ ├── inference.pdiparams │ └── inference.pdiparams.info └── ch_PP-OCRv4_rec/ ├── inference.pdmodel ├── inference.pdiparams └── inference.pdiparams.info這里有個(gè)容易翻車的地方PaddleOCR默認(rèn)會(huì)先從當(dāng)前工作目錄或~/.paddleocr/下查找模型如果找不到就自動(dòng)下載到用戶目錄。打包后的exe如果在別人電腦上不能聯(lián)網(wǎng)自動(dòng)下載就會(huì)失敗程序卡死在“下載模型”環(huán)節(jié)看起來像死機(jī)一樣。所以一定要在PPOCRLabel界面里把“檢測(cè)模型路徑”和“識(shí)別模型路徑”手動(dòng)指到inference目錄下的對(duì)應(yīng)位置或者直接修改配置文件把路徑固定為./inference/ch_PP-OCRv4_det這種相對(duì)路徑。4.3 如何避免工作目錄導(dǎo)致路徑失效又一個(gè)容易踩的坑雙擊exe的啟動(dòng)方式不同工作目錄就不同。如果從cmd里切到exe所在目錄再啟動(dòng)./inference能找到但如果從文件管理器里雙擊或者通過快捷方式啟動(dòng)工作目錄可能變成C:Windows\System32相對(duì)路徑就失效了。最穩(wěn)妥的做法是在PPOCRLabel的入口腳本里把當(dāng)前工作目錄強(qiáng)制切換到exe所在目錄import os import sys if getattr(sys, frozen, False): os.chdir(os.path.dirname(sys.executable))源碼模式下sys.executable指向Python解釋器而打包成exe后指向的是exe本身這段代碼在源碼模式下不影響正常運(yùn)行在exe模式下則會(huì)自動(dòng)把工作目錄切到exe同級(jí)。經(jīng)過這樣處理外部模型目錄、配置文件、日志文件的位置都能保持穩(wěn)定。4.4 模型加載成功與否的驗(yàn)證方式分發(fā)前做一個(gè)快速驗(yàn)證在干凈的無Python環(huán)境下運(yùn)行exe加載一張文字清晰的圖片點(diǎn)擊“自動(dòng)標(biāo)注”如果文本框正常彈出、識(shí)別文字正常顯示就說明模型路徑配置成功。如果沒有任何反應(yīng)打開PPOCRLabel的日志或控制臺(tái)輸出看一下是否出現(xiàn)“Model file not found”或“Cannot open file”的提示。這一步雖然簡(jiǎn)單卻能攔截大部分分發(fā)后才暴露的問題。5. 常見問題與排查技巧那些我踩過的坑5.1 缺少Visual C運(yùn)行庫導(dǎo)致DLL加載失敗這是把exe發(fā)到一臺(tái)全新電腦上最常遇到的問題。PaddlePaddle和OpenCV在Windows上依賴msvcp140.dll、vcruntime140.dll這些Visual C運(yùn)行庫如果目標(biāo)機(jī)器沒裝過VC Redistributable程序會(huì)在啟動(dòng)階段直接崩潰彈窗提示“找不到VCRUNTIME140.dll”或“DLL load failed”。解決辦法有兩種一是把vcruntime140.dll、vcruntime140_1.dll、msvcp140.dll三個(gè)文件手動(dòng)放進(jìn)exe同目錄PyInstaller打包時(shí)有時(shí)會(huì)自動(dòng)帶上有時(shí)不會(huì)建議手動(dòng)確認(rèn)二是在分發(fā)說明里加一條“先安裝VC運(yùn)行庫”一勞永逸。我一般兩種都做既在目錄里放了DLL也在說明里標(biāo)注了備選方案。5.2 殺毒軟件誤報(bào)與處理方案PyInstaller打包的exe被殺毒軟件誤報(bào)是圈內(nèi)老生常談。因?yàn)镻yInstaller加了自解壓殼行為特征和加殼惡意軟件有相似之處Windows Defender經(jīng)常直接刪除或攔截。我的處理方式比較傳統(tǒng)但也最有效給exe文件做數(shù)字簽名哪怕用的是自簽名證書也能大幅降低誤報(bào)概率。沒有證書的話只能在分發(fā)時(shí)提醒標(biāo)注員把程序目錄加入殺毒軟件白名單。這個(gè)問題在打包工具類軟件時(shí)幾乎無法繞開提前做好心理預(yù)期就行。5.3 啟動(dòng)極慢和界面空白的問題onefile模式的exe每次啟動(dòng)都會(huì)把整個(gè)包解壓到臨時(shí)目錄300MB的解壓時(shí)間在機(jī)械硬盤上可能長(zhǎng)達(dá)十幾秒第一次啟動(dòng)甚至更久。這不是程序卡了是解壓正在進(jìn)行。如果客戶反饋等太久可以考慮換成onedir模式。還有種情況是界面直接空白或文字無法顯示通常是resources目錄里字體文件沒有正確打包Qt找不到字體渲染引擎把resources完整打包并檢查對(duì)應(yīng)路徑就能解決。5.4 自動(dòng)標(biāo)注后沒有任何框出現(xiàn)這個(gè)問題排查起來最費(fèi)勁因?yàn)槌绦虿粓?bào)錯(cuò)單純沒輸出。我用過的排查順序是先在原Python環(huán)境里用同樣的圖片跑一遍自動(dòng)標(biāo)注如果正常說明模型和算法沒問題問題在打包環(huán)節(jié)然后檢查exe運(yùn)行時(shí)的sys.path和模型路徑看PaddleOCR是否找到了模型最后檢查shapely和pyclipper是否導(dǎo)入正常這兩個(gè)庫負(fù)責(zé)文本框幾何運(yùn)算導(dǎo)入失敗會(huì)導(dǎo)致檢測(cè)結(jié)果無法渲染但又不拋異常。另外注意這些低版本PaddleOCR依賴庫的兼容性問題在打包后更容易暴露。5.5 常見問題速查表問題現(xiàn)象可能原因處理方法提示缺少VCRUNTIME140.dll目標(biāo)機(jī)器缺VC運(yùn)行庫打包時(shí)包含運(yùn)行庫DLL或引導(dǎo)安裝啟動(dòng)后提示找不到模型文件模型路徑配置失效或模型未隨包分發(fā)使用外部模型目錄啟動(dòng)時(shí)切換工作目錄界面正常但自動(dòng)標(biāo)注無輸出shapely/pyclipper導(dǎo)入失敗在hiddenimports中顯式聲明相關(guān)模塊殺毒軟件刪除或攔截exePyInstaller加殼特征觸發(fā)數(shù)字簽名或加入白名單啟動(dòng)后黑窗一閃即退缺少Q(mào)t平臺(tái)插件檢查platforms目錄是否完整程序啟動(dòng)極慢onefile自解壓耗時(shí)改用onedir模式分發(fā)5.6 分發(fā)前的全功能自測(cè)清單打包完成后不要急著發(fā)出去我習(xí)慣在干凈的虛擬機(jī)里做一輪功能驗(yàn)證。所謂干凈就是除了基礎(chǔ)系統(tǒng)外不安裝Python、不安裝任何運(yùn)行庫模擬標(biāo)注員電腦的真實(shí)環(huán)境。驗(yàn)證清單包括雙擊exe是否能正常啟動(dòng)、導(dǎo)入一組樣本圖片、點(diǎn)擊自動(dòng)標(biāo)注、手動(dòng)拖動(dòng)修改文本框、刪除誤檢框、修改識(shí)別結(jié)果、導(dǎo)出JSON標(biāo)注文件。所有步驟都走完且結(jié)果正確再交付給團(tuán)隊(duì)能省掉大量遠(yuǎn)程協(xié)助排錯(cuò)的時(shí)間。6. 擴(kuò)展思路標(biāo)注之外的部署場(chǎng)景把PPOCRLabel打包成exe這件事解決的不只是標(biāo)注工具分發(fā)問題背后的思路可以遷移到其他PaddleOCR相關(guān)工具上。比如你寫了一個(gè)基于PaddleOCR的批量圖片文字提取小工具或者做了一個(gè)合同關(guān)鍵信息抽取的桌面程序都可以復(fù)用同樣的打包方式。甚至是PaddleOCR的模型預(yù)測(cè)服務(wù)雖然官方推薦用Paddle Inference或Paddle Serving部署但在輕量級(jí)場(chǎng)景下做成exe給業(yè)務(wù)人員本地用也是一條值得考慮的路子。從打包技術(shù)本身來看PyInstaller的spec文件、隱式依賴補(bǔ)齊、外部資源路徑規(guī)劃這幾個(gè)能力是通用的。以后再接到“幫我把某個(gè)Python工具打包成exe”的需求都會(huì)比這次順手得多因?yàn)楹诵碾y點(diǎn)不在PyInstaller命令怎么敲而在對(duì)你所依賴的那個(gè)重型框架的理解深度——你越清楚程序運(yùn)行時(shí)動(dòng)態(tài)加載了什么、依賴了哪些非Python資源打包成功率就越高。根據(jù)我個(gè)人的經(jīng)驗(yàn)第一次打包PPOCRLabel時(shí)遇到各種報(bào)錯(cuò)是很正常的事關(guān)鍵是要按照“先跑通源碼、再整理依賴、后配置spec、最終驗(yàn)證”的順序來每一步穩(wěn)扎穩(wěn)打基本兩三個(gè)小時(shí)就能拿到可用的exe。如果你也正在折騰這個(gè)希望這份整理能少讓你走幾個(gè)彎路。本文還有配套的精品資源點(diǎn)擊獲取