OpenHands: البديل المفتوح المصدر لـ Devin AI

إن عالم تطوير البرمجيات يشهد تحولًا زلزاليًا، driven by التقدم السريع في الذكاء الاصطناعي. لقد رأينا أدوات الذكاء الاصطناعي تتطور من مساعدات بسيطة تكمل الكود إلى أنظمة متطورة قادرة على فهم المتطلبات المعقدة وتوليد تطبيقات وظيفية. في هذه البيئة المثيرة، ظهر لاعب جديد يجذب خيال المطورين في جميع أنحاء العالم: OpenHands. وضعت كبديل مفتوح المصدر قوي مقابل مطوري الذكاء الاصطناعي المملوكين مثل Devin AI، تقدم OpenHands منصة حيث يمكن لوكلاء الذكاء الاصطناعي أداء مهام كانت حصرية سابقًا للمطورين البشريين.

تطوير OpenHands بواسطة All-Hands-AI، (المعروفة سابقًا باسم OpenDevin) ليست مجرد مساعد آخر لتدوين الكود. تم تصوره كمنصة متعددة الاستخدامات لوكلاء الذكاء الاصطناعي مصممة للتعامل مع مجموعة كاملة من مهام تطوير البرمجيات. تخيل ذكاءً اصطناعيًا يمكنه ليس فقط كتابة الكود ولكن أيضًا تعديل قواعد الكود الحالية، وتنفيذ أوامر الطرفية، وتصفح الويب للحصول على المعلومات (نعم، حتى البحث في Stack Overflow عن حلول)، والتفاعل مع APIs، وإدارة سير العمل المعقدة. هذه هي وعد OpenHands - "اكود أقل، اصنع أكثر".

ما يميز OpenHands حقًا هو التزامه بالبرمجيات مفتوحة المصدر. تم بناؤه بموجب ترخيص MIT المسموح، ويشجع على التعاون، والشفافية، والابتكار القائم على المجتمع. يتناقض ذلك بشدة مع النماذج مغلقة المصدر، مما يوفر للمطورين تحكمًا غير مسبوق، وتخصيصًا، ورؤية في الأعمال الداخلية لشريكهم في تطوير الذكاء الاصطناعي. للفرق والأفراد الحذرين من تعلق البائعين أو الذين يسعون لتكييف قدرات الذكاء الاصطناعي مع احتياجات محددة، تقدم OpenHands عرضًا مقنعًا.

ماذا تفعل OpenHands (المعروفة سابقًا باسم Open Devin)؟

فهم الوظائف الأساسية لـ OpenHands هو المفتاح لتقدير إمكانياتها كمنصة لتطوير الذكاء الاصطناعي. إنها تزود وكلاء الذكاء الاصطناعي بمجموعة شاملة من القدرات:

تعديل الكود الذكي

يمتلك وكلاء OpenHands القدرة على قراءة وفهم وتعديل الكود في سياق مشروع موجود. من خلال الاستفادة من نموذج اللغة الكبير (LLM) المختار، يقوم الوكيل بتحليل قاعدة الكود، وفهم الاعتماديات بين الملفات والدوال، وتنفيذ تعديلات مستهدفة استنادًا إلى مطالبات المستخدم. تتضمن هذه المهام مثل إعادة هيكلة الوظائف لتوضيحها، وإضافة نقاط نهاية جديدة لـ API، أو تحديث تبعيات المشروع كما هو مُوجه.

تنفيذ الأوامر بشكل آمن

أساس OpenHands هو قدرته على تنفيذ أوامر شل (مثل npm install، python manage.py runserver، git commit، ls، grep، وغيرها) ضمن بيئة صناديق رملية معزولة ومحافظة. هذه الصناديق الرملية، عادة ما يتم تنفيذها كحاوية Docker، تعزل أفعال الوكيل، مما يمنع أي تأثير غير مقصود على النظام الأساسي. وهذا يسمح للوكيل بعمل عمليات تطوير أساسية مثل إعداد بيئات المشروع، وتنفيذ مجموعات الاختبار، وتثبيت المكتبات الضرورية، وتشغيل سكربتات البناء، وإدارة التحكم في الإصدارات.

تصفح الويب المتكامل

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

التفاعل مع API

