الطلب الأول من Google Colab: احفظ مفتاح API في Secrets

يمكنك تشغيل طلبك الأول في دفتر Colab دون تثبيت أي شيء على حاسوبك. احفظ المفتاح في Colab Secrets، واقرأه باستخدام userdata.get(...)، ووجّه حزمة openai إلى https://api.cheaptokens.dev/v1، واطبع choices[0].message.content وusage. لا يوجد المفتاح أبدًا داخل خلية، لذا فإن مشاركة الدفتر لا تعني مشاركة مفتاحك.

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

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

ما تحتاج إليه#

• حساب Google ودفتر جديد على colab.research.google.com.
• مفتاح CheapTokens API ورصيد مُعاد تعبئته. المفاتيح والرصيد في حسابك؛ وتوضح الوثائق الخطوات الدقيقة.
• خمس دقائق.

واجهة API متوافقة مع OpenAI Chat Completions، لذا تعمل حزمة openai القياسية في Python مع base_url مختلف. يسرد ملف README الخاص بـ openai-python (تم التحقق منه في 5 نوفمبر 2026) Python 3.10 أو أحدث وpip install openai.

ضع المفتاح في Colab Secrets#

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

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

شغّل الطلب الأول#

يقرأ Colab الأسرار باستخدام google.colab.userdata.get(name)، وهي دالة في وحدة colabtools من Google (تم التحقق من docstrings في 5 نوفمبر 2026). ثبّت SDK، واقرأ السر، وأرسل طلبًا واحدًا.

!pip install -q openai

from google.colab import userdata
from openai import OpenAI

client = OpenAI(
    api_key=userdata.get('CHEAPTOKENS_KEY'),
    base_url='https://api.cheaptokens.dev/v1',
)

resp = client.chat.completions.create(
    model='deepseek-ai/DeepSeek-V4-Flash-0731',
    messages=[{'role': 'user', 'content': 'Explain a token in one sentence.'}],
    max_tokens=200,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

يعرض print الأول إجابة النموذج. ويطبع الثاني رقمين: الرموز التي أرسلتها والرموز التي كتبها النموذج. هذه هي الفاتورة كاملة للطلب، ولهذا نطبعها في كل مرة.

كم يكلّف الطلب#

الرموز هي ما تدفع مقابله، لذا انظر إلى السطر الثاني من المخرجات. لنفترض أن سؤالًا قصيرًا مثل السؤال أعلاه يستهلك نحو 40 رمزًا إدخالًا وأن الإجابة 150 رمزًا إخراجًا. يكلّف هذا الطلب $0.000016 بالسعر الحالي، وألف طلب منه تكلّف $0.0156. استبدل 40 و150 بالرقمين اللذين طبعهما دفترك.

DeepSeek-V4-Flash هو الافتراضي هنا لسبب: سياق 380K، وحتى 32,768 رمز إخراج لكل إجابة، وسعر واحد في أي وقت من اليوم، دون ساعات ذروة. يغطي رصيد واحد كل النماذج، لذا يمكنك تبديل النموذج في هذه الخلية دون تغيير أي شيء آخر. جرّب zai-org/GLM-5.3-Flash (سياق 390K، وحتى 8,192 رمز إخراج) وشغّل الخلية مرة أخرى. راجع كل النماذج والأسعار للقائمة الكاملة.

عندما تفشل خلية#

تأتي الأخطاء من جهة الأسرار أولًا، قبل أن يغادر أي طلب Colab. يذكر مصدر colabtools (تم التحقق منه في 5 نوفمبر 2026) أن userdata.get قد يرفع ثلاثة أخطاء.

• SecretNotFoundError: لا يوجد سر بهذا الاسم. قارن النص في userdata.get('...') مع الاسم في لوحة Secrets، حرفًا بحرف. حالة الأحرف مهمة.
• NotebookAccessError: السر موجود، لكن هذا الدفتر لا يملك صلاحية الوصول إليه. فعّل مفتاح الوصول في لوحة Secrets وأعد تشغيل الخلية.
• TimeoutException: لم يستجب Colab لطلب السر. تقول رسالة الخطأ إنه لا يمكن جلب الأسرار إلا عندما يعمل الكود من واجهة Colab، لذا شغّل الخلية في دفتر Colab نفسه، لا في سكربت مُصدَّر.

إذا حُمّل السر وفشل الطلب رغم ذلك، فالمشكلة على جهة API. يعني 401 أن المفتاح خاطئ أو مفقود؛ ويشير 404 عادةً إلى عنوان base URL أو معرّف نموذج خاطئ. يشرح API 401 أو 404: المفتاح، وعنوان base URL، ومعرّف النموذج كليهما، ويوضح سرد النماذج باستخدام GET /v1/models كيفية نسخ المعرّف الدقيق.

المشاركة والتدوير#

شارك الدفتر فينتقل معه الكود الذي يستدعي userdata.get؛ المفتاح ليس في أي خلية أو مخرجات، لذا لا يوجد ما يمكن تسريبه. يحتاج من يفتح الدفتر إلى سره الخاص بالاسم نفسه، وإلا فسيحصل على SecretNotFoundError (راجع أعلاه).

إذا أنشأت مفتاحًا جديدًا، فحدّث القيمة في لوحة Secrets؛ يبقى الكود كما هو لأنه يذكر اسم السر فقط.

تبقى عادة واحدة مهمة: لا تطبع المفتاح أبدًا. خلية مثل print(userdata.get('CHEAPTOKENS_KEY')) تضعه في المخرجات، والمخرجات تُحفظ مع الدفتر.

الخطوة التالية: ضع الإجابة في حلقة أو محادثة أو أداة صغيرة. تغطي الوثائق بقية واجهة API.