التعامل مع AI APIs· الدرس 3 من 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 دقيقة
الـ Structured Outputs — تطلّع JSON تقدر تعتمد عليه
في سطر واحد · بدل نص حر صعب تقراه بكودّك، بتطلب من الموديل يرجّعلك JSON بشكل ثابت (schema)، وتفضل تتحقّق منه بالـ schema قبل ما تعتمد عليه.
أي حتة بتربط الموديل بداتابيز أو UI محتاجة بيانات مضبوطة. من غير structure هتفضل تكتب regex وتصلّح كسور، وده أكبر مصدر bugs في تطبيقات الـ AI.
الفرق زي إجابة مقالية ضد استمارة بخانات: المقال جميل بس محتاج قراية وتفسير؛ الاستمارة كل معلومة في خانتها، تقدر تاخدها وتحطّها في مكانها فورًا. بس خلّي بالك — لسه لازم تراجع إن كل خانة اتملت صح.
الفرق زي الجمرك: بدل ما تسيب الناس تدخل بحاجاتها متلخبطة، بتخلّيهم يملّوا استمارة بخانات محدّدة، وأي استمارة ناقصة أو غلط بترجع من غير ما تعدّي.
بدل ما ترجع «العميل زعلان بخصوص التأخير»، تطلب {sentiment:'negative', topic:'delivery'} بـ schema صارم — دلوقتي تقدر تفلتر وتعدّ وترسم عليها من غير ما تخمّن، وأي رد بيكسر الـ schema بتردّه بدل ما تخزّنه.
بتعرّف schema (بـ JSON Schema أو Zod) وتبعتها مع الـ request في response_format أو ما يعادله، فالموديل يتقيّد بالشكل ده وهو بيولّد. بس القيد مش ضمانة كاملة: الموديل ممكن يرفض يجاوب، أو يرجّع قيم غلط منطقيًا جوّه شكل صح. عشان كده بتعمل validate بالـ schema بعد ما الرد يوصل، وأي رد يكسرها بترفضه — يا بتعيد المحاولة يا بتسجّله كـ failure، لكن عمرك ما تخزّنه.
import { z } from "zod";
const Ticket = z.object({
sentiment: z.enum(["positive", "neutral", "negative"]),
topic: z.string().min(1),
});
const data = await callModel({
messages,
response_format: { type: "json_schema", json_schema: ticketJsonSchema },
});
const parsed = Ticket.safeParse(JSON.parse(data.choices[0].message.content));
if (!parsed.success) {
// reject: retry or log — never store unvalidated output
}🧪 جرّب بنفسك: هات ٥ رسايل دعم فني حقيقية، واطلب من الموديل يطلّع {sentiment, topic} بـ schema صارمة فيها enum للـ sentiment. اعمل validate بـ Zod على كل رد، وعدّ كام رد اترفض — وجرّب من غير structured mode وشوف الفرق.
(١) تثق إن «شكل صح = معلومة صح»: رد عدّى الـ schema ممكن يكون قيمه غلط برضه — الـ schema بتضمن الشكل بس. (٢) تطلب JSON في الـ prompt بس وتعمل JSON.parse مباشرة — الموديل ساعات بيلفّ الرد في ```json fences فيقع الـ parse؛ استخدم structured mode حقيقي. (٣) تعمل schema سايبة كلها strings — الـ enums والقيود هي اللي بتشتغل نص الشغل.
أي حتة رد الموديل فيها بيتغذّى على كود: داتابيز، UI، فلترة، pipeline — لو في حد غيرك (كود) هيقرا الرد، لازم structure + validation.
الشات والكتابة الإبداعية — إجبار الموديل على JSON هناك بيوجع جودة النص وبيصرف tokens زيادة من غير سبب.