فهم الصور والمستندات عبر Claude وGemini ببنية طلب واحدة

قدر مدهش مما يُسمّى «ذكاء المستندات» ليس سوى إرسال صورة إلى نموذج محادثة وقراءة ما يردّه. إيصال، لقطة شاشة للوحة معلومات، صفحة PDF ممسوحة ضوئياً، صورة للوح أبيض — تقرأ نماذج Claude وGemini الحديثة كل ذلك أصلاً، دون الحاجة إلى محرك OCR منفصل. العقبة عادةً هي السباكة: لكل مزوّد طريقته الخاصة في إرفاق الصورة، ونقل الكود من واحد إلى آخر أمر مزعج.

عبر Brievio تستخدم بنية طلب واحدة — مصفوفة content الخاصة بـ OpenAI Chat Completions مع جزء image_url — وتعمل بشكل متطابق ضد Claude Opus 4.7 وSonnet 4.6 وHaiku 4.5 وGemini 2.5 Pro / Flash. هذه هي النماذج الأصلية الطرف الأول مع رؤية أصلية محترمة، فنفس ملف JPEG الذي يقرأه Claude جيداً، يقرأه Claude فعلاً. تتناول هذه التدوينة مدخلات الصور (الفهم)، لا توليد الصور: الروابط، وbase64، وprompts متعددة الصور، وأنماط OCR / المخططات / المستندات الممسوحة ضوئياً التي تظهر في العمل الحقيقي.

أبسط حالة: صورة عبر رابط URL

إذا كانت صورتك موجودة بالفعل على رابط HTTPS عام، فأرفقها كجزء image_url بجوار نصك. بدّل claude-sonnet-4-6 بـ gemini-2.5-pro ولا يتغير جسم الطلب — تلك القابلية للنقل هي بيت القصيد كله:

# أرسل صورة عبر رابط URL. نفس بنية محادثة OpenAI، ضد النموذج الأصلي.
from openai import OpenAI

client = OpenAI(
    api_key="sk-brievio-...",
    base_url="https://api.brievio.com/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",     # أو gemini-2.5-pro — نفس بنية الطلب
    max_tokens=500,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What does this chart show? Give the trend in one sentence."},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/q3-revenue.png"},
                },
            ],
        }
    ],
)

print(resp.choices[0].message.content)
# تُحتسب الصور بوصفها توكنات مدخلات — اقرأ resp.usage.prompt_tokens لمعرفة التكلفة.

أمر ينبغي استيعابه مبكراً: الصور تكلّف توكنات مدخلات. النموذج لا يرى البكسلات مجاناً — إنه يقسّم الصورة إلى بلاطات، وكل بلاطة تُحتسب كالنص. يبلّغ Brievio عن أعداد توكنات صادقة، فتظهر تكلفة الصورة في resp.usage.prompt_tokens تماماً كما يحتسبها المزوّد الأصلي. لقطة شاشة بملء الشاشة قد تستهلك من بضع مئات إلى ألفي توكن مدخلات بحسب الدقة. خصّص لها ميزانية كما تخصّص لفقرة من السياق، لا كهدية مجانية.

Base64: الحالة التي ستستخدمها فعلاً

في الإنتاج نادراً ما تكون الصورة رابطاً عاماً — إنها ملف رفعه المستخدم للتو، أو buffer من ماسح ضوئي، أو كائن S3 خاص. لتلك الحالات، ضمّن البايتات مباشرة كرابط بيانات data: بصيغة base64. لا يستطيع النموذج التفريق؛ ولا يحتاج بايتاتك أن تكون قابلة للوصول علناً قط:

# معظم صور الإنتاج ليست روابط عامة. ضمّنها مباشرة كروابط بيانات base64.
import base64
from openai import OpenAI

client = OpenAI(api_key="sk-brievio-...", base_url="https://api.brievio.com/v1")

def data_url(path: str, media_type: str = "image/png") -> str:
    with open(path, "rb") as f:
        b64 = base64.standard_b64encode(f.read()).decode("utf-8")
    return f"data:{media_type};base64,{b64}"

resp = client.chat.completions.create(
    model="gemini-2.5-flash",      # رخيص + سريع لـ OCR / الإيصالات
    max_tokens=800,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract every line item and total as JSON. Keys: items[], total."},
                {"type": "image_url", "image_url": {"url": data_url("receipt.jpg", "image/jpeg")}},
            ],
        }
    ],
)

print(resp.choices[0].message.content)
# نصيحة: تنفخ روابط البيانات حجم جسم الطلب بنحو 33% فوق حجم الملف الخام. أبقِ الصور
# بحجم معقول — لقطة شاشة بدقة 2-3 ميغابكسل تكفي للنص؛ نادراً ما تحتاج 12 ميغابكسل.

تحفّظان عمليان. أولاً، يضيف base64 نحو 33% من العبء إلى جسم طلبك، وهناك حدود لحجم الصورة الواحدة (تحدّ Anthropic الصور المفردة عند نحو 5 ميغابايت في الـ API؛ ولـ Gemini سقفه الخاص). إذا أعاد مسح كبير خطأ 413، فقلّل دقته — يبقى النص مقروءاً عند دقة أقل بكثير مما تتوقع. ثانياً، أرسل نوع الوسيط الصحيح media_type (image/png، image/jpeg، image/webp)؛ فالنوع غير المتطابق سبب شائع لفشل فكّ تشفير صامت. وعندما يفشل طلب فعلاً بخطأ 4xx أو 5xx على Brievio، فلن تُحاسَب عليه — النداءات الفاشلة مجانية، فيمكنك إعادة محاولة صورة مصغّرة دون أن تدفع مرتين.

prompts متعددة الصور والمستندات الممسوحة ضوئياً

