AR ▾

نموذج لغات كبير غير خاضع للرقابة لمعالجة النصوص بعد استخراجها ضوئيًاhttps://api.llmocrapi.com/v1

llmocrapi.comالدليل

توثيق واجهة برمجة OCR: نقاط النهاية، الأوضاع والحدود

تعمل هذه الصفحة كتوثيق لواجهة برمجة OCR للمطورين الذين يريدون الوصول الكامل إلى الواجهة في مكان واحد: نقطتا نهاية، أربعة أوضاع طلب، الحدود والأخطاء. تقوم الواجهة بتنظيف النص الذي أنتجه محرك OCR بالفعل؛ ولا تقرأ الصور.

تم التحديث

لوحات مرجعية عائمة مع عقد التدفق، وسلسلة من النقاط وشكل القوس، تمثل أوضاع توثيق واجهة برمجة التطبيقات

نقاط رئيسية

  • توجد طريقتان: POST /v1/chat/completions وGET /v1/models، مع المصادقة باستخدام مفتاح Bearer.
  • يتبع البث المتدفق، وضع JSON واستدعاء الدوال تنسيق دردشة OpenAI، مع معرف النموذج uncensored.
  • حدود: 8 طلبات متزامنة و300 في الدقيقة على المفتاح الكامل، و2 و60 على المفتاح التجريبي، حد حجم الطلب 8 MB.
  • الأخطاء عند الحمل الزائد هي HTTP 429 مع رمز يخبرك ما إذا كنت بحاجة إلى إبطاء السرعة أو تقليل التوازي.

نظرة عامة والمصادقة

الخدمة هي واجهة برمجة نصوص مستضافة ومتوافقة مع OpenAI. هدفها في هذا الموقع هو النصف الثاني من مهمة OCR: خذ السلسلة الخام التي أنتجها محرك OCR وأعد نصوصًا نظيفة، أو حقول منظمة، أو أسطر مميزة. الإدخال هو نص فقط. لا يوجد إدخال أو إخراج للصور أو الصوت أو الفيديو، ولا تضمينات ولا ضبط دقيق.

كل شيء تحت عنوان URL الأساسي نفسه، https://api.llmocrapi.com/v1. المصادقة عبر رأس Bearer القياسي: Authorization: Bearer YOUR_KEY. تنشئ المفتاح في صفحة مفتاح API بعد التسجيل عبر Google أو باستخدام البريد الإلكتروني وكلمة المرور. النموذج الذي يقف وراء نقطة النهاية هو نموذج مفتوح الأوزان واحد تشغله جهة مستقلة. إنه ليس API الرسمي لأي بائع نماذج، وليس وسيطاً بين عدة مزودين. معرفه دائماً uncensored.

لأجل جولة عملية بدلاً من المرجع، يغطي الدليل السريع في قسم المستندات خطوة إرسال الطلب الأول خطوة بخطوة.

نقاط النهاية بإيجاز

الطريقة والمسارالغرض
GET /v1/modelsتعرض قائمة النماذج المتاحة. استخدمها كاختبار سريع وفعال للمفتاح.
POST /v1/chat/completionsتشغّل النموذج على قائمة من الرسائل. تدعم البث المتدفق، وضع JSON، والأدوات.

هذه هي الواجهة الكاملة. بما أنها تتوافق مع بروتوكول OpenAI، فإن أي مكتبة عميل تتيح لك تعيين عنوان URL الأساسي ومفتاح ستعمل. أسهل طريقة للتحقق من صحة الاتصال هي:

curl https://api.llmocrapi.com/v1/models \
  -H "Authorization: Bearer $LLMOCR_API_KEY"

المفتاح الصحيح يعيد قائمة النماذج التي تحتوي على uncensored. المفتاح الخاطئ يعيد خطأ مصادقة، مما يخبرك أن المشكلة في المفتاح وليس في جسم الطلب.

معلمات الطلب

يحتاج طلب إكمال المحادثة إلى model و messages. الحقول الاختيارية أدناه تُمرر كما هي إلى النموذج.

  • temperature وtop_p: ضوابط أخذ العينات. لإصلاح الأخطاء في التعرف الضوئي على الحروف (OCR) استخدم temperature 0 بحيث يعطي الإدخال المتطابق مخرجات متطابقة.
  • max_tokens: اختياري. إذا لم تحدده، يمكن للنص المكتمل استخدام ما تبقى من نافذة الـ 100,000 رمز بعد موجّهك. اضبطه عندما تريد حداً أقصى صارماً للتكلفة لكل استدعاء.
  • stop: سلاسل نصية لإنهاء التوليد. مفيدة عندما تطلب مخرجات بين علامات محددة.
  • seed: يحسن إمكانية التكرار عبر الجلسات.
  • presence_penalty و frequency_penalty: تُمرر كما هي. اتركهما عند الصفر للتنظيف، لأن عقوبات التكرار قد تدفع النموذج لتعديل الكلمات الصحيحة المتكررة مثل عناوين الجداول.
  • stream، response_format، tools و tool_choice: مغطاة في الأقسام الثلاثة التالية.

