از PDF فارسی تا جست‌وجوی صفحه‌محور؛ یک خط لولهٔ کوچک با کنترل کیفیت

برای PDFهای فارسیِ متن‌دار، متن هر صفحه را استخراج و نسخه‌ای نرمال‌شده برای جست‌وجو ذخیره می‌کنیم. این راهنما یک ابزار اجرایی می‌سازد و نشان می‌دهد چه زمانی باید فایل را به مسیر OCR یا بررسی دستی فرستاد.

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

قرارداد خط لوله: هر صفحه یک رکورد، نه یک تودهٔ متن

مسیر را به سه مرحله محدود می‌کنیم: استخراج متن با PyMuPDF، ساخت متن جست‌وجویی و ذخیرهٔ رکورد هر صفحه. هر رکورد شامل نام منبع، شمارهٔ صفحه با شمارش از یک، متن خام، متن جست‌وجویی و یک وضعیت ساده است. این مرزبندی باعث می‌شود نتیجهٔ جست‌وجو به صفحهٔ قابل‌مشاهده برگردد و بعداً بتوان مرحلهٔ استخراج را بدون تغییر قرارداد خروجی جایگزین کرد. هنگام انتقال خروجی میان سامانه‌ها، خود PDF را نیز همراه آن نگه دارید؛ نام فایل به‌تنهایی شناسهٔ یکتای پایدار نیست.

PDF معمولاً ترتیب منطقی خواندن را مانند یک سند متنی تضمین نمی‌کند. گزینهٔ sort=True در استخراج PyMuPDF به مرتب‌سازی مکانی متن کمک می‌کند، اما تضمین بازسازی ستون‌ها، جدول‌ها یا ترتیب راست‌به‌چپ نیست. ابتدا چند صفحهٔ نماینده، شامل صفحهٔ معمولی، جدول و متن دو‌ستونی را استخراج کنید و متن خام را با تصویر صفحه تطبیق دهید. اگر حروف نامفهوم یا ترتیب واژه‌ها خراب است، نرمال‌سازی درمان آن نیست.

نرمال‌سازی محدود: اختلاف نویسه را حل کنیم، نه معنای جمله را

برای نسخهٔ جست‌وجویی، NFKC را اجرا می‌کنیم، «ي» و «ك» را به «ی» و «ک» تبدیل می‌کنیم، کشیده و نشانه‌های ترکیبی را حذف می‌کنیم و ارقام عربی و فارسی را به ارقام لاتین می‌بریم. نیم‌فاصله به فاصله تبدیل می‌شود و فاصله‌های متوالی جمع می‌شوند. همین تابع باید روی پرس‌وجو هم اجرا شود؛ در غیر این صورت یکسان‌سازی فقط نیمی از مسیر را پوشش می‌دهد. تابع unicodedata.normalize و رده‌بندی نویسه‌ها در مستندات رسمی پایتون توضیح داده شده‌اند.

این سیاست عمداً محافظه‌کار است: «می‌رود» با «می رود» تطبیق پیدا می‌کند، ولی با «میرود» نه. حذف همهٔ فاصله‌ها ممکن است بازیابی بیشتری بدهد، اما مرز واژه‌ها را هم از بین می‌برد و تطبیق کاذب می‌سازد. حذف اعراب و NFKC نیز بخشی از تمایزهای نوشتاری را از بین می‌برند؛ به همین دلیل متن خام را نگه می‌داریم و متن نرمال‌شده را فقط نمایهٔ جست‌وجو می‌دانیم، نه نسخهٔ معتبر سند.

ابزار اجرایی: استخراج، آزمون نمونه و جست‌وجو

با پایتون ۳ در یک محیط مجازی شروع کنید. کد زیر را در فایل pdf_search.py ذخیره کنید. فرمان demo یک ورودی فارسی کنترل‌شده را از همان تابع نرمال‌سازی عبور می‌دهد و خروجی صفحه‌محور می‌سازد؛ بنابراین آزمون آن به داشتن PDF خاص وابسته نیست. این آزمون فقط قرارداد ذخیره‌سازی و جست‌وجو را می‌سنجد، نه کیفیت استخراج از PDF واقعی.

```bash
python -m venv .venv
# در لینوکس یا macOS:
source .venv/bin/activate
# در PowerShell ویندوز، به‌جای خط بالا:
# .venv\Scripts\Activate.ps1
python -m pip install pymupdf
```

```python
import argparse
import json
import re
import unicodedata
from pathlib import Path

TRANSLATION = str.maketrans({
'ي': 'ی', 'ك': 'ک', '\u200c': ' ', 'ـ': '',
**dict(zip('۰۱۲۳۴۵۶۷۸۹', '0123456789')),
**dict(zip('٠١٢٣٤٥٦٧٨٩', '0123456789')),
})


def normalize(text):
text = unicodedata.normalize('NFKC', text).translate(TRANSLATION)
text = ''.join(c for c in text if not unicodedata.category(c).startswith('M'))
return re.sub(r'\s+', ' ', text).strip()


def record(source, page, raw):
searchable = normalize(raw)
return {
'source': source,
'page': page,
'raw_text': raw,
'search_text': searchable,
'status': 'no_text' if not searchable else 'text_present',
}


def write_records(rows, output):
with open(output, 'w', encoding='utf-8') as handle:
for row in rows:
handle.write(json.dumps(row, ensure_ascii=False) + '\n')


def extract(pdf):
import pymupdf
with pymupdf.open(pdf) as document:
if document.needs_pass:
raise ValueError('Encrypted PDF: decrypt with authorization first')
for number, page in enumerate(document, start=1):
yield record(Path(pdf).name, number,
page.get_text('text', sort=True))


def search(index, query):
needle = normalize(query)
if not needle:
raise ValueError('Query is empty after normalization')
with open(index, encoding='utf-8') as handle:
for line in handle:
row = json.loads(line)
if needle in row['search_text']:
print(json.dumps({'source': row['source'], 'page': row['page']},
ensure_ascii=False))


def main():
parser = argparse.ArgumentParser()
commands = parser.add_subparsers(dest='command', required=True)
build = commands.add_parser('build')
build.add_argument('pdf')
build.add_argument('output')
demo = commands.add_parser('demo')
demo.add_argument('output')
find = commands.add_parser('search')
find.add_argument('index')
find.add_argument('query')
args = parser.parse_args()
if args.command == 'build':
if Path(args.pdf).resolve() == Path(args.output).resolve():
parser.error('Input and output paths must differ')
write_records(extract(args.pdf), args.output)
elif args.command == 'demo':
rows = [record('demo', 1, 'اين كتاب دربارهٔ پردازش PDF است.'),
record('demo', 2, 'شمارهٔ گزارش ۱۲۳ است.')]
write_records(rows, args.output)
else:
search(args.index, args.query)


if __name__ == '__main__':
main()
```