تستوعب مصفوفة content أي عدد تريده من أجزاء image_url، متداخلة مع النص. وهذا يفتح سير العمل المفيد فعلاً: قارن لقطة شاشة قبل/بعد، أو اقرأ مستنداً ممسوحاً متعدد الصفحات، أو غذِّه بسلسلة من المخططات واطلب الخيط الناظم. والحيلة التي تؤتي ثمارها في كلتا عائلتي النماذج هي وسم كل صورة بنقطة ارتساء نصية صغيرة كي يستشهد بها النموذج:

# عدة صور في prompt واحد — قارن لقطتي شاشة، أو اقرأ مسحاً ضوئياً من 4 صفحات.
content = [
    {"type": "text", "text": "These are pages 1-3 of a scanned contract. Summarize the parties, term, and termination clause. Cite the page number for each."},
]
for i, path in enumerate(["page1.png", "page2.png", "page3.png"], start=1):
    content.append({"type": "text", "text": f"--- Page {i} ---"})
    content.append({"type": "image_url", "image_url": {"url": data_url(path)}})

resp = client.chat.completions.create(
    model="claude-opus-4-7",       # أقوى استدلال على المستندات الكثيفة
    max_tokens=1200,
    messages=[{"role": "user", "content": content}],
)

print(resp.choices[0].message.content)
# إدراج عنوان نصي قبل كل صورة ("--- Page 2 ---") يمنح النموذج
# نقطة ارتساء يستشهد بها، ويحسّن بوضوح الربط بين الصور المتعددة في كلتا العائلتين.

للمستندات الطويلة ثمة مفاضلة في اختيار النموذج. Gemini 2.5 Flash رخيص وسريع وخيار افتراضي ممتاز لـ OCR عالي الحجم والإيصالات واستخراج النماذج. أما Claude Opus 4.7 فيستدل بجهد أكبر على المواد الكثيفة متعددة الصفحات — العقود والبيانات المالية وكل ما تحتاج فيه أن يُبقي عدة صفحات في مرماه ويربط بينها. ويقع Sonnet 4.6 وGemini 2.5 Pro في المنتصف. يمكنك التوجيه حسب المهمة دون تغيير أي كود سوى سلسلة model؛ راجع القائمة الحية على /models.

فيمَ تبرع هذه النماذج (وفيمَ لا تبرع)

تتعامل الرؤية الأصلية مع طيف واسع من المهام الحقيقية بإتقان:

• OCR والنسخ — النص المطبوع، وخط اليد بدقة مفاجئة لا بأس بها. لا خطّ معالجة Tesseract لصيانته.
• المخططات ولوحات المعلومات — قراءة القيم من المخططات الشريطية/الخطية، وتلخيص اتجاه، والتحقق من معقولية مقياس في لقطة شاشة.
• الاستخراج المهيكل — تحويل الإيصالات والفواتير والنماذج والهويات إلى JSON. اقرنه بمخطط صارم في prompt الخاص بك للحصول على مخرجات نظيفة.
• فهم واجهات المستخدم والمخططات التوضيحية — وصف شاشة، وقراءة مربع حوار خطأ، وشرح مخطط معماري.

وبعض الحدود الصادقة. لا تزال النماذج تخطئ القراءة أحياناً في رقم مفرد أو خلية جدول كثيفة، لذا في أي حالة يكون فيها الرقم الخاطئ مكلفاً، تحقّق مقابل مخطط أو مجموع تدقيقي (مثلاً، ينبغي أن تجمع بنود الفاتورة إلى الإجمالي المذكور). النص الصغير في صورة منخفضة الدقة هو الإخفاق الأكثر شيوعاً — أعطه اقتصاصاً بدقة أعلى. ويختلف سلوك كل نموذج عن الآخر اختلافاً حقيقياً: تخطيط يتقنه نموذج قد يتعثّر فيه آخر، وهذا تحديداً سبب أن القدرة على تبديل النماذج خلف API واحد وإجراء اختبارات A/B عليها على مستنداتك أنت تساوي أكثر من أي معيار قياس منفرد.

إلى أبعد: الرؤية مع الأدوات

تتكامل الرؤية مع بقية الـ API. يمكنك أن تسلّم النموذج صورة ومعها مجموعة من الأدوات، فيقرأ لقطة شاشة ثم يستدعي دالة بما استخرجه — «اقرأ هذه الفاتورة، ثم استدعِ create_expense(amount, vendor, date)». طبقة استدعاء الأدوات تلك موحّدة أيضاً عبر Claude وGemini من خلال Brievio؛ ويغطي دليل استخدام الأدوات البنية المشتركة. وباقترانها بالرؤية، تكون معظم خطّ معالجة المستندات في طلب واحد.

الخلاصة

لفهم الصور لا تحتاج إلى خدمة OCR منفصلة ولا إلى SDKs خاصة بالمزوّد. أرفق جزء image_url — رابطاً أو رابط بيانات base64 — إلى طلب محادثتك المعتاد، وسِم الصور المتعددة كي يستطيع النموذج الاستشهاد بها، ووجّه إلى النموذج الذي يناسب المهمة: Gemini Flash للقراءات الرخيصة عالية الحجم، وClaude Opus للمستندات الصعبة. وتذكّر أن الصور تُحتسب بوصفها توكنات مدخلات (تُعرض بصدق في usage)، وأبقِ الدقة معقولة، وتحقّق من الأرقام المستخرجة، واتّكئ على إعادات المحاولة المجانية عند ارتداد مسح كبير. مرجع الطلب الكامل وحدود كل نموذج في الوثائق — ابدأ من هناك، وستجد المستندات تتدفق عبر Claude أو Gemini في عصر يوم واحد.