دليل المبتدئين: كيفية دمج واجهة برمجة تطبيقات ChatGPT مع مشاريع بايثون

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

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

المتطلبات الأساسية

لمتابعة هذا الدرس التعليمي، ستحتاج إلى ما يلي:

• معرفة لغة بايثون: يجب أن تكون على دراية بمفاهيم بايثون مثل الدوال، وتنفيذ نصوص بايثون، وبيئات بايثون الافتراضية.
• تثبيت بايثون: ستحتاج إلى تثبيت بايثون على نظامك. إذا لم تكن قد قمت بتثبيته بالفعل، فقم بتثبيت بايثون على جهازك.
• حساب OpenAI: يلزم وجود حساب OpenAI مزود بإمكانية الوصول إلى واجهة برمجة التطبيقات (API) ورصيد كافٍ لاستخدام واجهة برمجة تطبيقات ChatGPT. ستحصل على مفتاح واجهة برمجة التطبيقات الخاص بك من منصة OpenAI في الخطوة 1.

لا تقلق إذا كنت جديدًا في التعامل مع واجهات برمجة التطبيقات (APIs). سيرشدك هذا الدليل إلى كل ما تحتاج معرفته للبدء باستخدام واجهة برمجة تطبيقات ChatGPT وتطبيق ميزات الذكاء الاصطناعي في تطبيقاتك.

الخطوة 1: احصل على مفتاح API الخاص بك وقم بتثبيت حزمة OpenAI

قبل البدء في استخدام واجهة برمجة تطبيقات ChatGPT Python، ستحتاج إلى الحصول على مفتاح API وتثبيت مكتبة OpenAI Python. ابدأ بالحصول على مفتاح API من منصة OpenAI، ثم ثبّت الحزمة المطلوبة وتأكد من أن كل شيء يعمل بشكل صحيح.

احصل على مفتاح API الخاص بك

يمكنك الحصول على مفتاح API من منصة OpenAI باتباع الخطوات التالية:

• انتقل إلى platform.openai.com وقم بتسجيل الدخول إلى حسابك أو أنشئ حسابًا جديدًا إذا لم يكن لديك حساب بعد.
• انقر على أيقونة الإعدادات في الزاوية العلوية اليمنى وحدد مفاتيح API من القائمة الموجودة على اليسار.
• انقر على زر “إنشاء مفتاح سري جديد” لإنشاء مفتاح API جديد.
• في مربع الحوار الذي يظهر، أعط مفتاحك اسمًا وصفيًا مثل “مفتاح البرنامج التعليمي لـ Python” لمساعدتك في التعرف عليه لاحقًا.
• في حقل “المشروع”، حدد مشروعك المفضل.
• ضمن قسم الأذونات، حدد الكل لمنح مفتاحك حق الوصول الكامل إلى واجهة برمجة التطبيقات لأغراض التطوير.
• انقر على “إنشاء مفتاح سري” لإنشاء مفتاح API الخاص بك.
• انسخ المفتاح الذي تم إنشاؤه فوراً، حيث لن تتمكن من رؤيته مرة أخرى بعد إغلاق مربع الحوار.

الآن بعد حصولك على مفتاح API الخاص بك، عليك تخزينه بشكل آمن.

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

تقوم مكتبة OpenAI Python تلقائيًا بالبحث عن متغير بيئي باسم OPENAI_API_KEY عند إنشاء اتصال عميل. من خلال تعيين هذا المتغير في جلسة طرفية، ستتمكن من مصادقة طلبات واجهة برمجة التطبيقات (API) دون الكشف عن مفتاحك في التعليمات البرمجية.

قم بتعيين متغير البيئة OPENAI_API_KEY في جلسة الطرفية الخاصة بك:

PS> $env:OPENAI_API_KEY="your-api-key-here"

استبدل your-api-key-here بمفتاح API الفعلي الذي نسخته من منصة OpenAI.

تثبيت حزمة OpenAI

