الاتصال الأول: جلب مفاتيح API (Gemini / OpenAI) وكتابة أول سكربت اتصال

الاتصال الأول مع نماذج الذكاء الاصطناعي: من المفتاح السري إلى أول استجابة

في أي نظام يعتمد على LLMs، تبدأ الرحلة من نقطة هندسية بسيطة ظاهرياً لكنها أساسية جداً: الحصول على API Key، تخزينه بشكل آمن، ثم اختبار أول طلب اتصال ناجح. هذه الخطوة ليست مجرد تجربة أولية، بل هي حجر الأساس لأي معمارية لاحقة مثل مدخل إلى هندسة الذكاء الاصطناعي التوليدي: كيف تعمل نماذج اللغة الكبيرة (LLMs) برمجياً؟، أو أنظمة الاسترجاع المعزز RAG، أو خطوط المعالجة التي تستخدم LangChain.

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

قبل البدء: تجهيز بيئة العمل بشكل صحيح

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

• أنشئ بيئة افتراضية مستقلة للمشروع.
• ثبّت مكتبات مزودي النماذج بشكل منفصل لتسهيل الصيانة.
• لا تضع المفاتيح السرية مباشرة داخل الملفات المصدرية.
• استخدم متغيرات البيئة Environment Variables منذ البداية.

جلب مفتاح Gemini API

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

خطوات عملية للحصول على المفتاح

• سجل الدخول إلى منصة Google AI المناسبة لإدارة المفاتيح.
• أنشئ مشروعاً أو اختر مشروعاً قائماً.
• فعّل واجهة الاستخدام الخاصة بالنموذج إن لزم الأمر.
• أنشئ API Key جديداً.
• انسخه فوراً وخزّنه في مكان آمن مثل مدير أسرار أو ملف .env.

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

جلب مفتاح OpenAI API

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

ملاحظات هندسية مهمة

• أنشئ مفتاحاً مختلفاً لكل مشروع متى أمكن.
• فعّل حدود إنفاق أو مراقبة استخدام إن كانت متاحة.
• دوّن تاريخ إنشاء المفتاح لتسهيل التدوير Rotation.
• احذف المفاتيح غير المستخدمة فوراً.

تخزين المفاتيح بطريقة صحيحة داخل المشروع

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

الأسلوب الأكثر شيوعاً هو استخدام متغيرات البيئة:

import os

gemini_api_key = os.getenv("GEMINI_API_KEY")
openai_api_key = os.getenv("OPENAI_API_KEY")

if not gemini_api_key:
    raise ValueError("GEMINI_API_KEY is missing")

if not openai_api_key:
    raise ValueError("OPENAI_API_KEY is missing")

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

أول سكربت اتصال مع OpenAI

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

import os
from openai import OpenAI

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful AI assistant."},
        {"role": "user", "content": "Explain what an API is in one short paragraph."}
    ],
    temperature=0.3
)

print(response.choices[0].message.content)

Prompt مقترح للاختبار الأول: اشرح مفهوم API بلغة عربية مبسطة في فقرة قصيرة جداً مع مثال عملي واحد.

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

أول سكربت اتصال مع Gemini

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

import os
from google import genai

client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

response = client.models.generate_content(
    model="gemini-1.5-flash",
    contents="Explain what an API key is in simple Arabic."
)

print(response.text)

عند تشغيل السكربت بنجاح، فأنت فعلياً أنجزت أول دورة تشغيل كاملة End-to-End: من جهازك إلى واجهة النموذج ثم العودة بالناتج. هذه النقطة هي الأساس الذي ستبني فوقه لاحقاً أنظمة أكثر تعقيداً مثل سلاسل LLMs أو ربط النماذج بمصادر معرفة خارجية.

كيف تفكر هندسياً في الرد الناتج؟

المهندس لا يكتفي برؤية نص يظهر في الطرفية، بل يسأل: ما الذي حدث داخلياً؟ تم إرسال Input إلى النموذج، ثم جرى تحويله داخلياً إلى تمثيلات رقمية، وبعدها ولّد النموذج المخرجات اعتماداً على السياق والتعليمات والمعلمات مثل temperature. لذلك يجب تقييم الرد من زوايا متعددة:

• هل تم الاتصال بنجاح من دون أخطاء مصادقة؟
• هل النموذج المختار مناسب للتجربة أم مكلف بلا داعٍ؟
• هل المخرجات متسقة مع التعليمات؟
• هل بنية السكربت قابلة للتوسعة لاحقاً مع LangChain أو مع Embeddings؟

أخطاء شائعة في أول اتصال وكيف تعالجها

1) خطأ المفتاح غير صحيح

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

2) خطأ المكتبة غير مثبتة

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

3) اختيار نموذج غير متاح

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

4) تجاوز الحصص أو قيود الفوترة

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

أفضل ممارسة للانتقال من سكربت تجريبي إلى مشروع حقيقي

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

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

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