آموزش نصب Docling روی VPS؛ استخراج هوشمند متن، جدول، تصویر و ساختار PDF برای RAG و Document Intelligence

اگر قرار است اسناد PDF را به یک سیستم هوش مصنوعی بدهید، فقط استخراج متن کافی نیست. یک PDF واقعی ممکن است شامل عنوان، چند ستون، جدول، تصویر، نمودار، پاورقی، کد، فرمول و صفحات اسکن‌شده باشد. اگر همه این اطلاعات به یک متن ساده و نامرتب تبدیل شوند، بخش مهمی از ساختار سند قبل از رسیدن به مدل هوش مصنوعی از بین می‌رود.

Docling برای همین مرحله ساخته شده است؛ یعنی قبل از اینکه اطلاعات وارد LLM، RAG، Vector Database یا Agent شود، سند را تحلیل و به یک ساختار قابل استفاده برای ماشین تبدیل می‌کند. در این آموزش، Docling را روی سرور لینوکس نصب می‌کنیم، یک PDF واقعی را پردازش می‌کنیم، خروجی Markdown و JSON می‌گیریم، جدول‌ها را استخراج می‌کنیم، تصاویر را جدا می‌کنیم و در پایان مسیر استفاده از Docling در یک زیرساخت واقعی Document Intelligence را بررسی می‌کنیم.

Docling چیست و چرا برای پردازش PDF مهم است؟

Docling یک ابزار متن‌باز برای پردازش و درک ساختاری اسناد است که می‌تواند فرمت‌های مختلفی را پردازش کند و برای PDF قابلیت‌هایی مانند تشخیص Layout، ترتیب خواندن محتوا، ساختار جدول، تصاویر و OCR را در اختیار Pipeline قرار دهد. خروجی فقط یک متن خام نیست؛ Docling یک مدل سند ساختاریافته در اختیار برنامه قرار می‌دهد که می‌توان آن را به فرمت‌هایی مانند Markdown، HTML، JSON و فرمت‌های مناسب پردازش‌های بعدی تبدیل کرد.

در مستندات رسمی، Docling علاوه بر PDF از فرمت‌هایی مانند DOCX، PPTX، XLSX، HTML، تصاویر و چندین قالب دیگر نیز پشتیبانی می‌کند. برای پروژه‌های RAG نیز خروجی‌های Chunk و یکپارچه‌سازی با ابزارهای اکوسیستم هوش مصنوعی در نظر گرفته شده است.

بنابراین می‌توان Docling را یک Document Parser و Document Understanding Layer در نظر گرفت؛ لایه‌ای که بین فایل خام و سیستم هوش مصنوعی قرار می‌گیرد.

تفاوت Docling با تبدیل ساده PDF به متن چیست؟

تبدیل ساده PDF به TXT معمولاً فقط به دنبال پیدا کردن رشته‌های متنی است. مشکل زمانی ایجاد می‌شود که جایگاه متن، رابطه سلول‌های جدول، ترتیب ستون‌ها یا ارتباط تصویر و توضیح آن برای سیستم هوش مصنوعی اهمیت داشته باشد.

Docling در معماری یک سیستم هوش مصنوعی کجا قرار می‌گیرد؟

یکی از اشتباهات رایج این است که PDF مستقیماً وارد LLM شود. در یک معماری حرفه‌ای بهتر است سند ابتدا پردازش شود و بعد اطلاعات مناسب برای جست‌وجو، Embedding یا تولید پاسخ در اختیار سیستم قرار بگیرد.

در این معماری، Docling قرار نیست جای Vector Database یا LLM را بگیرد. وظیفه آن آماده‌سازی بهتر ورودی است. هرچه ورودی ساختاریافته‌تر باشد، مراحل بعدی نیز اطلاعات منظم‌تری دریافت می‌کنند.

پیش‌نیازهای نصب Docling روی VPS

برای این آموزش از یک سرور لینوکس استفاده می‌کنیم. Ubuntu برای مثال‌های زیر انتخاب شده، اما Docling روی Linux و معماری‌های x86_64 و arm64 نیز قابل نصب است.

مرحله اول؛ اتصال به سرور و بررسی سیستم

ابتدا با SSH به VPS متصل شوید و نسخه سیستم‌عامل و Python را بررسی کنید.

cat /etc/os-release
python3 --version
uname -m

در نسخه‌های جدید Docling، Python 3.9 دیگر پشتیبانی نمی‌شود و برای نصب جدید بهتر است از Python 3.10 یا بالاتر استفاده کنید.

مرحله دوم؛ نصب ابزارهای پایه Python

