شنو هو One API
One API هو نظام مفتوح المصدر لتدبير وترحيل واجهات برمجة التطبيقات ديال النماذج الكبيرة. كيوحّد واجهات مختلف مزوّدي النماذج فصيغة OpenAI API موحّدة، وكيخلّي التطبيقات تستعمل نفس API Base ورمز الولوج لاستدعاء قنوات متعددة.
المشروع كيدعم OpenAI وAzure OpenAI، وAnthropic Claude، وGoogle Gemini، وMistral، و豆包، و文心一言، و通义千问، و讯飞星火، وChatGLM، و腾讯混元، وMoonshot AI، وDeepSeek، وOllama، وCohere، وGroq، وCloudflare Workers AI، وxAI، وخدمات أخرى.
تنبيه قانوني: ملي كتستعمل One API، خاصك تحترم شروط استعمال OpenAI والقوانين والأنظمة المعمول بها، وممنوع تستعملو فأنشطة غير قانونية. وما خاصكش توفّر للعموم فالمناطق الصينية خدمات الذكاء الاصطناعي التوليدي بلا التسجيلات والتراخيص اللازمة.
الوظائف الرئيسية
واجهة موحّدة: الولوج لمختلف النماذج الكبيرة عبر صيغة API متوافقة مع OpenAI.
قنوات متعددة وتوزيع الحمل: إعداد عدة قنوات upstream، وإذا ما تحددات حتى قناة، كيتدار توزيع الحمل أوتوماتيكياً.
الإخراج المتدفق: دعم وضع stream باش يكون الرد بحال الكتابة حرف بحرف.
تدبير الرموز: تحديد تاريخ الانتهاء، الرصيد، نطاقات IP المسموح بها، والنماذج المسموح بالوصول ليها.
تدبير القنوات: إنشاء القنوات بالجملة، تحديد لائحة النماذج، تجميع القنوات، وربط النماذج.
الرصيد والفوترة: عرض تفاصيل الرصيد، مجموعات المستخدمين والقنوات، معاملات التسعير، والرصيد بالدولار.
الموثوقية: إعادة المحاولة أوتوماتيكياً من بعد الفشل، النشر على عدة آلات، وتكوين Redis واتصالات قاعدة البيانات.
توسيع الإدارة: استدعاء API الإدارة باستعمال رمز الولوج للنظام، وتوسيع وظائف التدبير بلا تعديل الكود المصدري.
نظام المستخدمين: دعم التسجيل والولوج عبر البريد الإلكتروني، Feishu، GitHub، والحسابات الرسمية ديال WeChat، وغيرها.
تخصيص الواجهة: تخصيص اسم النظام، Logo، التذييل، الصفحة الرئيسية، صفحة حول النظام، والثيم.
النشر السريع باستعمال Docker
تحضير مجلد البيانات
SQLite مناسب للتجربة السريعة أو للنشر بعدد قليل من الطلبات المتزامنة. فالأول حضّر مجلداً قابل للكتابة، وغادي يتخزنو فيه قاعدة البيانات والسجلات.
mkdir -p /home/ubuntu/data/one-apiتشغيل One API
docker run --name one-api -d --restart always -p 3000:3000 -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-apiالمنفذ اللي فالجهة اليسرى من -p 3000:3000 هو منفذ الجهاز المضيف، وتقدر تبدلو حسب الحاجة. من بعد التشغيل، دخل لـ http://localhost:3000/.
اسم المستخدم الأولي هو root، وكلمة السر الأولية هي 123456.
مهم: من بعد أول دخول بحساب root، خاصك تبدّل كلمة السر الافتراضية فوراً.
إلا تعذّر سحب الصورة من Docker Hub، تقدر تعوّض justsong/one-api بـ ghcr.io/songquanpeng/one-api. وإلا فشل تشغيل الحاوية، جرّب تزيد --privileged=true اعتماداً على سجلات مشاكل المشروع.
النشر باستعمال MySQL
إلى كان عدد الطلبات المتزامنة كبير، فالـREADME كينصح بوضوح بتعيين SQL_DSN وما تبقاش تستعمل SQLite. خاص قاعدة البيانات oneapi تكون مخلوقة من قبل، أما جداول البيانات فغادي ينشئها البرنامج أوتوماتيكياً.
docker run --name one-api -d --restart always -p 3000:3000 -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-apiعوّض اسم المستخدم وكلمة السر والعنوان والمنفذ بمعطيات قاعدة البيانات الفعلية. إلا كان MySQL خدام على الجهاز المضيف، تقدر تزيد --network="host" حسب إعدادات الشبكة، باش تقدر الحاوية توصل لقاعدة بيانات الجهاز المضيف.
استعمال Docker Compose
المستودع كيوفّر طريقة تشغيل باستعمال Docker Compose. التوضيحات الحالية كتستعمل MySQL، وكتخزّن البيانات فالمجلد ./data/mysql.
docker-compose up -d
docker-compose psالنشر اليدوي من الكود المصدري
إلى بغيتي تبني المشروع بنفسك، حضّر بيئة Node.js وnpm وGo، ومن بعد بنِ الواجهة الأمامية والخلفية بالتتابع.
git clone https://github.com/songquanpeng/one-api.git
cd one-api/web/default
npm install
npm run build
cd ../..
go mod download
go build -ldflags "-s -w" -o one-apiمن بعد ما يكمل البناء، زِد صلاحية التنفيذ وشغّل الخدمة:
chmod u+x one-api
./one-api --port 3000 --log-dir ./logs--port كيتستعمل لتحديد منفذ الاستماع، والقيمة الافتراضية هي 3000؛ و--log-dir كيتستعمل لتحديد مجلد السجلات. وتقدر تستعمل --version باش تشوف الإصدار، أو --help باش تشوف المساعدة.
إكمال الإعداد الأساسي
حل صفحة إدارة One API، دخل بحساب root وبدّل كلمة السر الافتراضية.
دخل لصفحة القنوات، اختار نوع المزوّد المناسب وزِد مفتاح API ديال upstream.
حدّد لائحة النماذج والمجموعات اللي كتدعمها القناة حسب قدرات upstream.
دخل لصفحة الرموز وأنشئ رمز الولوج اللي غادي يستعملو العميل.
حدّد للرمز، حسب الحاجة، الرصيد، مدة الصلاحية، نطاقات IP المسموح بها، والنماذج اللي يمكن الولوج ليها.
One API خدام مباشرة من بعد التثبيت. وباقي الإعدادات تقدر تكملها من خلال واجهة الإدارة، أو متغيرات البيئة، أو ملف .env، أو معاملات سطر الأوامر. إلى استعملت .env، تقدر ترجع للملف .env.example الموجود فالمستودع وتعاود تسميتو .env.
الاستعمال عبر الواجهة المتوافقة مع OpenAI
خاص العميل يعيّن API Base على عنوان نشر One API ديالك، ويعيّن API Key على رمز One API اللي أنشأتي قبل. الصيغة الدقيقة ديال Base URL كتختلف حسب العميل؛ وبالنسبة للمكتبة الرسمية ديال OpenAI، فالـREADME كيعطي صيغة الإعداد التالية:
OPENAI_API_KEY="sk-xxxxxx"
OPENAI_API_BASE="https://<HOST>:<PORT>/v1"الطلبات غادي توصل أولاً لـOne API، ومن بعد One API غادي يرحّلها لـOpenAI أو Azure أو قنوات نماذج أخرى. وبالنسبة لـupstream اللي كتستعمل صيغة مختلفة، One API كيتكلف بتحويل جسم الطلب وجسم الرد اللازمين للترحيل.
الاشتغال مع العملاء الموجودين
أغلب العملاء اللي كيدعمو تخصيص عنوان واجهة OpenAI يقدرو يتربطو. مثلاً مع ChatGPT Next Web، شغّل حاوية العميل أولاً:
docker run --name chat-next-web -d -p 3001:3000 yidadaa/chatgpt-next-webمن بعد، عمّر فصفحة العميل عنوان واجهة One API ورمز One API. وخاص المنفذ ما يكونش متعارض مع 3000 اللي كيستعملو One API.
وChatGPT Web حتى هو يقدر يتصل بـOne API عبر متغيرات البيئة:
docker run --name chatgpt-web -d -p 3002:3002 -e OPENAI_API_BASE_URL=https://openai.example.com -e OPENAI_API_KEY=sk-xxx chenzhaoyu94/chatgpt-webعوّض النطاق والرمز الموجودين فالمثال بالإعدادات ديالك.
تقنيات الإعداد المتقدمة
تحديد قناة أو تفعيل توزيع الحمل
فالحالة الافتراضية، الطلبات اللي ما تحدداتش ليها قناة كتتوزع بين القنوات المتاحة. والرموز اللي كيخلقها المدير تقدر تزيد من بعدها معرّف القناة، باش تفرض معالجة الطلب الحالي من طرف قناة محددة:
Authorization: Bearer ONE_API_KEY-CHANNEL_IDالرموز اللي كيخلقها المستخدمون العاديون ما كتقدرش تحدد معرّف القناة بهاد الطريقة.
استعمال ربط النماذج بحذر
ربط النماذج يقدر يعاود يوجّه النموذج المطلوب من طرف المستخدم لنموذج آخر. ولكن الـREADME كينبّه أنه إلا ما كانتش ضرورة، ما خاصكش تضبط ربط النماذج، حيث من بعد التفعيل كيعاود يتبنى جسم الطلب وما كيبقاش كيتنقل مباشرة، وبعض الحقول اللي مازال ما مدعومينش رسمياً يمكن ما يتنقلوش بنجاح.
استعمال التخزين المؤقت Redis
من بعد تعيين REDIS_CONN_STRING، غادي يستعمل One API Redis كتخزين مؤقت:
REDIS_CONN_STRING=redis://default:redispw@localhost:49153إلا كان التأخير فالوصول لقاعدة البيانات منخفض بزاف، ما كايناش حاجة لتفعيل Redis، حيث التخزين المؤقت يقدر يسبب تأخراً فمزامنة البيانات. فحالة Sentinel أو العنقود، تقدر تعيّن هاد المتغير كلائحة ديال العقد، مع استعمال REDIS_PASSWORD وREDIS_MASTER_NAME.
تحسين اتصالات قاعدة البيانات
تقدر تعدّل اتصالات قاعدة البيانات عبر متغيرات البيئة التالية:
SQL_MAX_IDLE_CONNS: الحد الأقصى للاتصالات غير النشيطة، والقيمة الافتراضية هي100.SQL_MAX_OPEN_CONNS: الحد الأقصى للاتصالات المفتوحة، والقيمة الافتراضية هي1000.SQL_CONN_MAX_LIFETIME: أقصى مدة حياة للاتصال، والقيمة الافتراضية هي60دقيقة.BATCH_UPDATE_ENABLED=true: تفعيل تجميع التحديثات الجماعية لقاعدة البيانات. يقدر يخفف من كثرة الاتصالات، ولكن يمكن يسبب تأخراً فـتحديث الرصيد.BATCH_UPDATE_INTERVAL=5: تحديد الفاصل بين عمليات تجميع التحديثات، والوحدة هي الثواني.
إلا بان الخطأ Error 1040: Too many connections، خاصك تنقص بشكل مناسب من SQL_MAX_OPEN_CONNS، وتقدر حتى تقيّم واش تفعّل التحديثات الجماعية.
إعداد الجلسات والمهلة والوكيل
SESSION_SECRET: تعيين مفتاح جلسة ثابت، باش تبقى ملفات Cookie ديال المستخدمين اللي داخلين صالحة من بعد إعادة التشغيل.RELAY_TIMEOUT: تحديد مهلة طلبات الترحيل، والوحدة هي الثواني.RELAY_PROXY: جعل طلبات الترحيل تمر عبر وكيل محدد للوصول إلى API ديال upstream.USER_CONTENT_REQUEST_TIMEOUT: تحديد مهلة تنزيل المحتوى اللي رفعو المستخدمون.USER_CONTENT_REQUEST_PROXY: إعداد وكيل تنزيل لمحتوى المستخدمين المرفوع، بحال الصور.
إعداد مراقبة القنوات
تقدر تحدّث رصيد القنوات بشكل دوري وتختبر مدى توفرها:
CHANNEL_UPDATE_FREQUENCY=1440
CHANNEL_TEST_FREQUENCY=1440
POLLING_INTERVAL=5الوحدات ديال الجوج متغيّرات اللّولين هي الدقايق، أما الوحدة ديال POLLING_INTERVAL فهي الثواني، وكتستعمل باش تتحكّم فالفاصل بين الطلبات ملي كتدار العمليات بالجملة.
إعداد النشر على بزاف ديال الأجهزة
النشر على بزاف ديال الأجهزة ما يقدرش يبقى معتمد على SQLite المحلي. خاص جميع العُقد يتّاصلو بنفس قاعدة بيانات MySQL، ويحافظو على نفس إعدادات الجلسات.
خاص جميع الخوادم يضبطو نفس
SESSION_SECRET.خاص جميع الخوادم يتّاصلو بنفس قاعدة بيانات MySQL عبر
SQL_DSN.ضبط
NODE_TYPE=slaveفخوادم العبيد؛ إلا ما تضبطاتش، كيتعتبر الخادم رئيسي بشكل افتراضي.استعمل
SYNC_FREQUENCYباش تزامن الإعدادات دورياً من قاعدة البيانات.يقدر خادم العبد يضبط
FRONTEND_BASE_URLباش يوجّه طلبات الصفحات للخادم الرئيسي.يمكن تنصيب Redis فكل خادم عبد وضبط
REDIS_CONN_STRINGلتقليل الولوج لقاعدة البيانات خلال مدة صلاحية التخزين المؤقت.إلا كان التأخير ديال الخادم الرئيسي فالوصول لقاعدة البيانات كبير، من الأحسن حتى هو تفعيل Redis والمزامنة الدورية.
SESSION_SECRET=random_string
SQL_DSN=root:123456@tcp(database:3306)/oneapi
NODE_TYPE=slave
SYNC_FREQUENCY=60
FRONTEND_BASE_URL=https://openai.example.com
REDIS_CONN_STRING=redis://default:redispw@localhost:49153إعداد Nginx وHTTPS
فبيئة الإنتاج، تقدر تستعمل Nginx كوكيل عكسي لـ One API. بالنسبة للنماذج اللي كتاخذ وقت طويل فالاستجابة، خاص تزيد مهلة القراءة بالشكل المناسب.
server {
server_name openai.example.com;
location / {
client_max_body_size 64m;
proxy_http_version 1.1;
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_cache_bypass $http_upgrade;
proxy_set_header Accept-Encoding gzip;
proxy_read_timeout 300s;
}
}فـ Ubuntu، تقدر تستعمل Certbot باش تطلب وتضبط HTTPS:
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx
sudo service nginx restartتشخيص المشاكل الشائعة
كيبان إشعار بأن الرصيد ما كافيش: بالإضافة لرصيد الحساب، خاصك حتى تتأكد من الحد الأقصى ديال رصيد التوكن نفسو.
كيبان إشعار بعدم وجود قناة متاحة: راجع مجموعة المستخدم، ومجموعة القنوات، ولائحة النماذج اللي كتدعمها القناة.
الحِمل ديال المجموعة الحالية وصل للتشبّع: غالباً كيعني أن قناة المصدر رجّعات 429.
العميل كيعطي Failed to fetch: راجع عنوان الواجهة، وAPI Key، وإعدادات HTTPS؛ فالطلبات HTTP داخل صفحات HTTPS يقدر المتصفح يحجبها.
اختبار القناة كيرجّع invalid character: ممكن تكون القناة المصدر رجّعات HTML ماشي JSON صالح، وممكن حتى يكون عنوان IP ديال خادم النشر أو عقدة الوكيل محظورين من طرف Cloudflare.
كاين تخوّف من ضياع البيانات من بعد الترقية: بيانات MySQL ما كتضيعش بسبب ترقية عادية؛ أما SQLite، فخاص تركّب مجلد البيانات بالشكل الصحيح باش يبقى الملف
one-api.dbمحفوظ.
خلاصة
One API مناسب لتوحيد بزاف ديال مزوّدي النماذج ضمن طريقة استدعاء متوافقة مع OpenAI، ولتدبير القنوات والتوكنات والأرصدة والمستخدمين مركزياً. فالاستعمال الشخصي أو فالحالات قليلة التزامن، تقدر تبدا بـ Docker وSQLite؛ أما فحالات التزامن العالي والبيئات متعددة الأجهزة، خاصك تستعمل قاعدة بيانات مشتركة، وتدخل Redis بحذر حسب حالة التأخير. قبل الاستعمال الفعلي، بدّل كلمات السر الافتراضية، وضبط HTTPS، وحافظ على البيانات بشكل دائم، وتأكد أن الخدمة متوافقة مع الشروط والقوانين والأنظمة ذات الصلة.
المشروع مفتوح المصدر بموجب رخصة MIT، ولكن ملف README كيلزم بالإبقاء على نسبة المشروع ورابطو فأسفل الصفحة؛ وإذا بغيتي تحيد النسبة، خاصك تاخذ الترخيص قبل. لمزيد من المعلومات، شوف مستودع One API على GitHub.