كيفية الحصول على مفتاح API لـ Jev (TypeSafe AI)؟

Jev هو نموذج اتخاذ القرار الخاص بـ TypeSafe AI. تقوم بإرسال جزء من الحالة ومجموعة من الأسئلة المكتوبة، ويجيب باحتمالات بدلاً من النثر. يغطي هذا الدليل مفتاح Jev API وطلبك الأول؛ للحصول على معلومات أساسية حول ماهية Jev ولماذا يعيد أرقامًا بدلاً من النص، اقرأ ما هو Jev أولاً. للتوضيح، نظرًا لأن نتائج البحث فوضوية: هذا هو Jev نموذج TypeSafe AI، وليس FaZe Jev اليوتيوبر، وليس لقاح JEV.

يعمل مفتاح Jev API مثل أي رمز حامل آخر، فإذا كنت جديدًا على هذا النمط، فإن ما هو مفتاح API يغطي الأساسيات. الوصول المباشر إلى API متاح في مرحلة الوصول المبكر، لذا فإن الخطوة الأولى هي الخروج من قائمة الانتظار. بعد ذلك ستقوم بإنشاء المفتاح، ومعرفة شكل الطلب، واستدعاء نقطة النهاية باستخدام curl و Python SDK، وقراءة حقول الاحتمالات، وربط الطلب بـ Apidog مع تأكيدات على تلك الاحتمالات. إذا لم تتمكن من الانتظار، فإن نفس النموذج متاح على Vercel AI Gateway بدون قائمة انتظار؛ الأسئلة الشائعة تغطي هذا المسار.

الخطوة 1: الحصول على الوصول المبكر، ثم إنشاء المفتاح

Jev متاح في مرحلة الوصول المبكر حتى تاريخ كتابة هذا الدليل. يذكر منشور إطلاق TypeSafe أنه "يعمل على إخراج المطورين من قائمة الانتظار بأسرع ما يمكن"، لذا انضم إلى قائمة الانتظار على typesafe.ai وانتظر دعوة وحدة التحكم؛ لا يوجد تسجيل ذاتي الخدمة بعد. بمجرد تنشيط حساب وحدة التحكم الخاص بك، انتقل إلى console.typesafe.ai/settings/keys وأنشئ مفتاحًا. انسخه مرة واحدة وتعامل معه ككلمة مرور.

قم بتصديره كمتغير بيئة بدلاً من لصقه في الكود:

export TYPESAFE_API_KEY="ts_..."

تقوم أمثلة curl الرسمية و Python SDK بقراءة TYPESAFE_API_KEY من البيئة، لذا يغطي متغير واحد كل مثال أدناه. إذا ظهر مفتاح في التزام (commit) في أي وقت، فقم بتدويره في وحدة التحكم وقم بإجراء فحص تسرب مفتاح API عبر المستودع.

الخطوة 2: فهم شكل الطلب

كل استدعاء لـ Jev هو طلب POST https://api.typesafe.ai/v1/systemone واحد بثلاثة حقول في الجسم، موثقة في مرجع TypeSafe API:

كل سؤال هو أحد ثلاثة أنواع أساسية (primitives):

تحمل الاستجابة أيضًا model و usage.input_tokens / usage.output_tokens. يمكن أن تشترك الأسئلة من أنواع مختلفة في حالة واحدة وتعود في رحلة ذهاب وعودة واحدة.

الخطوة 3: قم بإجراء الطلب الأول باستخدام curl

يقوم هذا الطلب بتشغيل جميع الأنواع الأساسية الثلاثة مقابل تذكرة دعم واحدة:

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "My card was charged twice for one order and nobody has replied in three days.",
    "questions": {
      "needs_review": {
        "type": "noul",
        "instructions": "Does this ticket need a human agent?",
        "criteria": {
          "true": "money, legal, or an unanswered complaint",
          "false": "a routine question a bot can close"
        }
      },
      "route": {
        "type": "choice",
        "instructions": "Route this ticket to a team.",
        "criteria": {
          "billing": "payment or charge problems",
          "shipping": "delivery problems",
          "technical": "application bugs"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this ticket?",
        "criteria": ["low", "medium", "high"]
      }
    }
  }'

تبدو الاستجابة بهذا الشكل (القيم توضيحية):

{
  "model": "jev-1.13.0",
  "answers": {
    "needs_review": { "type": "noul", "noul": 0.97 },
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.98,
      "probabilities": { "billing": 0.98, "shipping": 0.01, "technical": 0.01 }
    },
    "urgency": {
      "type": "score",
      "score": 1.6,
      "confidence": 0.62,
      "legend": { "0": "low", "1": "medium", "2": "high" },
      "probabilities": { "0": 0.02, "1": 0.36, "2": 0.62 }
    }
  },
  "usage": { "input_tokens": 190, "output_tokens": 0 }
}