در Ubuntu می‌توانید ابزارهای پایه Python و محیط مجازی را نصب کنید:

apt update
apt install -y python3 python3-pip python3-venv

مرحله سوم؛ ساخت Virtual Environment برای Docling

توصیه می‌شود Docling را مستقیماً در محیط اصلی Python نصب نکنید. یک محیط مجازی بسازید تا کتابخانه‌های پروژه با سایر سرویس‌های سرور تداخل پیدا نکنند.

mkdir -p /opt/docling
cd /opt/docling

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

python -m pip install --upgrade pip setuptools wheel

اگر فعال شدن محیط مجازی موفق باشد، معمولاً نام محیط در ابتدای Prompt ترمینال دیده می‌شود.

مرحله چهارم؛ نصب Docling روی VPS

نصب اصلی بسیار ساده است و طبق مستندات رسمی می‌توان بسته docling را با pip نصب کرد.

pip install docling

در سرورهای Linux که هدف فقط استفاده CPU است، مستندات رسمی Docling نصب با Wheelهای CPU مربوط به PyTorch را نیز به عنوان یک گزینه پیشنهاد می‌کنند.

pip install docling --extra-index-url https://download.pytorch.org/whl/cpu

مرحله پنجم؛ تست نصب Docling

ابتدا بررسی کنید که CLI در دسترس است:

docling --help

سپس می‌توانید نسخه نصب‌شده را از محیط Python بررسی کنید:

python -c "import docling; print(docling.__version__)"

مرحله ششم؛ آماده کردن اولین PDF

فرض کنیم فایل شما در مسیر زیر قرار دارد:

/opt/docling/input/sample.pdf

پوشه‌های لازم را بسازید:

mkdir -p /opt/docling/input
mkdir -p /opt/docling/output

استخراج PDF با CLI

ساده‌ترین روش این است که فایل را مستقیماً به CLI بدهید:

docling /opt/docling/input/sample.pdf --output /opt/docling/output

CLI جدید Docling گزینه‌هایی برای تعیین فرمت خروجی، OCR، استخراج جدول، Pipeline، تصاویر و حتی Chunkهای مناسب RAG دارد.

گرفتن خروجی Markdown، JSON و HTML

برای یک Pipeline هوش مصنوعی معمولاً فقط یک خروجی کافی نیست. Markdown برای خواندن و پردازش متنی بسیار کاربردی است، JSON برای نگهداری ساختار سند مناسب‌تر است و HTML می‌تواند ساختار تصویری بیشتری را حفظ کند.

docling convert /opt/docling/input/sample.pdf \
  --to md \
  --to json \
  --to html \
  --output /opt/docling/output

Docling همچنین خروجی‌هایی مانند Text، DocTags، DocLang، Chunks و LaTeX را ارائه می‌کند. این تنوع زمانی مهم است که خروجی Docling مستقیماً وارد یک سرویس دیگر شود.

استخراج جدول‌های PDF با Docling

جدول یکی از بخش‌هایی است که تبدیل ساده PDF به متن معمولاً آن را خراب می‌کند. مثلاً اگر یک جدول قیمت پنج ستون داشته باشد، تبدیل خطی ممکن است ترتیب سلول‌ها را به هم بزند. Docling برای تشخیص و بازسازی ساختار جدول قابلیت اختصاصی دارد.

در CLI می‌توان استخراج جدول را فعال نگه داشت و در صورت نیاز حالت پردازش جدول را نیز تنظیم کرد.

docling convert /opt/docling/input/sample.pdf \
  --to md \
  --to json \
  --tables \
  --output /opt/docling/output

اگر بخواهید جدول را به شکل DataFrame پردازش کنید، API پایتون نیز امکان استخراج جدول و تبدیل آن به DataFrame را فراهم می‌کند.

استخراج جدول به CSV با Python

from pathlib import Path
import pandas as pd

from docling.document_converter import DocumentConverter

input_file = Path("/opt/docling/input/sample.pdf")
output_dir = Path("/opt/docling/output/tables")
output_dir.mkdir(parents=True, exist_ok=True)

converter = DocumentConverter()
result = converter.convert(input_file)

for index, table in enumerate(result.document.tables, start=1):
    df = table.export_to_dataframe()
    df.to_csv(
        output_dir / f"table-{index}.csv",
        index=False
    )

print("Table extraction completed.")

این روش برای زمانی مناسب است که بعد از استخراج PDF می‌خواهید جدول‌ها را وارد PostgreSQL، Pandas، Data Warehouse یا یک سیستم تحلیل داده کنید.

استخراج تصاویر، شکل‌ها و نمودارهای داخل PDF

