egg/OCR
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
715805b3b8dcb616033b81adb4714db832dc8bdb
OCR/docs/project-risk-assessment.md
egg 59206a6ab8 feat: simplify layout model selection and archive proposals 
Changes:
- Replace PP-Structure 7-slider parameter UI with simple 3-option layout model selector
- Add layout model mapping: chinese (PP-DocLayout-S), default (PubLayNet), cdla
- Add LayoutModelSelector component and zh-TW translations
- Fix "default" model behavior with sentinel value for PubLayNet
- Add gap filling service for OCR track coverage improvement
- Add PP-Structure debug utilities
- Archive completed/incomplete proposals:
  - add-ocr-track-gap-filling (complete)
  - fix-ocr-track-table-rendering (incomplete)
  - simplify-ppstructure-model-selection (22/25 tasks)
- Add new layout model tests, archive old PP-Structure param tests
- Update OpenSpec ocr-processing spec with layout model requirements

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-27 13:27:00 +08:00

3.9 KiB
Raw Blame History

Project Risk & Issue Outlook

本文件整理當前專案的可預見問題、潛在問題與建議修復方向（依風險與可行性排序）。依據來源：git log（97 commits, 2025-11-12~11-26）、docs/architecture-overview.md、openspec/changes/archive/2025-11-26-enhance-memory-management/tasks.md 等。

可預見的問題項目

  • 記憶體管理文件缺口：openspec/changes/archive/2025-11-26-enhance-memory-management/tasks.md 的 8.2 文檔未完成，ModelManager/ServicePool/MemoryGuard 的調參與故障處置缺乏 runbook，部署或擴容時易踩坑。方向：補完架構說明、調參指南、故障排解與監控落地範例（Prometheus 指標與警戒值）。
  • PDF 生成回歸風險高：版面保持與表格/圖片渲染在 fa1abcd 之後多次修正（例如 d33f605→92e326b、108784a→3358d97、6e050eb），顯示缺少自動回歸。方向：建立最小回歸集（多欄文本、含圖表/表格、列表/Span 混排）與 golden PDF/JSON 比對，覆蓋 Direct/OCR 雙軌。
  • 最新 OCR 表格格式修復未經回歸：6e050eb 修正 OCR 軌表格資料格式與裁剪，無對應測試。方向：為 OCR 軌加表格解析/PDF 出圖的整合測試，確保與前端下載/展示一致。
  • PP-Structure 參數調校可能影響資源：frontend 支援前端可調 pp_structure_params（2312b4c），若缺乏 guard，可能放大 GPU/記憶體壓力。方向：在後端對超參做白名單與上限檢查，並納入 MemoryGuard 預估。
  • Chart 能力啟停策略缺少驗證：b048f2d 禁用 → 7e12f16 重新啟用；缺少覆蓋率與性能數據。方向：為 chart 模型啟用/關閉建立健康檢查與 A/B 測試數據收集。

潛在的問題項目

  • UnifiedDocument 結構漂移風險：雙軌共用輸出，近期多次調整（列表、Span、多欄、LOGO 元素），缺少結構驗證或 schema 鎖定。可能導致前端/匯出器/PDF 生成不一致。方向：定義 JSON Schema 或 pydantic 驗證，建立 contract 測試。
  • 服務池與記憶體守護的長時間行為未驗證：雖有單元/整合測試，缺乏長時間 soak/stress（GPU 記憶碎片、模型 unload/reload、信號處理）。方向：加入 24h soak 測試與記憶體走勢告警，驗證 SIGTERM/SIGINT 清理。
  • LibreOffice 轉檔鏈低觀測性：Office 直抽與轉 PDF (ef335cf) 依賴系統 LibreOffice，缺少失敗監控與重試策略。方向：為轉檔階段增加 metrics/告警，並提供 fallback/重試。
  • 前端/後端 API 契約缺少檢查：多次 V1→V2 遷移與新增參數（pp_structure_params 等），目前僅靠 E2E，缺少型別/契約檢查。方向：加入 OpenAPI 契約測試或生成型別校驗（ts-sdk 對齊 FastAPI schema）。
  • 混合抽圖/圖片保存路徑邊界：Direct/OCR 混合抽圖與 _save_image 實作曾多次修復，仍缺少對 None/缺檔路徑的防禦。方向：為缺檔/無圖的 PDF 生成加強斷言與 fallback。

建議修復與方向

  1. 完成記憶體管理文檔與樣板設定：在 docs/ 新增 MemoryGuard/ServicePool 調參與故障排除指南，附 .env 範例與 Prometheus 規則，對應 tasks 8.2 清單。
  2. 建立 PDF/UnifiedDocument 回歸套件：收集代表性樣本（多欄、表格、列表、含圖/LOGO、OCR/Direct 雙軌），產生 golden JSON/PDF，加入 CI 比對，並為 6e050eb 相關表格路徑新增測試。
  3. 加入 UnifiedDocument Schema 驗證：定義 schema（pydantic/JSON Schema），在匯出/PDF 生成前驗證；同時讓前端型別由 OpenAPI 生成以防 drift。
  4. PP-Structure 參數防護與資源估算：後端實作白名單/上限與 MemoryGuard 預估，避免前端自由調參造成 GPU OOM；增加拒絕/降級回饋。
  5. 長時間穩定性與轉檔可觀測性：增加 soak/stress pipeline，追蹤 GPU/CPU/記憶碎片；為 LibreOffice/轉檔階段加 metrics、重試與錯誤分類告警。