بني واجهات API لاتخاذ القرارات بالاستدلال مع Jeeves

شنو هو Jeeves؟

Jeeves هو مصنّف بنمط Jev كينتج سلسلة ديال الاستدلال قبل ما يدير قرار منظّم. مبني على Qwen3.5-9B مع محوّلات LoRA، ورأس مؤشّر، واحتمالات معايرة، وصانع مسودات diffusion من نوع block-4. المستودع فيه كود النموذج وصانع المسودات، وخط أنابيب التدريب، وأدوات التقييم، وبيانات التدريب والتطوير والاختبار.

المشروع مصمّم للتطبيقات اللي كتحتاج أكثر من توليد نص حر. انطلاقاً من حالة مشتركة وسؤال واحد ولا كثر، Jeeves كيرجع أجوبة منظّمة واحتمالات عبر API متوافق مع Jev. يمكن معالجة أسئلة متعددة فـ نفس الطلب.

المزايا الرئيسية

• ثلاثة أنواع ديال القرارات: أسئلة ثنائية noul، واختيارية choice، وترتيبية score.
• الاستدلال قبل القرارات: النموذج يقدر يولّد سلسلة ديال الاستدلال ومن بعد يستعمل رأس المؤشّر ديالو باش ينقّط الخيارات المتاحة.
• مخرجات معايرة: احتمالات الخيارات النهائية كتستعمل درجة حرارة مضبوطة على مجموعة التطوير.
• API متوافق مع Jev: عملاء Jev الحاليين يقدرو يرسلو صيغة الطلب الأساسية، بينما الخيارات الخاصة بـ Jeeves كتتحكم فالاستدلال.
• SDK ديال Python: الحزمة المضمّنة sdk/ كتخدم كبديل مباشر لـ typesafe-sdk ديال Jev.
• صياغة بالـ diffusion: صانع مسودات block-4 كيسرّع توليد سلاسل الاستدلال وكيَدعم طبقات Gated DeltaNet ديال Qwen3.5.
• كود التدريب: المستودع فيه مكوّنات SFT وCISPO والمعايرة والتقييم والتصدير وتدريب صانع المسودات.

مع استدلال جشع محدود فـ 2,560 توكن، README كيتحدث على دقة قدرها 0.889 فمجموعة الاختبار المحجوزة وخارج النطاق، و0.935 عبر 231 عنصر علني من JevBench. ولكن نتائجه فالمعرفة أقل من Jev فـ MMLU وMMLU-Pro، لذلك ملاءمته للمعايير كتختلف حسب المهمة.

المتطلبات المسبقة

خاصك Python 3.12 وGPU ديال CUDA. نواة FP8 فتنفيذ الاستدلال كتحتاج GPU من نوع Hopper. نفّذ الأوامر التالية من جذر المستودع.

ثبّت الاعتماديات

pip install -r requirements.txt

نزّل الأوزان المُصدرة

استعمل Hugging Face CLI باش تنزّل نقطة التحقق المنشورة ديال 9B وصانع المسودات block-4 ديالو:

hf download PostHog/jeeves --local-dir jeeves-weights

النموذج المُصدَر متاح من Hugging Face.

شغّل خادم API

python -m inference.serve --model jeeves-weights --drafter jeeves-weights/drafter_k4.safetensors --port 8009

هاد الشي كيشغّل الخدمة المتوافقة مع Jev فالمنفذ 8009. عميل Python المضمّن كيستعمل http://127.0.0.1:8009 افتراضياً، ما كيحتاج حتى مفتاح API، وكيتسنى حتى لـ 120 ثانية باش يوصله الرد.

صيفط أول طلب ديال قرار

نقطة النهاية /v1/systemone كتقبل state، وخريطة ديال questions، وضوابط اختيارية للاستدلال. الطلب التالي كيسول Jeeves يوجّه مشكل ديال زبون، ويقرر واش خاصو التصعيد، ويقيّم درجة إحباط الزبون.

curl -s localhost:8009/v1/systemone \
  -H 'content-type: application/json' \
  -d '{
    "state": "الحداء وصل متأخر بجوج سيمانات وبالمقاس الغلط. وزيد عليها، بان ليا جوج اقتطاعات فالبطاقة ديالي.",
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "شنو هو الفريق اللي خاصو يتكلف بهاد المشكل؟",
        "criteria": {
          "returns": "التبديل، الاسترجاع، السلع الغلط ولا المتضررة",
          "shipping": "حالة التوصيل، التأخير، الطرود الضايعة",
          "billing": "الاقتطاعات، الفواتير، مشاكل الأداء"
        }
      },
      "escalate": {
        "type": "noul",
        "instructions": "واش هاد المشكل كيحتاج تدخل مستعجل من شي موظف؟"
      },
      "frustration": {
        "type": "score",
        "instructions": "شحال الزبون محبط؟",
        "criteria": ["هادي", "محبط", "غاضب بزاف"]
      }
    },
    "options": {"max_think": 512}
  }'

فهم أنواع الأسئلة

