تلخيص ملفات PDF باستخدام بايثون — دليل واجهة برمجة تطبيقات تلخيص PDF

المتطلبات الأساسية

• بايثون 3.8+ ومكتبة requests (pip install requests).
• مفتاح API: أنشئ حساباً مجانياً وانسخ مفتاحك من لوحة التحكم. احفظه في متغير بيئي بدلاً من تضمينه في الكود:

export PDF_SUMMARIZE_KEY="sk_live_..."

أول ملخص PDF لك باستخدام بايثون

import os
import requests

API_URL = "https://pdf-summarize.com/api/summarize.php"
API_KEY = os.environ["PDF_SUMMARIZE_KEY"]

def summarize_pdf(path, length="medium", fmt="bullets", lang="auto"):
    with open(path, "rb") as f:
        resp = requests.post(
            API_URL,
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"file": (os.path.basename(path), f, "application/pdf")},
            data={"length": length, "format": fmt, "outputLang": lang, "includeKeywords": "1"},
            timeout=180,
        )
    data = resp.json()
    if resp.status_code != 200 or not data.get("success"):
        raise RuntimeError(f"{resp.status_code}: {data.get('error', data)}")
    return data

result = summarize_pdf("annual-report.pdf")
print(result["summary"])
print("الصفحات:", result["page_count"], "| الكلمات الرئيسية:", result.get("keywords"))

الاستجابة

{
  "success": true,
  "summary": "- نمت الإيرادات بنسبة 6% لتصل إلى...",
  "keywords": "الإيرادات، الهامش، التوجيهات،...",
  "page_count": 48,
  "original_length": 182340,
  "summary_length": 1210,
  "processing_time": 6.214,
  "requests_remaining": 4987
}

حقل requests_remaining يمثل حصتك الشهرية المتبقية (القيمة -1 تعني بلا حدود).

بث الملخص (Streaming)

للمستندات الطويلة أو التطبيقات التفاعلية، قم ببث الملخص أثناء توليده:

import json

def stream_summary(path):
    with open(path, "rb") as f:
        with requests.post(
            API_URL + "?stream=1",
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"file": (os.path.basename(path), f, "application/pdf")},
            data={"length": "long", "format": "mixed"},
            stream=True, timeout=300,
        ) as resp:
            resp.raise_for_status()
            for line in resp.iter_lines(decode_unicode=True):
                if not line or not line.startswith("data: "):
                    continue
                payload = line[6:]
                if payload == "[DONE]":
                    break
                event = json.loads(payload)
                if "error" in event:
                    raise RuntimeError(event["error"])
                if event.get("type") == "summary":
                    print(event["content"], end="", flush=True)

stream_summary("research-paper.pdf")

معالجة مجلد كامل من ملفات PDF

import pathlib, time

out_dir = pathlib.Path("summaries")
out_dir.mkdir(exist_ok=True)

for pdf in sorted(pathlib.Path("pdfs").glob("*.pdf")):
    target = out_dir / (pdf.stem + ".md")
    if target.exists():
        continue                      # يدعم استئناف المعالجة
    for attempt in range(3):
        try:
            data = summarize_pdf(str(pdf), length="long", fmt="mixed")
            target.write_text(data["summary"], encoding="utf-8")
            print("تم بنجاح", pdf.name, data["page_count"], "صفحة")
            break
        except RuntimeError as e:
            if str(e).startswith("429"):
                time.sleep(30 * (attempt + 1))   # تجاوز الحد: الانتظار ثم إعادة المحاولة
            else:
                print("فشل", pdf.name, e)
                break

الأخطاء التي يجب التعامل معها

نصائح هامة

• اضبط مهلة الانتظار (Timeouts) بسخاء (2-3 دقائق) لملفات PDF الطويلة.
• خزن النتائج مؤقتاً (Cache) باستخدام تجزئة الملف (File Hash) لتجنب دفع التكلفة مرتين لنفس المستند.
• حافظ على سرية المفاتيح في الخادم الخلفي — ولا تضمنها أبداً في تطبيقات الواجهة الأمامية أو الجوال.
• للتعرف على كافة المعلمات: راجع توثيق واجهة برمجة التطبيقات.

الأسئلة الشائعة