تحتسب نافذة السياق مجموع الرموز في الموجّه والمخرجات عند 100,000 رمز، وقد يكون جسم الطلب بحجم يصل إلى 8 ميجابايت. عملياً، يصل حد الرموز أولاً.

استجابات البث المتدفق

حدد "stream": true لتقوم الواجهة بإرسال أحداث Server-Sent Events (SSE) أثناء توليد النص. يساعد البث المتدفق الأدوات التفاعلية، مثل محرر حيث يراقب المستخدم ظهور فقرة تم تنظيفها. يتم الإبلاغ عن استخدام الرموز في نهاية البث، لذا يمكنك تسجيل التكلفة.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.llmocrapi.com/v1", api_key=os.environ["LLMOCR_API_KEY"])

stream = client.chat.completions.create(
    model="uncensored",
    stream=True,
    messages=[{"role": "user", "content": "Fix this OCR text: th1s is a sam-\nple."}],
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if getattr(chunk, "usage", None):
        print("\ntokens:", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)

هناك تفصيل واحد يؤثر على معدل نقل البيانات. يشغل الطلب المتدفق فتحة التزامن حتى ينتهي البث. إذا توقفت شيفرتك عن القراءة في المنتصف وتركت الاتصال مفتوحاً، تظل هذه الفتحة مشغولة. أغلق البث صراحةً، أو استهلكه حتى النهاية.

وضع JSON

يطلب وضع JSON من النموذج الرد بكائن JSON بدلاً من نص عادي. فعّله باستخدام response_format ووصف المفاتيح في تعليماتك.

{
  "model": "uncensored",
  "temperature": 0,
  "response_format": {"type": "json_object"},
  "messages": [
    {"role": "system", "content": "Return JSON with keys 'text' (cleaned string) and 'uncertain_lines' (array of integers)."},
    {"role": "user", "content": "line one\nl1ne two\nline thr3e"}
  ]
}

قم بالتحليل بحذر. وضع JSON يشكل المخرجات، لكن يجب عليك التحقق من صحة المفاتيح والأنواع قبل إدخالها في قاعدة البيانات الخاصة بك. إذا تم قطع الاستجابة بواسطة max_tokens، فقد يكون JSON غير مكتمل، لذا ارفع الحد أو أرسل قطعًا أصغر.

استدعاء الدوال

استدعاء الدوال يسمح للنموذج بطلب كودك للقيام بشيء ما بدلاً من كتابة نص. بالنسبة لأعمال التعرف الضوئي على الحروف (OCR)، الاستخدام الشائع هو إرجاع تصحيحات منظمة: يستدعي النموذج دالةً برقم السطر والاستبدال، ويطبق كودك ذلك. عرّف الأدوات في مصفوفة tools، واختر السلوك بـ tool_choice، وأعد النتائج كرسائل بـ role: "tool". عند البث المتدفق، تصل استدعاءات الدوال تدريجيًا كقيم tool_calls متغيرة.

tools = [{
    "type": "function",
    "function": {
        "name": "replace_line",
        "description": "Replace one line of the OCR text with a corrected version.",
        "parameters": {
            "type": "object",
            "properties": {
                "line": {"type": "integer"},
                "text": {"type": "string"},
            },
            "required": ["line", "text"],
        },
    },
}]

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "1: The inven-\n2: tory was com1leted."}],
    tools=tools,
    tool_choice="auto",
)
for call in resp.choices[0].message.tool_calls or []:
    print(call.function.name, call.function.arguments)

تعود الحجج كسلسلة نصية JSON. قم بتحليلها، وطبق التغيير، وإذا استمرت المحادثة، أضف رسالة المساعد ورسالة role: "tool" مع معرف tool_call_id المطابق. يحافظ هذا النمط على عدد الرموز في المخرجات منخفضاً، لأن النموذج يعيد فقط الأسطر التي يغيرها.

الإعدادات المناسبة لتنظيف النصوص