غالبًا ما تتضمن بنية البرمجيات الحديثة دمج العديد من الخدمات عبر APIs. يمكن توجيه وكلاء OpenHands للتفاعل مع هذه APIs الخارجية. قد يتضمن ذلك جلب البيانات من مصدر تابع، أو إرسال التحديثات إلى نظام آخر، أو تنظيم سير العمل الذي يمتد عبر أدوات مختلفة، مما يجعل العمليات التطويرية الأكثر تعقيدًا آلية.

إدارة نظام الملفات

تحتاج الوكلاء إلى القدرة على التفاعل مع ملفات المشروع. تمنحهم OpenHands الأذونات لإنشاء وقراءة وكتابة وحذف الملفات والمجلدات ضمن مساحة العمل المحددة لهم (عادة ما يتم تعيينها من النظام المحلي إلى صناديق رملية الوكيل). يتيح لهم ذلك هيكلة المشاريع بشكل منطقي، وإضافة وحدات أو مكونات جديدة، وإدارة ملفات التكوين، وتخزين نتائج المخرجات.

تمكن هذه القدرات المتنوعة، المنسقة بواسطة واجهة LLM الخلفية المختارة من قبل المستخدم، وكلاء OpenHands من التعامل بشكل مستقل مع مهام تطوير معقدة ومتعددة الخطوات، متجاوزة بكثير توليد الكود الأساسي نحو دعم حقيقي قائم على الذكاء الاصطناعي في هندسة البرمجيات.

كيفية تثبيت OpenHands على ماك، لينكس، ويندوز

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

متطلبات النظام

تأكد من أن نظامك يفي بالمطلبات التالية:

• نظام التشغيل:
• macOS (مع دعم Docker Desktop)
• لينكس (اختبار Ubuntu 22.04، من المحتمل أن تكون توزيعات حديثة أخرى متوافقة)
• ويندوز (مع WSL 2 ودعم Docker Desktop)
• الأجهزة: يُفضل أن يكون لديك نظام بمعالج حديث وذاكرة وصول عشوائي لا تقل عن 4 جيجابايت. ستستفيد المهام التي تتضمن عمليات معقدة أو التي تشغل LLMs محلية أكبر من زيادة ذاكرة الوصول العشوائي وموارد المعالجة/GPU.

خطوات تثبيت المتطلبات اللازمة

اتبع هذه الخطوات بعناية لإعداد المتطلبات الضرورية.

الخطوة 1: تثبيت Docker Desktop

