راهنمای فارسی Bookly
گفتوگو با PDFهای فارسی و انگلیسی، همراه با ارجاع به صفحات منبع.
کتابخانه و جستوجو روی دستگاه خودت؛ مدل محلی یا ابری، به انتخاب خودت.
شروع سریع · اتصال مدل · تنظیمات · حریم خصوصی · رفع اشکال
Bookly یک دستیار RAG محلی و خودمیزبان برای کتابهای PDF خود شماست.
متن را استخراج میکند، در صورت نیاز OCR انجام میدهد و با جستوجوی هیبریدی، بخشهای مرتبط را برای پاسخگویی مدل پیدا میکند.
| PDFهای فارسی و انگلیسی، پوشههای دلخواه و پردازش افزایشی کتابها. | بازیابی معنایی و واژهای، با ترکیب قابل تنظیم و sparse اختیاری. | گفتوگوی جریانی با منبع شمارهدار و ارجاع به صفحهٔ کتاب. |
پاسخ از کتاب، نه صرفاً از حافظهٔ مدل.
Bookly برای پاسخگویی بر اساس متن بازیابیشده و اعلام نبود اطلاعات در کتابها طراحی شده است. با این حال، هیچ مدل زبانی کاملاً بیخطا نیست؛ پاسخهای مهم را با صفحات ارجاعشده تطبیق دهید.
flowchart TD
A["📚 کتابهای PDF"] --> B["استخراج متن + OCR در صورت نیاز"]
B --> C["تکهبندی"]
C --> D["ایندکس هیبریدی: Dense + BM25 + Sparse اختیاری"]
Q["💬 پرسش شما"] --> E["بازیابی و ترکیب نتایج: CC / Weighted RRF"]
D --> E
E --> F["مدل هوش مصنوعی محلی یا ابری"]
F --> G["📖 پاسخ + ارجاع به صفحه"]
classDef input fill:#251A13,stroke:#D4A373,color:#F3E5D0;
classDef process fill:#3A281D,stroke:#A47148,color:#F3E5D0;
classDef output fill:#6F442D,stroke:#D4A373,color:#FFF8EE;
class A,Q input;
class B,C,D,E,F process;
class G output;
| قابلیت | در Bookly چه میکند؟ |
|---|---|
| رابط وب دوزبانه | فارسی و انگلیسی، تم روشن و تاریک، تاریخچهٔ چت و نمایش جریانی پاسخ |
| بازیابی هیبریدی | Dense embeddings ⨁ BM25 ⨁ فهرست sparse اختیاری |
| ترکیب قابل تنظیم | Convex Combination یا RRF وزندار |
| ارجاع به صفحه | منابع شمارهدار مانند [1] همراه با عنوان کتاب و صفحه؛ قابل کلیک برای مراجعه به منبع |
| پنل مدیریت مدل | اتصال مدل سازگار با OpenAI بدون تغییر کد |
| مدل محلی یا ابری | Ollama، LM Studio، vLLM، OpenAI، OpenRouter و سرویسهای سازگار |
| پردازش فارسی | نرمالسازی نیمفاصله و حروف عربی، توکنساز فارسی BM25 |
| پشتیبانی از اسکن | OCR جایگزین برای صفحات نیازمند پردازش، همراه با کنترل کیفیت |
| sync افزایشی | تشخیص کتابهای جدید، تغییرکرده و حذفشده؛ ردکردن کتابهای بدون تغییر |
| شروع بدون embedding | ساخت ایندکس قابل جستوجوی واژهای با --no-embed |
| ادامهٔ پردازش M3 | checkpointing در backend نوع m3 برای ادامه پس از توقف |
| بازرتبهبندی اختیاری | cross-encoder؛ بهصورت پیشفرض خاموش و با توصیه به استفاده از GPU |
| نسخهٔ ترمینال | پرسش تکمرحلهای و محیط تعاملی با همان موتور |
| نمونهٔ آماده | یک کتاب کوچک و ایندکس واژهای آماده برای امتحان رابط پیش از sync کتابخانه |
- Python 3.11+؛ پروژه از
tomllibاستاندارد پایتون استفاده میکند. - کتابهای PDF فارسی یا انگلیسی.
- Tesseract OCR فقط برای PDFهای اسکنشده؛ PDFهای دارای متن قابل انتخاب، OCR را رد میکنند.
- مدل محلی یا سرویس ابری برای تولید پاسخ گفتوگویی.
برای راهاندازی OCR:
- Tesseract را نصب کنید. در ویندوز میتوانید از بیلدهای UB Mannheim استفاده کنید.
- فایلهای
fas.traineddataوeng.traineddataرا از tessdata_best دریافت کنید. - فایلهای زبان را در
app/tessdata/بگذارید. - در صورت نیاز، مسیر Tesseract را در
booksearch.tomlتنظیم کنید.
git clone https://github.com/Amin-Moniry/bookly.git
cd bookly
python -m venv .venvویندوز — PowerShell
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txtلینوکس / macOS
source .venv/bin/activate
python -m pip install -r requirements.txtدستورهای بعدی از ریشهٔ پروژه و با محیط مجازی فعال اجرا میشوند. در سیستمی که دستور Python با
python3در دسترس است، همان را جایگزین کنید.
PDFها را در library/ بگذارید:
library/
├── poetry-collection.pdf
├── ai-handbook.pdf
└── my-notes/
└── another-book.pdf
نام فایلها و زیرپوشهها میتواند فارسی یا انگلیسی باشد. نامهای بالا صرفاً نمونهاند.
python app/ingest.py syncروند پردازش:
extract → OCR if needed → chunk → embed → merge
ایندکس در index/ ساخته میشود.
برای شروع سریعتر
ابتدا ایندکس واژهای بسازید؛ embedding را بعداً اضافه کنید:
python app/ingest.py sync --no-embedسپس برای افزودن لایهٔ معنایی:
python app/ingest.py sync --force embedpython app/server.pyدر مرورگر باز کنید: http://127.0.0.1:8765
هنوز کتابی ایندکس نکردهاید؟
پروژه یک کتاب نمونه در
demo/sample-book.pdfو ایندکس واژهای آماده درindex/sample/دارد. برنامه تا پیش از اولین sync واقعی از نمونه استفاده میکند و سپس به کتابخانهٔ شما تغییر میکند.
از دکمهٔ ✨ AI models در هدر، مدل را اضافه و فعال کنید.
پرسش نمونه:
خلاصهٔ فصل سوم چیه؟
یا:
نویسنده در این کتاب چه دلایلی برای این موضوع آورده؟
پاسخها برای ارجاع به منابعی مانند [n] و صفحهٔ کتاب طراحی شدهاند. اگر اطلاعات مرتبط پیدا نشود، برنامه باید نبود پاسخ در کتابها را اعلام کند؛ این رفتار را نیز مانند خود پاسخ، در استفادههای حساس بررسی کنید.
پس از افزودن، تغییر یا حذف کتابها، دوباره اجرا کنید:
python app/ingest.py syncکتابهای بدون تغییر رد میشوند؛ فقط موارد نیازمند پردازش دوباره بررسی میشوند.
برنامه را باز کنید و روی ✨ AI models بزنید:
| فیلد | نمونهٔ محلی | نمونهٔ ابری |
|---|---|---|
| Base URL | Ollama: http://127.0.0.1:11434/v1LM Studio: http://127.0.0.1:1234/v1 |
https://api.openai.com/v1 یا میزبان سازگار دیگر |
| API Key | در تنظیمات معمول محلی خالی؛ وابسته به سرور | کلید سرویسدهندهٔ خودتان |
| Model ID | mistral یا qwen2.5:7b، در صورت نصب |
مثلاً gpt-4o-mini، در صورت ارائه توسط سرویس |
روی مدل کلیک کنید تا فعال شود. نام مدل فعال در هدر دیده میشود.
- Ollama / LM Studio / vLLM برای endpointهای محلی قابل استفادهاند.
- OpenAI / OpenRouter / میزبانهای سازگار برای اتصال ابری قابل استفادهاند.
- شناسهٔ مدل باید با مدل نصبشده یا مدل ارائهشده توسط سرویس مطابقت داشته باشد.
- سرور محلی مدل باید پیش از تست اتصال در حال اجرا باشد.
- Base URL را بدون پسوند
/chat/completionsوارد کنید.
Bookly به یک مدل مشخص مانند Qwen یا Mistral محدود نیست. مدل چت را از پنل انتخاب میکنید؛ backend جستوجو و embedding، تنظیم جداگانهای دارد.
پرسش تکمرحلهای:
python app/booker.py "یک سؤال دربارهٔ کتابهات"حالت تعاملی:
python app/booker.pyپیشفرضهای چت ترمینال در بخش [llm] فایل تنظیمات قرار دارند.
تنظیمات اصلی در booksearch.toml قرار دارند؛ توضیحات آن فارسی و انگلیسیاند.
| بخش | چه چیزی را کنترل میکند؟ |
|---|---|
[paths] |
مسیر library/ و index/ |
[extract] |
موتور OCR، DPI، workerهای موازی و کنترل کیفیت صفحات اسکنشده |
[chunk] |
اندازهٔ تکه، همپوشانی جملهها و سربرگ بخشها |
[embed] |
backend پیشفرض st یا گزینهٔ m3 برای کیفیت بالاتر |
[search] |
fusion با cc یا rrf، عمق جستوجو، آستانهها و تکههای همسایه |
[rerank] |
cross-encoder اختیاری؛ خاموش بهصورت پیشفرض، GPU توصیه میشود |
[llm] |
پیشفرضهای مدل در چت ترمینال |
کلید واقعی API را در این فایل ننویسید.
کلیدهای اضافهشده از پنل مدل در
app/llm_models.jsonذخیره میشوند؛ این فایل برای انتشار در Git نیست.
| انتخاب | نقش |
|---|---|
| مدل چت | تولید پاسخ از متن بازیابیشده؛ از پنل مدل انتخاب میشود |
| backend ایندکس | روش پردازش embedding؛ از بخش [embed] تنظیم میشود |
| روش fusion | ترکیب فهرستهای بازیابی؛ از بخش [search] تنظیم میشود |
st و m3 نام backend هستند، نه نام مدل چت. همچنین rrf تنها گزینهٔ ترکیب نیست؛ مقدار فعال را در تنظیمات نسخهٔ خودتان بررسی کنید.
زمانهای تقریبی برای یک PDF حدود ۳۰۰ صفحهای روی CPU لپتاپ معمولی، بدون GPU:
| حالت | PDF عمدتاً متنی | PDF اسکنشده با OCR |
|---|---|---|
اولین ایندکس با st — پیشفرض |
حدود ۵ تا ۱۵ دقیقه | حدود ۱۵ تا ۴۵ دقیقه |
اولین ایندکس با m3 — گزینهٔ کیفیت بالاتر |
حدود ۱ تا ۳ ساعت | حدود ۳ تا ۶ ساعت |
| sync مجدد | بدون تغییر معمولاً چند ثانیه؛ در صورت تغییر، پردازش همان کتابها | فقط کتابهای تغییرکرده پردازش میشوند |
- استخراج متن ساده در README پروژه حدود ۱ میلیثانیه برای هر صفحه برآورد شده است.
- برای OCR حدود ۱ تا ۳ ثانیه برای هر صفحه ذکر شده؛ اسکن معمولاً بخش کندتر است.
- با
--no-embedمیتوان برای ورودی مناسب، ایندکس متنی را در کمتر از یک دقیقه ساخت. - backend نوع
m3از checkpointing پشتیبانی میکند؛ اجرای دوباره میتواند پردازش قطعشده را ادامه دهد. - لازم نیست از همهٔ کتابخانه شروع کنید؛ ابتدا یک کتاب را ایندکس و امتحان کنید.
زمان واقعی به سختافزار، تعداد صفحات، کیفیت اسکن و تنظیمات بستگی دارد. این اعداد برای کل کتابخانه یا هر نوع PDF تضمین نمیشوند و زمان تولید پاسخ مدل را نشان نمیدهند.
| لایه | پشتیبانی |
|---|---|
| رابط کاربری | انگلیسی و فارسی، همراه با تم روشن و تاریک |
| متن فارسی | نرمالسازی نیمفاصله و حروف عربی |
| جستوجوی واژهای | توکنساز فارسی BM25 |
| کتابهای اسکنشده | OCR با دادههای زبان fas و eng |
| فایلها و پوشهها | نامهای فارسی یا انگلیسی و زیرپوشههای دلخواه |
کیفیت OCR به کیفیت اسکن و دادهٔ زبان بستگی دارد. اگر جستوجوی یک کتاب اسکنشده ضعیف است، ابتدا متن استخراجشده را بررسی کنید.
- PDFها و ایندکس جستوجو.
- استخراج، OCR، تکهبندی و بازیابی.
- کلیدهای پنل مدل در
app/llm_models.json. - تاریخچهٔ چت در
localStorageمرورگر شما.
پرسش و بخشهای مرتبط کتاب برای تولید پاسخ ممکن است به endpoint انتخابی ارسال شوند. پردازش و نگهداری آن داده تابع سیاستهای همان سرویس است.
برای inference روی دستگاه خودتان، از سرور مدل محلی استفاده کنید.
| مسیر | محتوا |
|---|---|
library/ |
PDFهای شخصی شما |
index/ |
ایندکس اصلی کتابخانه؛ index/sample/ نمونهٔ آماده و استثنای عمدی است |
app/llm_models.json |
تنظیمات مدل و کلیدهای API |
eval/questions.jsonl |
پرسشهای ارزیابی خصوصی که ممکن است از کتابها نقلقول کنند |
eval/results.jsonl |
نتایج ارزیابی خصوصی |
| فایلهای دادهٔ OCR | فایلهای زبان دانلودشده؛ از جمله دادههای مورد استفاده در app/tessdata/ |
نمونهٔ قابل انتشار قالب ارزیابی: eval/questions.sample.jsonl.
قبل از انتشار مخزن
git statusو تغییرات staged را بررسی کنید..gitignoreاز ثبت خودکار فایل جدید جلوگیری میکند؛ فایل از قبل trackشده را از Git یا تاریخچه حذف نمیکند. کلیدها، کتابها و دادههای شخصی را دستی هم بازبینی کنید.
python -m pytest tests -qدر README جدید پروژه، ۴۴ تست برای این حوزهها ذکر شده است:
| حوزه | پوشش |
|---|---|
| پردازش متن | نرمالسازی و tokenizer |
| بازیابی | ترکیب نتایج با RRF |
| پایداری ایندکس | پایداری شناسهٔ تکهها |
| sync افزایشی | افزودن، تغییر نام، ویرایش و حذف |
| ارزیابی | ابزار ارزیابی retrieval |
| ترمینال | رفتار CLI |
تعداد و نتیجهٔ فعلی تستها را با اجرای دستور بالا در نسخهٔ نصبشده بررسی کنید؛ عدد تست به معنی تضمین کیفیت پاسخ مدل نیست.
| نشانه | بررسی پیشنهادی |
|---|---|
| برای همهٔ سؤالها پاسخ پیدا نمیشود | وجود PDF در library/ را بررسی و python app/ingest.py sync را اجرا کنید |
| متن PDF اسکنشده نامفهوم است | نصب Tesseract، فایلهای fas و eng در app/tessdata/ و تنظیمات OCR را بررسی کنید؛ tesseract موتور پیشفرض است |
| چت پیام Server unreachable میدهد | سرور را با python app/server.py اجرا کنید |
| embedding روی CPU کند است | backend را روی st نگه دارید؛ m3 را برای نیازهای حساس به کیفیت انتخاب کنید |
| تست مدل ناموفق است | Base URL باید قبل از /chat/completions تمام شود؛ شناسهٔ مدل و کلید سرویس ابری را هم بررسی کنید |
| نیاز به ایندکس تازه دارید | دادههای لازم را پشتیبان بگیرید، ایندکس تولیدشده را حذف و sync را دوباره اجرا کنید |
- OCR لازم نیست روی همهٔ PDFها اجرا شود. کتاب دارای لایهٔ متن سالم میتواند مرحلهٔ OCR را رد کند.
- مراجعه به صفحه همچنان مهم است. ارجاع، راه بررسی پاسخ است؛ تضمین درستی خودکار پاسخ نیست.
bookly/
├── README.md # English guide
├── booksearch.toml # Main configuration
├── requirements.txt # Python dependencies
│
├── app/ # Server, search, ingest, chat, evaluation
│ ├── server.py # Local web server
│ ├── ingest.py # Library indexing and sync
│ ├── booker.py # Terminal chat
│ ├── web/
│ │ └── index.html # Single-file frontend; no build step
│ ├── tessdata/ # Downloaded OCR language data
│ └── llm_models.json # Local model settings and keys; git-ignored
│
├── static/
│ ├── main.png # Chat screenshot
│ └── Ai-Part.png # Model-panel screenshot
│
├── demo/
│ ├── sample-book.pdf # Small demo book
│ └── make_sample_book.py # Demo generator
│
├── library/ # Your PDFs; git-ignored
├── index/ # Generated library index
│ └── sample/ # Bundled demo keyword index
│
├── eval/ # Evaluation data
│ └── questions.sample.jsonl
├── tests/ # Pytest suite
├── docs/
│ └── dev-notes.md # Persian guide — this file
└── LICENSE # MIT
این درخت، مسیرهای اصلی توضیحدادهشده در راهنمای پروژه را نشان میدهد؛ فهرست کامل همهٔ فایلهای برنامه نیست.
| سؤال | پاسخ |
|---|---|
| بدون GPU هم کار میکند؟ | بله؛ backend پیشفرض st نقطهٔ شروع سریعتر است. نیاز مدل چت محلی به مدل انتخابی بستگی دارد. |
| حتماً به API ابری نیاز دارم؟ | خیر؛ میتوانید مدل محلی سازگار با OpenAI متصل کنید. |
| بدون embedding میتوانم شروع کنم؟ | بله؛ sync --no-embed ایندکس قابل جستوجوی واژهای میسازد. |
| PDF فارسی اسکنشده پشتیبانی میشود؟ | بله؛ با Tesseract و دادهٔ زبان فارسی، با کیفیت وابسته به اسکن. |
| با افزودن کتاب باید همه چیز را از اول بسازم؟ | خیر؛ sync افزایشی کتابهای بدون تغییر را رد میکند. |
| قبل از ایندکس کتابها میتوانم برنامه را ببینم؟ | بله؛ کتاب و ایندکس نمونه در مخزن وجود دارد. |
| پاسخها حتماً درستاند؟ | خیر؛ هدف، پاسخ مستند به کتاب است، اما بررسی صفحات برای ادعاهای مهم ضروری است. |
| تاریخچهٔ چت کجاست؟ | در localStorage مرورگر روی دستگاه شما. |
| فرانتاند به build نیاز دارد؟ | خیر؛ رابط در app/web/index.html قرار دارد. |
| نسخهٔ انگلیسی راهنما کجاست؟ | در README اصلی مخزن. |
منتشرشده تحت MIT License — متن کامل در LICENSE.
کتابخانهٔ خودت. مدل خودت. با سرعت خودت.
English README · شروع سریع · GitHub