• choice: كيختار من بين بدائل مسمّاة وكيرجع المفتاح المختار والاحتمالات ودرجة الثقة.
• noul: كيمثّل قراراً من نوع نعم/لا وكيرجع قيمة رقمية ديال noul.
• score: كيقيّم لائحة مرتّبة ديال التسميات وكيرجع نقطة رقمية ووسيلة إيضاح والاحتمالات ودرجة الثقة.

الرد فيه حتى معلومات الاستعمال، بما فيها عدد توكنات الإدخال والإخراج والاستدلال، وزيد عليها المدة الإجمالية. الأسئلة اللي فـ نفس الطلب تقدر تدير الاستدلال بالتوازي.

استعمل Jeeves من Python

ثبّت SDK المضمّن

pip install ./sdk

صايب أسئلة مكتوبة الأنواع

from jeeves_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    result = client.system_one(
        state="I was charged twice. Please help.",
        questions={
            "billing": Noul(
                instructions="Is this about billing?"
            ),
            "tone": Choice(
                instructions="What is the tone?",
                criteria={"calm": None, "angry": None},
            ),
            "urgency": Score(
                instructions="How urgent is this?",
                criteria=["can wait", "this week", "today"],
            ),
        },
        max_think=768,
        return_reasoning=True,
    )

    print(result.nouls["billing"].noul)
    print(result.choices["tone"].choice)
    print(result.scores["urgency"].score)
    print(result.reasoning["tone"].text)

TypeSafeClient كيجمع القيم الراجعة حسب نوع السؤال. ومنين كتعيّن return_reasoning=True، كيتوفّر حتى النص ديال الاستدلال الخاص بكل سؤال. كينبّه README بلي ما تستعمل حتى مكافأة ديال الاتساق اللغوي فالتدريب، وهادشي علاش سلاسل الاستدلال ماشي بالضرورة ساهلة فالفهم.

الربط بسيرفر مختلف

العميل كيتوجّه افتراضياً لـ http://127.0.0.1:8009. عيّن متغيّر البيئة JEEVES_BASE_URL إلا كان السيرفر خدام فـ عنوان آخر.

export JEEVES_BASE_URL=http://your-server:8009

التحكم فالاستدلال والكمون

الكائن الاختياري options كيوفّر أربعة ديال إعدادات الاستدلال. والأعلام المطابقة فالسيرفر تقدر تحدد الإعدادات الافتراضية على مستوى السيرفر كامل.

• think: القيمة الافتراضية هي true. عيّنها لـ false باش يجاوب مباشرة انطلاقاً من الـ prompt بلا ما ينتج سلسلة استدلال.
• max_think: القيمة الافتراضية هي 2560. كيقص كل سلسلة استدلال عند عدد الـ tokens المحدد قبل ما يجاوب النموذج.
• nothink_threshold: القيمة الافتراضية هي null. منين كتكون مضبوطة، Jeeves كيتجاوز الاستدلال إلا وصلات الثقة ديالو فعدم الحاجة للاستدلال أو فاتت العتبة.
• return_reasoning: القيمة الافتراضية هي false. فعّلها باش يضمّن نص الاستدلال فالجواب.

اختيار إعداد الكمون

فالتقييم التطويري ديال README اللي فيه 325 سؤال، حقق الاستدلال الكامل دقة قدرها 0.825 بمتوسط 1,138 token ديال الاستدلال وكمون وسيط قدره 3.3 ثواني. واستعمال max_think بقيمة 768 مع nothink_threshold بقيمة 0.9 عطى دقة 0.806، ومتوسط 344 token ديال الاستدلال، وكمون وسيط قدره 2.0 ثواني. وتعطيل الاستدلال عطى دقة 0.775 فحوالي 0.3 ثواني.

إعداد عملي ومتوازن هو:

{
  "options": {
    "max_think": 768,
    "nothink_threshold": 0.9,
    "return_reasoning": false
  }
}

الاستدلال الكامل عندو ذيل طويل ديال الكمون: قيمة p90 المبلّغ عليها هي 17.1 ثانية. استعمل سلاسل أقصر أو استدلال مبني على الثقة ملي كيكون وقت الاستجابة مهم.

كيفاش كيتخذ Jeeves القرارات

Jeeves كينسّق الحالة وتعليمات السؤال واختيارات الجواب باستعمال tokens نادرة من tokenizer ديال Qwen. من بعد كينتج سلسلة استدلال كتبدأ بعلامة think. ومن بعد الاستدلال، كيتعاود السؤال والاختيارات قبل علامة القرار.

رأس المؤشر كيحسب حاصل الضرب النقطي المُقاس بين إسقاط query فـ علامة القرار وإسقاطات key عند حدود كل اختيار. ومن بعد softmax كيحوّل هاد النقط لاحتمالات، ودرجة حرارة متلائمة مع مجموعة التطوير كتعايرها. وحسب تجارب الإزالة فـ README، تعويض tokens الخاصة بالـ prompt بتسميات عادية أو حذف السؤال المكرر من بعد الاستدلال نقص من الأداء.

مُنشئ Diffusion

