AIProxyServer - الدليل

البدء

1. تشغيل التطبيق

افتح AIProxyServer. عند التشغيل الأول يبدأ الوكيل تلقائياً ويستمع على المنفذ 8421 في جهازك المحلي. تعرض النافذة الرئيسية ثلاثة أقسام:

• خادم الوكيل — الحالة الحالية، وBase URL، وزراً لبدء المستمع أو إيقافه
• Bearer Token — مفتاح اختياري لتشغيل المصادقة أو إيقافها وعرض الرمز المميز
• المزوّدون — جميع مزوّدي AI السحابيين المدعومين، مع تعيين مفتاح API زر في كل صف

2. إضافة أول مفتاح API

1. اختر أي مزوّد من قائمة المزوّدين (مثل OpenAI (ChatGPT))
2. انقر الحصول على مفتاح API لفتح وحدة تحكم المزوّد في متصفحك، ثم أنشئ مفتاحاً أو انسخه
3. انقر تعيين مفتاح API في الصف نفسه والصق القيمة في مربع الحوار
4. انقر حفظ. يتغير ملصق الحالة إلى تم الإعداد بالأخضر

3. توصيل تطبيق عميل

وجّه أي عميل متوافق مع OpenAI إلى الوكيل. يكون Base URL هو http://localhost:8421/<provider>/v1. يحدد مقطع المزوّد السحابة التي تستقبل الطلب.

# مثال: توجيه OpenAI Python SDK إلى الوكيل
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/openai/v1",
    api_key="not-used-but-required-by-sdk",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

لا يرى العميل المفتاح الحقيقي مطلقاً. يضيف AIProxyServer بيانات اعتماد المصدر عند إعادة توجيه الطلب.

نظرة عامة على الواجهة

لوحة خادم الوكيل

لوحة Bearer Token

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

لوحة المزوّدين

صف واحد لكل مزوّد سحابي مدعوم. يعرض كل صف:

• الاسم المعروض (على سبيل المثال Claude (Anthropic))
• حالة الإعداد — باللون الأخضر تم الإعداد عند حفظ مفتاح API، وبالرمادي غير مُعدّ في غير ذلك
• مسار URL الذي يستخدمه عملاؤك، مثل /anthropic/v1/chat/completions
• تعيين مفتاح API — يفتح مربع حوار لإدخال بيانات الاعتماد
• الحصول على مفتاح API — يفتح وحدة تحكم المزوّد في متصفحك

المزوّدون المدعومون

تتضمن الحزمة إحدى عشرة خدمة AI سحابية. يستخدم معظمها تنسيق OpenAI Chat Completions أصلاً ويُمرَّر كما هو. أما ثلاث خدمات (Anthropic وGemini وERNIE) فتستخدم بروتوكولاتها الخاصة؛ ويترجم AIProxyServer الطلبات والاستجابات فوراً كي لا يرى عميلك سوى تنسيقات OpenAI.

ملاحظات خاصة بالمزوّد

• Azure OpenAI — الصق نقطة نهاية التوزيع الكاملة في حقل Endpoint Base URL، على سبيل المثال حقل، على سبيل المثال https://my-resource.openai.azure.com/openai/deployments/gpt-4o. يضيف الوكيل /chat/completions?api-version=2024-02-01 تلقائياً.
• ERNIE — يستخدم Baidu Qianfan OAuth، لذا يلزم كل من API Key و Secret Key . يطلب AIProxyServer رموز الوصول ويخزنها مؤقتاً في الخلفية.
• Gemini — تتم المصادقة عبر معلمة استعلام URL؛ ويضيفها الوكيل نيابةً عنك. لا تزال حصص المستوى المجاني لكل دقيقة سارية.

مرجع API

نقاط النهاية

البث

عندما يرسل العميل "stream": true، يستجيب الوكيل بأحداث مرسلة من الخادم بتنسيق OpenAI:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},...}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},...}]}

data: [DONE]

تُترجم التدفقات الأصلية لـ Anthropic وGemini إلى هذا الشكل كي يتمكن جميع العملاء من استخدام محلل واحد.

رأس المصادقة

عندما يكون طلب مصادقة Bearer Token مفعّلاً، أرسل الرمز من النافذة الرئيسية مع كل طلب:

Authorization: Bearer <token-shown-in-app>

الإعدادات

افتح نافذة الإعدادات من أيقونة الترس في شريط الأدوات السفلي.

أمثلة العملاء

cURL

# OpenAI (تمرير مباشر)
curl http://localhost:8421/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Claude عبر نفس تنسيق OpenAI
curl http://localhost:8421/anthropic/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

حزمة OpenAI SDK للغة Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # يتم تجاهله عند إيقاف Bearer Token
)
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Flutter / Dart

// استخدام أي عميل Dart متوافق مع OpenAI
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // غير مستخدم عند إيقاف Bearer Token
);

نصائح

• اترك Bearer Token متوقفاً أثناء التطوير محلياً؛ وفعّله فور تمكين الوصول عبر LAN.
• استخدم عناوين URL أساسية مميزة لكل مزود في رمز العميل لتتمكن من تبديل المزودين بتغيير ثابت واحد.
• يبدأ الوكيل تلقائياً، لكن يمكنك إيقافه مؤقتاً من النافذة الرئيسية إذا حدث تعارض في المنفذ.
• إذا فرضت الطبقة المجانية لأحد المزودين حداً للمعدل، تُمرَّر رسالة خطأ المصدر كما هي. لا توجد أي آلية إعادة محاولة مخفية عن العميل.
• نقطة النهاية /v1/providers مفيدة لاكتشاف المزودين الذين جرى تكوينهم أثناء وقت التشغيل.

استكشاف الأخطاء وإصلاحها

الوكيل لا يبدأ

• قد تكون عملية أخرى تستخدم المنفذ 8421 بالفعل. غيّر المنفذ في الإعدادات ثم أعد تشغيل الوكيل.
• تحقق من سجل النظام بحثاً عن رسالة الخطأ المعروضة عند بدء التشغيل.

يعيد الطلب الخطأ 401 غير مصرح به

• شرط Bearer Token مفعّل، لكن العميل لم يرسل قيمة مطابقة في Authorization: Bearer ... الترويسة.
• قد يكون مفتاح API الخاص بالمزود غير صالح — يُمرَّر خطأ المصدر، لذا تحقق من نص الرسالة.

يعيد الطلب رسالة "مفتاح API غير مُكوَّن"

• افتح قائمة المزودين وانقر على تعيين مفتاح API للمزود المعني.
• بالنسبة إلى ERNIE، يجب ملء كل من API Key وSecret Key. وبالنسبة إلى Azure OpenAI، يلزم أيضاً عنوان URL الأساسي لنقطة النهاية.

لا يستطيع الجهاز المحمول الوصول إلى الوكيل

• فعّل السماح بالوصول عبر LAN في الإعدادات.
• استخدم عنوان IP لشبكة LAN المعروض في حقل عنوان URL الأساسي، وليس localhost.
• تأكد من أن الجهازين على شبكة Wi-Fi نفسها وأن جدار الحماية يسمح بالاتصالات الواردة على منفذ الوكيل.

تصل استجابات البث دفعة واحدة

• تأكد من أن عميلك يرسل "stream": true في نص JSON.
• تقوم بعض مكتبات HTTP بتخزين SSE مؤقتاً افتراضياً — عطّل تخزين الاستجابة مؤقتاً من جانب العميل.

الخصوصية

• تُخزَّن مفاتيح API مشفّرة باستخدام Fernet في ~/Library/Application Support/AIProxyServer/credentials.enc. مفتاح التشفير في master.key لديه أذونات 0600.
• يُخزَّن Bearer Token أيضاً، عند تفعيله، في الخزنة المشفرة فقط ولا يُكتب مطلقاً في ملف الإعدادات العادي.
• لا يمرّر الوكيل الطلبات إلا إلى المزودين الذين أعددتهم صراحةً. ولا يجري أي اتصالات صادرة أخرى.
• لا قياس عن بُعد، ولا تحليلات، ولا تقارير أعطال.
• ربط الشبكة الافتراضي هو 127.0.0.1 فقط. إتاحة LAN اختيارية.
• لا تُخزَّن محتويات المحادثة. يمرر AIProxyServer البايتات ثم ينساها فوراً.