بعد إعداد مفتاح API الخاص بك، يمكنك الآن تثبيت مكتبة OpenAI الخاصة بلغة بايثون. تتوفر حزمة openai على فهرس حزم بايثون (PyPI)، ويمكنك تثبيتها باستخدام pip.

افتح نافذة طرفية أو موجه أوامر، أنشئ بيئة افتراضية جديدة، ثم قم بتثبيت المكتبة:

PS> python -m venv venv
PS> venv\Scripts\activate
(venv) PS> python -m pip install openai

سيقوم هذا الأمر بتثبيت أحدث إصدار من مكتبة OpenAI من PyPI على جهازك. تتضمن المكتبة كل ما تحتاجه للمصادقة مع واجهة برمجة تطبيقات OpenAI وإرسال الطلبات إلى ChatGPT.

تحقق من إعداداتك

بعد تثبيت مفتاح API ومكتبة OpenAI، يمكنك الآن التأكد من أن كل شيء يعمل بشكل صحيح. أنشئ ملف بايثون جديدًا باسم verify_setup.py وأضف الكود التالي:

from openai import OpenAI

client = OpenAI()
print("OpenAI client created successfully!")
print(f"Using API key: {client.api_key[:8]}...")

قم بتشغيل هذا الملف من خلال سطر الأوامر الخاص بك:

(venv) $ python verify_setup.py

إذا تم إعداد كل شيء بشكل صحيح، فسترى مخرجات تؤكد إنشاء العميل:

(venv) $ python verify_setup.py
OpenAI client created successfully!
Using API key: sk-proj-...

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

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

الخطوة الثانية: استدعاء واجهة برمجة تطبيقات ChatGPT Python لإنشاء استجابة نصية بالذكاء الاصطناعي

بعد تثبيت مكتبة OpenAI وتكوين مفتاح API الخاص بك، يمكنك البدء في إجراء استدعاءات API لنماذج OpenAI التي تدعم ChatGPT. أبسط عملية هي إرسال طلب نصي واستلام رد مُولّد.

إنشاء عميل OpenAI

ابدأ بإنشاء ملف بايثون جديد باسم basic_chatgpt_call.py وقم باستيراد الوحدة اللازمة:

from openai import OpenAI

client = OpenAI()

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

ملاحظة: إذا لم تقم بإعداد متغير البيئة وترغب في تمرير مفتاح API مباشرةً، فيمكنك فعل ذلك باستخدام client = OpenAI(api_key=”your-api-key-here”). مع ذلك، تُعد هذه الطريقة أقل أمانًا ولا يُنصح باستخدامها في بيئة الإنتاج.

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

إرسال رسالة نصية أساسية

يمكنك الآن إرسال أول رسالة إلى ChatGPT باستخدام التابع ()responses.create.:

from openai import OpenAI

client = OpenAI()

text_response = client.responses.create(
    model="gpt-5",
    input="Tell me a joke about Python programming"
)

print(f"Joke:\n{text_response.output_text}")

في هذا المثال، ستنشئ طلب استجابة يتضمن معلَمين رئيسيين. يحدد معلَم النموذج نموذج ChatGPT المراد استخدامه. هنا، ستستخدم نموذج gpt-5 من OpenAI. أما معلَم الإدخال فيحتوي على نص الطلب كسلسلة نصية.

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

(venv) $ python basic_chatgpt_call.py

سترى رد ChatGPT مطبوعًا على الطرفية:

(venv) $ python basic_chatgpt_call.py
Joke:
Why do Python programmers prefer dark mode?

Because light attracts bugs!

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

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

التحكم في السلوك باستخدام الرسائل القائمة على الأدوار

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

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

ولتوضيح ذلك، أنشئ ملفًا جديدًا باسم coding_assistant.py وأضف إليه الكود التالي:

from openai import OpenAI

user_input = input("How can I help you? ")

client = OpenAI()

