الموارد · Output Contracts

عقود مخرجات موحدة

مواصفة عقد استجابة إنتاجي يحافظ على ثبات المخرجات عبر مزودي النص والصوت والصورة والفيديو.

عقد الاستجابة القياسي

{
  "success": true,
  "content": "Primary human-readable output",
  "provider": "openai",
  "usage": {
    "input_tokens": 120,
    "output_tokens": 64
  },
  "metadata": {
    "model": "gpt-x",
    "latency_ms": 540,
    "trace_id": "trc_123"
  },
  "images": [],
  "files": [],
  "videos": []
}

مبادئ التصميم

Envelope واحد لكل الوسائط والمزودين.
أسماء الحقول ثابتة عبر إصدارات التشغيل.
تفاصيل المزود توضع داخل metadata بدون تغيير شكل الاستجابة الأساسي.
في حالة عدم وجود مخرجات وسيط، تُعاد مصفوفات فارغة بدل تغيير الشكل.
حقل success إلزامي لمعالجة عميل حتمية.

مرجع الحقول

success: نتيجة العملية بشكل boolean.
content: المخرج النصي الأساسي القابل للقراءة.
provider: معرف المزود بصيغة موحدة.
usage: كائن محاسبة موحد.
metadata: معلومات تشخيص وسياق التنفيذ.
images/files/videos: مصفوفات مخرجات الوسائط.
error: كائن خطأ منظم عندما success=false.

أمثلة متعددة المزودين

استجابة موحدة بأسلوب OpenAI

{
  "success": true,
  "content": "Generated response",
  "provider": "openai",
  "usage": { "input_tokens": 90, "output_tokens": 52 },
  "metadata": { "latency_ms": 480 },
  "images": [],
  "files": [],
  "videos": []
}

استجابة موحدة بأسلوب Replicate

{
  "success": true,
  "content": "Image generation completed",
  "provider": "replicate",
  "usage": { "input_tokens": 0, "output_tokens": 0 },
  "metadata": { "duration_ms": 2300 },
  "images": [{ "url": "https://..." }],
  "files": [],
  "videos": []
}

قواعد توافق العميل

منطق العرض في الواجهة يجب أن يعتمد على شكل Envelope لا على تفاصيل المزود.
العميل يجب أن يتحمل مفاتيح metadata غير المعروفة لضمان التوافق المستقبلي.
المصفوفات الفارغة مخرجات صحيحة للوسائط غير المنطبقة.
التحليل يجب أن يعتمد على فحص الحقول الصريحة بدل التفرع حسب المزود.

عقد الأخطاء

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request payload",
    "details": {}
  },
  "provider": "system",
  "metadata": {
    "trace_id": "trc_123"
  }
}

عقد الخطأ يجب أن يحتوي code قابل للآلة و message مفهومة للبشر.
يجب تمرير trace identifiers لأغراض التشخيص.
استجابات success=false لا يجب أن تعيد استخدام حقول النجاح فقط.
حالة HTTP وكود الخطأ المنظم يجب أن يظلا متسقين.