PaddleOCR là gì? Phân tích repo PaddlePaddle/PaddleOCR và hướng dẫn sử dụng

PaddleOCR là gì? Phân tích repo PaddlePaddle/PaddleOCR và hướng dẫn sử dụng dễ hiểu

Ảnh trích xuất từ GitHub Open Graph preview của repo PaddlePaddle/PaddleOCR. Ảnh không phải SVG.¹

Tóm tắt nhanh

PaddleOCR là bộ công cụ OCR và Document AI mã nguồn mở của PaddlePaddle. Repo chính thức mô tả PaddleOCR là công cụ chuyển PDF hoặc ảnh tài liệu thành dữ liệu có cấu trúc cho AI, hỗ trợ hơn 100 ngôn ngữ và xuất dữ liệu ở dạng JSON/Markdown để dùng trong LLM, RAG và ứng dụng agent.²

Nói dễ hiểu: nếu bạn có ảnh chụp hóa đơn, scan hợp đồng, boarding pass, bảng biểu trong PDF, tài liệu nhiều cột, ảnh có chữ, hoặc file cần trích xuất text để đưa vào AI, PaddleOCR giúp phát hiện chữ, nhận dạng chữ, giữ lại vị trí chữ và có thể phân tích layout tài liệu phức tạp.

PaddleOCR phù hợp với ba nhóm việc chính:

• OCR thông thường: lấy chữ từ ảnh hoặc PDF.
• Document parsing: tách heading, đoạn văn, bảng, công thức, ảnh, biểu đồ và xuất Markdown/JSON.
• Document AI cho LLM/RAG: biến tài liệu thành dữ liệu có cấu trúc để chatbot, search, RAG hoặc agent dùng được.

PaddleOCR giải quyết vấn đề gì?

Dữ liệu trong doanh nghiệp không chỉ nằm ở database. Rất nhiều thông tin nằm trong:

• ảnh chụp giấy tờ;
• file scan PDF;
• hóa đơn, biên lai, đơn hàng;
• hợp đồng và biểu mẫu;
• báo cáo tài chính;
• bảng biểu trong PDF;
• slide hoặc tài liệu văn phòng;
• ảnh màn hình;
• tài liệu nhiều cột;
• tài liệu có chữ viết tay, con dấu, công thức hoặc bảng.

LLM không đọc ảnh/PDF thô tốt bằng text có cấu trúc. PaddleOCR nằm giữa tài liệu và hệ thống AI:

Ảnh / PDF / tài liệu scan
        ↓
PaddleOCR
        ↓
Text, tọa độ, layout, bảng, Markdown, JSON
        ↓
RAG / chatbot / database / workflow tự động

Repo PaddlePaddle/PaddleOCR có gì đáng chú ý?

Trên GitHub, repo PaddlePaddle/PaddleOCR là một trong các repo OCR lớn nhất, có hơn 79k sao tại thời điểm truy cập, license Apache-2.0, và mô tả repo là công cụ chuyển PDF/ảnh tài liệu thành dữ liệu có cấu trúc cho AI.²

README nêu các điểm chính:

• Hỗ trợ 100+ ngôn ngữ.
• Có PP-OCRv5 cho OCR đa ngôn ngữ.
• Có PP-StructureV3 để chuyển PDF/ảnh phức tạp thành Markdown hoặc JSON.
• Có PaddleOCR-VL là dòng VLM 0.9B cho document parsing.
• Có tích hợp với hệ sinh thái AI agent như Dify, RAGFlow, Pathway, Cherry Studio.
• Có deployment cho nhiều phần cứng như NVIDIA GPU, Intel CPU, Kunlunxin XPU và AI accelerator khác.²

PaddleOCR không phải là gì?

Để tránh hiểu nhầm:

Nếu bạn chỉ cần đọc vài ảnh đơn giản, dùng PP-OCRv5 là đủ. Nếu bạn cần phân tích tài liệu phức tạp, bảng, công thức, layout, Markdown thì nên xem PP-StructureV3 hoặc PaddleOCR-VL.

Các thành phần chính

PP-OCRv5