Docling فقط متن را پردازش نمی‌کند. می‌توان تصاویر و عناصر تصویری سند را نیز استخراج کرد. این قابلیت برای PDFهای فنی، کاتالوگ‌ها، گزارش‌های سازمانی، مقالات علمی و اسنادی که نمودار یا شکل دارند اهمیت زیادی دارد.

در API، PictureItem و TableItem قابل پیمایش هستند و می‌توان تصویر عنصر را استخراج و در فایل جداگانه ذخیره کرد.

from pathlib import Path

from docling.document_converter import DocumentConverter
from docling_core.types.doc import PictureItem

input_file = Path("/opt/docling/input/sample.pdf")
output_dir = Path("/opt/docling/output/images")
output_dir.mkdir(parents=True, exist_ok=True)

converter = DocumentConverter()
result = converter.convert(input_file)

counter = 0

for element, _level in result.document.iterate_items():
    if isinstance(element, PictureItem):
        image = element.get_image(result.document)

        if image:
            counter += 1
            image.save(
                output_dir / f"picture-{counter}.png",
                "PNG"
            )

print(f"Exported {counter} pictures.")

حفظ تصویر داخل Markdown یا به صورت فایل جداگانه

Docling برای خروجی Markdown و HTML حالت‌های مختلفی برای تصاویر دارد. می‌توانید تصویر را در خروجی Embed کنید یا به صورت فایل جداگانه ذخیره کرده و به آن Reference بدهید.

docling convert /opt/docling/input/sample.pdf \
  --to md \
  --image-export-mode referenced \
  --output /opt/docling/output

حالت Reference برای Pipelineهایی که نمی‌خواهند Base64 تصاویر داخل JSON یا Markdown قرار بگیرد، معمولاً مدیریت ساده‌تری دارد.

پردازش PDFهای اسکن‌شده با OCR

اگر PDF از اسکن صفحات ساخته شده باشد، ممکن است Text Layer واقعی نداشته باشد. در چنین شرایطی OCR لازم است. Docling از چند موتور OCR پشتیبانی می‌کند؛ از جمله Tesseract، EasyOCR و RapidOCR.

یکی از مزیت‌های مهم این معماری این است که OCR را می‌توان به عنوان بخشی از Pipeline پردازش سند در نظر گرفت، نه اینکه قبل از هر پروژه مجبور باشید یک سیستم کاملاً جدا برای OCR بسازید.

نصب Tesseract در Ubuntu

apt update
apt install -y tesseract-ocr tesseract-ocr-eng libtesseract-dev libleptonica-dev pkg-config

اگر سند شما فارسی است، زبان فارسی Tesseract را نیز روی سیستم نصب کنید:

apt install -y tesseract-ocr-fas

سپس زبان‌های نصب‌شده را بررسی کنید:

tesseract --list-langs

Docling زبان OCR را می‌تواند با کد زبان موتور انتخاب‌شده یا با قالب BCP-47 و پیشوند iso: دریافت کند. بنابراین در پروژه‌های چندزبانه باید زبان OCR را متناسب با سند انتخاب کنید.

فعال کردن OCR در CLI

docling convert /opt/docling/input/scanned.pdf \
  --to md \
  --ocr \
  --ocr-lang fas \
  --output /opt/docling/output

OCR اجباری برای PDFهای مشکل‌دار

گاهی PDF یک Text Layer ناقص دارد، اما اطلاعات واقعی صفحات بیشتر به صورت تصویر هستند. در این شرایط می‌توانید OCR را به صورت اجباری اجرا کنید.

docling convert /opt/docling/input/problem.pdf \
  --to md \
  --force-ocr \
  --ocr-lang fas \
  --output /opt/docling/output

از force OCR بهتر است فقط زمانی استفاده کنید که واقعاً لازم باشد؛ چون OCR کامل می‌تواند زمان پردازش را افزایش دهد و در اسناد دارای Text Layer مناسب، استخراج مستقیم متن معمولاً انتخاب منطقی‌تری است.

ساخت Pipeline با Python به جای CLI

اگر قرار است Docling بخشی از یک سرویس واقعی باشد، بهتر است از API پایتون استفاده کنید. در این حالت می‌توانید فایل را از کاربر دریافت کنید، تبدیل را انجام دهید، خروجی را در Storage ذخیره کنید و سپس آن را وارد مرحله Chunking یا Embedding کنید.

from pathlib import Path

from docling.document_converter import DocumentConverter

input_file = Path("/opt/docling/input/sample.pdf")
output_file = Path("/opt/docling/output/document.md")

converter = DocumentConverter()
result = converter.convert(input_file)

