واجهة OpenAI API لنماذج LLM المحلية: التشغيل محلياً، والتبديل إلى الاستضافة

معنى العبارة

يستخدم الناس عبارة "local LLM OpenAI API" لأمرين مترابطين. الأول هو نموذج لغوي تشغله بنفسك على جهاز محمول أو خادم منزلي، يستمع على منفذ محلي ويتكلم بصيغة دردشة OpenAI. الثاني هو عادة كتابة تطبيقك بناءً على تلك الصيغة بحيث يمكن استبدال النموذج الذي يقف وراءها.

الصيغة هي عقد بسيط. يرسل تطبيقك جسم JSON يحتوي على اسم model وقائمة من messages، لكل منها دور system أو user أو assistant. يرد الخادم بجسم JSON يحتوي على الرسالة المولدة، أو بتدفق من أجزاء صغيرة إذا طلبت streaming. تغلف SDKs الرسمية لـ Python و JavaScript هذا، وتتيح لك تجاوز الـ base URL، وهو السر كله.

تكشف العديد من الأدوات المحلية هذا العقد. يقدم Ollama وLM Studio وخادم llama.cpp وvLLM كل منها مسارًا على نمط OpenAI. تقدم الخدمات المستضافة ذلك أيضًا، وهو السبب في أن نفس عشرين سطرًا من كود العميل يمكنها التحدث مع أي منهما. نقطة النهاية في هذا الموقع هي واحدة من الأنواع المستضافة. تقبل POST /v1/chat/completions وGET /v1/models، ويمكن الوصول إليها عبر https://api.onekeyllmapi.com/v1.

المحلي مقابل المستضاف في لمحة

لا يوجد خيار أفضل بشكل عام. كلاهما يُقدّم المزايا مقابل الجهد. يلتزم الجدول بالاختلافات التي تنطبق على الفئة، وليس على منتج معين.

إذا كان يجب ألا تغادر بياناتك أبدًا جهازًا تتحكم فيه، فإن الحل المحلي هو الفائز والخيار المستضاف هو الأداة غير المناسبة. إذا كنت بحاجة إلى نموذج أكبر مما تحمله أجهزتك، أو بوت يظل متاحًا من أماكن متعددة، فإن الخيار المستضاف هو الفائز. الإعداد الشائع يجمع بين الاثنين ويختار لكل مهمة.

تبديل العميل من المحلي إلى المستضاف

إذا كان كودك يتحدث بالفعل مع مشغل محلي، فإن الخطوة تتكون من ثلاث قيم. كل شيء آخر، بما في ذلك كيفية بناء الرسائل وقراءة أجزاء البث المتدفق، يبقى كما هو.

1. عنوان URL الأساسي. استخدم https://api.onekeyllmapi.com/v1 بدلاً من عنوانك المحلي.
2. مفتاح API. غالبًا ما تتجاهل الخوادم المحلية المفتاح. يتطلب المستضاف منه كـ Authorization: Bearer <key>، ويرسله لك الـ SDK.
3. معرف النموذج. الأسماء المحلية هي أي شيء قمت بسحبه. هنا المعرف هو uncensored.

طريقة أنيقة للحفاظ على هذا المرونة هي قراءة القيم الثلاث من متغيرات البيئة، بحيث يعمل ملف واحد في كلا المكانين.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.onekeyllmapi.com/v1"),
    api_key=os.environ.get("LLM_API_KEY", "YOUR_KEY"),
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

models = client.models.list()
print([m.id for m in models.data])

resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "Answer in two sentences."},
        {"role": "user", "content": "Why do OpenAI-style endpoints make switching models easy?"},
    ],
    temperature=0.5,
)
print(resp.choices[0].message.content)

نفس الاستدعاء من سطر الأوامر، وهو مفيد لإجراء اختبار سريع:

Copycurl https://api.onekeyllmapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "uncensored", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 20}'

مع Node.js، يكون النمط متطابقاً:

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.LLM_BASE_URL ?? "https://api.onekeyllmapi.com/v1",
  apiKey: process.env.LLM_API_KEY,
});

const res = await client.chat.completions.create({
  model: process.env.LLM_MODEL ?? "uncensored",
  messages: [{ role: "user", content: "Name three uses for JSON mode." }],
});
console.log(res.choices[0].message.content);

ما تغطيه واجهة API المتوافقة مع OpenAI وما لا تغطيه

التوافق يعني تطابق تنسيق السلك (wire format). لا يعد ذلك بوجود كل ميزة تقدمها الخدمة الأصلية. قبل نقل تطبيق حقيقي، تحقق من كل نقطة أدناه مقابل الهدف.

ما تدعمه واجهة API هذه

• إكمالات الدردشة عبر POST /v1/chat/completions وقائمة النماذج عبر GET /v1/models.
• البث المتدفق عبر أحداث المرسلة من الخادم (SSE) مع stream: true، مع الإبلاغ عن الاستخدام في نهاية البث.
• استدعاء الدوال عبر tools وtool_choice، مع بث tool_calls، وإرسال النتائج كرسائل role: "tool".
• وضع JSON عبر response_format: {"type": "json_object"}.
• ضوابط أخذ العينات: تمرير temperature و top_p و stop و seed ومعاملات العقوبة كما هي.

ما لا تفعله