المنشئ الاختياري كيسرّع توليد الاستدلال باستعمال فك الترميز التخميني. وهو كيكيّف منهج Orthrus ديال diffusion مع طبقات Gated DeltaNet ديال Qwen3.5، بالسماح لـ mask tokens أنها تدير cross-attention مع keys وvalues اللي من بعد convolution.

معدل النقل المبلّغ عليه لسؤال واحد كيرتفع من 109 chain tokens فالثانية مع فك ترميز greedy عادي مبني على graph لـ 176 token فالثانية مع block 4. أما block 8 كيوصل لـ 193 token فالثانية، ولكن block 4 باقي هو الافتراضي حيث كيبقى قليل التكلفة ملي كتتجمع عدة أسئلة فدفعة وحدة. وثمانية أسئلة مجمّعة مع block 4 كتوصل لحوالي 960 chain token فالثانية فالمجموع.

تشغيل checkpoint درّبتيه

Jeeves كيستعمل LoRA فالتدريب. قبل ما تشغّل checkpoint مدرّب، دمجو فـ model مستقل ووفّر ملف drafter المطابق:

python export.py runs/cispo/final --out runs/fused
python -m inference.serve \
  --model runs/fused \
  --drafter runs/drafter_k4/drafter.safetensors \
  --port 8009

إعادة إنتاج مسار التدريب

تحضير مجموعات البيانات

سكريبتات التحضير كتنزّل مجموعات بيانات عامة من Hugging Face فالإصدارات المحددة فـ prep/public.py. وكل مجموعة بيانات مصدر كتبقى خاضعة للرخصة ديالها.

python -m prep.prep

تشغيل التدريب والتقييم

مسار إعادة الإنتاج الموثّق كيستعمل ثمانية ديال الـ GPUs. كيدير الضبط الدقيق الخاضع للإشراف، وتدريب CISPO، وتقييم test وJevBench، وتصدير النموذج، وتوليد السلاسل، وتدريب drafter ديال block-4.

torchrun --nproc_per_node 8 train.py sft --run-dir runs/sft

torchrun --nproc_per_node 8 train.py cispo \
  --run-dir runs/cispo \
  --init runs/sft/final

torchrun --nproc_per_node 8 test.py runs/cispo/final
torchrun --nproc_per_node 8 jevbench.py runs/cispo/final
python export.py runs/cispo/final --out runs/fused

torchrun --nproc_per_node 8 -m drafter.gen --model runs/fused

torchrun --nproc_per_node 8 train.py drafter \
  --model runs/fused \
  --block 4 \
  --run-dir runs/drafter_k4

الوصفة المنشورة كاتبدا بجوج ديال دورات SFT على 19,126 سؤال من 12 مجموعة بيانات عمومية وبيانات اصطناعية ديال السياسات. من بعد كيتطبّق CISPO بثمانية rollouts لكل سؤال، وبدرجة حرارة 1، وبحدّ ديال 2,560 token للتفكير. التدريب توقف فالخطوة 402 من بين 624 خطوة مبرمجة، حيث الخطوات اللاحقة زادت حدّة pointer head على pool ديال التعلم بالتعزيز اللي وصل للتشبّع. وفالأخير، تدار معايرة ديال درجة حرارة وحدة باستعمال مجموعة التطوير.

نصائح متقدمة للاستعمال

1. جمع القرارات المرتابطة. حطّ بزاف ديال الأسئلة تحت state مشتركة باش يقدر السيرفر يعالج سلاسل التفكير ديالها بالتوازي.
2. استعمل الأجوبة المباشرة فالحالات السهلة. عيّن nothink_threshold باش تخلي التفكير غير للقرارات اللي الثقة ديالها بلا تفكير نازلة على العتبة اللي اخترتي.
3. حدّد التفكير فالخدمات الحساسة للتأخير. نقّص max_think بلا ما تعطل التفكير كامل، إلا بغيتي حل وسط بين السرعة والدقة.
4. رجّع التفكير بشكل انتقائي. خَلّي return_reasoning معطّل إلا كان التطبيق محتاج النص، خصوصاً حيث ما كاينش ضمان تكون هاد السلاسل سهلة الفهم والتفسير.
5. قيّم على المجال ديالك. Jeeves كيدير مزيان فـ test split ديال المشروع وفطبقات JevBench العمومية، ولكن كيبقى ورا Jev فالتقييمات المعرفية المعلنة ديال MMLU وMMLU-Pro.
6. فسّر المقارنات بحذر. من غير JevBench، المقارنات المنشورة بين Kev وJev كتستعمل عناصر مختلفة من نفس المصادر الأساسية.

الخلاصة

Jeeves كيجمع بين مخرجات منظمة على طريقة Jev، والتفكير وقت الاختبار، والاحتمالات المعايرة، وتوليد سلاسل التفكير بسرعة أكبر. بدا بالـ weights اللي تطرحو وبـ HTTP endpoint المتوافق مع Jev، واستعمل Python SDK للكود التطبيقي المقيّد بالأنواع، وضبط max_think وnothink_threshold باش توازن بين الدقة والتأخير. وللتخصيص العميق، المستودع كيوفّر pipeline كاملة ديال SFT وCISPO والمعايرة والتصدير وdrafter.