PP-OCRv5 là pipeline OCR tổng quát. Tài liệu nói OCR là công nghệ chuyển text trong ảnh thành text có thể chỉnh sửa; general OCR pipeline dùng để trích xuất thông tin text từ ảnh và xuất ra dạng text.³

Pipeline OCR thường gồm:

• phân loại hướng tài liệu, nếu cần;
• làm phẳng/chỉnh ảnh, nếu cần;
• phân loại hướng dòng chữ, nếu cần;
• phát hiện vùng chữ;
• nhận dạng chữ.

README nêu PP-OCRv5 có hỗ trợ 100+ ngôn ngữ và cải thiện 13% accuracy so với thế hệ trước trong nhiều tình huống.²

PP-StructureV3

PP-StructureV3 dùng khi bạn cần hiểu cấu trúc tài liệu, không chỉ lấy text. Tài liệu mô tả layout analysis là quá trình nhận diện text blocks, titles, paragraphs, images, tables và các layout elements khác; PP-StructureV3 cải thiện layout detection, table recognition, formula recognition, multi-column reading order, chart understanding và chuyển kết quả thành Markdown.⁴

Dùng PP-StructureV3 khi bạn có:

• PDF nhiều cột;
• báo cáo có bảng;
• tài liệu có công thức;
• tài liệu có con dấu;
• tài liệu có hình/biểu đồ;
• bài nghiên cứu hoặc hợp đồng dài;
• nhu cầu xuất Markdown/JSON cho RAG.

PaddleOCR-VL

PaddleOCR-VL là dòng vision-language model cho document parsing. Tài liệu nói PaddleOCR-VL dùng VLM 0.9B nhỏ gọn, hỗ trợ 109 ngôn ngữ và nhận diện tốt các phần tử phức tạp như text, table, formula và chart.⁵

Dùng PaddleOCR-VL khi:

• tài liệu rất phức tạp;
• layout khó;
• scan bị nghiêng, cong, chụp màn hình, ánh sáng kém;
• cần đầu ra Markdown/structured output tốt;
• có GPU hoặc hạ tầng inference phù hợp.

Cài đặt PaddleOCR

Bước 1: Tạo môi trường Python

python -m venv .venv
source .venv/bin/activate

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Bước 2: Cài inference engine

Quick Start nói PaddleOCR hỗ trợ cấu hình inference engine thống nhất, hiện hỗ trợ PaddlePaddle và Transformers.⁶

CPU:

python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

GPU ví dụ CUDA 11.8 trên Linux:

python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

Nếu dùng Transformers:

python -m pip install "transformers>=5.8.0"

Bước 3: Cài paddleocr

Cài chức năng mặc định:

python -m pip install paddleocr

Cài full tính năng:

python -m pip install "paddleocr[all]"

Tài liệu Installation nói paddleocr mặc định gồm general OCR và document image preprocessing; các nhóm dependency khác gồm doc-parser, ie, trans, doc2md và all.⁷

Nếu chỉ cần OCR ảnh/PDF cơ bản, bắt đầu với:

python -m pip install paddleocr

Nếu muốn document parsing, Markdown, IE, translation và nhiều pipeline hơn:

python -m pip install "paddleocr[all]"

Dùng PaddleOCR bằng CLI

OCR ảnh cơ bản:

paddleocr ocr -i ./image.png \
  --use_doc_orientation_classify False \
  --use_doc_unwarping False \
  --use_textline_orientation False \
  --engine paddle

Dùng Transformers engine:

paddleocr ocr -i ./image.png \
  --use_doc_orientation_classify False \
  --use_doc_unwarping False \
  --use_textline_orientation False \
  --engine transformers

Tách riêng text detection:

paddleocr text_detection -i ./image.png --engine paddle

Tách riêng text recognition:

paddleocr text_recognition -i ./text_crop.png --engine paddle

Phân tích tài liệu với PP-StructureV3:

paddleocr pp_structurev3 -i ./document.png \
  --use_doc_orientation_classify False \
  --use_doc_unwarping False \
  --engine paddle

Các lệnh trên lấy từ Quick Start chính thức.⁸

Dùng PaddleOCR bằng Python

Ví dụ OCR cơ bản:

from paddleocr import PaddleOCR

ocr = PaddleOCR(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    engine="paddle",
)

result = ocr.predict("./image.png")

