ما علمنا إياه بناء "شيبّي" حول بناء الوكلاء

ما الذي علمنا إياه بناء "شيبّي" حول بناء الوكلاء الأذكياء

يُعد بناء وكلاء ذكاء اصطناعي موثوقين من أصعب المشكلات في مجال التعلم الآلي التطبيقي اليوم. على مدار العام الماضي، طوّر فريقنا "شيبّي" (Shippy)، وهو وكيل مفتوح المصدر مصمم لأتمتة سير عمل نشر البرمجيات — بدءًا من مراجعة الكود وصولاً إلى النشر. ما بدأ كنموذج أولي بسيط تحول إلى تجربة تعليمية عميقة في هندسة الوكلاء، ومعالجة الأخطاء، وتصميم الأنظمة. يشارك هذا المقال الدروس العملية التي تعلمناها، مع أمثلة كودية ملموسة وخطوات تهيئة يمكنك تطبيقها على مشاريع الوكلاء الخاصة بك.

المشكلة التي سعينا لحلها

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

كان الهدف طموحًا: بناء وكيل يمكنه استنساخ مستودع، وفهم نظام البناء الخاص به، وتشغيل الاختبارات، وإصلاح المشكلات الشائعة، وفتح طلب سحب مع الإصلاح — كل ذلك دون مطالبة بشرية تتجاوز الهدف الأولي.

المتطلبات

قبل أن نتعمق في التنفيذ، إليك المتطلبات الأساسية لبناء وكيل مثل "شيبّي":

• **بايثون 3.10+** – منطق الوكيل مكتوب بلغة بايثون، مستفيدًا من أنماط المعالجة غير المتزامنة لتنفيذ المهام بالتوازي.
• **Git** – يحتاج الوكيل إلى استنساخ المستودعات، والالتزام بها، ودفع التغييرات إليها.
• **مفتاح واجهة برمجة تطبيقات OpenAI** – استخدمنا GPT-4 للاستدلال وتوليد الكود، لكن أي واجهة برمجة تطبيقات لنموذج لغوي كبير (LLM) تفي بالغرض.
• **Docker** (اختياري) – لتشغيل الاختبارات في بيئات معزولة.
• **قائمة انتظار المهام** – استخدمنا Redis و Celery للتعامل مع المهام طويلة الأمد بشكل غير متزامن.
• **Node.js 18+** – مطلوب فقط إذا كان وكيلك بحاجة للتفاعل مع مشاريع JavaScript/TypeScript.

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

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

1. إنشاء بيئة افتراضية وتثبيت التبعيات

أولاً، قم بإعداد بيئة بايثون معزولة:

python3 -m venv shippy-env
source shippy-env/bin/activate

قم بتثبيت التبعيات الأساسية:

pip install openai gitpython pydantic httpx redis celery

توفر هذه الحزم واجهة النموذج اللغوي الكبير (`openai`)، وعمليات Git (`gitpython`)، والتحقق من صحة البيانات (`pydantic`)، وطلبات HTTP (`httpx`)، وإدارة المهام غير المتزامنة (`redis`, `celery`).

2. تهيئة متغيرات البيئة

أنشئ ملف `.env` في جذر مشروعك:

OPENAI_API_KEY=sk-your-key-here
GITHUB_TOKEN=ghp_your-token-here
REDIS_URL=redis://localhost:6379/0

قم بتحميل هذه المتغيرات في كود بايثون الخاص بك:

import os
from dotenv import load_dotenv

load_dotenv()

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")
REDIS_URL = os.getenv("REDIS_URL")

3. إعداد نواة الوكيل

أنشئ ملف `agent.py` مع الفئة الأساسية للوكيل:

from openai import OpenAI
from git import Repo
import json

class ShippyAgent:
    def __init__(self, api_key: str, github_token: str):
        self.client = OpenAI(api_key=api_key)
        self.github_token = github_token

    def clone_repo(self, repo_url: str, local_path: str) -> Repo:
        """استنساخ مستودع GitHub إلى مسار محلي."""
        repo = Repo.clone_from(
            repo_url,
            local_path,
            env={"GIT_ASKPASS": "echo", "GITHUB_TOKEN": self.github_token}
        )
        return repo

    def analyze_project(self, repo_path: str) -> dict:
        """تحليل هيكل المشروع لفهم نظام البناء."""
        import os
        files = os.listdir(repo_path)
        structure = {}
        if "package.json" in files:
            structure["type"] = "node"
        elif "pyproject.toml" in files:
            structure["type"] = "python"
        elif "Cargo.toml" in files:
            structure["type"] = "rust"
        else:
            structure["type"] = "unknown"
        return structure

    def generate_fix(self, error_log: str, project_type: str) -> str:
        """استخدام النموذج اللغوي الكبير لتوليد إصلاح لخطأ معين."""
        prompt = f"""
        أنت مهندس برمجيات أول. بالنظر إلى سجل الأخطاء هذا من مشروع {project_type}، اقترح إصلاحًا للكود.
        سجل الأخطاء:
        {error_log}
        قدم الإصلاح كفرق (diff) أو تغيير في الكود.
        """
        response = self.client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": prompt}],
            temperature=0.2
        )
        return response.choices[0].message.content

4. إضافة قائمة انتظار المهام للعمليات طويلة الأمد

أنشئ ملف `tasks.py` للمعالجة الخلفية:

from celery import Celery
from agent import ShippyAgent

