دليل مبتدئين لـ Agent2API: ربط حالة تسجيل الدخول ديال الذكاء الاصطناعي فسطح المكتب ببوابة متوافقة مع OpenAI

شنو هو Agent2API

Agent2API هو بوابة API محلية ديال الذكاء الاصطناعي، كتجمع حسابات مسجّلة الدخول فعدد من تطبيقات الذكاء الاصطناعي المكتبية، وكتوفّر إمكانية استدعاء النماذج من خلال واجهة موحّدة متوافقة مع OpenAI. أي تطبيق كيدعم تخصيص base_url يقدر يتّصل بـ http://127.0.0.1:3065/v1، وغالباً ما كيحتاجش لمفتاح API من المزوّد الأصلي ولا لتعديل التطبيق.

المشروع كيدعم ثلاثة بروتوكولات: Chat وResponses وMessages، وكيقدّم حتى واجهة لائحة النماذج /v1/models. البوابة كتخدم فالحاسوب المحلي ديالك أو فالسيرفر اللي نشرتي فيه الخدمة، والحصة ديال الحساب كتبقى مرتبطة بالحساب المعني.

نظرة عامة على الوظائف الرئيسية

• واجهة متوافقة مع OpenAI: كتدعم /v1/chat/completions و/v1/responses و/v1/messages، وMessages كتدعم حتى count_tokens.
• مزوّدون متعددون: فيها عدة مزوّدين مدمجين، منهم WorkBuddy و小浣熊 وCatPaw وQoder وTrae وغيرهم، ويمكن حتى إعداد مزوّد مخصص.
• تدوير الحسابات: الحسابات كيتنظمو حسب الأولوية، وعند وقوع 429 يمكن الانتقال لحساب آخر، والحسابات اللي ففترة التبريد بسبب تجاوز الحد ما كيتستعملوش من جديد.
• تدبير بيانات الاعتماد: بعض المزوّدين كيدعمو التجديد التلقائي للرمز، والتحديث الجماعي لبيانات الاعتماد القريبة من الانتهاء، وتحديث كتالوج النماذج.
• الشبكة والأمان: يمكن تعيين بروكسي مستقل للخروج من الشبكة لكل حساب، وتوزيع الصلاحيات باستعمال عدة مفاتيح للبوابة.
• التدبير التشغيلي: كتوفّر تقارير على عدد الطلبات، ونسبة النجاح، واستهلاك Token، ونسبة إصابة التخزين المؤقت، والخرائط الحرارية طويلة المدى.
• المهام المجدولة: يمكن تدبير مهام تسجيل الحضور التلقائي، وصيانة بيانات الاعتماد، وتحديث كتالوج النماذج.

اختيار طريقة النشر

Agent2API كيتوفّر بثلاثة أشكال. نسخة سطح المكتب مناسبة للاستعمال فالحاسوب الشخصي، وكتدعم Windows وmacOS وLinux، ويمكنها البقاء خدامة فشريط النظام؛ نسخة السيرفر مناسبة لبيئات Windows Server أو Linux بلا واجهة رسومية؛ وDocker مناسبة للمستخدمين اللي عندهم بيئة الحاويات من قبل. الطرق الثلاثة ما كتحتاجش تثبيت Node.js وقت التشغيل.

• نسخة سطح المكتب: شغّل التطبيق باستعمال حزمة التثبيت، والبوابة كتخدم داخل مسار التطبيق.
• نسخة السيرفر: ثبّتها كخدمة نظام، ودخل للوحة التدبير من المتصفح، مع دعم التشغيل التلقائي عند بدء النظام.
• Docker: استعمل الصورة aimodcc/agent2api:latest، وهي كتدعم amd64 وarm64.

التثبيت والإعداد الأولي

الطريقة الأولى: نسخة سطح المكتب

حمّل حزمة التثبيت المناسبة للنظام من Latest Releases ديال المشروع. من بعد التشغيل، دخل لصفحة “الحسابات” وزِد حساباً أو أكثر للمزوّدين. بوابة نسخة سطح المكتب كتستمع افتراضياً للمنفذ 3065 فالجهاز المحلي.

الطريقة الثانية: سيرفر Linux

tar -xzf agent2api-server-linux-amd64.tar.gz && cd agent2api-server-linux-amd64 && sudo bash install.sh

