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

مقدمة

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

أهداف التعلم

• فهم بنية الطلب: نموذج، رسائل بأدوار، حد أقصى للرموز.
• حماية مفتاح الـ API واستدعاء النموذج من الخادم فقط.
• فهم الرموز (Tokens) والتكلفة وحدود المعدل.
• طلب إخراج منظم والتحقق منه.

1. شكل الطلب

معظم واجهات الدردشة تأخذ قائمة رسائل لكل منها دور (user أو assistant) وتعليمات نظام اختيارية. مثال بواجهة Anthropic Messages:

// server-only: هذا الكود يعمل على الخادم، والمفتاح لا يصل إلى المتصفح
const res = await fetch('https://api.anthropic.com/v1/messages', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.ANTHROPIC_API_KEY!,
    'anthropic-version': '2023-06-01',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    model: process.env.AI_MODEL,          // من الإعدادات: الأسماء تتغير مع الإصدارات
    max_tokens: 500,
    system: 'أنت مساعد يشرح مفاهيم البرمجة بالعربية بإيجاز ودقة.',
    messages: [{ role: 'user', content: 'ما الفرق بين let وconst في JavaScript؟' }],
  }),
  signal: AbortSignal.timeout(30_000),
});
if (!res.ok) throw new Error(`AI request failed: ${res.status}`);
const data = await res.json();
const text = data.content.find((b: { type: string }) => b.type === 'text')?.text ?? '';

• اسم النموذج في إعداد، لا ثابت في الكود، لأن النماذج تتجدد.
• max_tokens يحد طول الرد والتكلفة.
• المهلة (timeout) ضرورية: الردود قد تستغرق ثواني.

2. المفتاح لا يغادر الخادم

أي مفتاح يُرسل إلى المتصفح أو يُضمَّن في تطبيق جوال يمكن استخراجه واستخدامه على حسابك. الصحيح: واجهتك الأمامية تستدعي خادمك، وخادمك — بعد التحقق من هوية المستخدم وحدوده — يستدعي المزود.

المتصفح → /api/explain (خادمك: مصادقة + حد استخدام) → مزود النموذج

3. الرموز والتكلفة والحدود

• النص يُقسم إلى رموز؛ والتسعير عادة لكل مليون رمز إدخال ورمز إخراج بشكل منفصل.
• السياق الطويل (محادثة كاملة، ملفات) يكلف في كل طلب.
• المزودون يفرضون حدوداً للطلبات والرموز في الدقيقة؛ ستتلقى أحياناً 429 أو 529 (تحميل زائد).

لذلك ضع حداً لكل مستخدم في خادمك، وسجّل الاستهلاك، وأعد المحاولة بتأخير متزايد للأخطاء المؤقتة فقط:

async function withRetry<T>(fn: () => Promise<T>, tries = 3): Promise<T> {
  for (let i = 0; ; i++) {
    try { return await fn(); }
    catch (e) {
      if (i >= tries - 1) throw e;
      await new Promise((r) => setTimeout(r, 500 * 2 ** i + Math.random() * 250));
    }
  }
}

4. إخراج منظم يمكن التحقق منه

حين تحتاج بيانات لا نصاً حراً (مثل تصنيف سؤال)، اطلب JSON بمخطط محدد وتحقق منه، ولا تثق بالشكل لمجرد أنك طلبته:

import { z } from 'zod';
const Classification = z.object({
  category: z.enum(['web', 'mobile', 'data', 'other']),
  confidence: z.number().min(0).max(1),
});
const parsed = Classification.safeParse(JSON.parse(text));
if (!parsed.success) {
  // تعامل مع الرد غير الصالح: أعد المحاولة أو استخدم قيمة افتراضية
}

كثير من المزودين يوفرون أيضاً وضع «استخدام الأدوات» أو «المخرجات المنظمة» الذي يقيد الرد بمخطط.

5. الخصوصية

لا ترسل بيانات شخصية أو أسراراً إلى نموذج خارجي دون ضرورة وإذن، واقرأ سياسة المزود في الاحتفاظ بالبيانات. وأخبر المستخدم أن الرد مولَّد آلياً.

تمرين عملي

1. اكتب نقطة API على خادمك (POST /api/explain) تستقبل سؤالاً، وتتحقق أن المستخدم مسجل، وتطبق حداً بعشرة طلبات في الساعة، ثم تستدعي النموذج.
2. أضف مهلة 30 ثانية وإعادة محاولة للأخطاء 429/5xx فقط.
3. اطلب تصنيف السؤال بصيغة JSON وتحقق منه بـ Zod، واعرض رسالة مناسبة إن فشل التحقق.

أخطاء شائعة

• وضع المفتاح في كود الواجهة الأمامية أو في مستودع Git.
• لا مهلة ولا حد استخدام، فتتفاجأ بفاتورة كبيرة.
• الوثوق بشكل الإخراج دون تحقق.
• إعادة المحاولة على أخطاء دائمة (400) فتهدر الطلبات.

الخلاصة

استدعِ النموذج من الخادم فقط، اجعل اسم النموذج إعداداً، ضع مهلة وحدوداً وإعادة محاولة ذكية، وتحقق من كل إخراج منظم قبل استخدامه.

مصادر مقترحة

• التوثيق الرسمي لمزود النماذج الذي تستخدمه (قسم Messages/Chat وRate limits).
• OWASP Top 10 for LLM Applications.
• توثيق Zod للتحقق من المخططات.