ما تحتاجه قبل البدء
مثيل n8n (سحابي أو مُستضاف ذاتيًا) ومفتاح API من هذه الخدمة. إذا لم يكن لديك مفتاح بعد، فإن صفحة مفتاح API ترشدك خلال عملية التسجيل باستخدام Google أو البريد الإلكتروني وكلمة المرور. يمكن للمستخدمين الجدد المطالبة برصيد تجريبي بقيمة $0.50 بنقرة واحدة على تلك الصفحة، وهو صالح لمدة 7 أيام دون الحاجة إلى بطاقة.
تدخل ثلاث قيم في n8n:
- عنوان URL الأساسي:
https://api.onekeyllmapi.com/v1 - مفتاح API: يُرسل كـ
Authorization: Bearer <key>، وهو ما يقوم به n8n نيابةً عنك - معرف النموذج:
uncensored
هذه الخدمة هي واجهة برمجة تطبيقات LLM نصية مُدارة تتبع تنسيق طلبات OpenAI لـ /v1/chat/completions، و/v1/responses، و/v1/models. وهي ليست واجهة برمجة التطبيقات الرسمية لأي مورد للنماذج، لذا فإن أي شيء يرسله n8n إلى نقطة النهاية الخاصة بالدردشة في OpenAI سيعمل هنا طالما كان طلبًا نصيًا.
الخطوة 1: إنشاء الاعتماد
في n8n، افتح الاعتمادات، واختر إنشاء اعتماد، وابحث عن OpenAI API. املأه كما يلي:
- الصق مفتاحك في حقل مفتاح API.
- اترك حقل معرف المؤسسة فارغًا.
- استبدل عنوان URL الأساسي الافتراضي بـ
https://api.onekeyllmapi.com/v1. احتفظ بـ/v1في النهاية ولا تضيف/chat/completions. - احفظ الإعدادات. يقوم n8n بإجراء اختبار اتصال صغير عند الحفظ؛ إذا فشل، انتقل إلى قسم استكشاف الأخطاء وإصلاحها أدناه.
احتفظ ببيانات اعتماد واحدة لكل بيئة. إذا كنت تشغل n8n في بيئة تجريبية وبيئة إنتاج، امنح كل منهما مفتاحًا خاصًا به حتى تتمكن من رصد الإنفاق بشكل منفصل وإلغاء صلاحية أحدهما دون التأثير على الآخر.
الخطوة 2: بناء سير عمل دردشة بسيط
ابدأ بأبسط شيء يثبت الاتصال: مُفعّل يدوي وطلب نموذج واحد.
- أضف عقدة مُفعّل يدوي.
- أضف عقدة OpenAI (أو العقدة الفرعية نموذج دردشة OpenAI داخل سلسلة LLM الأساسية، اعتمادًا على إصدار n8n) واختر بيانات الاعتماد من الخطوة 1.
- بالنسبة للنموذج، ابحث عن طريقة لإدخال المعرف يدويًا. تقدم إصدارات n8n الحديثة وضع حسب المعرف بجانب القائمة. اكتب
uncensoredهناك. قد تكون القائمة فارغة أو تعرض أسماء OpenAI فقط، لأن n8n يقوم بتصفيتها من جانبها. - أضف موجّهًا مثل لخص تذكرة الدعم هذه في جملتين وقم بتشغيل العقدة.
إذا كان إصدار n8n الخاص بك يُصر على الاختيار من قائمة، فاستخدم نهج طلب HTTP في القسم التالي. إنه يعمل دائمًا لأنك تتحكم في الطلب بالكامل.
استدعاء واجهة برمجة التطبيقات باستخدام عقدة طلب HTTP
عقدة طلب HTTP هي الطريقة الأكثر قابلية للتنبؤ لاستدعاء واجهة برمجة التطبيقات هذه من n8n، وهي تعرض كل معلمة تقبلها واجهة برمجة التطبيقات، بما في ذلك seed، وstop، وtop_p، وtools. قم بتكوينه كما يلي:
- الطريقة:
POST - عنوان URL:
https://api.onekeyllmapi.com/v1/chat/completions - المصادقة: نوع الاعتماد العام مع مصادقة الرأس، الاسم
Authorization، القيمةBearer YOUR_KEY - إرسال الجسم: على، نوع المحتوى JSON
الهيكل (قم بتغيير الحقل إلى التعبير إذا كنت تريد إدراج بيانات من العقد السابقة):
{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Summarize this support ticket in two sentences."}
],
"temperature": 0.4
}
يوجد نص الرد في choices[0].message.content. في العقدة التالية يمكنك الإشارة إليه باستخدام {{ $json.choices[0].message.content }}.
للتحقق من صحة الطلب نفسه خارج n8n أولاً، قم بتشغيل هذا في الطرفية:
curl https://api.onekeyllmapi.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say hello in five words."}]}'
إذا نجح curl ولم ينجح n8n، فإن المشكلة في إعدادات العقدة، وليس في المفتاح أو الرصيد.
وضع JSON لسير العمل التي تقوم بتحليل المخرجات
تفشل سير العمل عندما يلتف النموذج حول البيانات بنثر ودّي. يطلب وضع JSON من الـ API إرجاع كائن JSON صالح، يمكنك تمريره مباشرة إلى عقدة Set أو IF. أضف response_format إلى جسم الطلب:
{
"model": "uncensored",
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Reply only with a JSON object with keys sentiment and summary."},
{"role": "user", "content": "The delivery was late but support fixed it fast."}
]
}
عادتان تجعلان هذا موثوقاً. أولاً، اذكر كلمة JSON وسمِّ المفاتيح في الـ prompt، لأن وضع JSON يضمن البنية، وليس مخططك. ثانياً، لا يزال الرد يصل كسلسلة نصية في message.content، لذا أضف عقدة Code أو تعبيراً يحتوي على JSON.parse() قبل قراءة الحقول. في عقدة OpenAI، يظهر نفس التبديل كخيار تنسيق الرد ضمن خيارات العقدة.
التعامل مع أخطاء 429 والأخطاء الأخرى
يعالج n8n العناصر بالتوازي، لذا يمكن لمجموعة من 50 صفًا أن تصل إلى الحدود بسرعة. يسمح المفتاح الكامل بـ 8 طلبات متزامنة و300 طلب في الدقيقة؛ ويسمح المفتاح التجريبي بـ 2 و60. عند تجاوز الحد، يجيب الـ API بـ HTTP 429 مع الكود rate_limited (عدد كبير جداً في الدقيقة) أو concurrency (عدد كبير جداً في وقت واحد). في حالة الحمل الزائد المؤقت، تحصل على 429 مع رأس Retry-After: 5.
الإعدادات العملية في n8n:
- افتح العقدة، انتقل إلى الإعدادات، فعّل إعادة المحاولة عند الفشل، اضبط الحد الأقصى للمحاولات على 3 أو 4 والانتظار بين المحاولات على 5000 مللي ثانية.
- ضع عقدة Loop Over Items (بحجم دفعة يتراوح بين 4 و6) قبل استدعاء النموذج لتبقى تحت حد 8 طلبات متوازية.
- تحت عقدة الإعدادات، يمكن ضبط عند الخطأ على الاستمرار بمخرج خطأ، بحيث لا يتوقف التنفيذ بسبب صف واحد سيئ.
لمزيد من التفاصيل حول نوعي الحد، اقرأ توثيق الـ API. الأخطاء الأخرى بسيطة: يعني 401 أن المفتاح خاطئ أو أن الرأس يفتقد كلمة Bearer، و404 تعني عادةً وجود خطأ إملائي في Base URL أو جزء مسار إضافي.
قائمة استكشاف الأخطاء
تأتي معظم الأعطال من قائمة قصيرة من الأسباب. انتقل إليها من الأعلى إلى الأسفل قبل أن تشك في الخدمة.
| العرض | السبب المحتمل | الحل |
|---|---|---|
| خطأ 401 عند الحفظ أو التشغيل | مفتاح خاطئ، أو أن الرأس يفتقد كلمة Bearer | الصق المفتاح مرة أخرى؛ في Header Auth يجب أن تبدأ القيمة بـ Bearer |
| 404 | يحتوي Base URL على خطأ إملائي أو مسار إضافي | استخدم بالضبط https://api.onekeyllmapi.com/v1 في بيانات الاعتماد |
| النموذج غير موجود | لم يتم كتابة معرف النموذج كـ uncensored | قم بالتبديل إلى حسب المعرف، أو استخدم عقدة طلب HTTP |
| 429 مع التزامن | أكثر من 8 عمليات تشغيل متوازية (2 على مفتاح تجريبي) | معالجة الدفعات باستخدام Loop Over Items وإضافة إعادة المحاولة |
| خطأ في تحليل JSON في الخطوات التالية | الرد عبارة عن نص، أو لم يحدد الموجّه المفاتيح | قم بالتحليل باستخدام JSON.parse() واذكر المفاتيح في موجّه النظام |
عند التواصل مع الدعم، أدرج رأس الاستجابة X-Request-Id من الطلب الذي فشل. في n8n يمكنك رؤية الرؤوس من خلال تفعيل خيار تضمين رؤوس الاستجابة والحالة في خيارات عقدة طلب HTTP.
الاختبار دون إنفاق الكثير
استخدم رصيد التجربة أثناء البناء. عند 2 طلبًا متزامنًا و60 طلبًا في الدقيقة، يكون مفتاح التجربة بطيئًا للحزم، لكنه كافٍ للتحقق من بيانات الاعتماد، والموجّه، ومنطق التحليل. انتقل إلى مفتاح كامل عند نقل سير العمل إلى جدول زمني.
التكلفة وتصميم سير عمل معقول
التسعير يعتمد على الاستخدام: $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج، من رصيد مسبق الدفع. سير عمل يصنّف 1,000 بريد إلكتروني يوميًا بـ 600 رمز مدخل و100 رمز مخرج لكل بريد يستخدم 0.6 مليون رمز مدخل ($0.09) و0.1 مليون رمز مخرج ($0.05)، أي حوالي $0.14 يوميًا. الطلبات الفاشلة أو المرفوضة لا تُحسب، لذا فإن إعادة المحاولة عند الأخطاء لا تضاعف الفاتورة. التفاصيل في صفحة التسعير.
حافظ على اختصار الموجّهات، وأرسل فقط الحقول التي يحتاجها النموذج، واضبط max_tokens عندما تعلم أن الإجابة موجزة. إذا كنت تشغل نماذج أخرى على جهازك الخاص، اطّلع على المقال حول استخدام نموذج لغوي كبير محلي عبر واجهة API على طراز OpenAI، الذي يستخدم إعدادات العميل نفسها.
