استخراج المحتوى النصي باستخدام NextPDF Connect (Pro)

لمحة سريعة

استخدم extract_text لاستخراج النص من ملف ⁨PDF⁩ موجود لأغراض الفهرسة أو التحليل أو المعالجة اللاحقة. يُسجّل مزوّد أدوات ⁨Pro⁩ الكائن new ExtractTextTool() تحت اسم البروتوكول extract_text، وتتحقّق هذه الصفحة من ذلك الربط. extract_text أداة من مستوى ⁨Pro.⁩ عند الإقلاع، يفحص الخادم ذلك عبر class_exists() ولا يسجّلها إلا عند تثبيت حزمة ⁨Pro.⁩ يمكنك طلب مخرجات عادية، أو حصر الاستخراج في نطاق صفحات، أو طلب مخرجات منظَّمة مقسّمة حسب الصفحات.

التثبيت

composer require nextpdf/server
composer require nextpdf/pro

اربط وسيلة نقل. قبل الاعتماد على الأداة، تأكّد من توفّرها عبر diagnostic.capabilities.

نظرة مفاهيمية عامة

يقرأ الاستخراج معاملات إظهار النص من دفق المحتوى وفق ترتيب الدفق (⁨ISO 32000-2⁩ §9.4). تعكس المخرجات ترتيب القراءة المُرمَّز (⁨ISO 32000-2⁩ §9.10). قد لا يُرجع ملف ⁨PDF⁩ ممسوح ضوئيًا بلا طبقة نصية إلا نصًا قليلًا، أو قد لا يُرجع أي نص على الإطلاق. وهذا يعكس حالة الملف المصدري، وليس خللًا في الأداة. format: "plain" يُعيد سلسلة نصية واحدة. format: "structured" يُعيد كائنات لكل صفحة مع عدد الأحرف. page_range يقصر المعالجة على الصفحات المحدّدة.

واجهة ⁨API⁩

الأداة	المستوى	الدور	مستوى الخطورة
`extract_text`	⁨Pro⁩	استخراج النص (عادي / منظَّم / نطاق)	آمنة
`parse_pdf`	⁨Core⁩ (مُقيَّدة ببيئة التشغيل)	البنية منخفضة المستوى (عدد الصفحات، البيانات الوصفية)	آمنة

أسماء الأدوات هي أسماء البروتوكول في السجلّ. كتالوج الأدوات هو الكتالوج المرجعي المعتمد. يتوقف توفّر الأدوات على المستوى المثبّت.

نموذج التعليمات البرمجية — بداية سريعة

extract_text مع source (مسار قابل للقراءة من الخادم) وformat: "plain".
extract_text مع page_range: "1-3" لمجموعة فرعية.
extract_text مع format: "structured" للمخرجات المقسّمة حسب الصفحات.

نموذج التعليمات البرمجية — بيئة الإنتاج

استخدم parse_pdf (أو استدعاءً سابقًا غير محدود لـ extract_text) للحصول على عدد الصفحات قبل طلب نطاق. للتوليد المعزّز بالاسترجاع (⁨RAG⁩) أو الفهرسة، يُفضَّل format: "structured" بحيث تُجزَّأ كل صفحة على حدة. إذا كان المصدر مشفَّرًا، زوِّد مُعامِل كلمة المرور. أعداد الأحرف هي أعداد نقاط الترميز ⁨UTF-8⁩، وليست وحدات بايت.

الحالات الحدّية والمزالق

المصدر مفقود. يُعيد المسار غير الصالح خطأ يفيد بعدم العثور على الملف. استخدم مسارات مطلقة يستطيع الخادم قراءتها.
ملف ⁨PDF⁩ ممسوح ضوئيًا. من دون طبقة نصية، يُعيد الاستخراج نصًا فارغًا أو شبه فارغ. شغّل التعرّف الضوئي على الحروف (⁨OCR⁩) على المصدر أولًا.
صفحة خارج النطاق. يُرفَض النطاق الذي يتجاوز المستند مع إرجاع عدد الصفحات الفعلي.
مصدر مشفَّر. زوِّد مُعامِل كلمة المرور.
غياب ⁨Pro.⁩ عند استخدام ⁨Core⁩ وحدها، لا تُسجَّل extract_text. افحص عبر diagnostic.capabilities.

الأداء

يتناسب الاستخراج مع حجم المستند، وتستوعب الميزانية مدخلات كبيرة. يكون ملف التعريف structural لأي ناتج يُنشأ لأن هذه الأداة تُعيد نصًا، وليس ملف ⁨PDF.⁩

ملاحظات أمنية

قد يحتوي النص المُستخرَج على محتوى حسّاس. عامِل النتيجة على أنها سرّية، ولا تُرجِعها إلا عبر قناة موثوقة. لا تملك الأداة صلاحية الكتابة في نظام الملفات. تقرأ مسار المصدر بصلاحيات الخادم، لذا قيّد المسارات التي يجوز للمستدعي تمريرها.

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
يُظهَر النص بواسطة معاملات النص بترتيب الدفق.	⁨ISO 32000-2⁩	§9.4
يعكس الاستخراج ترتيب القراءة المُرمَّز.	⁨ISO 32000-2⁩	§9.10

لا تؤكّد هذه الوصفة أن النص المُستخرَج يحافظ بدقّة على ترتيب القراءة المنطقي لمستند غير موسوم. الترتيب هو الترتيب المُرمَّز.

السياق التجاري

extract_text أداة من مستوى ⁨Pro⁩، لا تُسجَّل إلا عند توفّر حزمة ⁨Pro⁩ عند إقلاع الخادم.

توفّر وسائل النقل

وسيلة النقل	متاحة	ملاحظات
⁨MCP⁩ (⁨stdio⁩)	نعم (⁨Pro⁩)	يزيد النص الكبير حجم إطار ⁨stdio.⁩
⁨REST⁩	نعم (⁨Pro⁩)	دفّق النتائج الكبيرة حيثما كان ذلك مدعومًا.
⁨gRPC⁩	نعم (⁨Pro⁩)	تنطبق حدود حجم الرسالة على النص الكبير.

مستوى خطورة ⁨HITL⁩

extract_text آمنة (للقراءة فقط، بلا آثار جانبية) ولا تطلب موافقة أبدًا.

غلاف ⁨JSON⁩ لبوّابة التأكيد

لا يطلب الاستخراج المخصص للقراءة فقط موافقة أبدًا:

{ "allowed": true }