code_response = client.responses.create(
    model="gpt-5",
    input=[
        {
            "role": "developer",
            "content": (
                "You are a Python coding assistant. "
                "Only accept Python-related questions."
            ),
        },
        {
            "role": "user",
            "content": f"{user_input}",
        },
    ],
)

print(f"\n{code_response.output_text}")

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

يُعدّ فهم هذه الأدوار أمرًا بالغ الأهمية لهندسة الاستجابة الفورية الفعّالة. توضح وثائق OpenAI كيف تُعطي النماذج مستويات مختلفة من الأولوية للرسائل ذات الأدوار المختلفة:

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

عند تشغيل ملف coding_assistant.py، سيطلب منك البرنامج إدخال بيانات. يمكنك تجربة طلبات مختلفة متعلقة بلغة بايثون لمعرفة كيف يؤثر دور المطور على الاستجابات. على سبيل المثال، جرّب السؤال عن كلمات بايثون الرئيسية:

(venv) $ python coding_assistant.py

How can I help you? How many keywords does Python have?

It depends on the Python version. The reliable way is to check your interpreter:

- Reserved keywords: in Python 3.10–3.13 there are 35.
- There are also "soft keywords" (not reserved) such as:
  - 3.10–3.11: match, case
  - 3.12+: match, case, type

Check on your system:
- Reserved: import keyword; len(keyword.kwlist)
- Soft: import keyword; getattr(keyword, "softkwlist", [])

يُعد دور المطور بمثابة ضمانة أيضًا. فإذا سألت عن مواضيع لا تتعلق بلغة بايثون، سيرفض المساعد ذلك بلطف.

(venv) $ python coding_assistant.py
How can I help you? How can I reverse a string in JavaScript?

I'm a Python coding assistant and can only help with Python-related questions.
However, if you'd like to know how to reverse a string in Python,
I'd be happy to help with that!

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

حدد نموذج إخراج Pydantic

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

(venv) PS> python -m pip install pydantic

بعد التأكد من توفر Pydantic، يمكنك تعريف نموذج Pydantic الذي يمثل البنية التي تتوقعها من استجابة ChatGPT. أنشئ ملفًا جديدًا باسم structured_output.py:

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()

class CodeOutput(BaseModel):
    function_name: str
    code: str
    explanation: str
    example_usage: str

في هذا الكود، تقوم بإنشاء فئة CodeOutput التي ترث من BaseModel الخاص بـ Pydantic وتحدد أربعة سمات نصية تمثل البنية التي تتوقعها في الاستجابة.

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

عند استخدام هذا النموذج مع واجهة برمجة التطبيقات (API)، يصبح كل سمة حقلاً يقوم ChatGPT بتعبئته:

لاستخدام هذا النموذج مع واجهة برمجة التطبيقات، عليك استدعاء الدالة ()responses.parse. بدلاً من الدالة ()responses.create.:

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()

class CodeOutput(BaseModel):
    function_name: str
    code: str
    explanation: str
    example_usage: str

code_response = client.responses.parse(
    model="gpt-5",
    input=[
        {
            "role": "developer",
            "content": ("You are a coding assistant. Generate clean,"
                        "well-documented Python code."
                       )
        },
        {
            "role": "user",
            "content": "Write a simple Python function to add two numbers."
        }
    ],
    text_format=CodeOutput,
)

code_result = code_response.output_parsed

print(f"Function Name: {code_result.function_name}")
print("\nCode:")
print(code_result.code)
print(f"\nExplanation: {code_result.explanation}")
print(f"\nExample Usage:\n{code_result.example_usage}")

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

إلى جانب استخدام ()responses.parse، يكمن الاختلاف الرئيسي الآخر هنا في مُعامل text_format، الذي يُخبر واجهة برمجة التطبيقات (API) بتنظيم استجابتها وفقًا لنموذج Pydantic الخاص بك. أنت تُمرر فئة CodeOutput مباشرةً، وتضمن واجهة برمجة التطبيقات (API) أن تتطابق الاستجابة مع هذا التنظيم.

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