الخطوة 4: قراءة حقول الاحتمالات

اقرأ الأرقام بدقة:

• `noul` هو احتمال "نعم". 0.97 يعني أن Jev متأكد بنسبة 97% أن هذه التذكرة تحتاج إلى تدخل بشري.
• `choice` هو الخيار ذو الاحتمالية الأعلى، وتسرد `probabilities` كل خيار، ويخبرك `confidence` بمدى حسم الاختيار. مسار بنسبة 0.98 آمن للأتمتة؛ أما المسار بنسبة 0.51 مع 0.47 للخيار البديل فهو بمثابة رمي عملة (غير حاسم).
• `score` هو الموضع المرجح بالاحتمالات عبر المستويات المرتبة، لذا فإن 1.6 يقع بين "متوسط" (1) و"مرتفع" (2). تربط `legend` كل فهرس بعلامته، وتُظهر `probabilities` النطاق الكامل.

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

الخطوة 5: نفس الاستدعاء باستخدام Python SDK

ثبّت SDK؛ يلتقط العميل TYPESAFE_API_KEY من البيئة:

pip install typesafe-sdk

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="My card was charged twice for one order and nobody has replied in three days.",
        questions={
            "needs_review": Noul(
                instructions="Does this ticket need a human agent?",
                criteria={"true": "money, legal, or an unanswered complaint",
                          "false": "a routine question a bot can close"},
            ),
            "route": Choice(
                instructions="Route this ticket to a team.",
                criteria={"billing": "payment or charge problems",
                          "shipping": "delivery problems",
                          "technical": "application bugs"},
            ),
            "urgency": Score(
                instructions="How urgent is this ticket?",
                criteria=["low", "medium", "high"],
            ),
        },
    )

print(response.nouls["needs_review"].noul)
print(response.choices["route"].choice, response.choices["route"].probabilities)
print(response.scores["urgency"].score)

يتم تجميع الإجابات حسب النوع في كائن الاستجابة (nouls، choices، scores). يوجد JavaScript SDK بنفس الشكل، وإذا كنت تستخدم Vercel AI Gateway بالفعل، فإن experimental_evaluate من AI SDK 7 يستدعي النموذج باسم typesafe-ai/jev، مع اختلاف واحد: يعيد نوع السؤال البولياني حقل probability بدلاً من noul.

الخطوة 6: تخزين واختبار مفتاح Jev API في Apidog

يثبت Curl أن المفتاح يعمل مرة واحدة. يجعل Apidog الطلب قابلاً لإعادة التشغيل والتأكيد والمحاكاة للفريق بأكمله.

قم بتخزين المفتاح كمتغير سري. أنشئ بيئة باسم TypeSafe وأضف TYPESAFE_API_KEY كسر حتى تظل قيمته مخفية في واجهة المستخدم وبعيدًا عن التصديرات؛ يشرح بيئات Apidog والمتغيرات السرية الإعداد. اضبط المصادقة على الطلب إلى Bearer Token مع {{TYPESAFE_API_KEY}} كقيمة.

أنشئ طلب POST. أضف طلب POST إلى https://api.typesafe.ai/v1/systemone، الصق جسم JSON من الخطوة 3، وأرسله. تعرض لوحة الاستجابة شجرة الإجابات، بحيث يمكنك التحقق من الاحتمالات قبل كتابة تأكيد.

أكّد على الاحتمالات، وليس على النثر. في منشئ التأكيدات المرئي، وجّه تعبيرات JSONPath إلى الحقول التي تهتم بها:

• `$.answers.needs_review.noul` أكبر من `0.9`
• `$.answers.route.choice` يساوي `billing`
• `$.answers.route.probabilities.billing` أكبر من `0.8`
• `$.answers.urgency.score` أكبر من أو يساوي `1`
• `$.usage.input_tokens` أقل من `1000`

إذا كنت تفضل السكربتات، فإن المعالج اللاحق يقبل واجهة pm المألوفة:

const body = pm.response.json();
pm.test("ticket flagged for a human", () => {
  pm.expect(body.answers.needs_review.noul).to.be.above(0.9);
});
pm.test("routed to billing", () => {
  pm.expect(body.answers.route.choice).to.eql("billing");
});