markdown = result.document.export_to_markdown()
output_file.write_text(markdown, encoding="utf-8")

print(f"Saved: {output_file}")

مستندات رسمی Docling نیز الگوی اصلی کار را به صورت تبدیل Source به DoclingDocument و سپس استفاده از خروجی آن توضیح می‌دهند.

ساخت JSON ساختاریافته برای پردازش هوش مصنوعی

یکی از مهم‌ترین تفاوت‌های Docling با استخراج متن ساده، امکان نگهداری ساختار سند است. در پروژه‌هایی که بعداً نیاز به تحلیل دقیق‌تر دارید، JSON می‌تواند از یک فایل Markdown ساده ارزشمندتر باشد.

from pathlib import Path

from docling.document_converter import DocumentConverter

input_file = Path("/opt/docling/input/sample.pdf")
output_file = Path("/opt/docling/output/document.json")

converter = DocumentConverter()
result = converter.convert(input_file)

result.document.save_as_json(output_file)

print(f"Saved: {output_file}")

JSON ساختاریافته می‌تواند برای نگهداری اطلاعات سند، پردازش اختصاصی، استخراج Metadata یا ساخت Pipelineهای چندمرحله‌ای مورد استفاده قرار گیرد.

Docling و RAG؛ چرا قبل از Embedding باید به ساختار سند اهمیت داد؟

در RAG، کیفیت Retrieval فقط به مدل Embedding وابسته نیست. اگر ورودی اولیه خراب باشد، Embedding نیز روی اطلاعات ناقص یا نامرتب ساخته می‌شود.

فرض کنید یک PDF شامل این اطلاعات باشد:

اگر همه این موارد به یک متن درهم تبدیل شوند، ارتباط بین بخش‌ها ضعیف می‌شود. اما اگر ساختار سند حفظ شود، می‌توان برای هر بخش Metadata و Chunk مناسب‌تری ساخت.

استفاده از Chunkهای آماده Docling برای RAG

CLI جدید Docling گزینه‌ای برای خروجی Chunk دارد و می‌توان نوع Chunking، حداکثر Token و Tokenizer را مشخص کرد. این موضوع باعث می‌شود Docling فقط یک PDF Parser نباشد و بتواند مستقیماً در مرحله آماده‌سازی داده برای RAG نیز نقش داشته باشد.

docling convert /opt/docling/input/sample.pdf \
  --to chunks \
  --chunks-type hybrid \
  --output /opt/docling/output

باکس پیشنهادی؛ سرور مناسب برای اجرای Docling

اگر Docling روی سرور کند است چه کار کنیم؟

کندی پردازش همیشه به معنی خراب بودن Docling نیست. ابتدا باید مشخص کنید Bottleneck در کدام بخش قرار دارد.

چگونه مصرف منابع Docling را بررسی کنیم؟

هنگام اجرای یک فایل PDF، در یک SSH دیگر وضعیت منابع سرور را مشاهده کنید:

htop

برای بررسی RAM:

free -h

و برای مشاهده فضای دیسک:

df -h

خطای کمبود حافظه هنگام پردازش PDF

اگر هنگام پردازش PDFهای بزرگ با OOM یا توقف ناگهانی Python مواجه شدید، ابتدا مصرف RAM و Swap را بررسی کنید. در یک VPS با RAM محدود، پردازش چند فایل بزرگ به صورت هم‌زمان می‌تواند فشار زیادی ایجاد کند.

free -h
swapon --show
dmesg -T | grep -i -E "oom|killed process"

اگر منابع برای پروژه واقعی کافی نیست، کاهش هم‌زمانی یا انتخاب VPS با RAM بیشتر معمولاً از اجرای دائمی Pipeline روی یک سرور کم‌منبع منطقی‌تر است.

اجرای Docling به عنوان سرویس API

اگر چند برنامه مختلف قرار است PDF به Docling ارسال کنند، بهتر است به جای نصب جداگانه Docling در هر پروژه، آن را به عنوان یک سرویس پردازش اسناد در نظر بگیرید. اکوسیستم Docling برای اجرای سرویس و API نیز ابزارهایی دارد و می‌توان فایل را از طریق HTTP برای تبدیل ارسال کرد.

در این معماری، مثلاً پنل مدیریت اسناد فایل را دریافت می‌کند، آن را به سرویس Docling می‌فرستد، خروجی ساختاریافته را تحویل می‌گیرد و سپس آن را برای Chunking و Embedding ارسال می‌کند.

چه زمانی GPU برای Docling لازم می‌شود؟