ورودی آزمون در فرمان demo شامل «اين كتاب» با ی و ک عربی و عدد «۱۲۳» است. دو پرس‌وجوی زیر به‌ترتیب یکسان‌سازی حروف و ارقام را بررسی می‌کنند. خروجی مورد انتظار، دو خط زیر است؛ هر فرمان یک خط چاپ می‌کند. اگر خروجی متفاوت بود، پیش از آزمون فایل واقعی، ذخیره‌شدن کد با UTF-8 و اجرای همان فایل را بررسی کنید.

```bash
python pdf_search.py demo demo.jsonl
python pdf_search.py search demo.jsonl 'این کتاب'
python pdf_search.py search demo.jsonl '123'
```

```other
{"source": "demo", "page": 1}
{"source": "demo", "page": 2}
```

اکنون یک PDF واقعی با نام report.pdf را کنار اسکریپت بگذارید و فرمان‌های زیر را اجرا کنید. فایل pages.jsonl باید به تعداد صفحات PDF رکورد داشته باشد؛ این فایل در هر ساخت بازنویسی می‌شود. نتیجهٔ جست‌وجوی «گزارش» وابسته به محتوای سند است و خروجی ثابت ندارد. برای بررسی کیفیت، raw_text چند رکورد را بخوانید و صفحهٔ متناظر را در نمایشگر PDF باز کنید.

```bash
python pdf_search.py build report.pdf pages.jsonl
python pdf_search.py search pages.jsonl 'گزارش'
```

دروازهٔ کیفیت: کجا متوقف شویم و کجا OCR لازم است؟

وضعیت no_text فقط می‌گوید متن جست‌وجویی خالی است؛ صفحه ممکن است اسکن، تصویر نمودار یا واقعاً سفید باشد. وضعیت text_present هم مهر تأیید کیفیت نیست: یک سربرگ متنی روی تصویر اسکن‌شده کافی است تا این وضعیت ثبت شود. بنابراین صفحات خالی از متن را بازبینی کنید و از صفحات دارای متن نیز نمونه بگیرید. اگر چند عبارت که در تصویر دیده می‌شوند در متن خام وجود ندارند، انتشار نمایه را متوقف کنید و علت را در استخراج یا لایهٔ متن پیدا کنید.

برای صفحهٔ تصویری، مسیر درست رندر صفحه به تصویر و اجرای OCR است، نه تکرار تابع استخراج متن. Tesseract دادهٔ زبان فارسی با شناسهٔ fas دارد؛ کیفیت تصویر، کجی و بخش‌بندی صفحه روی نتیجه اثر دارند. خروجی OCR را می‌توان وارد همین قرارداد صفحه‌محور کرد، اما باید روش استخراج را در نسخهٔ توسعه‌یافتهٔ رکورد ثبت کرد و کیفیت را دوباره سنجید. روی صفحات متن‌دار سالم، OCR انتخاب پیش‌فرض خوبی نیست: هزینهٔ پردازش و احتمال خطای تشخیص را اضافه می‌کند.

جست‌وجوی این نمونه هر بار کل JSONL را می‌خواند؛ مزیتش شفافیت و وابستگی کم است، نه سرعت در مقیاس بزرگ. وقتی پیمایش فایل برای کاربرد شما کند شد، همین متن نرمال‌شده و شناسهٔ صفحه را به یک نمایهٔ جست‌وجو منتقل کنید و سیاست نرمال‌سازی را ثابت و نسخه‌دار نگه دارید. این روش برای اثبات این‌که «عبارت در کدام صفحه است» مناسب است؛ برای تشخیص نبود قطعی یک بند حقوقی، بازیابی معنایی یا هایلایت دقیق روی تصویر کافی نیست، چون نه کامل‌بودن استخراج را تضمین می‌کند و نه مختصات واژه‌ها را نگه می‌دارد.

منابع

PyMuPDF — Text extraction recipes
https://pymupdf.readthedocs.io/en/latest/recipes-text.html
روش‌های استخراج متن و مرتب‌سازی مکانی خروجی.

Python — unicodedata
https://docs.python.org/3/library/unicodedata.html
مرجع نرمال‌سازی یونیکد و رده‌بندی نویسه‌ها.

Tesseract — OCR quality improvement
https://tesseract-ocr.github.io/tessdoc/ImproveQuality.html
عوامل مؤثر بر کیفیت تشخیص متن، از تصویر تا بخش‌بندی.

Tesseract — Official trained language data
https://github.com/tesseract-ocr/tessdata
مخزن داده‌های زبانی، از جمله فایل fas.traineddata برای فارسی.

No comments yet