AI Prompt Engineering · درس

مخططات الأدوات والدوال

مخططات لاستدعاء الدوال.

مخططات الأدوات والدوال درس مجاني في AI Prompt Engineering على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في AI Prompt Engineering، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة AI Prompt Engineering 4 دروس في المجموع.

الأدوات هي مخططات مضافًا إليها الغرض

يتيح استدعاء الدوال للنموذج أن يطلب من كودك تنفيذ إجراء. وتُعرَّف كل أداة باسم ووصف (متى تُستخدم) ومخطط JSON لمعلماتها.

لا يشغّل النموذج الكود أبدًا؛ بل يصدر طلب استدعاء مهيكلًا يوجّه وقت التشغيل لتنفيذه. والمخطط هو ما يجعل تحليل المعاملات ممكنًا.

مكوّنات تعريف الأداة

تعريف الأداة هو إعلان عن قدرة ملفوف بمخطط.

{
  'type': 'function',
  'function': {
    'name': 'get_weather',
    'description': 'Get current weather for a city. Use when the user asks about weather.',
    'parameters': {
      'type': 'object',
      'properties': {
        'city': {'type': 'string'},
        'units': {'type': 'string', 'enum': ['celsius', 'fahrenheit']}
      },
      'required': ['city', 'units'],
      'additionalProperties': False
    }
  }
}

الوصف يوجّه الاختيار

عند توفر أدوات كثيرة، يختار النموذج الأداة أساسًا بناءً على الوصف. اكتب الأوصاف في صورة قواعد قرار:

اذكر متى تُستخدم ومتى لا تُستخدم.
ميّزها عن الأدوات النظيرة.
اذكر الشروط المسبقة المطلوبة.

تؤدي الأوصاف الضعيفة إلى اختيار الأداة الخطأ أكثر مما تؤدي المخططات الضعيفة إلى أخطاء المعاملات.

حلقة الاستدعاء والتنفيذ والإرجاع

استدعاء الدوال عملية متعددة الأدوار. يُصدر النموذج استدعاءً، وتنفّذه، وتضيف النتيجة، ثم يواصل النموذج عمله.

resp = client.chat.completions.create(model='gpt-4o', messages=msgs, tools=tools)
call = resp.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)
result = dispatch(call.function.name, args)
msgs.append(resp.choices[0].message)
msgs.append({'role': 'tool', 'tool_call_id': call.id,
             'content': json.dumps(result)})
# call the model again to continue with the tool result

استدعاءات الأدوات المتوازية

يمكن للنماذج الحديثة طلب استدعاءات أدوات متعددة في دور واحد عندما تكون الإجراءات مستقلة. ينبغي لوقت التشغيل أن يمر على جميع tool_calls وينفذها (ويُفضّل بالتزامن)، ثم يعيد رسالة أداة واحدة لكل tool_call_id.

لا تفترض أبدًا وجود استدعاء واحد؛ نفّذ حلقة على الاستدعاءات دائمًا.

for call in resp.choices[0].message.tool_calls:
    args = json.loads(call.function.arguments)
    result = dispatch(call.function.name, args)
    msgs.append({'role': 'tool', 'tool_call_id': call.id,
                 'content': json.dumps(result)})

فرض استخدام الأدوات وتقييده

تحكم في الاختيار باستخدام tool_choice:

auto — يقرر النموذج.
required — يجب استدعاء أداة ما.
{name: ...} — فرض أداة محددة.
none — تعطيل الأدوات في هذا الدور.

يحوّل فرض أداة محددة استدعاء الدوال إلى استخراج مهيكل محض.

client.chat.completions.create(
    model='gpt-4o', messages=msgs, tools=tools,
    tool_choice={'type': 'function', 'function': {'name': 'get_weather'}}
)

التحقق من صحة المعاملات قبل التنفيذ

حتى مع المخططات الصارمة، تعامل مع معاملات الأدوات بوصفها إدخالًا غير موثوق. أعد التحقق من صحتها مقابل المخطط، وطبّق قواعد العمل قبل لمس أنظمة حقيقية (قواعد البيانات، والمدفوعات، وحذف الملفات).

def dispatch(name, args):
    schema = TOOLS[name]['function']['parameters']
    jsonschema.validate(args, schema)   # defense in depth
    if name == 'refund' and args['amount'] > MAX_AUTO_REFUND:
        return {'error': 'requires human approval'}
    return HANDLERS[name](**args)

أخطاء الأدوات جزء من البروتوكول

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

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

{'status': 'error',
 'code': 'CITY_NOT_FOUND',
 'message': 'No city named Xyz. Ask the user to clarify the city.'}

إبقاء مجموعة الأدوات محدودة

تؤدي عشرات الأدوات إلى خفض دقة الاختيار وزيادة تكلفة الرموز (إذ يوجد مخطط كل أداة في السياق في كل دور). طرق التخفيف:

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

تحصين المخطط للآثار الجانبية

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

{
  'name': 'delete_records',
  'parameters': {
    'type': 'object',
    'properties': {
      'table': {'type': 'string', 'enum': ['logs', 'temp_cache']},
      'confirm': {'type': 'boolean'},
      'max_rows': {'type': 'integer', 'minimum': 1, 'maximum': 1000}
    },
    'required': ['table', 'confirm', 'max_rows'],
    'additionalProperties': False
  }
}

اختبار تعريفات الأدوات

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

cases = [
  {'prompt': 'Whats it like in Paris?', 'expect_tool': 'get_weather'},
  {'prompt': 'Convert 10 USD to EUR', 'expect_tool': 'fx_convert'}
]
for c in cases:
    assert run(c['prompt']).tool_name == c['expect_tool']

اختبار سريع

يُصدر النموذج استدعاءين مستقلين للأدوات في دور واحد للمساعد. ما الذي يجب أن يفعله وقت التشغيل لديكم؟

خلاصة

مخططات الأدوات والدوال عمليًا:

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

التالي: حلقات الإصلاح والتحقق عند استمرار حدوث أخطاء في المخرجات.

الأسئلة الشائعة

هل درس «مخططات الأدوات والدوال» مجاني؟

نعم — نص درس «مخططات الأدوات والدوال» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة AI Prompt Engineering، انتقل إلى CoddyKit PRO. تتضمن دورة AI Prompt Engineering 4 دروس في المجموع.

ماذا ستتعلم في «مخططات الأدوات والدوال»؟

مخططات لاستدعاء الدوال. تتمرن على AI Prompt Engineering مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ AI Prompt Engineering؟

لا تُشترط خبرة سابقة. AI Prompt Engineering على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «مخططات الأدوات والدوال»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس AI Prompt Engineering هذا؟

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

جميع الدروس في هذه الدورة

← العودة إلى AI Prompt Engineering