ابنِ أول تطبيق بالـAPI — من مفتاح فارغ إلى خدمة صالحة للإنتاج
مساعد دعم فنّي كامل في نحو مئة سطر، مع بثّ حيّ ومعالجة أخطاء وتتبّع كلفة — والخطوات التي تفصل التجربة عن الإنتاج.
سنبني في هذه المقالة خدمة صغيرة حقيقية: نقطة تستقبل سؤال عميل وتعيد ردًّا مبثوثًا، مع معالجة أخطاء لائقة وتسجيل للكلفة. الشفرة بجافاسكربت (Node) بلا أي مكتبة خارجية، والمنطق نفسه ينتقل إلى أي لغة بلا تغيير يُذكر.
1. المفتاح أولًا
أنشئ مفتاحًا من لوحة حسابك، وضعه في متغيّر بيئة. لا تضعه في الشفرة، ولا في ملفٍّ يدخل المستودع.
export VORIX_API_KEY="vx_live_..."
export VORIX_BASE_URL="https://<host>/v1"تحقّق من الإعداد بنداءٍ واحد قبل أن تكتب سطرًا:
curl "$VORIX_BASE_URL/me" -H "Authorization: Bearer $VORIX_API_KEY"إن عاد لك رصيدك وحدّك فأنت جاهز. وإن عاد 401 فالمشكلة في الترويسة أو في المفتاح لا في شفرتك — وقد وفّرت على نفسك ساعة تصحيح.
2. أصغر نداء يعمل
const BASE = process.env.VORIX_BASE_URL
const KEY = process.env.VORIX_API_KEY
async function ask(question) {
const response = await fetch(`${BASE}/chat/completions`, {
method: "POST",
headers: {
Authorization: `Bearer ${KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "vorix-pro",
messages: [
{ role: "system", content: "You are a support assistant. Answer in at most four sentences." },
{ role: "user", content: question },
],
max_tokens: 400,
temperature: 0.3,
}),
})
if (!response.ok) {
const { error } = await response.json()
throw new Error(`${error.code}: ${error.message}`)
}
return response.json()
}لاحظ ثلاثة قرارات صغيرة كبيرة الأثر: temperature منخفضة لأن ردّ الدعم يجب أن يكون ثابتًا لا
مبدعًا، وmax_tokens مضبوطة على ما تعرضه واجهتك فعلًا، وتعليمات النظام تحدّد الطول صراحةً.