من بعد ما يكمل التثبيت، دخل من المتصفح إلى http://127.0.0.1:3065/. إلا كانت الخدمة خدامة فمضيف بعيد، بدّل اسم المضيف فالعنوان بعنوان IP ديال السيرفر أو باسم النطاق.

الطريقة الثالثة: Windows Server

Expand-Archive agent2api-server-windows-amd64.zip -DestinationPath C:\agent2api-pkg
cd C:\agent2api-pkg
.\install-service.ps1

نفّذ الأوامر السابقة فـ PowerShell بصلاحيات المسؤول. سكريبت التثبيت غادي يسجّل الخدمة فالنظام.

الطريقة الرابعة: Docker

docker run -d --name agent2api --restart unless-stopped -p 3065:3065 -v ./data:/data aimodcc/agent2api:latest

‏./data:/data هنا كتستعمل لحفظ الإعدادات وبيانات الحسابات بشكل دائم. من بعد تشغيل الحاوية، حلّ http://127.0.0.1:3065/ وكمل الإعداد الأولي.

إعداد المدير ومفتاح البوابة

1. حلّ لوحة التدبير وسجّل حساب المدير.
2. دخل لصفحة “مفاتيح البوابة” وأنشئ مفتاحاً لاستعماله من طرف التطبيقات.
3. دخل لصفحة “الحسابات”، واختار المزوّد والإصدار، ومن بعد كمّل تسجيل الدخول عبر الويب أو استورد حالة الدخول حسب الخطوات المعروضة.
4. تأكّد بأن حالة الحساب، والصلاحية، ومعلومات الرصيد عادية.
5. دخل لصفحة “تدبير النماذج” وراجع النماذج المتاحة وربط النماذج.

إلا ما كانش مفتاح البوابة مهيّأ، المشروع كيرفض طلبات API افتراضياً. ما تعرّضش مفتاح البوابة فالكود العمومي أو السجلات أو التطبيقات غير الموثوقة.

إعداد الحسابات والنماذج

فصفحة تدبير الحسابات تقدر تشوف صلاحية الحساب، والرصيد، والطابور العام، وحالة تبريد الحدود حسب النموذج. من بعد إضافة عدة حسابات، النظام كيدبّرها حسب الأولوية؛ وإذا وصل شي حساب لرمز 429 أو دخل فحالة التبريد، يمكن الانتقال لحساب آخر متاح.

صفحة تدبير النماذج كتسمح بعرض لائحة النماذج، والمعامل، ومعلومات السياق، وعلاقات الربط حسب المزوّد. المزوّدون اللي كيدعمو جلب اللائحة تلقائياً عبر الإنترنت كيتحدّثو بانتظام؛ وبعض المنصات كتوفّر حتى جدولاً ثابتاً مدمجاً كحل احتياطي.

أول استدعاء لـ API

فالتطبيق اللي كيدعم تخصيص عنوان API، عيّن Base URL على الشكل التالي:

http://127.0.0.1:3065/v1

حط مفتاح API اللي أنشأتيه قبل فمكان مفتاح البوابة. تقدر تستعمل sk-local كقيمة تجريبية، ولكن فالاستدعاء الفعلي خاصك تستعمل المفتاح اللي تولّد من اللوحة.

أولاً تأكّد من حالة البوابة:

curl http://127.0.0.1:3065/health

من بعد شوف لائحة النماذج:

curl http://127.0.0.1:3065/v1/models \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY"

مثال على استدعاء واجهة Chat Completions:

curl http://127.0.0.1:3065/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "سلام، عرّفني براسك من فضلك."}
    ]
  }'

بدّل YOUR_GATEWAY_KEY بمفتاح البوابة، وبدّل YOUR_MODEL_ID بمعرّف النموذج اللي رجعاتو /v1/models. بروتوكولا Responses وMessages كيستعملو حتى هما نفس عنوان البوابة، وحقول الطلب خاصها تتبع الصيغة ديال التطبيق أو البروتوكول المعني.

حسابات متعددة، البروكسي والمهام المجدولة

تدوير الحسابات المتعددة

من بعد إضافة عدة حسابات لنفس المزوّد، تقدر تستافد من طابور الأولوية العام وآلية التخفيض عند 429 باش تحسّن التوفّر. من الأفضل تضبط الأولوية حسب حصة الحساب، والصلاحية، وسيناريو الاستعمال، وتراجع بانتظام الحسابات اللي فالتبريد.