app = Celery('shippy', broker='redis://localhost:6379/0')

@app.task
def fix_repo(repo_url: str, error_log: str):
    agent = ShippyAgent(
        api_key="your-openai-key",
        github_token="your-github-token"
    )
    local_path = "/tmp/repos/" + repo_url.split("/")[-1].replace(".git", "")
    repo = agent.clone_repo(repo_url, local_path)
    structure = agent.analyze_project(local_path)
    fix = agent.generate_fix(error_log, structure["type"])
    # تطبيق الإصلاح وإنشاء طلب سحب (مبسط)
    with open(f"{local_path}/fix.patch", "w") as f:
        f.write(fix)
    return {"status": "fix_generated", "patch_file": "fix.patch"}

قم بتشغيل عامل Celery:

celery -A tasks worker --loglevel=info

أمثلة على الاستخدام

الآن دعنا نرى "شيبّي" أثناء العمل مع سيناريوهات واقعية.

مثال 1: إصلاح اختبار بايثون فاشل

افترض أن لديك مشروع بايثون حيث تفشل الاختبارات بسبب استيراد مفقود. قم بتشغيل الوكيل:

from agent import ShippyAgent

agent = ShippyAgent(
    api_key="sk-your-key",
    github_token="ghp_your-token"
)

error = """
ModuleNotFoundError: No module named 'requests'
File: tests/test_api.py, line 3
"""

result = agent.generate_fix(error, "python")
print(result)
# الإخراج: أضف `import requests` في أعلى ملف test_api.py، أو أضف `requests` إلى ملف requirements.txt

مثال 2: أتمتة مراجعة الكود

يمكن للوكيل أيضًا مراجعة طلبات السحب. إليك أداة مراجعة طلبات سحب مصغرة:

def review_pr(repo_url: str, pr_number: int):
    # استنساخ فرع طلب السحب
    repo = agent.clone_repo(repo_url, "/tmp/pr-review")
    # الحصول على الفرق
    diff = repo.git.diff("main", "feature-branch")
    # مطالبة النموذج اللغوي الكبير بالمراجعة
    prompt = f"راجع هذا الفرق (diff) واذكر أي مشكلات:\n{diff}"
    response = agent.client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

مثال 3: التشغيل في Docker للعزل

لتشغيل الاختبارات بأمان دون التأثير على نظام المضيف، استخدم Docker:

docker run --rm -v $(pwd):/workspace python:3.11 bash -c "cd /workspace && pip install -r requirements.txt && pytest"

قم بدمج هذا في الوكيل:

import subprocess

def run_tests_in_docker(repo_path: str) -> str:
    result = subprocess.run(
        ["docker", "run", "--rm", "-v", f"{repo_path}:/workspace", "python:3.11",
         "bash", "-c", "cd /workspace && pip install -r requirements.txt && pytest"],
        capture_output=True, text=True
    )
    return result.stdout + result.stderr

الدروس الرئيسية المستفادة

1. يحتاج الوكلاء إلى استرداد قوي من الأخطاء

افترضت النسخة الأولى من "شيبّي" أن كل خطوة ستنجح. لم يحدث ذلك. تعلمنا تنفيذ منطق إعادة المحاولة مع التراجع الأسي. على سبيل المثال، إذا فشل استنساخ Git بسبب مشكلات في الشبكة، أعد المحاولة حتى ثلاث مرات:

import time
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
def clone_with_retry(repo_url, local_path):
    return Repo.clone_from(repo_url, local_path)

2. السياق هو كل شيء

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

3. الاختبار في بيئات شبيهة بالإنتاج

تشغيل الوكلاء على حاسوبك المحمول جيد للنماذج الأولية، لكن الإنتاج يتطلب العزل. حاويات Docker لكل مهمة منعت تلوث الحالة بين عمليات التشغيل. أضفنا أيضًا مهلات زمنية لمنع الوكلاء الجامحين:

from concurrent.futures import TimeoutError

with timeout(seconds=120):
    result = agent.run_task()

4. وجود الإنسان في الحلقة لا يزال ضروريًا

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

5. المراقبة وتسجيل الدخول أمران لا غنى عنهما

قمنا بتجهيز كل إجراء للوكيل بتسجيل منظم. سمح لنا هذا بتصحيح أخطاء الفشل وتحسين المطالبات بمرور الوقت. استخدم وحدة `logging` في بايثون مع منسق JSON:

import logging
import json

class JsonFormatter(logging.Formatter):
    def format(self, record):
        return json.dumps(record.__dict__)

logger = logging.getLogger("shippy")
handler = logging.StreamHandler()
handler.setFormatter(JsonFormatter())
logger.addHandler(handler)

الخاتمة

علمنا بناء "شيبّي" أن وكلاء الذكاء الاصطناعي ليسوا سحرًا — بل هي أنظمة مصممة بعناية تجمع بين استدلال النماذج اللغوية الكبيرة وممارسات الهندسة القوية. الدرس الأهم هو أن موثوقية الوكيل تأتي من البنية التحتية، وليس فقط من النموذج. منطق إعادة المحاولة، وجمع السياق، والعزل، والإشراف البشري حوّل نموذجًا أوليًا هشًا إلى أداة مفيدة.

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

*لمزيد من القراءة حول أنماط تصميم الوكلاء، راجع مدونة Hugging Face، وأخبار OpenAI، ومدونة Microsoft AI، وأخبار Anthropic.*