برای نصب پایه Docling الزاماً به GPU نیاز ندارید. اما برخی Pipelineهای Vision و VLM می‌توانند از GPU استفاده کنند و برای پردازش سنگین تصویر یا مدل‌های Vision، GPU می‌تواند تفاوت قابل توجهی ایجاد کند.

در مستندات رسمی، برای برخی نمونه‌های استخراج جدول مبتنی بر Granite Vision نیز GPU توصیه شده است؛ CPU همچنان ممکن است کار کند اما پردازش می‌تواند بسیار کندتر شود.

Docling برای چه پروژه‌هایی مناسب است؟

Docling برای چه کاری ساخته نشده است؟

Docling خودش یک LLM یا ChatGPT خصوصی نیست. وظیفه اصلی آن پردازش و ساختارسازی اسناد است. بنابراین اگر هدف شما ساخت یک سیستم پرسش و پاسخ است، Docling تنها یکی از اجزای معماری خواهد بود.

یک سیستم کامل می‌تواند Docling را در کنار Embedding Model، Vector Database، Retriever و LLM قرار دهد. در چنین ساختاری، هر ابزار یک وظیفه مشخص دارد و Docling مسئول آماده‌سازی بهتر سند است.

امنیت در اجرای Docling روی VPS

اگر اسناد خصوصی شرکت را روی VPS پردازش می‌کنید، یکی از مزیت‌های اجرای محلی این است که Pipeline پردازش می‌تواند روی زیرساخت خودتان قرار داشته باشد. با این حال، امنیت فقط به نصب محلی محدود نمی‌شود.

عیب‌یابی خطاهای رایج نصب Docling

خطای نصب PyTorch یا ناسازگاری Wheel

Docling به PyTorch وابستگی دارد. اگر معماری سرور یا نیاز CPU/GPU خاصی دارید، Wheel مناسب PyTorch اهمیت پیدا می‌کند. در Linuxهای CPU-only، استفاده از Index مربوط به نسخه CPU می‌تواند گزینه مناسبی باشد.

دستور docling پیدا نمی‌شود

which python
which pip
which docling

source /opt/docling/.venv/bin/activate

OCR اجرا نمی‌شود

ابتدا موتور OCR و زبان مورد نیاز را بررسی کنید. در Tesseract، فایل زبان باید واقعاً روی سیستم نصب شده باشد. Docling زبان‌های OCR را بر اساس موتور انتخاب‌شده بررسی می‌کند.

tesseract --list-langs

PDF تبدیل می‌شود اما جدول خراب است

کیفیت PDF، پیچیدگی جدول، نوع Backend و Pipeline انتخاب‌شده روی نتیجه تأثیر دارند. اگر جدول برای پروژه حیاتی است، خروجی را با PDF اصلی مقایسه کنید و صرفاً به یک تبدیل موفق اکتفا نکنید.

PDF فارسی به‌درستی خوانده نمی‌شود

ابتدا مشخص کنید PDF دارای Text Layer واقعی است یا اسکن‌شده. در حالت اسکن، OCR مناسب و زبان صحیح اهمیت زیادی دارد. همچنین باید خروجی را از نظر ترتیب خواندن، حروف فارسی، جدول‌ها و ستون‌ها بررسی کنید.

بهترین روش تست Docling بعد از نصب

به جای اینکه فقط یک PDF ساده را آزمایش کنید، یک فایل واقعی و پیچیده انتخاب کنید که چند نوع محتوا داشته باشد:

سپس خروجی Markdown، JSON، تصاویر و جدول‌ها را با سند اصلی مقایسه کنید. این تست بهتر از بررسی صرفاً سرعت اجرای یک فایل PDF ساده است.

Docling و انتخاب سرور؛ چه منابعی برای پروژه واقعی لازم است؟

برای یک پروژه شخصی کوچک ممکن است VPS با منابع متوسط کافی باشد؛ اما معماری سازمانی داستان متفاوتی دارد. اگر هم‌زمان Docling، Vector Database، Embedding Server، API، Storage و LLM را روی یک ماشین اجرا کنید، مجموع مصرف منابع باید بررسی شود.

باکس رفع مشکل و کانفیگ سرور

منابع رسمی Docling

برای بررسی نسخه‌های جدید، گزینه‌های CLI و تغییرات API، بهتر است مستندات رسمی پروژه را ملاک قرار دهید:

🔹 مستندات رسمی Docling

🔹 راهنمای نصب رسمی Docling

🔹 مخزن رسمی Docling در GitHub

جمع‌بندی؛ آیا نصب Docling روی VPS ارزش دارد؟

سؤالات متداول درباره نصب و اجرای Docling