التعامل مع AI APIs· الدرس 1 من 7
- 1أول Call — تنادي الموديل من كودّك7 دقيقة
- 2الـ Streaming — الرد بيوصل كلمة كلمة7 دقيقة
- 3الـ Structured Outputs — تطلّع JSON تقدر تعتمد عليه8 دقيقة
- 4الأخطاء والـ Retries — لمّا الـ call يقع9 دقيقة
- 5الـ Rate Limits — سقف الطلبات في الدقيقة6 دقيقة
- 6المفاتيح والـ Secrets — تأمين مفتاح الـ API6 دقيقة
- 7الـ Timeouts والـ Idempotency — طلبات ما تتكرّرش بالغلط8 دقيقة
أول Call — تنادي الموديل من كودّك
في سطر واحد · بتبعت request فيه رسايلك والـ model اللي عايزه، والـ API بيرجّعلك رد الموديل جوّه JSON — نفس فكرة أي HTTP call.
ده الفرق بين إنك تلعب في الـ playground وإنك تبني منتج فعلي. كل حاجة جاية في الدومين ده مبنية على أول call ماشي صح.
زي ما تطلب أكل أونلاين: تبعت الطلب (رسايلك + الموديل)، تستنّى شوية، ييجي الرد. الـ API endpoint هو المطعم، والـ response هي الأوردر اللي رجعلك.
الموديل شيف موجود في مطبخ بعيد؛ إنت مش بتكلّمه صوت، بتبعتله ورقة طلب (request) وبتستنّى الطبق (response) يرجعلك.
تبعت POST فيه messages: [{role:'user', content:'رحّب بيّا'}] والموديل، فيرجّعلك JSON فيه رد assistant جوّه choices — تطلّع منه النص وتعرضه.
الـ call بيتكوّن من ٣ حاجات: endpoint بتبعتله POST، وheader فيه مفتاحك (Authorization)، وbody فيه اسم الموديل ومصفوفة الـ messages. السيرفر بيشغّل inference على كلامك ويرجّعلك JSON فيه رد الموديل + بلوك usage بيعدّلك الـ tokens اللي اتصرفت. إنت بتتأكد الأول إن الـ status ناجح، وبعدين تطلّع النص من جوّه الرد وتستخدمه.
const res = await fetch("https://api.example.com/v1/chat/completions", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.API_KEY}`, // never hardcode the key
},
body: JSON.stringify({
model: "model-name",
messages: [{ role: "user", content: "Say hello!" }],
}),
});
if (!res.ok) throw new Error(`API error ${res.status}: ${await res.text()}`);
const data = await res.json();
console.log(data.choices[0].message.content);🧪 جرّب بنفسك: اكتب سكريبت صغير يقرا المفتاح من env var، يبعت POST فيه رسالة واحدة، ويطبع رد الموديل + عدد الـ tokens من بلوك الـ usage. ولو الـ status مش 200، خلّيه يطبع رسالة الخطأ كاملة بدل ما يقع بصمت.
(١) تكتب المفتاح جوّه الكود وترفعه على GitHub — كارثة حقيقية بتحصل كل يوم. (٢) تعمل res.json() على طول من غير ما تبصّ على الـ status — فتقعد تصارع undefined بدل ما تقرا رسالة الخطأ الحقيقية. (٣) تفتكر إن الموديل «فاكر» المحادثة — كل call مستقلة تمامًا، ولازم تبعت الـ history كله في messages كل مرة.
أول ما تعدّي مرحلة التجريب وتيجي تبني feature حقيقية: سكريبت، endpoint في الـ backend، أو أي أتمتة محتاجة رد موديل جوّه كود.
لو لسه بتجرّب صياغة prompts، الـ playground أسرع وأرخص. وعمرك ما تعمل الـ call من كود المتصفح مباشرة — المفتاح هيتسرّب؛ خلّي الـ call تعدّي على backend بتاعك.