دوز مباشرة للمحتوى الرئيسي
دروس فالذكاء الاصطناعي

بني بوابة متعددة المزوّدين لوكلاء البرمجة باستعمال My Free Code

تعلّم كيفاش تثبّت My Free Code v0.8، تهيّأ الموديلات المرتابطة بالمزوّدين ولا المحلية، تربط وكلاء البرمجة، تسيّر توجيه المستويات والبدائل المرتّبة، تستكشف واجهة الإدارة، وتأمّن البوابة للاستعمال المحلي.

حوالي 21 دقايق ديال القراية
بوابة متعددة المزوّدين لوكلاء البرمجة باستعمال My Free Code

شنو كيدير الكود المجاني ديالي

My Free Code v0.8 هو بوابة مستقلة كتدعم بزاف ديال المزوّدين، مخصّصة لـ Claude Code ووكلاء البرمجة الآخرين. كتشغّل بوابة FastAPI محلية كتقبل طلبات الوكيل، كتختار الموديل المهيّأ، كترجم الطلب للمزوّد المعني، وكتبعث الجواب للعميل بشكل متدفّق. المشروع ما عندوش علاقة بـ Anthropic.

البوابة كتدعم بروتوكول Anthropic Messages فـ /v1/messages، وحساب التوكنات ديال Anthropic فـ /v1/messages/count_tokens، ونقطة نهاية متوافقة مع OpenAI Responses فـ /v1/responses. وكتوفّر حتى اكتشاف الموديلات عبر /v1/models، ونقطة فحص الحالة فـ /health، وواجهة إدارة محلية فـ /admin، وواجهات إدارية موثّقة تحت /api/admin/*.

أهم المزايا

  • بروتوكولات متعددة للوكلاء: قبول طلبات متوافقة مع Anthropic Messages وOpenAI Responses عبر بوابة وحدة.
  • قدرات الوكلاء: التعامل مع Server-Sent Events المتدفقة، وتعريفات الأدوات، واستدعاءات الأدوات، ونتائج الأدوات، والصور، وتمرير بيانات الاستدلال بلا تغيير.
  • توجيه مستويات Claude: تعيين موديلات مختلفة من المزوّدين لطلبات Fable وOpus وSonnet وHaiku.
  • توجيه resilient: استعمال بدائل مرتبة للموديلات، وتأخير إعادة المحاولة حسب صحة المزوّد، وضوابط التزامن لكل مزوّد، والتحكم فـ نوافذ المعدّل.
  • هوية مستقرة للموديل: الحفاظ على هوية موديل البوابة العمومية حتى ملي كيوجّه الراوتر الطلب لمزوّد آخر.
  • توحيد الاستدلال: فصل نية التفكير على طريقة Claude عن حقول الطلب الخاصة بكل مزوّد.
  • دعم الموديلات المحلية: الربط مع Ollama أو LM Studio أو llama.cpp عبر نقاط النهاية المتوافقة مع OpenAI.
  • مشغّلات الوكلاء: تهيئة بيئة البروكسي لـ Claude Code وCodex وPi وOpenCode وCline وHermes وDeepSeek Harness وGrok Build وMuse Code.

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

كيفاش كتخدم البنية

             Coding Agents / IDEs
                      |
          +-----------+-----------+
          |                       |
    Anthropic Messages       OpenAI Responses
          |                       |
          +-----------+-----------+
                      |
                FastAPI Gateway
                      |
                Model Router
                      |
          +-----------+-----------+
          |                       |
       Primary                  Fallbacks
          |                       |
          +-----------+-----------+
                      |
              Provider Runtime
                      |
       +--------------+--------------+
       |              |              |
 OpenAI-compatible  Specialized   Local
     adapter          adapter     runtime
       |              |              |
     APIs          provider API  Ollama/LM Studio

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

ثبّت البوابة

المتطلبات

  • Python 3.10 أو أحدث.
  • نسخة محلية من المستودع.
  • بيانات الاعتماد ديال أي مزوّدين عن بُعد ناوي تستعملهم.
  • عميل وكيل البرمجة اللي بغيتي تشغّلو، مثبّت ومتاح فـ PATH.

1. صايب بيئة افتراضية

python -m venv .venv

2. فعّلها وثبّت الاعتماديات

فـ Windows PowerShell، نفّذ:

.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
copy .env.example .env

فـ macOS أو Linux، نفّذ:

source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env

3. شغّل My Free Code

python -m my_free_code

افتراضياً، البوابة متاحة فـ http://127.0.0.1:8082. تقدر تفحص الخدمة عبر http://127.0.0.1:8082/health وتحل واجهة الإدارة المحلية فـ http://127.0.0.1:8082/admin.

هيّأ الموديلات والمزوّدين

عدّل ملف .env اللي تخلق باش تختار الموديل الافتراضي، وتعيّن الموديلات لمستويات Claude، وتحدّد البدائل المرتبة. المثال التالي كيستعمل موديلات من مزوّدين مختلفين:

MODEL=open_router/openrouter/free
MODEL_SONNET=deepseek/deepseek-chat
MODEL_HAIKU=groq/llama-3.3-70b-versatile
MODEL_OPUS=nvidia_nim/meta/llama-3.3-70b-instruct
FALLBACK_MODELS=deepseek/deepseek-chat,ollama/llama3.1

زِد مفاتيح API ديال المزوّدين المعنيين فـ .env. استعمل .env.example كمرجع لحقول الإعدادات المدعومة. عاود شغّل البوابة من بعد ما تبدّل البيئة ديالها.

MODEL كيختار الموديل العام ديال البوابة. المتغيّرات الخاصة بالمستوى، بحال MODEL_SONNET وMODEL_HAIKU وMODEL_OPUS، كتخلّي الراوتر يوجّه مستويات موديلات Claude لخدمات مختلفة من المزوّدين. FALLBACK_MODELS هي لائحة مرتبة ديال البدائل مفروقة بفواصل.

ربط Claude Code

الخيار 1: عيّن البيئة يدوياً

فـ Windows PowerShell، وجّه Claude Code للبوابة المحلية المتوافقة مع Anthropic:

$env:ANTHROPIC_BASE_URL="http://127.0.0.1:8082"
$env:ANTHROPIC_AUTH_TOKEN="local"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
claude

الـURL الأساسي كيوجّه طلبات Claude Code لـ My Free Code، بينما اكتشاف الموديلات كيخلّي الكليون يقدر يستعلم على كاتالوغ الموديلات ديال الـgateway.

الخيار 2: استعمل الواجهة ديال التشغيل

python -m my_free_code.cli.mfc claude

الـlauncher كيحضّر البيئة ديال الـproxy المحلي ومن بعد كيفوّض الآرگومونات للكليون المثبّت ديال Claude Code. ما كيثبّتش الكليون براسو.

شغّل وكلاء برمجة آخرين

نفس التجريد ديال الـlauncher كيدعم حتى لعدة كلاينتات إضافية:

python -m my_free_code.cli.mfc codex
python -m my_free_code.cli.mfc pi
python -m my_free_code.cli.mfc opencode
python -m my_free_code.cli.mfc cline
python -m my_free_code.cli.mfc hermes
python -m my_free_code.cli.mfc deepseek-harness
python -m my_free_code.cli.mfc grok
python -m my_free_code.cli.mfc muse

قبل ما تشغّل شي واحد من هاد الأوامر، تأكّد باللي الكليون المناسب مثبّت ويمكن الوصول ليه من PATH. الـlauncher غير كيجهّز بيئة الـgateway وكيشغّل البرنامج الموجود.

فهم التراجعات المرتّبة

إلى افترضنا باللي البيئة فيها إعداد التوجيه هادا:

MODEL_SONNET=deepseek/deepseek-chat
FALLBACK_MODELS=groq/llama-3.3-70b-versatile,ollama/llama3.1

طلب Sonnet كيمشي فاللول لـ deepseek/deepseek-chat. إلا فشل هاد المحاولة قبل ما تخرّج شي نتيجة، الراوتر كيجرب groq/llama-3.3-70b-versatile. وإلا فشلت المحاولة الثانية حتى هي قبل الإخراج، كيجرب ollama/llama3.1.

Claude Code
    |
    v
deepseek/deepseek-chat
    |
    | failure before output
    v
groq/llama-3.3-70b-versatile
    |
    | failure before output
    v
ollama/llama3.1

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

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

Ollama

شغّل خدمة Ollama بوحدها، ومن بعد ضبّط الـbase URL المتوافق مع OpenAI والموديل:

OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
MODEL=ollama/llama3.1

LM Studio

شغّل السيرفر المحلي ديال LM Studio واستعمل:

LM_STUDIO_BASE_URL=http://127.0.0.1:1234/v1
MODEL=lmstudio/qwen3.5-coder

llama.cpp

شغّل سيرفر llama.cpp وضبّط:

LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1
MODEL=llamacpp/my-model

الـruntimes المحلية تقدر حتى هي تكون فـ FALLBACK_MODELS، وبهذا يقدر موديل محلي يخدم كبديل منين كيفشل طلب بعيد قبل ما يخرج أي إخراج.

ضبط سلوك الاستدلال

الـgateway كيقبل نية التفكير بصيغة Claude وكيطبّعها قبل ما يحوّل adapter ديال المزوّد الطلب. المودات المدعومة هي:

auto
on
off

وتقدر تحدّد مستوى المجهود اختيارياً:

low
medium
high

هاد الفصل كيخلّي سياسة الاستدلال اللي كيتعامل معاها الـagent مستقلة على الحقول الخاصة بكل مزوّد. كل adapter ديال مزوّد يقدر يربط المود ومستوى المجهود المطبّعين بالحقول الموثّقة عند داك المزوّد.

راقب الـgateway

حلّ واجهة الإدارة محلياً فـ:

http://127.0.0.1:8082/admin

واجهة Admin API الموثّقة بصيغة JSON فيها:

GET /api/admin/status
GET /api/admin/models
GET /api/admin/providers

استعمل هاد الـendpoints باش تراقب حالة الـgateway، وكاتالوغ الموديلات، والمزوّدين المكوّنين. الـendpoints الإدارية كتحتاج للمصادقة وخصها تبقى خاصة.

نصائح متقدمة

خلّي هوية الموديل العمومية ثابتة

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

صمّم ترتيب التراجع بقصد

حطّ الموديلات فـ FALLBACK_MODELS بالترتيب الدقيق اللي بغيتي تجربهم به. خذ بعين الاعتبار توفّر المزوّدين، وواش خاص runtime محلي يكون هو الخيار الأخير. تذكّر باللي التراجع كيوقع غير قبل ما يلتازم إخراج البث.

حترم الاختلافات بين المزوّدين

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

استعمل نقاط نهاية البروتوكول مباشرة عند الحاجة

  • صيفط طلبات Anthropic Messages لـ /v1/messages.
  • حسب التوكنات بصيغة Anthropic عبر /v1/messages/count_tokens.
  • استعمل الواجهة المتوافقة مع OpenAI Responses فـ /v1/responses.
  • اكتشف الموديلات عبر /v1/models.
  • تحقّق من صحة الخدمة عبر /health.

شغّل حزمة الاختبارات

pytest -q

المستودع فيه اختبارات حتمية للتوجيه، وتحويل البروتوكولات، والمصادقة، والاستدلال، وكاتالوغ الموديلات، وأساسيات البث. شغّلهم من بعد أي تغيير فـgateway ولا التوجيه ولا كود المزوّد.

إرشادات الأمان

My Free Code مخصّص للاستعمال المحلي. طبّق الاحتياطات التالية:

  • خلّي HOST=127.0.0.1 باش الخدمة تربط غير بالماكينة المحلية.
  • عيّن PROXY_AUTH_TOKEN ما يكونش ساهل التخمين.
  • عمّر ما تـcommitّيش ملف .env فـsource control.
  • ما تعرّضش الـAdmin endpoints مباشرة للإنترنت.
  • خلّي بيانات اعتماد المزوّدين فـالبيئة ولا فالإعدادات. الـgateway ما كيبعثش بيانات اعتماد مزوّد لمزوّد آخر.

الخلاصة

My Free Code كيوفّر طبقة محلية للتوافق والتوجيه بين وكلاء البرمجة ومزوّدي نماذج سحابيين أو محليين متعدّدين. من بعد ما كتثبّت التبعيات ديال Python، وكتكوّن النماذج وبيانات الاعتماد، وكتشغّل البوابة، تقدر تربط Claude Code ولا شي عميل آخر مدعوم، وتعيّن النماذج حسب مستويات Claude، وتبني سلسلة احتياطية مضبوطة. والطبقات المفصولة ديالو، الخاصة بالبروتوكول والتوجيه والمزوّد والمشغّل، كتسهّل حتى فحص المشروع واختباره.