for res in result:
    res.print()
    res.save_to_img("output")
    res.save_to_json("output")

Quick Start chính thức cũng dùng pattern PaddleOCR(...).predict() rồi print(), save_to_img() và save_to_json().⁹

Ví dụ lấy text để đưa vào app:

from paddleocr import PaddleOCR

ocr = PaddleOCR(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    engine="paddle",
)

result = ocr.predict("./invoice.png")

texts = []
for page in result:
    data = page.json if hasattr(page, "json") else None
    page.print()

Trong production, bạn nên kiểm tra object output thực tế theo version đang dùng, vì field kết quả có thể thay đổi theo pipeline/model.

Nên chọn pipeline nào?

PaddleOCR cho RAG và chatbot tài liệu

Một pipeline RAG cơ bản:

PDF / ảnh scan
    ↓
PaddleOCR / PP-StructureV3 / PaddleOCR-VL
    ↓
Markdown hoặc JSON
    ↓
Chunking
    ↓
Embedding
    ↓
Vector database
    ↓
Chatbot hỏi đáp tài liệu

Ví dụ xử lý batch:

from pathlib import Path
from paddleocr import PaddleOCR

ocr = PaddleOCR(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    engine="paddle",
)

input_dir = Path("scans")
output_dir = Path("ocr_json")
output_dir.mkdir(exist_ok=True)

for img in input_dir.glob("*"):
    if img.suffix.lower() not in [".png", ".jpg", ".jpeg", ".pdf"]:
        continue

    result = ocr.predict(str(img))
    for i, res in enumerate(result):
        res.save_to_json(str(output_dir))

Nếu tài liệu có bảng, heading và layout phức tạp, dùng PP-StructureV3 thay vì OCR cơ bản để giữ cấu trúc tốt hơn.

Triển khai dạng API service

PaddleOCR docs nói serving là cách triển khai phổ biến trong production: đóng gói khả năng inference thành service để client gọi qua network; client có thể dùng ngôn ngữ khác với server-side code.¹⁰

Tài liệu khuyến nghị dùng PaddleX cho serving. Basic serving dùng lệnh:

paddlex --install serving
paddlex --serve --pipeline OCR

Server mặc định chạy Uvicorn trên http://0.0.0.0:8080.¹¹

Mô hình triển khai:

Client app
  ↓ HTTP
PaddleOCR/PaddleX Serving
  ↓
GPU/CPU inference
  ↓
JSON/Markdown result

Dùng serving khi:

• nhiều app cần gọi chung OCR;
• muốn chạy model trên GPU server;
• muốn tách OCR khỏi backend chính;
• muốn scale worker riêng;
• muốn client viết bằng Java/Go/Node vẫn dùng OCR.

MCP Server cho AI agent

PaddleOCR có MCP Server để đưa OCR và document parsing vào ứng dụng LLM. Tài liệu nói MCP server nhẹ này giúp tích hợp text recognition, layout parsing và các năng lực khác vào ứng dụng large-model.¹²

Các tool/pipeline được hỗ trợ:

MCP phù hợp khi bạn muốn Claude Desktop, Cursor, OpenClaw hoặc agent khác có tool OCR.

Agent Skills

PaddleOCR cũng có official Agent Skills. Tài liệu nói Agent Skills đóng gói routing rules, calling steps, configuration requirements và best practices để AI app dùng OCR/document parsing ổn định hơn.¹³

Hai skill chính:

Cài bằng skills CLI:

npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-text-recognition -y
npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-doc-parsing -y

Nếu mạng chậm, clone repo rồi cài local:

git clone https://github.com/PaddlePaddle/PaddleOCR.git
npx skills add ./PaddleOCR/skills/paddleocr-text-recognition
npx skills add ./PaddleOCR/skills/paddleocr-doc-parsing

Tài liệu nêu yêu cầu Python 3.9+, PaddleOCR 3.6.0+ và access token từ AI Studio cho skills.¹⁴

Hướng dẫn triển khai cho cá nhân

Cách đơn giản nhất:

python -m venv .venv
source .venv/bin/activate

python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -m pip install paddleocr

Test:

