دليل واجهة برمجة تطبيقات OpenAI للمساعدين الذكاء الاصطناعي

1. مقدمة في واجهة برمجة تطبيقات OpenAI للمساعدين

1.1 التعريف والغرض من واجهة برمجة تطبيقات المساعدين

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

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

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

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

1.3 المفاهيم الأساسية للمساعدين

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

المساعد

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

الخيط

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

الرسالة

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

تشغيل

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

2. عملية تطوير واجهة برمجة تطبيقات المساعدين

2.1 إنشاء مساعدك

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

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "أنت مدرس رياضيات شخصي. اكتب وقم بتشغيل الكود للرد على أسئلة الرياضيات.",
    "name": "مدرس الرياضيات",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4"
  }'

معاملات الواجهة البرمجية:

• instructions - تعليمات النظام التي تخبر المساعد بما يجب فعله.
• name - اسم المساعد.
• tools - يعرف أي أدوات يمكن استخدامها من قبل المساعد. يمكن لكل مساعد أن يحتوي على ما يصل إلى 128 أداة. أنواع الأدوات الحالية يمكن أن تكون مترجم الكود، الاسترجاع، أو الوظيفة.
• model - أي نموذج يجب أن يستخدمه المساعد؟

بعد إنشاء المساعد بنجاح، ستتلقى معرف المساعد.

2.2 إنشاء خيط جلسة

يمثل "الخيط" محادثة، ونوصي بإنشاء خيط جلسة لكل مستخدم عندما يبدأ المستخدم محادثة. يمكنك إنشاء خيط على النحو التالي:

curl https://api.openai.com/v1/threads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d ''

بعد إنشاء الخيط، ستتلقى معرف الخيط.

2.3 إضافة رسائل إلى الموضوع

يمكنك إضافة رسائل إلى موضوع معين، تحتوي على نص واختياريًا تسمح بتحميل ملفات من قبل المستخدم. على سبيل المثال:

curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "أحتاج لحل هذه المعادلة `3x + 11 = 14`. هل يمكنك مساعدتي؟"
    }'

معلمات الواجهة البرمجية:

• thread_id - يمثل معرف موضوع المحادثة، الذي يمكنك الحصول عليه عند إنشاء الموضوع.

جسم طلب واجهة برمجة التطبيقات هو رسالة مستخدم، تمثل عادة سؤال المستخدم، مماثلة لهيكل الرسالة لنموذج المحادثة.

2.4 تشغيل المساعد لتوليد استجابة

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

ملاحظة: حتى هذه النقطة، لم يرد المساعد على سؤال المستخدم. فقط عند استدعاء API لتشغيل (Run)، سيقوم المساعد الذكاء الاصطناعي بالرد على سؤال المستخدم.

curl https://api.openai.com/v1/threads/{thread_id}/runs \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "assistant_id",
    "instructions": "عنوان المستخدم كجين دو. المستخدم لديه حساب مميز."
  }'

معلمات الواجهة البرمجية:

• thread_id - يمثل معرف موضوع المحادثة، الذي يمكنك الحصول عليه عند إنشاء الموضوع.
• assistant_id - يمثل معرف المساعد، الذي يمكنك الحصول عليه عند إنشاء المساعد.
• instructions - تعليمات المساعد التي يمكن أن تتجاوز التعليمات المحددة عند إنشاء المساعد.

سيعيد طلب واجهة برمجة التطبيقات الناجح معرف تشغيل (Run).

2.5 التحقق من حالة تشغيل المساعد

بعد بدء مهمة (Run) في المساعد، فإن تنفيذ المهمة يكون غير متزامن. هذا يعني أنه يجب علينا التحقق بانتظام من حالة التشغيل لتحديد ما إذا تم الانتهاء منه أم لا. للتحقق من حالة التشغيل، يمكن إجراء طلب HTTP باستخدام CURL. أدناه هو شرح محدد لهذه العملية.

مثال على طلب CURL:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

تفسير معلمات واجهة البرمجة الرسجية:

• https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123: هذا هو عنوان URL للطلب API، حيث thread_abc123 هو المعرف الفريد للموضوع (Thread)، و run_abc123 هو المعرف الفريد لتشغيل (Run).

مثال على جسم الاستجابة:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "completed",
  "created_at": 1699073585,
  ...
}

تفسير معلمات الاستجابة لواجهة البرمجة الرسجية:

• id: المعرف الفريد للتشغيل (Run).
• object: يشير إلى نوع الكائن المُرجع، وهو thread.run هنا.
• status: حالة التشغيل، القيم الممكنة تشمل queued، in_progress، completed، requires_action، failed، وما إلى ذلك.
• created_at: الطابسة الزمنية لعند تم إنشاء التشغيل.

2.6 الحصول على نتائج استجابة المساعد

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

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

مثال على طلب CURL:

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

شرح معلمات واجهة برمجة التطبيقات (API):

• https://api.openai.com/v1/threads/thread_abc123/messages: عنوان URL للطلب إلى واجهة برمجة التطبيقات، حيث thread_abc123 هو المعرف الفريد للموضوع (Thread).
• نفس رؤوس الطلب المستخدمة لفحص حالة التشغيل سابقًا، بما في ذلك معلومات المصادقة ومعلومات إصدار واجهة برمجة التطبيقات.

مثال نتائج رد المساعد:

في هذا المثال، طلب المستخدم من المساعد حل سؤال رياضي، وأضاف المساعد رسالة استجابة إلى الموضوع بعد معالجته.

User: I need to solve the equation `3x + 11 = 14`. Can you help me?
Assistant: بالطبع، جين دو. لحل المعادلة `(3x + 11 = 14)`, تحتاجين إلى عزل `(x)` على أحد جانبي المعادلة. دعيني أحسب قيمة `(x)` لك.
Assistant: الحل للمعادلة `(3x + 11 = 14)` هو `(x = 1)`.

بعد الحصول على نتائج الاستجابة من المساعد، يمكن تقديمها للمستخدم لمساعدتهم في فهم واستخدام الخدمات التي يوفرها المساعد.

3. أدوات: الأدوات المدمجة المقدمة بواسطة OpenAI

3.1 أداة مترجم الشفرة

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

تمكين مترجم الشفرة

لتمكين مترجم الشفرة، يجب تمرير code_interpreter في معلمة tools عند إنشاء كائن المساعد:

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "أنت معلم رياضيات شخصي. عندما يُطلب منك سؤال رياضيات، اكتب وشغل الشفرة للإجابة عليه.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-turbo-preview"
  }'

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

استخدام مترجم الشفرة لمعالجة الملفات

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

يمكن الوصول إلى الملفات الممررة على مستوى المساعدين من جميع التشغيلات المرتبطة بهذا المساعد:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/mydata.csv"

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "أنت معلم رياضيات شخصي. عندما يُطلب منك سؤال رياضيات، اكتب شفرة وشغلها للإجابة عليه.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

قراءة الصور والملفات التي تم إنشاؤها بواسطة مترجم الكود

يمكن لمترجم الكود أيضًا إنتاج ملفات في واجهة برمجة التطبيقات (API)، مثل إنشاء رسوم بيانية للصور وملفات CSV وPDF. هناك نوعان من الملفات المنشأة: الصور وملفات البيانات (على سبيل المثال، ملف CSV يحتوي على البيانات التي تم إنشاؤها بواسطة المساعد).

عندما ينتج مترجم الكود صورة، يمكنك العثور على هذا الملف وتنزيله في حقل file_id لرد الرسالة الخاصة بالمساعد:

{
    "id": "msg_abc123",
    "object": "thread.message",
    "created_at": 1698964262,
    "thread_id": "thread_abc123",
    "role": "assistant",
    "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "file-abc123"
      }
    }
  ]
  // ...
}

3.2 أداة الاسترداد

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

تمكين الاسترداد

لتمكين الاسترداد في معلمات المساعد tools، يرجى تمرير retrieval:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "أنت مساعد لدعم العملاء. استخدم قاعدة المعرفة الخاصة بك للرد على استفسارات العملاء بفعالية.",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
  }'

رفع الملفات للاسترداد

بالمثل لمترجم الكود، يمكن رفع الملفات على مستوى المساعد أو على مستوى رسالة فردية.

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/knowledge.pdf"

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "أنت مساعد لدعم العملاء. استخدم قاعدة المعرفة الخاصة بك للرد على استفسارات العملاء بفعالية.",
    "name": "معلم الرياضيات",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
    "file_ids": ["file_123abc456"]
  }'

3.3 أداة استدعاء الوظيفة

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

تعريف الدوال

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

الكود التالي يوضح كيفية تحديد دالتين باستخدام أمر curl عند إنشاء مساعد:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "أنت بوت توقعات الطقس. استخدم الدوال المقدمة للرد على الأسئلة.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "getCurrentWeather",
        "description": "الحصول على حالة الطقس لموقع محدد",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "المدينة والولاية، مثلاً، سان فرانسيسكو، كاليفورنيا"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "getNickname",
        "description": "الحصول على اللقب لمدينة معينة",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "المدينة والولاية، مثلاً، سان فرانسيسكو، كاليفورنيا"}
          },
          "required": ["location"]
        }
      }
    }],
    "model": "gpt-4-turbo-preview"
  }'

قراءة الدوال المستدعاة بواسطة المساعد

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

فيما يلي مثال على استرداد كائن التشغيل، يوضح كيفية الحصول على معلومات استدعاء الدوال:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "getCurrentWeather",
            "arguments": "{\"location\":\"سان فرانسيسكو\"}"
          }
        },
        {
          "id": "call_abc456",
          "type": "function",
          "function": {
            "name": "getNickname",
            "arguments": "{\"location\":\"لوس أنجلوس\"}"
          }
        }
      ]
    }
  },
  ...
}

المعلمة tool_calls تحتوي على معلومات استدعاء الدوال، ويكفي أن تقوم بالاتصال بالدالة المقابلة في برنامجك المحلي.

تقديم نتائج الدوال

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

فيما يلي مثال على كيفية تقديم نتائج الدوال:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_123/submit_tool_outputs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_abc123",
        "output": "{\"temperature\": \"22\", \"unit\": \"celsius\"}"
      }, 
      {
        "tool_call_id": "call_abc456",
        "output": "{\"nickname\": \"لوس أنجلوس\"}"
      }
    ]
  }'

تفسير الباراميترات:

• thread_abc123 يمثل معرف محادثة الخيط
• run_123 يمثل معرف كائن التشغيل
• tool_call_id يمثل معرف استدعاء دالة محدد، والذي يتم الحصول عليه من المعلمة tool_calls السابقة.

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