يكون المرجع أكثر فائدة مع نقطة بداية موصى بها، لذا إليك كيفية دمج المعاملات عادةً لإصلاح OCR. هذه اقتراحات تستند إلى سلوك المهمة، وليست مقاييس دقيقة.

  • إصلاح حتمي: temperature 0، بدون عقوبات تكرار، و seed ثابت. استخدم هذا للأرشيف حيث تريد إعادة التشغيل أن تُعيد إنتاج مخرجات الأمس.
  • استخراج الحقول: temperature 0، response_format مضبوطة على json_object، مع حد أقصى لـ max_tokens أعلى بقليل من أكبر كائن تتوقعه.
  • مراجعة تفاعلية: stream true وموجّه نظام قصير، بحيث يرى المحرر النص المصحح يظهر ويمكنه إيقافه مبكرًا.
  • إصلاحات على مستوى الأسطر: أدوات تحتوي على دالة بنمط replace_line، بحيث يُرجع النموذج التغييرات فقط.

تتبع أدوار الرسائل الاتفاقية المعتادة: system للتعليمات الثابتة، user لنص الـ OCR، assistant للردود السابقة في جلسة متعددة الأدوار، و tool لنتائج الدوال. ضع التعليمات في رسالة النظام والنص الخام في رسالة المستخدم. إذا كان نص الـ OCR نفسه يحتوي على ما يشبه التعليمات، مثل لافتة ممسوحة ضوئياً تقول تجاهل النصوص السابقة، فإن الفصل يسهل إعلام النموذج بأن رسالة المستخدم هي بيانات للإصلاح وليست أمراً يجب اتباعه. اذكر ذلك صراحةً في موجّه النظام.

احتفظ بسجل لقيمة X-Request-Id لكل استدعاء. هذا هو المعرف الذي يحتاجه الدعم إذا عادت صفحة واحدة خاطئة وأردت فحصها.

الحدود، الرؤوس والأخطاء

الحدمفتاح كاملمفتاح التجربة
طلبات متزامنة82
الطلبات في الدقيقة30060
الحد الأقصى لحجم الجسم8 MB8 MB
نافذة السياق100,000 رمز (token)100,000 رمز (token)

تتضمن الاستجابات X-Request-Id (اذكره للدعم)، X-Balance-USD (رصيدك المتبقي)، X-RateLimit-Limit-Requests و X-RateLimit-Limit-Concurrency.

عند تجاوز حدّ المعدل، يجيب الـ API بـ HTTP 429. رمز الخطأ rate_limited يعني طلبات كثيرة في الدقيقة، لذا وزّع الحمل. الرمز concurrency يعني طلبات كثيرة قيد التنفيذ، لذا قلل عدد الـ workers. استجابة 429 التي تحمل رأس Retry-After: 5 يشير إلى حمل زائد مؤقت: انتظر خمس ثوانٍ وأرسل مرة أخرى. الطلبات الفاشلة والمرفوضة لا تُحسب، لذا فإن حلقة إعادة المحاولة آمنة.

الفوترة لكل رمز: $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج، تُخصم من رصيد مسبق الدفع لا ينتهي. انظر صفحة الأسعار لمبالغ الشحن والمكافآت. الموجّهات لا تُستخدم للتدريب. قاعدة المحتوى هي حد واحد صارم: لا محتوى جنسي يتضمن القاصرين. توجَّه الأسئلة المتعلقة بالسياسة إلى الدعم.

أسئلة وأجوبة

ما هي نقاط النهاية التي تقدمها الـ API؟

اثنان: POST /v1/chat/completions للتوليد و GET /v1/models لقائمة النماذج. كلاهما يستخدم نفس مفتاح Bearer.

هل يدعم البث المتدفق واستدعاء الدوال؟

نعم. اضبط stream إلى true لـ SSE مع الاستخدام في النهاية، واستخدم tools و tool_choice لاستدعاء الدوال، بإرجاع النتائج كرسائل دور tool.

ما هو الحد الأقصى لحجم الإدخال؟

نافذة السياق هي 100,000 رمز للموجّه بالإضافة إلى الإكمال، ويمكن أن يكون جسم الطلب حتى 8 ميجابايت.

لماذا حصلت على خطأ 429؟

تجاوزت إما الطلبات في الدقيقة (rate_limited)، الطلبات المتزامنة (concurrency)، أو وصلت إلى حمل زائد مؤقت، بما في ذلك Retry-After: 5. انتظر وأعد المحاولة.

مفتاحك على بُعد استمارة واحدة

أنشئ حساباً، وانسخ المفتاح، ثم غيّر عنوان URL الأساسي. هذا هو الإعداد كله.

احصل على مفتاح API