paddleocr ocr -i ./image.png \
  --use_doc_orientation_classify False \
  --use_doc_unwarping False \
  --use_textline_orientation False \
  --engine paddle

Nếu cần full document parsing:

python -m pip install "paddleocr[all]"
paddleocr pp_structurev3 -i ./document.png --engine paddle

Hướng dẫn triển khai cho team

Giai đoạn 1: thử nghiệm local

• Chọn 20–50 tài liệu mẫu.
• Test PP-OCRv5 với ảnh đơn giản.
• Test PP-StructureV3 với PDF phức tạp.
• So sánh output JSON/Markdown.
• Ghi lại lỗi: mất dấu, sai thứ tự đọc, sai bảng, sai tiếng Việt, sai ảnh scan.

Giai đoạn 2: chuẩn hóa pipeline

• Chọn pipeline theo use case.
• Quy định input: DPI, kích thước ảnh, định dạng file.
• Lưu raw file, output JSON/Markdown và log.
• Gắn version model và version package.
• Thiết kế bước human review nếu output dùng cho nghiệp vụ quan trọng.

Giai đoạn 3: triển khai service

• Dùng PaddleX Serving hoặc FastAPI wrapper riêng.
• Chạy worker OCR tách khỏi backend chính.
• Giới hạn file size và timeout.
• Dùng hàng đợi nếu tài liệu lớn.
• Dùng GPU nếu throughput cao.
• Theo dõi latency, lỗi, memory, GPU utilization.

Giai đoạn 4: tích hợp RAG/agent

• Với RAG, lưu Markdown trung gian.
• Với AI agent, dùng MCP hoặc Agent Skills.
• Với dữ liệu nhạy cảm, ưu tiên local/self-hosted mode.
• Có cơ chế xóa file tạm sau xử lý.

Lưu ý bảo mật và production

OCR thường xử lý tài liệu nhạy cảm như CCCD, hóa đơn, hợp đồng, bảng lương hoặc báo cáo nội bộ. Khi triển khai PaddleOCR:

• không log toàn bộ nội dung OCR nếu có dữ liệu cá nhân;
• giới hạn file size và số trang PDF;
• chạy OCR trong container hoặc worker cô lập;
• scan file upload nếu nhận từ internet;
• kiểm soát quyền đọc/ghi thư mục;
• xóa file tạm;
• giới hạn timeout;
• không expose service OCR public nếu chưa có auth;
• dùng HTTPS và token auth;
• tách môi trường test/production;
• audit output nếu dùng cho quyết định pháp lý/tài chính;
• không mặc định tin 100% vào OCR confidence.

Khi nào nên dùng PaddleOCR?

Nên dùng khi:

• cần OCR offline/local;
• cần OCR nhiều ngôn ngữ;
• cần xử lý ảnh/PDF số lượng lớn;
• cần kết quả có tọa độ và confidence;
• cần document parsing sang Markdown/JSON;
• cần xây RAG từ tài liệu scan;
• cần tích hợp OCR vào AI agent;
• cần triển khai service riêng.

Không nên dùng một cách mù quáng khi:

• tài liệu quá mờ hoặc scan rất kém;
• cần kết quả pháp lý không có human review;
• không có tài nguyên phần cứng cho model nặng;
• chỉ cần OCR nhanh vài ảnh và không cần pipeline lớn;
• chưa có kiểm soát bảo mật cho tài liệu upload.

So sánh nhanh PaddleOCR với MarkItDown

Hai công cụ có thể bổ sung cho nhau: MarkItDown chuyển nhiều file số sang Markdown; PaddleOCR xử lý phần ảnh, scan, OCR và layout phức tạp.

FAQ

PaddleOCR là gì?

PaddleOCR là toolkit OCR và Document AI mã nguồn mở của PaddlePaddle, dùng để chuyển ảnh/PDF thành text, JSON, Markdown hoặc dữ liệu có cấu trúc cho LLM/RAG.²

PaddleOCR có hỗ trợ tiếng Việt không?

README nói PaddleOCR hỗ trợ 100+ ngôn ngữ. Với tiếng Việt, bạn nên test trực tiếp trên dữ liệu thật vì chất lượng phụ thuộc font, dấu, ảnh scan, model và cấu hình pipeline.²