بدلاً من الوصول إلى output_text.، يمكنك استخدام output_parsed. لاسترجاع كائن Pydantic يحتوي على جميع الحقول المُعرّفة. يحتوي هذا الكائن على سمات تُطابق كل حقل في النموذج، مما يُتيح الوصول إلى المعلومات الفردية.

عند تشغيل ملف structured_output.py، سترى مخرجات منظمة بحقول محددة بوضوح:

(venv) $ python structured_output.py
Function Name: add_numbers
Code:
from typing import Union

Number = Union[int, float]

def add_numbers(a: Number, b: Number) -> Number:
    """Add two numbers.

    Args:
        a: First number (int or float).
        b: Second number (int or float).

    Returns:
        The sum of a and b. If both inputs are ints, the result is an int;
        otherwise, it's a float.
    """
    return a + b

Explanation: A minimal, well-typed function that accepts integers or floats,
             and returns the sum.
             It relies on Python's built-in addition,
             and preserves integer type when both inputs are integers.
Example Usage: print(add_numbers(2, 3))       # 5
print(add_numbers(2.5, 1.75))  # 4.25
print(add_numbers(2, 3.5))     # 5.5

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

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

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

لقد تعلمت كيفية دمج واجهة برمجة تطبيقات ChatGPT في مشاريع بايثون الخاصة بك. يمكنك الآن تثبيت مكتبة openai، والمصادقة باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك، وإرسال المطالبات، والعمل مع كل من الردود النصية العادية والردود المنظمة.

إليك بعض الاتجاهات التي يمكنك استكشافها للبناء على ما تعلمته:

• اعتبارات أمنية: احرص دائمًا على تأمين مفاتيح واجهة برمجة التطبيقات (API). استخدم متغيرات البيئة أو خدمات إدارة المفاتيح الآمنة في تطبيقات الإنتاج. لا تُضِف مفاتيح واجهة برمجة التطبيقات إلى نظام التحكم في الإصدارات، وقم بتدويرها بانتظام إذا كان من المحتمل أن تكون قد انكشفت. ضع في اعتبارك تطبيق تحديد معدل الاستخدام في تطبيقاتك لتجنب تكاليف واجهة برمجة التطبيقات غير المتوقعة.
• معالجة الأخطاء: أضف معالجة مناسبة للأخطاء إلى استدعاءات واجهة برمجة التطبيقات (API). قد تُثير مكتبة OpenAI استثناءات لأسباب عديدة، منها مشاكل الشبكة، أو مفاتيح واجهة برمجة التطبيقات غير الصالحة، أو أخطاء تجاوز الحد المسموح به. غلّف استدعاءات واجهة برمجة التطبيقات بكتل try وexcept، وتعامل مع الاستثناءات الشائعة بسلاسة.
• إدارة التكاليف: راقب استخدامك لواجهة برمجة التطبيقات (API) من خلال لوحة تحكم OpenAI. تختلف أسعار النماذج المختلفة، وتتراكم التكاليف بناءً على عدد الرموز المميزة المُعالجة. ضع في اعتبارك المفاضلة بين إمكانيات النموذج وتكلفته عند اختيار النموذج الأنسب لتطبيقك. أثناء التطوير، يمكنك اختبار منطق التكامل الخاص بك باستخدام نقاط نهاية وهمية مجانية، مثل واجهة برمجة تطبيقات OpenAI الوهمية من Beeceptor، لتجنب التكاليف أثناء العمل على تطبيقك.
• سياق المحادثة: بالنسبة لتطبيقات روبوتات الدردشة، احتفظ بسجل المحادثات من خلال تضمين الرسائل السابقة في قائمة الإدخال. يسمح هذا للذكاء الاصطناعي بالحفاظ على سياق المحادثات المتعددة. ضع في اعتبارك أن المحادثات الطويلة تستهلك المزيد من الرموز وتزيد التكاليف.

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