بروكسي الخروج من الشبكة

المشروع كيدعم إعداد مخرج مستقل لكل حساب. هاد الوظيفة مناسبة للحالات اللي خاص فيها تدبير شبكة الخروج بشكل منفصل لكل حساب، ولكن خاص المستخدم يقيّم بنفسه مدى توفّر البروكسي، والامتثال، ومخاطر مراقبة الحساب.

المهام المجدولة

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

عرض التقارير والاستهلاك

صفحة التقارير كتسمح بعرض عدد الطلبات، ونسبة النجاح، وإجمالي Token، والنماذج الأكثر استعمالاً، وترتيب الحسابات، كما يمكن عرض توزيع الاستهلاك حسب المزوّد. صفحة الاتجاهات كتعرض نسبة إصابة التخزين المؤقت خلال 24 ساعة، واستهلاك Token، والبيانات المحسوبة حسب اليوم.

إلا كان المزوّد كيدعم الاستعلام عن الرصيد أو الاستهلاك، تقدر تشوف هاد المعلومات مباشرة فصفحة الحساب. أما مركز تسجيل الحضور فمخصّص لعرض النظرة العامة على التسجيل ومجموعات التسجيل اليومية.

ملاحظات على التطوير والبناء

إلا بغيتي تبني نسخة سطح المكتب من المصدر، فالبيئة خاصها Rust 1.77 أو إصدار أحدث، وسلسلة أدوات Tauri 2، وNode.js 18.17 أو إصدار أحدث. Node.js كيتستعمل غير فبناء الواجهة الأمامية وسكريبتات Tauri، أما نسخة سطح المكتب من بعد التغليف فما كتحتاجش Node.js وقت التشغيل.

npm run tauri:install
npm run tauri:dev
npm run tauri:build
npm run build:icon

من بينها، tauri:dev كيتستعمل فمود التطوير وإعادة التحميل السريع، وtauri:build كيتستعمل لبناء حزم تثبيت تطبيقات سطح المكتب. ملف DMG ديال macOS ما كيتبناش غير فـ macOS، وما يمكنش تبنيه بشكل متقاطع من Windows؛ الإصدارات النهائية كينتجها مسار CI ديال المشروع.

أمان بيانات الدخول وحدود الاستعمال

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

المشروع كيخزّن بيانات الدخول ديال الحساب، بحال accessToken وrefreshToken، بصيغة واضحة فدليل الإعدادات المحلي، والمكان الافتراضي هو ~/.agent2api/. الملفات المصدّرة حتى هي ممكن تحتوي على بيانات دخول واضحة، لذلك ما خاصكش ترفع الإعدادات لمستودع عام، ولا تحطها فخدمة تخزين سحابية، ولا تشاركها مع شي حد.

الـ README كيمنع بوضوح استعمال المشروع لأغراض تجارية، أو إعادة توزيعه بهدف الربح، أو تسيير حسابات بكميات كبيرة، أو تجاوز قيود الفوترة أو الحصص ديال الخدمة الأصلية، أو أي أنشطة أخرى مخالفة للقوانين والأنظمة. فحالات الإنتاج أو الاستعمال التجاري، خاصك تستعمل القنوات الرسمية وواجهة API الرسمية ديال الخدمة الأصلية. قبل الاستعمال، قرا الترخيص وتصريح الاستعمال ديال المشروع.

الخلاصة

Agent2API كيجمع حسابات ديال بزاف ديال عملاء سطح المكتب فبوابة محلية وحدة متوافقة مع OpenAI. من بعد ما تكمل التثبيت، وتزيد الحسابات، وتنشئ مفتاح البوابة، غادي تقدر تستعمل base_url موحّد مع الأدوات اللي كتدعم تخصيص عنوان API؛ أما التناوب بين الحسابات، وتدبير النماذج، والوكيل، والمهام المجدولة، والتقارير، فهي مناسبة لاحتياجات التدبير المحلي المتقدمة. أثناء الاستعمال، حافظ مزيان على بيانات الدخول والتزم بدقة بشروط الخدمة الأصلية وتصريح الاستعمال الإضافي ديال المشروع.