Dùng PaddleOCR có cần GPU không?

Không bắt buộc cho thử nghiệm nhỏ; có thể chạy CPU. Nhưng với tài liệu lớn, model nặng hoặc throughput cao, GPU giúp tăng tốc đáng kể.

PP-OCRv5 khác PP-StructureV3 thế nào?

PP-OCRv5 tập trung nhận dạng chữ. PP-StructureV3 tập trung phân tích cấu trúc tài liệu như heading, paragraph, table, formula, image và xuất Markdown/structured output.³⁴

PaddleOCR-VL dùng để làm gì?

PaddleOCR-VL là dòng VLM cho document parsing, hỗ trợ nhiều ngôn ngữ và phần tử phức tạp như text, table, formula, chart, phù hợp tài liệu khó và layout phức tạp.⁵

PaddleOCR có MCP không?

Có. PaddleOCR MCP Server cung cấp tool ocr, pp_structurev3 và paddleocr_vl để tích hợp OCR/document parsing vào ứng dụng LLM.¹²

Kết luận

PaddlePaddle/PaddleOCR là một repo lớn và thực dụng nếu bạn cần OCR hoặc Document AI cho ảnh, PDF và tài liệu scan. Với người mới, hãy bắt đầu từ paddleocr ocr và Python API PaddleOCR(...).predict(). Khi cần giữ cấu trúc tài liệu, chuyển sang PP-StructureV3. Khi tài liệu phức tạp hơn và có hạ tầng phù hợp, xem PaddleOCR-VL.

Trong production, điểm quan trọng không chỉ là accuracy. Bạn cần kiểm soát input, output, file tạm, bảo mật dữ liệu, timeout, scaling, logging và human review cho các nghiệp vụ nhạy cảm. PaddleOCR rất mạnh, nhưng OCR vẫn là bước trích xuất xác suất, không nên xem là sự thật tuyệt đối nếu không có kiểm chứng.

Nguồn tham khảo

Footnotes

1. GitHub Open Graph preview image for PaddlePaddle/PaddleOCR. https://opengraph.githubassets.com/paddleocr-guide/PaddlePaddle/PaddleOCR ↩

2. GitHub. PaddlePaddle/PaddleOCR. https://github.com/PaddlePaddle/PaddleOCR ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶

3. PaddleOCR Documentation. “General OCR Pipeline Usage Tutorial.” https://www.paddleocr.ai/latest/en/version3.x/pipeline_usage/OCR.html ↩ ↩²

4. PaddleOCR Documentation. “PP-StructureV3 Usage Tutorial.” https://www.paddleocr.ai/latest/en/version3.x/pipeline_usage/PP-StructureV3.html ↩ ↩²

5. PaddleOCR Documentation. “PaddleOCR-VL Usage Tutorial.” https://www.paddleocr.ai/latest/en/version3.x/pipeline_usage/PaddleOCR-VL.html ↩ ↩²

6. PaddleOCR Documentation. “Quick Start.” https://www.paddleocr.ai/latest/en/quick_start.html ↩

7. PaddleOCR Documentation. “Installation.” https://www.paddleocr.ai/latest/en/version3.x/installation.html ↩

8. PaddleOCR Quick Start, command-line usage examples. https://www.paddleocr.ai/latest/en/quick_start.html ↩

9. PaddleOCR Quick Start, Python script usage examples. https://www.paddleocr.ai/latest/en/quick_start.html ↩

10. PaddleOCR Documentation. “Self-hosted Serving.” https://www.paddleocr.ai/latest/en/version3.x/inference_deployment/serving/serving.html ↩

11. PaddleOCR Serving docs, Basic Serving via PaddleX. https://www.paddleocr.ai/latest/en/version3.x/inference_deployment/serving/serving.html ↩

12. PaddleOCR Documentation. “MCP Server.” https://www.paddleocr.ai/latest/en/version3.x/integrations/mcp_server.html ↩ ↩²

13. PaddleOCR Documentation. “Agent Skills.” https://www.paddleocr.ai/latest/en/version3.x/integrations/skills.html ↩

14. PaddleOCR Agent Skills docs, prerequisites and installation. https://www.paddleocr.ai/latest/en/version3.x/integrations/skills.html ↩