• لا يوجد توليد صور أو صوت أو فيديو. النص فقط.
• لا توجد نقطة نهاية للتضمين (embeddings) ولا ضبط دقيق (fine-tuning). إذا كان تطبيقك يبني فهرساً متجهياً، فأنت بحاجة إلى مصدر تضمين منفصل.
• استمارة واحدة فقط. النموذج هو نموذج مفتوح الأوزان تشغله مزود مستقل. إنه ليس واجهة API الرسمية لأي بائع كبير، وليس وسيطاً بين مزودين، لذا لا يمكنك الاختيار بين عائلات النماذج بتغيير المعرف.

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

الاختلافات في السياق والحدود والتكلفة

ثلاثة أرقام تتغير عند مغادرة الخادم المحلي. الأول هو نافذة السياق. طول سياق المشغل المحلي هو إعداد مرتبط بذاكرة جهازك. هنا هو ثابت عند 100,000 رمز، مشترك بين الموجّه والإكمال، وmax_tokens اختياري. الثاني هو التزامن. يمكن أن يكون جهازك الخاص في طابور بعمق لا نهاية له، لكن المفتاح الكامل هنا يسمح بـ 8 طلبات متزامنة و300 في الدقيقة، والمفتاح التجريبي يسمح بـ 2 و60. الثالث هو الفاتورة.

تكاليف الاستخدام المستضاف هي $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج، الدفع عند الاستخدام من رصيد مسبق الدفع. دعنا نمر عبر مهمة يومية كمثال: معالج تلخيص يعالج 400 مستند يومياً، كل منها 3,000 رمز مدخل و300 رمز مخرج. المدخلات هي 400 × 3,000 = 1,200,000 رمز، والتي تكلف 1.2 × $0.15 = $0.18. المخرجات هي 400 × 300 = 120,000 رمز، والتي تكلف 0.12 × $0.50 = $0.06. إجمالي اليوم هو $0.24، وشهر من 30 يوماً هو $7.20. قارن ذلك بتكلفة تشغيل بطاقة GPU وتكلفة البطاقة نفسها قبل اتخاذ القرار.

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

يحتفظ الطلب المتدفق بمكان التزامن الخاص به حتى ينتهي البث، لذا أغلق البث الذي تتوقف عن قراءته. تبدأ الشحنات من $20؛ الطبقات والمكافآت موجودة في صفحة الأسعار.

استكشاف الأخطاء عند سوء سلوك التبديل

تعود معظم عمليات النقل الفاشلة إلى مجموعة صغيرة من الأسباب. عالِجها بهذا الترتيب.

• أخطاء 404 أو أخطاء الاتصال. على الأرجح يفتقر عنوان URL الأساسي إلى اللاحقة /v1، أو يحتوي على مسار إضافي. استخدمه بالضبط كما هو https://api.onekeyllmapi.com/v1.
• أخطاء المصادقة. المفتاح مفقود أو يُرسل في رأس خاطئ. التنسيق هو Authorization: Bearer <key>. يجب على مستخدمي SDK تأكيد أن متغير البيئة قد تم تحميله فعلياً.
• النموذج غير موجود. اسم النموذج المحلي القديم لا يزال في تكوينك. اتصل بـ GET /v1/models واستخدم المعرف الذي يدرجه، وهو uncensored.
• أخطاء 429 تحت الحمل. لقد تجاوزت 8 طلبات متزامنة أو 300 في الدقيقة على مفتاح كامل. أضف طابوراً أو قنواة (semaphore).
• يبدو أن معلمة ما تُتجاهل. تحقق من أنها واحدة من الحقول الممررة المذكورة أعلاه، وقارن السلوك مع seed ثابت ودرجة حرارة منخفضة.

تتضمن كل استجابة رأس X-Request-Id. سجّله بجانب معرّف الطلب الخاص بك لتتبع الإجابة السيئة لاحقاً. إذا كنت تشغّل حركة إنتاجية وتريد قياس الجودة مع مرور الوقت، فإن مقال الموقع LLM Observability: Myths vs Facts قراءة جيدة للمتابعة. من الجدير أيضاً التقاط رؤوس الاستجابة X-Balance-USD، وX-RateLimit-Limit-Requests، وX-RateLimit-Limit-Concurrency.

جربه دون التزام

أرخص طريقة لاختبار ما إذا كان كودك ينتقل بسلاسة هي تشغيله مرة واحدة. أنشئ حساباً باستخدام Google أو البريد الإلكتروني وكلمة المرور، ثم استحوذ على رصيد التجربة بقيمة $0.50 من صفحة المفتاح. يستغرق ذلك نقرة واحدة، ولا يحتاج إلى بطاقة، ومحدود لشخص واحد فقط، وينتهي صلاحيته بعد 7 أيام. احصل على مفتاحك من صفحة مفتاح API، اضبط متغيرات البيئة الثلاثة المذكورة أعلاه وشغّل مجموعة الاختبار الحالية.

إذا نجحت الاختبارات وكان الاستخدام ضمن ميزانيتك، قم بشحن الرصيد من $20، بالبطاقة (Visa، Mastercard، Apple Pay، Google Pay) أو بالعملات المشفرة (USDT على TRC20، USDC على Base). لا تُستخدم المطالبات للتدريب. النموذج مُعدّ للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين، مع قاعدة ثابتة واحدة: لا محتوى جنسي يتضمن القاصرين.

المزيد من الأدلة

• مراقبة LLM: خرافات مقابل حقائق