احفظه كسيناريو اختبار. ضع الطلب في سيناريو اختبار مع ملف CSV صغير من التذاكر والمسارات المتوقعة، وقم بتشغيله عند كل تغيير في تعليماتك أو معاييرك. تعديلات الأوامر هي تغييرات في التعليمات البرمجية؛ سيناريو من عشرة صفوف يلتقط التعديل الذي ينقل 0.95 بهدوء إلى 0.6. يتم تشغيل نفس السيناريو في CI عبر Apidog CLI، لذا فإن أي تراجع (regression) يمنع الدمج.

قم بمحاكاة شكل الاستجابة المعلن. حدد مخطط الاستجابة على نقطة النهاية (كائنات الإجابة الثلاثة بالإضافة إلى usage)، ويقدم Apidog's smart mock احتمالات وهمية واقعية على الفور. يمكن للواجهة الأمامية بناء شارة "يحتاج إلى مراجعة" وواجهة مستخدم التوجيه مقابل المحاكاة قبل شحن الواجهة الخلفية، ثم تبديل عنوان URL للمحاكاة بنقطة النهاية الحقيقية بتغيير بيئة واحدة.

لتخطيط المقاعد: خطة Apidog المجانية تتضمن 4 مستخدمين، والطبقات المدفوعة هي لكل مقعد.

العتبات في الكود

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

REVIEW_THRESHOLD = 0.9
AUTO_ROUTE_CONFIDENCE = 0.85

needs_review = response.nouls["needs_review"].noul >= REVIEW_THRESHOLD
route = response.choices["route"]

if route.confidence >= AUTO_ROUTE_CONFIDENCE and not needs_review:
    assign(ticket, team=route.choice)
else:
    queue_for_human(ticket, suggested=route.choice)

سجّل خريطة `probabilities` الكاملة مع كل قرار حتى تتمكن من ضبط العتبات من البيانات الحقيقية لاحقًا، واجعل المراجعة البشرية هي الافتراضية عندما تكون الثقة منخفضة؛ النموذج يخبرك بأنه غير متأكد.

القيود، التسعير، والنماذج

مباشرة من صفحة نماذج TypeSafe:

بهذا السعر، يكلف مليون تذكرة قصيرة أقل من 10 دولارات. تذكر TypeSafe أيضًا أن Jev لم يتم تدريبه على طلبات العملاء أو استجاباتهم.

الأخطاء الشائعة وكيفية إصلاحها

422 هو الخطأ الذي ستواجهه غالبًا أثناء التكرار؛ يلتقط مخطط نقطة النهاية من الخطوة 6 معظم هذه الأخطاء قبل أن يغادر الطلب جهازك.

الأسئلة الشائعة

هل توجد طبقة مجانية لـ Jev API؟ تسرد المستندات العامة تسعيرًا حسب الرمز ولا تصف طبقة مجانية أو أرصدة بدء التشغيل، والوصول نفسه يخضع لقائمة انتظار في الوقت الحالي. تحقق من وحدة التحكم بمجرد وصول دعوتك للاطلاع على العرض الحالي، وتعامل مع أي رقم تراه في أي مكان آخر على أنه غير رسمي.

هل يمكنني الحصول على عدة إجابات من طلب واحد؟ نعم. questions عبارة عن خريطة، لذا يمكن تشغيل noul وخيار ودرجة كلها مقابل حالة واحدة في استدعاء واحد. إنه أرخص من ثلاثة طلبات ويحافظ على اتساق الإجابات لأنها تشترك في إدخال واحد.

كيف يختلف هذا عن المخرجات المنظمة في نموذج الدردشة؟ تجبر المخرجات المنظمة نموذج اللغة على إصدار JSON صالح، لكن القيم الداخلية لا تزال رموزًا تم إنشاؤها، وحقل "الثقة" هو نص كتبه النموذج عن نفسه. يعيد Jev احتمالات مقاسة كمخرجات أصلية، ولهذا السبب يمكنك التأكيد على أن noul > 0.9 والثقة في المقارنة.

هل أحتاج إلى SDK الخاص بـ TypeSafe إذا كنت أستخدم Vercel؟ لا. يعرض Vercel AI SDK Jev من خلال experimental_evaluate مع typesafe-ai/jev كمعرف للنموذج. ستصادق باستخدام مفتاح AI Gateway الخاص بك بدلاً من مفتاح TypeSafe، وتعود الإجابة البوليانية كـ probability.

الخطوات التالية

لديك الآن مفتاح Jev API، وطلب عامل في curl و Python، وفهم واضح لـ noul، choice، و score. ضع الطلب في Apidog، أضف تأكيدات الاحتمالات، واحفظ سيناريو الاختبار حتى يتم اختبار تعديلات الأوامر مثل الكود. قم بتنزيل Apidog للمتابعة.