AIProxyServer - الدليل

البدء

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

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

• Proxy Server — الحالة الحالية وbase URL وزر لبدء أو إيقاف المستمع
• Bearer Token — مفتاح اختياري للمصادقة وعرض الرمز
• Providers — كل مزودي AI السحابيين المدعومين، مع زر Set API Key لكل صف

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

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

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

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

# Example: OpenAI Python SDK pointed at the proxy
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 بيانات اعتماد المنبع عند إعادة توجيه الطلب.

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

لوحة Proxy Server

لوحة Bearer Token

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

لوحة Providers

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

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

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

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

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

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

مرجع API

نقاط النهاية

التدفق

عندما يرسل العميل "stream": true، يستجيب proxy بأحداث Server-Sent Events بتنسيق 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 إلى هذا الشكل حتى يتمكن جميع العملاء من استخدام محلل واحد.

ترويسة المصادقة

عند تشغيل Require Bearer Token authentication، أرسل الرمز من النافذة الرئيسية مع كل طلب:

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

الإعدادات

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

أمثلة العميل

cURL

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

# Claude via the same OpenAI shape
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 Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # ignored when Bearer Token is off
)
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

// Using any OpenAI-compatible Dart client
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // unused when Bearer Token is off
);

نصائح

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

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

لا يبدأ proxy

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

يعيد الطلب 401 Unauthorized

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

يعيد الطلب "API key is not configured"

• افتح قائمة Providers وانقر Set API Key للمزود المعني.
• بالنسبة لـ ERNIE، يجب تعبئة كل من API Key وSecret Key. بالنسبة لـ Azure OpenAI، يلزم أيضًا Endpoint Base URL.

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

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

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

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

الخصوصية

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