مستند واجهة برمجة تطبيقات DeepSeek-OCR للتعرّف البصري على النصوص (OCR)

توفر هذه الواجهة وظيفة التعرّف على النصوص في الصور (OCR) بالاعتماد على نموذج DeepSeek-OCR. تعتمد هذه الـ API تنسيق الإكمالات الحوارية (Chat Completions) المتوافق مع OpenAI، وتدعم رفع الصور عبر الرابط URL أو عبر ترميز Base64 وتحويلها إلى نص أو إلى تنسيق Markdown.

نطاق الخدمة: https://api.codingplanx.ai
مسار الواجهة: /v1/chat/completions
طريقة الطلب: POST
حالة الواجهة: تم الإصدار (Released)

1. معاملات الطلب

1.1 ترويسات الطلب (Headers)

اسم المعامل	مطلوب	النوع	قيمة مثال	الوصف
Content-Type	نعم	String	`application/json`	تنسيق جسم الطلب
Accept	نعم	String	`application/json`	تنسيق جسم الاستجابة
Authorization	نعم	String	`Bearer YOUR_API_KEY`	مفتاح API المستخدم للمصادقة

1.2 جسم الطلب (Request Body)

اسم المعامل	مطلوب	النوع	الوصف
model	نعم	String	معرّف النموذج المستخدم، ولأغراض OCR يجب تحديده على أنه `deepseek-ocr`
messages	نعم	Array	قائمة الرسائل التي تحتوي على محتوى المحادثة. بالنسبة لـ OCR، يجب تضمين معلومات الصورة داخل الرسائل.
stream	لا	Boolean	القيمة الافتراضية هي `false`. إذا كانت `true` فسيتم إرجاع الاستجابة بشكل متدفق.
temperature	لا	Number	درجة حرارة أخذ العينات (0-2). القيم المنخفضة تكون أكثر تركيزًا واستقرارًا، والقيم الأعلى أكثر عشوائية.
top_p	لا	Number	عتبة احتمال أخذ العينات النواتية (nucleus sampling).
max_tokens	لا	Integer	الحد الأقصى لعدد الـ Token التي سيتم توليدها.
response_format	لا	Object	يحدد تنسيق الإرجاع، مثل `{"type": "json_object"}` لتفعيل وضع JSON.
tools	لا	Array	قائمة الأدوات التي يمكن للنموذج استدعاؤها (حاليًا يدعم بشكل أساسي استدعاء الدوال).

2. أمثلة الطلب

2.1 طلب OCR للتعرّف على الصور (JSON)

{
  "model": "deepseek-ocr",
  "stream": false,
  "messages": [
    {
      "role": "system",
      "content": "<image>\r
OCR مجاني."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://s3.ffire.cc/files/pdf_to_markdown.jpg" 
          }
        }
      ]
    }
  ]
}

ملاحظة: يدعم الحقل image_url.url تمرير رابط عام مباشر للصورة، أو تمرير سلسلة بيانات مرمزة بـ Base64 (بصيغة مثل: data:image/jpeg;base64,...).

3. شرح الاستجابة

3.1 بنية جسم الاستجابة

الحقل	النوع	الوصف
id	String	المعرّف الفريد لهذا الطلب.
object	String	نوع الكائن، وعادةً يكون `chat.completion`.
created	Integer	طابع زمني Unix (بالثواني).
choices	Array	يحتوي على عدة خيارات ناتجة.
└─ message	Object	الرسالة التي أعادها النموذج، وتتضمن `role` و`content`.
└─ finish_reason	String	سبب التوقف (مثل `stop` أو `length`).
usage	Object	إحصاءات استخدام الـ Token، وتشمل Tokens الخاصة بالموجّه، والإكمال، والإجمالي.

3.2 مثال على الاستجابة

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "هذا هو النص الذي تم التعرف عليه بواسطة OCR، وعادةً ما يتم إرجاعه بصيغة Markdown للحفاظ على تنسيق المحتوى داخل الصورة."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 512,
        "completion_tokens": 128,
        "total_tokens": 640
    }
}

4. الأسئلة الشائعة (FAQs)

س1: ما تنسيقات الصور التي يدعمها DeepSeek-OCR؟
ج: يتم دعم معظم تنسيقات الصور الشائعة حاليًا مثل JPEG وPNG وWebP وBMP. يُنصح بأن تكون الصورة واضحة وبدقة مناسبة لضمان أفضل دقة في التعرّف.

س2: كيف يمكنني رفع صورة باستخدام Base64؟
ج: استبدل قيمة image_url.url بسلسلة Base64 فقط. مثال على التنسيق: "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."。

س3: لماذا يتم اقتطاع نتيجة التعرّف؟
ج: يرجى التحقق من finish_reason في الاستجابة. إذا كانت القيمة length فهذا يعني أن المحتوى الناتج تجاوز الحد المحدد في max_tokens، ويُنصح بزيادة قيمة max_tokens.

س4: هل تدعم هذه الواجهة التعرّف على عدة صور دفعة واحدة؟
ج: يمكنك محاولة إضافة عدة كائنات image_url داخل messages في طلب واحد، ولكن يُنصح بإرسال طلب منفصل لكل صورة للحصول على أفضل معالجة سياقية واستجابة أكثر استقرارًا.

س5: كيف أحصل على تنسيق أكثر دقة (مثل الجداول أو المعادلات)؟
ج: يمكنك إضافة تعليمات إضافية داخل رسالة system أو user، مثل: "يرجى استخدام تنسيق Markdown للحفاظ على بنية الجداول داخل الصورة والتعرّف على الصيغ الرياضية الموجودة فيها".

س6: هل يتم دعم الإخراج المتدفق (Streaming)؟
ج: نعم، مدعوم. اضبط المعامل stream في الطلب على true، وسيقوم النموذج بإرجاع مقاطع النص المتعرّف عليها بشكل فوري، وهو مناسب للسيناريوهات التفاعلية التي تتطلب تقليل زمن ظهور أول استجابة.