قم بتنزيل وتثبيت Docker Desktop المصمم لنظام التشغيل الخاص بك مباشرة من الموقع الرسمي لـ Docker (https://www.docker.com/products/docker-desktop/). اتبع المعالج المقدم من Docker. بعد التثبيت، تحقق من أن خادم Docker نشط؛ يجب أن يكون رمزه مرئيًا في علبة النظام أو شريط القائمة الخاص بك.

الخطوة 2: تكوين Docker بناءً على نظام التشغيل

هناك تكوينات محددة مطلوبة اعتمادًا على نظام التشغيل الخاص بك.

تكوين macOS

1. قم بتشغيل Docker Desktop.
2. الوصول إلى الإعدادات (عادةً من خلال رمز التروس).
3. انتقل إلى قسم متقدم.
4. تحقق من أن الخيار السماح باستخدام مأخذ Docker الافتراضي مُفعل (مؤشر). هذه الإذن ضرورية لكي يتمكن حاوية OpenHands من إدارة حاويات Docker الأخرى مثل صناديق الرمل.

تكوين لينكس

1. قم بتثبيت Docker Desktop على لينكس من خلال اتباع الوثائق الرسمية لـ Docker.
2. تأكد أن خدمة Docker تعمل بعد التثبيت.
   (ملاحظة: في حين تم اختباره على Ubuntu 22.04، يُتوقع التوافق مع توزيعات لينكس الأخرى ولكن لا يُضمن ذلك.)

تكوين ويندوز

1. تثبيت WSL (نظام ويندوز الفرعي للينكس): إذا لم تكن WSL 2 مثبتة بالفعل، افتح PowerShell كمدير وانفذ wsl --install. يقوم هذا الأمر بتثبيت WSL وتوزيعة لينكس افتراضية (غالبًا Ubuntu). قد يتطلب الأمر إعادة تشغيل النظام.
2. تحقق من إصدار WSL: افتح نافذة PowerShell القياسية أو موجه الأوامر واكتب wsl --version. تحقق من أنه يظهر أن إصدار WSL هو 2 أو أعلى. إذا ظهر الإصدار 1، قم بتحديث WSL أو تعيين الإصدار 2 كإفتراضي باستخدام wsl --set-default-version 2.
3. تثبيت Docker Desktop لويندوز: تابع تثبيت Docker Desktop إذا لم تكن قد قمت بذلك بالفعل.
4. تكوين تكامل WSL في Docker Desktop: قم بتشغيل Docker Desktop، واذهب إلى الإعدادات. ضمن عام تأكد من أن استخدام محرك WSL 2 مُفعل (مؤشر). تحت الموارد > تكامل WSL تأكد من أن تفعيل التكامل مع توزيعة WSL الافتراضية الخاصة بي مُفعل (مؤشر). طبق التغييرات وأعد تشغيل Docker إذا تم طلب ذلك.
5. ملاحظة حاسمة: لمستخدمي ويندوز، يجب تنفيذ جميع أوامر docker المتعلقة بـ OpenHands من داخل بيئة محطة WSL (مثل محطة Ubuntu)، وليس مباشرةً من PowerShell أو موجه الأوامر.

بدء تطبيق OpenHands

مع استيفاء المتطلبات، يمكنك الآن بدء تطبيق OpenHands.

الخطوة 1: فتح محطة الأوامر لديك

• على macOS أو لينكس، افتح تطبيق محطة الأوامر الافتراضية لديك.
• على ويندوز، افتح محطة توزيعتك المثبتة من WSL (مثل Ubuntu).

الخطوة 2: سحب صورة وقت التشغيل (اختياري)

تستخدم OpenHands صورة Docker منفصلة لبيئة التنفيذ المعزولة الخاصة بها. يمكن أن تسارع هذه الصورة عند سحبها مسبقًا بدء التشغيل الأول. استخدم العلامة الموصى بها في الوثائق الرسمية:

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.34-nikolaik

(تحقق دائمًا من أحدث علامة موصى بها من مستودع OpenHands على GitHub أو الوثائق الرسمية، حيث قد تتغير العلامات.)

الخطوة 3: تشغيل حاوية OpenHands

نفذ الأمر الشامل التالي داخل محطة الأوامر الخاصة بك (استخدم محطة WSL على ويندوز):

docker run -it --rm --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.34-nikolaik \
    -e LOG_ALL_EVENTS=true \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands-state:/.openhands-state \
    -p 3000:3000 \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app \
    docker.all-hands.dev/all-hands-ai/openhands:0.34

الخطوة 4: الوصول إلى واجهة المستخدم الويب

بمجرد تنفيذ الأمر docker run، تابع سجل الإخراج في محطة الأوامر الخاصة بك. عندما تكتمل سلسلة بدء تشغيل التطبيق، افتح متصفح الويب المفضل لديك وانتقل إلى http://localhost:3000.

مع استكمال هذه الخطوات، تم تثبيت OpenHands بنجاح وتعمل محليًا. الخطوة التالية الفورية تتعلق بتكوين نموذج لغة كبير لتشغيل الوكيل.

البدء مع Open Hands

مع تشغيل OpenHands، المرحلة الحيوية التالية هي ربطها بـ LLM، والذي يعمل كعقل الوكيل. بعد إعداد LLM، يمكنك البدء في تعيين مهام التطوير. يوضح هذا القسم الإعداد الأولي ويقدم أمثلة تفاعلية توضيحية.

إعداد LLM الأولي

هذه خطوة إلزامية عند تشغيل واجهة المستخدم.

• أول تشغيل: عند الوصول إلى http://localhost:3000 للمرة الأولى، ستظهر نافذة إعدادات تلقائيًا.
• الحقول الإلزامية: يجب عليك اختيار موفر LLM (مثل OpenAI، Anthropic، Google، OpenRouter، خيارات محلية مثل Ollama)، اختيار نموذج LLM معين يقدمه ذلك الموفر، وإدخال مفتاح API الخاص بك المقابل.
• الوصول إلى الإعدادات لاحقًا: إذا تم إغلاق النافذة الأولية أو كنت بحاجة لتعديل الإعدادات لاحقًا، انقر على رمز التروس (⚙️) الموجود في واجهة المستخدم (غالبًا بالقرب من منطقة إدخال الدردشة أو في شريط جانبي).

(ستجد تعليمات مفصلة عن تكوين موفري LLM المحددين في القسم التالي.)

تفاعلك الأول: مهمة "مرحبًا بالعالم"

قم ببدء تفاعل مع مهمة أساسية لملاحظة عملية الوكيل.

الخطوة 1: قم بتحفيز الوكيل

ادخل التعليمة التالية في حقل إدخال الدردشة واضغط على Enter:

اكتب سكربت Bash hello.sh الذي يطبع "مرحبًا بالعالم!"

الخطوة 2: راقب مرحلة التخطيط

تحيل OpenHands الطلب إلى LLM المُعد، الذي ينشئ بعد ذلك خطة استراتيجية. عادةً، ست-outline الوكيل أفعاله المقصودة في واجهة المستخدم، مثل:

1. إنشاء ملف جديد باسم hello.sh.
2. إدراج الأمر Bash echo "مرحبًا بالعالم!" في هذا الملف.
3. توفير أذونات التنفيذ للسكربت باستخدام chmod +x hello.sh.
4. تنفيذ السكربت via ./hello.sh للتأكد من أن الإخراج يتوافق مع التوقعات.

الخطوة 3: راقب مرحلة التنفيذ

يتقدم الوكيل لتنفيذ الخطوات المخططة داخل بيئة التنفيذ المعزولة على Docker. سيعرض السجل في واجهة المستخدم الأوامر التي يتم تشغيلها ويعكس التعديلات في نظام الملفات كما تحدث.

الخطوة 4: التحقق من النتيجة

بمجرد الانتهاء بنجاح، يجب على الوكيل الإبلاغ عن نتيجة التنفيذ، بما في ذلك المخرجات المتوقعة: "مرحبًا بالعالم!".

الخطوة 5: التحسين التكراري

الآن، دعنا نعدل السكربت باستخدام تعليمات متابعة:

عدل hello.sh بحيث يقبل اسمًا كأول حجة، ولكنه يُرجع بشكل افتراضي إلى "العالم"

الخطوة 6: راقب عملية التعديل

1. قراءة المحتويات الحالية ل hello.sh.
2. تحديث كود السكربت ليتضمن التعامل مع الحجج، ربما باستخدام توسيع معلمات Bash مثل echo "مرحبا بـ ${1:-world}!".
3. اختياريًا، تشغيل اختبارات مع وبدون حجج (مثل ./hello.sh و ./hello.sh المطور) للتحقق من التغييرات.

الخطوة 7: مهمة تحويل اللغة

أظهر مرونة الوكيل عن طريق طلب تغيير اللغة:

يرجى تحويل hello.sh إلى سكربت Ruby، وتشغيله

الخطوة 8: راقب تكيف البيئة

إذا كانت بيئة الصندوق الرملية تفتقر إلى المفسر المطلوب لـ Ruby، قد يخطط الوكيل أولاً ويقوم بتنفيذ أوامر التثبيت (مثل apt-get update && apt-get install -y ruby). ثم، سيقوم بترجمة المنطق إلى كود Ruby (مثل puts "مرحبًا بـ #{ARGV[0] || 'العالم'}!")، وحفظه في hello.rb، وجعله قابلاً للتنفيذ، وتشغيل السكربت الجديد.

هذا المثال التقديمي يسلط الضوء على سير العمل الأساسي لدى الوكيل: فهم التعليمات، التخطيط لخطوات التنفيذ، التفاعل مع نظام الملفات والشل داخل صندوق الرمل، والتكيف استنادًا إلى المطالبات المتكررة.

البناء من الصفر: مثال تطبيق TODO

غالبًا ما يثبت الوكلاء أدائهم القوي في مشاريع "المشاريع الجديدة"، حيث يمكنهم تأسيس الهيكل دون الحاجة إلى سياق موسع من قاعدة كود معقدة موجودة مسبقًا.

الخطوة 1: تقديم فكرة المشروع الأولية

كن دقيقًا بشأن الميزات المطلوبة وstack التقنية:

قم بإنشاء تطبيق TODO يعمل على الواجهة الأمامية فقط في React. يجب تخزين كل الحالة في تخزين محلي. تنفيذ الوظائف الأساسية لإضافة مهام جديدة وعرض القائمة الحالية للمهام.

الخطوة 2: راقب التخطيط والبناء

قد يخطط الوكيل كما يلي:

1. استخدام create-react-app (إذا كانت متاحة / مُخصصة) أو تحديث هيكل أساسي يدويًا يتضمن HTML وCSS وملفات JavaScript / JSX.
2. تطوير مكونات React لنموذج إدخال المهمة وعرض قائمة المهام.
3. تنفيذ إدارة حالة التطبيق باستخدام هوكي React مثل useState و useEffect.
4. دمج localStorage.setItem() و localStorage.getItem() للحفاظ على البيانات بين الجلسات.
5. كتابة الهيكل HTML اللازم وتطبيق التنسيق الأساسي باستخدام CSS.

الخطوة 3: طلب تحسينات الميزات

بمجرد تشغيل تطبيق الأساس، اطلب ميزات إضافية:

السماح بإضافة تاريخ استحقاق اختياري لكل مهمة. عرض هذا التاريخ بجوار وصف المهمة في القائمة.

الخطوة 4: راقب التطوير التكراري

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

الخطوة 5: تنفيذ أفضل ممارسات التحكم في الإصدار

احفظ تقدم الوكيل بانتظام باستخدم نظام التحكم في الإصدارات، تمامًا كما تفعل في التطوير اليدوي. يمكنك أيضًا توجيه الوكيل للتعامل مع الالتزامات:

قم بالتزام التغييرات الحالية مع رسالة الالتزام "feat: أضف وظيفة تاريخ الاستحقاق إلى المهام" ودفع الالتزام إلى فرع جديد يسمى "feature/due-dates" على المستودع الأصلي.

(ملاحظة: يتطلب تنفيذ أوامر Git بنجاح، خاصة الدفع إلى البعيدات، أن يكون Git مثبتًا ويمكن تكوينه باستخدام بيانات اعتماد المصادقة ضمن بيئة العمل / صناديق الرمل الخاصة بالوكيل.)

إضافة كود جديد إلى مشاريع قائمة

تستطيع OpenHands دمج تعليمات جديدة وميزات في قواعد الكود القائمة.

المثال 1: إضافة إجراء GitHub

• طلب:

أضف إجراء GitHub إلى هذا المستودع يتحقق من كود JavaScript باستخدام ESLint متى ما تم دفع الكود إلى الفرع الرئيسي.

• سلوك الوكيل: قد يقوم الوكيل أولاً بفحص هيكل المشروع (مثل ls .github/workflows) لمعرفة ما إذا كانت هناك إجراءات موجودة. ثم سيحدد المحلل المناسب (أو يستخدم المحلل المحدد)، وينشئ ملف YAML جديد (مثل .github/workflows/lint.yml)، ويملأه بالتكوين الصحيح لإجراء GitHub يتم تشغيله عند دفع التعديلات إلى main، مع تشغيل ESLint.

المثال 2: إضافة مسار خلفي (السياق هو المفتاح)

• طلب:

عدل ملف التطبيق Express.js الموجود في './backend/api/routes.js'. أضف نقطة نهاية GET جديدة في '/api/tasks' تسترجع وتعيد جميع المهام من خلال استدعاء الدالة غير المتزامنة 'getAllTasks' الموجودة في './db/queries.js'.

• سلوك الوكيل: توفير مسار الملف المحدد (./backend/api/routes.js) والمعلومات السياقية ذات الصلة (مثل وجود وموقع getAllTasks في ./db/queries.js) يزيد بشكل كبير من كفاءة ودقة الوكيل. سيستهدف الوكيل الملف المحدد ويقوم بإدراج كود معالج المسار اللازم، بما في ذلك استيراد الدالة المطلوبة.

إعادة هيكلة الكود

استفد من OpenHands لجهود إعادة هيكلة الكود المستهدفة.

مثال 1: إعادة تسمية المتغيرات للتوضيح

• طلب: في الملف './utils/calculation.py'، أعد تسمية جميع المتغيرات ذات الحرف الواحد داخل دالة 'process_data' لتصبح أكثر وصفية عن غرضها.

مثال 2: تقسيم الدوال الكبيرة

• طلب: أعد هيكلة الدالة 'process_and_upload_data' في 'data_handler.java'. قسم منطقها إلى دالتين متميزتين: 'process_data' و 'upload_data'، مع الحفاظ على الوظائف العامة الأصلية.

مثال 3: تحسين هيكل الملف

• طلب: قم بتفكيك تعريفات المسارات الرئيسية في './api/routes.js' إلى ملفات منفصلة بناءً على المورد (على سبيل المثال، 'userRoutes.js'، 'productRoutes.js'). قم بتحديث الملف الرئيسي للخادم ('server.js') لاستيراد واستخدام هذه الملفات المسارية المودولية.

إصلاح الأخطاء

بينما يمكن أن يكون إصلاح الأخطاء معقدًا، يمكن لـ OpenHands المساعدة، خاصةً عندما يكون المشكلة محددة جيدًا.

مثال 1: تصحيح منطق معين

• طلب: إن التعبير النمطي المستخدم للتحقق من صحة البريد الإلكتروني في معالج نقطة النهاية '/subscribe' ضمن 'server/handlers.js' يرفض خطأً أسماء النطاقات الصالحة '.co.uk'. يرجى تصحيح نمط التعبير النمطي.

مثال 2: تعديل السلوك

• طلب: تقوم الدالة 'search_items' المطبقة في 'search.php' حاليًا بإجراء بحث حساس لحالة الأحرف. عدل هذه الدالة للتأكد من أن البحث غير حساس لحالة الأحرف.

مثال 3: اعتماد نهج مدفوع بالاختبار

1. طلب لإنشاء اختبار: تنهار الدالة 'calculate_discount' في 'pricing.js' عندما تكون كمية الإدخال صفرًا. اكتب حالة اختبار جديدة باستخدام Jest في ملف 'pricing.test.js' reproducing هذا الخطأ بالتحديد.
2. راقب تنفيذ الاختبار: يقوم الوكيل بإنشاء كود الاختبار، وتنفيذ مجموعة الاختبارات (مثلاً عبر npm test)، والإبلاغ عن الفشل المتوقع.
3. طلب لتصحيح الكود: الآن، قم بتعديل الدالة 'calculate_discount' في 'pricing.js' للتعامل بشكل صحيح مع حالة الكمية الصفرية، مما يضمن نجاح الاختبار المكتوب سابقًا.
4. راقب الإصلاح والتأكيد: يقوم الوكيل بتعديل منطق الدالة (ربما بإضافة تحقق شرطي للكمية الصفرية) وإعادة تشغيل مجموعة الاختبارات، مع الإبلاغ عن النتيجة الناجحة.

استراتيجية الاستخدام الأساسية: ابدأ بطلبات بسيطة ومحددة. قدم السياق الضروري مثل مسارات الملفات وأسماء الدوال. قسم الأهداف المعقدة إلى خطوات أصغر ومتكررة. قم بالتزام التغييرات بشكل متكرر باستخدام التحكم في الإصدار.

كيفية تكوين OpenHands مع LLMs (OpenAI، OpenRouter، Google Gemini، محلي)

تأسيس الاتصال بين OpenHands و LLM قادر هو أمر أساسي. تتم إدارة هذه التكوين من خلال واجهة مستخدم الويب الخاصة بـ OpenHands.

الوصول إلى إعدادات تكوين LLM

• أثناء الإعداد الأولي: تظهر نافذة إعداد تلقائيًا عند تحميل واجهة المستخدم لأول مرة على http://localhost:3000.
• للتغييرات اللاحقة: انقر على رمز التروس (⚙️) داخل واجهة المستخدم، عادة ما يكون موجودًا بالقرب من إدخال الدردشة أو في لوحة إعدادات.

إجراءات تكوين LLM العامة

1. اختر موفر LLM: اختر خدمتك المطلوبة (مثل "OpenAI"، "Anthropic"، "Google"، "OpenRouter"، "Ollama") من القائمة المنسدلة المتاحة.
2. إدخال مفتاح API: ألصق بعناية مفتاح API المرتبط بمزودك المختار في حقل الإدخال المخصص. يجب التعامل مع مفاتيح API بنفس أمان كلمات المرور.
3. حدد نموذج LLM: اختر النموذج المحدد الذي تنوي استخدامه من المزود المختار (مثل gpt-4o، claude-3-5-sonnet-20240620، gemini-1.5-pro-latest). قد تُملأ النماذج المتاحة ديناميكيًا بناءً على المزود المحدد، أو قد تحتاج إلى إدخال اسم النموذج يدويًا.
4. استكشاف الخيارات المتقدمة (اختياري): قم بتبديل الإعدادات المتقدمة لإظهار إمكانيات تكوين إضافية:

• نموذج مخصص: إذا لم يكن النموذج المفضل لديك مدرجًا، يمكنك غالبًا إدخال معرفه الدقيق هنا (راجع وثائق المزود للحصول على النموذج الصحيح).
• عنوان URL الأساسي: هذا الإعداد مهم عند الاتصال بـ LLMs المستضافة محليًا أو استخدام خدمات الوكيل. يحدد عنوان URL الخاص بنقطة API التي يجب أن تستهدفها OpenHands لطلبات.

5. حفظ التكوين: طبق واحفظ الإعدادات المختارة.

خطوات تكوين خاصة بالموفر

اتبع هذه الخطوات التفصيلية لموفري LLM الشائعين:

تكوين OpenAI

1. قم بزيارة https://platform.openai.com/.
2. قم بتسجيل الدخول أو إنشاء حساب جديد.
3. انتقل إلى قسم مفاتيح API وقم بإنشاء مفتاح سري جديد. انسخ هذا المفتاح على الفور لأنه قد لا يظهر مرة أخرى.
4. تأكد من إعداد معلومات الفواتير بشكل صحيح ضمن إعدادات الفواتير لتمكين استخدام API.
5. ضمن إعدادات واجهة المستخدم لـ OpenHands:

• قم بتعيين الموفر إلى OpenAI.
• ألصق مفتاح API الذي تم إنشاؤه في حقل مفتاح API.
• اختر أو اكتب النموذج المرغوب فيه من OpenAI (مثل gpt-4o، gpt-4-turbo).

تكوين Anthropic (Claude)

1. اذهب إلى https://console.anthropic.com/.
2. قم بتسجيل الدخول أو انشئ حسابًا.
3. الوصول إلى إعدادات الحساب > مفاتيح API وقم بإنشاء مفتاح API جديد. انسخ المفتاح الذي تم إنشاؤه.
4. قم بتكوين الفواتير تحت خطط وفواتير. فكّر في تعيين حدود الاستخدام لإدارة التكاليف بشكل فعّال.
5. في إعدادات واجهة المستخدم لـ OpenHands:

• قم بتعيين الموفر إلى Anthropic.
• ألصق مفتاح API المنسوخ.
• اختر أو أدخل النموذج المحدد من Claude (مثل claude-3-5-sonnet-20240620، claude-3-opus-20240229).

تكوين Google Gemini

1. احصل على مفتاح API من خلال أحد الخيارات:

• استوديو Google AI: (https://aistudio.google.com/app/apikey) - مناسب للتجارب الفردية.
• Google Cloud Vertex AI: (https://cloud.google.com/vertex-ai) - يُنصح به للتطبيقات المؤسسية أو المحوسبة السحابية.

2. إذا كنت تستخدم Google Cloud، تأكد من تمكين APIs اللازمة لـ Vertex AI وتم تكوين الفواتير لمشروعك.

3. في إعدادات واجهة المستخدم لـ OpenHands:

• قم بتعيين الموفر إلى Google.
• ألصق مفتاح API الذي حصلت عليه.
• اختر أو أدخل النموذج المطلوب من Gemini (مثل gemini-1.5-pro-latest، gemini-1.5-flash-latest).

تكوين OpenRouter

1. توجه إلى https://openrouter.ai/.
2. قم بتسجيل الدخول أو إنشاء حساب.
3. اذهب إلى قسم المفاتيح وأنشئ مفتاح API جديد. انسخه.
4. أضف أرصدة إلى حسابك عبر قسم الفواتير لتمكين الاستخدام.
5. في إعدادات واجهة المستخدم لـ OpenHands:

• قم بتعيين الموفر إلى OpenRouter.
• ألصق مفتاح API الخاص بـ OpenRouter الذي تم إنشاؤه.
• اختر أو اكتب معرف النموذج المحدد تمامًا كما هو مستخدم من قبل OpenRouter (مثل anthropic/claude-3.5-sonnet، google/gemini-pro-1.5، mistralai/mistral-7b-instruct). راجع وثائق نماذج OpenRouter للحصول على قائمة بالمعرفات المتاحة.

تكوين LLMs المحلية (مثل عبر Ollama)

1. تثبيت Ollama: اتبع دليل التثبيت على https://ollama.com/.
2. تنزيل النموذج: استخدم واجهة سطر الأوامر لـ Ollama لتنزيل نموذج مرغوب، على سبيل المثال، ollama pull llama3 (أو نماذج أخرى مثل codellama، mistral).
3. تشغيل خادم Ollama: تأكد من تشغيل خادم Ollama في الخلفية (عادة ما يبدأ تلقائيًا بعد التثبيت).
4. في إعدادات واجهة المستخدم لـ OpenHands:

• قم بتعيين الموفر إلى Ollama (أو ربما LiteLLM إذا كنت تستخدمها كوسيط).
• مفتاح API: عادة ما يكون غير مطلوب للإعدادات القياسية لـ Ollama؛ يمكنك تركه فارغًا أو إدخال NA أو ollama.
• تمكين الخيارات المتقدمة.
• تحديد عنوان URL الأساسي: هذا أمر أساسي. نظرًا لأن OpenHands تعمل داخل Docker، فإن localhost يشير إلى الحاوية نفسها، وليس إلى جهاز المضيف الذي يعمل عليه Ollama. استخدم اسم DNS الخاص http://host.docker.internal:11434. host.docker.internal تحل إلى عنوان IP لجهاز المضيف الخاص بك من داخل الحاوية، و 11434 هو المنفذ الافتراضي لخادم API الخاص بـ Ollama.
• تحديد النموذج: اختر أو اكتب اسم النموذج الذي قمت بتنزيله (مثل llama3، codellama) في حقل النموذج أو النموذج المخصص.

كيفية تكوين وقت تشغيل OpenHands على Docker

يشير مصطلح "وقت التشغيل" ضمن تصميم OpenHands إلى بيئة صناديق الرمل المعزولة حيث ينفذ الوكيل الأوامر ويتفاعل مع نظام الملفات. تشمل التكوينات بشكل رئيسي تحديد صورة وقت التشغيل التي يجب استخدامها عند بدء تشغيل الحاوية الرئيسية لـ OpenHands.

غرض بيئة وقت التشغيل

• العزلة والأمان: تعمل حاوية وقت التشغيل بشكل مستقل عن حاوية التطبيق الرئيسية لـ OpenHands. تخلق هذه العزلة صندوق رمل آمن، مما يمنع الأفعال التي يقوم بها الوكيل (مثل تثبيت البرمجيات أو تنفيذ الكود) من التأثير مباشرة على التطبيق الأساسي أو النظام المضيف.
• بيئة التنفيذ: تتضمن صورة وقت التشغيل عادةً أدوات أساسية ضرورية (مثل شل وأدوات سطر الأوامر الشائعة). اعتمادًا على الصورة المحددة المختارة، قد تأتي أيضًا مثبتة مسبقًا بأدوات تطوير مثل Python، Node.js، أو Git. علاوة على ذلك، غالبًا ما يحتوي الوكيل على القدرة على تثبيت أدوات إضافية ضرورية داخل هذه البيئة الرملية باستخدام مديري الحزم (apt، npm، pip، إلخ).

التكوين من خلال أمر docker run

الطريقة الأساسية لتكوين وقت التشغيل هي من خلال علامة -e (متغير البيئة) داخل أمر docker run المستخدم لبدء تطبيق OpenHands:

-e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.34-nikolaik

هذا المتغير البيئي يوجه تطبيق OpenHands بشأن العلامة المحددة لصورة Docker التي يجب استخدامها كلما احتاجت إلى توفير حاوية سندات جديدة لمعالجة تنفيذ مهمة الوكيل.

تعديل أو تحديث وقت التشغيل

• تبديل إصدارات وقت التشغيل: إذا أصبحت نسخة جديدة من صورة وقت التشغيل متاحة (مثل 0.35-newfeature), سيتوجب عليك أولاً إيقاف حاوية OpenHands الجاري تشغيلها (مثل docker stop openhands-app). بعد ذلك، أعد تشغيلها باستخدام أمر docker run، مع تحديث العلامة المحددة في العلامة -e SANDBOX_RUNTIME_CONTAINER_IMAGE:

docker run ... -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.35-newfeature ... docker.all-hands.dev/all-hands-ai/openhands:<corresponding_app_version>

(ملاحظة: يُنصح عمومًا بتحديث العلامة الرئيسية لتطبيق openhands بالتزامن لضمان التوافق بين التطبيق وبيئة وقت التشغيل.)

• استخدام الإصدارات التطويرية: للاختبار في أحدث الميزات، غير المستقرة، يمكنك استخدام علامة main لصورة وقت التشغيل:

-e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:main

• استغلال الترقيم الدلالي: الوثائق تشير إلى أن علامات الإصدارات قد تدعم تقاليد الترقيم الدلالي (مثل :0.9 التي قد تشير إلى آخر 0.9.x للإصدار التصحيح). قد يُقدم هذا وسيلة لتلقي تحديثات طفيفة تلق