Skip to content

طرق التثبيت البديلة: uv و npm و الاتصال المباشر بواجهة API عبر curl ​

في الدرس السابق سلكنا المسار الرئيسي باستخدام venv + pip، لكن تثبيت TypeSafe SDK لا يقتصر على مسار واحد: البداية السريعة الرسمية تقدم ثلاث طرق بديلة في آنٍ واحد: uv، و JavaScript / TypeScript SDK، والاتصال المباشر عبر Bash. في هذا الدرس سنمر بالطرق الثلاث — بعد 8 دقائق، اختر واحدة منها حسب مشروعك.

ماذا ستستطيع أن تفعل بعد إتمام الدرس ​

  • إكمال تثبيت TypeSafe SDK بأمرين من uv، وقفل التبعيات داخل uv.lock
  • تثبيت Jev JavaScript SDK عبر npm (@typesafe-ai/sdk)، وتشغيل نفس مثال الأسئلة الثلاثة عن التذكرة من الدرس السابق بنجاح
  • تشغيل نفس الشيفرة مباشرة بـ TypeScript (Node.js 22.18+)
  • الاتصال المباشر بواجهة TypeSafe API باستخدام curl 7.76+، ورؤية استجابة JSON خام في سطر واحد كامل
  • ذكر متطلبات الإصدارات لكل من المسارات الثلاثة، واختيار المسار المناسب لمشروعك

المأزق الذي أنت فيه الآن ​

  • المشروع يستخدم uv بالفعل، والعودة إلى venv + pip أشبه بالسير إلى الخلف
  • مكدسنا التقني كله Node / TypeScript، وإعداد بيئة Python كاملة من أجل استدعاء API واحد لا يستحق
  • لم نقرر بعد أي SDK نستخدم، ونريد أولًا استخدام curl لرؤية ما تعيده واجهة API فعلًا قبل البدء

متى تستخدم هذه الطريقة ​

عندما تحتاج إلى:

  • إضافة Jev إلى مشروع Python يديره uv
  • استدعاء Jev من مشروع Node.js أو الواجهة الأمامية أو TypeScript
  • إجراء استدعاء HTTP مباشر بأي لغة (للتحقق من النتيجة أولًا، أو عندما لا توفر الجهة الرسمية SDK للغتك)

ولا تريد:

  • تشغيل python3 -m venv يدويًا ثم pip install
  • تثبيت SDK كاملًا من أجل طلب curl واحد

🎒 الاستعدادات قبل البدء ​

  • أنجزت درس التثبيت وأول طلب — هذا الدرس سيعيد استخدام نفس مثال route_ticket.py
  • لديك Key في متغيرات البيئة: تنفيذ echo $TYPESAFE_API_KEY في الطرفية يطبعها (إن لم يكن لديك، فارجع إلى التسجيل ومفتاح API)
  • جهّز حسب المسار الذي ستسلكه: Python 3.10+ (مسار uv)، Node.js 22+ (مسار npm)، curl 7.76+ (مسار curl)
  • سطر الأوامر يستخدم Bash (macOS / Linux / Windows WSL — أوامر البداية السريعة الرسمية مكتوبة لهذه البيئة)

الفكرة الأساسية ​

يعرض قسم «اكتب الشيفرة وأرسل أول طلب» في البداية السريعة الرسمية أربع علامات تبويب: Python و JavaScript و TypeScript و Bash. الدرس السابق سلك مسار Python عبر venv + pip، وهذا الدرس يكمل المسارات المتبقية.

مقارنة بين المسارات البديلة الثلاثة:

المسارما الذي يُثبِّتمتطلبات الإصدارلمن يناسب
uvtypesafe-sdk (نفس الحزمة المتاحة عبر pip)Python 3.10+، مع ضرورة تثبيت uvمشاريع Python التي تستخدم uv بالفعل أو تريد استخدامه
npm@typesafe-ai/sdkNode.js 22+ (تشغيل TS مباشرة 22.18+)مشاريع Node والواجهات الأمامية و TypeScript
curlلا يثبِّت شيئًاcurl 7.76+أي لغة؛ للتحقق السريع من استجابة API

المسارات الثلاثة تستدعي نفس نقطة النهاية: POST https://api.typesafe.ai/v1/systemone، والمصادقة في جميعها هي Authorization: Bearer <Key>. الاختلاف الوحيد في «من يغلّف HTTP نيابةً عنك».

يقوم SDK بثلاثة أمور نيابةً عنك، وعند الاتصال المباشر عليك القيام بها بنفسك:

الأمرما يفعله SDKعند الاتصال المباشر عبر curl
المصادقةيقرأ TYPESAFE_API_KEY تلقائيًايبني ترويسة الطلب -H "Authorization: Bearer $TYPESAFE_API_KEY" كتابتها يدويًا
إعادة المحاولة عند تحديد المعدل429 / 529 إعادة محاولة افتراضية بتراجع أُسّيتكتبها بنفسك (صفحة الأخطاء الرسمية تشترط صراحةً التراجع الأُسّي)
صيغة الإرسال والاستقبالالحالة والأسئلة مغلفة بفئات، والإجابات تُجلب حسب IDتبني JSON بنفسك وتحلل JSON بنفسك

اتبع خطواتي ​

المسارات الثلاثة مستقلة عن بعضها، فاختر واحدًا حسب لغتك (راجع الجدول أعلاه للمقارنة)؛ أرقام الخطوات متسلسلة لتسهيل الإحالات المتبادلة.

الخطوة 1: إكمال تثبيت TypeSafe SDK باستخدام uv ​

لماذا: uv هو طريقة تثبيت مذكورة في البدء السريع الرسمي جنبًا إلى جنب مع pip، حيث تنشئ الأمران مشروعًا وتثبّتان SDK، كما يُولَّد تلقائيًا ملف قفل متوافق مع جميع المنصات uv.lock.

تحقق أولًا مما إذا كان uv مثبتًا:

bash
uv --version

إذا لم يكن مثبتًا، استخدم سكربت التثبيت الرسمي (macOS / Linux):

bash
curl -LsSf https://astral.sh/uv/install.sh | sh

ثبّت SDK. نفّذ في دليل المشروع:

bash
uv init --bare
uv add typesafe-sdk

يجب أن ترى: عدم ظهور أي خطأ في كلا الأمرين؛ يُخرج الأمر الثاني شيئًا مشابهًا لـ Installed 14 packages، مع سطر في القائمة مثل typesafe-sdk==0.7.5 (رقم الإصدار يعتمد على وقت تثبيتك). ظهر في الدليل كلٌّ من .venv/ و uv.lock، وأُضيف "typesafe-sdk>=0.7.5" إلى dependencies في pyproject.toml.

  • ظهر في دليل المشروع كلٌّ من .venv/ و uv.lock

شغّل مثال الدرس السابق — دون الحاجة إلى تفعيل أي بيئة:

bash
uv run route_ticket.py

يجب أن ترى: الأسطر الثلاثة نفسها تمامًا كما في الدرس السابق:

text
technical
0.67
0.99

route_ticket.py هو نفسه المثال الرسمي من الدرس السابق، انسخه كما هو (الكود في التثبيت وأول طلب).

ثلاثة تفاصيل حول مسار uv (استنادًا إلى وثائق uv الرسمية):

التفصيلالشرح
uv init --bareيُنشئ pyproject.toml فقط، دون إنشاء دليل src أو README أو git — يكفي للبدء السريع
.venvيدير uv البيئة الافتراضية بجانب pyproject.toml؛ ويضمن uv run تلقائيًا بقائها متزامنة مع ملف القفل. يمكن أيضًا استخدام .venv/bin/python route_ticket.py مباشرة
uv.lockيثبّت الإصدارات الدقيقة، وتوصي الوثائق الرسمية بإدراجه في نظام التحكم بالإصدارات، ما يتيح إعادة إنتاج المجموعة نفسها من التبعيات على جهاز آخر

الخطوة 2: تثبيت Jev JavaScript SDK عبر npm وتشغيل المثال بنجاح ​

لماذا: يُعد JavaScript / TypeScript SDK أحد اثنين من عملاء SDK الرسميين، ويستخدم أسلوب «state + questions» نفسه المستخدم في Python SDK، كما يمكن استنتاج أنواع الإجابات تلقائيًا من تعريف الأسئلة.

تحقق أولًا من إصدار Node — هناك فخ يسهل الوقوع فيه هنا:

bash
node --version

تذكر تبويب JavaScript في البدء السريع الرسمي «Node.js 20 or later»، لكن ذلك كان معيار الإصدار القديم: صفحة وثائق SDK وسجل التغييرات يذكران Node.js 22 or newer (تغييرات جذرية بدءًا من الإصدار v0.7.0)، وحقل engines في حزمة npm هو >=22 أيضًا. اعتمد على 22+ (التفاصيل في تنبيه المخاطر أدناه).

ثبّت SDK:

bash
npm install @typesafe-ai/sdk
npm pkg set type=module

يضع الأمر الثاني علامة على المشروع كوحدة ES module — يستخدم المثال الرسمي صيغة import، وبدون هذا الإعداد سيظهر خطأ عند تحميل Node.

يجب أن ترى: يُخرج الأمر الأول added 1 package؛ ظهر في الدليل كلٌّ من node_modules/ و package.json و package-lock.json. يوجد في package.json القيمة "@typesafe-ai/sdk": "^0.7.0"، وبعد تنفيذ الأمر الثاني تظهر أيضًا "type": "module".

أنشئ باستخدام محرر النصوص ملف route_ticket.js، والصق فيه المثال الرسمي:

javascript
import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";

const ticket = "Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed.";

const client = new TypeSafeClient({ defaultModel: "jev-latest" }); // Reads TYPESAFE_API_KEY.
const response = await client.systemOne({
  state: ticket,
  questions: {
    department: choice("Which team should handle this", {
      billing: "Payment or subscription issues",
      technical: "Bugs or integration problems",
      sales: "Pricing or account questions",
    }),
    frustration: score("How frustrated the customer appears", [
      "Calm, just stating facts",
      "Frustrated but civil",
      "Very angry, strong language",
    ]),
    is_urgent: noul("The message conveys urgency or time-sensitivity"),
  },
});

console.log(response.answers.department.choice);
console.log(response.answers.frustration.score);
console.log(response.answers.is_urgent.noul);

شغّله:

bash
node route_ticket.js

يجب أن ترى: ثلاثة أسطر من المخرجات، متوافقة مع مسار Python:

text
technical
0.67
0.99
  • node route_ticket.js طبع technical / 0.67 / 0.99

التشغيل المباشر بـ TypeScript (اختياري) ​

الكود نفسه، احفظه كما هو باسم route_ticket.ts (المحتوى مطابق تمامًا لـ route_ticket.js)، ثم مباشرة:

bash
node route_ticket.ts

يجب أن ترى: أسطر المخرجات الثلاثة نفسها. يتطلب هذا Node.js 22.18 أو أحدث (يدعم تشغيل TypeScript مباشرة)؛ كما يستنتج SDK نوع الإجابة من تعريف أسئلتك — نوع response.answers.department.choice هو "billing" | "technical" | "sales"، والإكمال التلقائي في المحرر متاح فورًا.

الخطوة 3: الاتصال المباشر بواجهة TypeSafe API باستخدام curl ​

لماذا: مثال Bash في البدء السريع الرسمي هو ببساطة «طلب HTTP كامل بدون SDK». يمكن لأي لغة قادرة على إرسال HTTP (Go أو Java أو Rust...) استدعاء Jev بنفس هذا الهيكل؛ كما أنه مناسب للتحقق من استجابة الواجهة أولًا قبل تقرير تثبيت SDK.

أنشئ باستخدام محرر النصوص ملف route_ticket.sh، والصق فيه المثال الرسمي:

bash
#!/usr/bin/env bash
set -euo pipefail
: "${TYPESAFE_API_KEY:?Set TYPESAFE_API_KEY first.}"

curl --fail-with-body --silent --show-error \
  https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "state": "Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales": "Pricing or account questions"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language"
      ]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}
JSON

شغّله:

bash
bash route_ticket.sh

يجب أن ترى: سطر واحد كامل من JSON خام — بخلاف القيم الثلاث التي يطبعها مسار SDK، هذه هي الاستجابة الكاملة، وتتضمن confidence و probabilities لكل إجابة، بالإضافة إلى قياس usage. النموذج الكامل بعد التنسيق موجود في قسم «فهم الاستجابة الكاملة» في الدرس السابق، ولن نكرر معاني الحقول: التثبيت وأول طلب.

عند عدم تعيين المفتاح، يوقف السكربت الطلب محليًا أولًا: route_ticket.sh: line 3: TYPESAFE_API_KEY: Set TYPESAFE_API_KEY first. — هذا هو دور سطر الحماية في السطر رقم 3 في البداية، لتجنب إرسال مفتاح فارغ إلى الخادم دون فائدة.

  • bash route_ticket.sh طبع سطرًا كاملًا من JSON يحتوي على "answers"

تنبيهان لمسار curl:

البندالشرح
--fail-with-bodyيتطلب curl 7.76+: عند حدوث خطأ HTTP يكون رمز الخروج غير 0، لكنه يطبع متن الاستجابة مع ذلك، ما يسهّل معرفة موضع الخطأ
429 / 529في حل الاتصال المباشر عليك كتابة إعادة المحاولة مع التراجع الأسي بنفسك (SDK يتضمنها افتراضيًا)؛ عند الاستلام ألقِ نظرة على متن الاستجابة، وخذ قسطًا من الراحة ثم أعد الإرسال

نقطة تحقق ✅ ​

  • مسار uv: العناصر الثلاثة .venv/ و uv.lock و pyproject.toml موجودة جميعها، و uv run route_ticket.py يُخرج ثلاثة أسطر من الإجابات
  • مسار npm: يوجد في package.json كلٌّ من "@typesafe-ai/sdk" و "type": "module"
  • مسار curl: bash route_ticket.sh يُخرج سطرًا كاملًا من JSON يحتوي على answers
  • أعرف أن المسارات الثلاثة تستدعي نقطة النهاية نفسها: POST /v1/systemone
  • أعرف الحد الأدنى للإصدارات: Python 3.10+ / Node 22+ (تشغيل TS المباشر 22.18+) / curl 7.76+

تنبيهات المخاطر ​

❌ npm pkg set type=module يعرض npm error code ENOENT ​

الظاهرة: تشغيل npm pkg set type=module مباشرة في دليل فارغ يعرض Could not read package.json ... no such file or directory.

السبب: npm pkg set هو أمر «لتعديل package.json»، وعندما لا يوجد هذا الملف في الدليل فلن ينشئه لك (تم التحقق فعليًا على npm 10.9.7).

الطريقة الصحيحة: اتبع الترتيب الرسمي — أولًا npm install @typesafe-ai/sdk (سيولّد npm تلقائيًا package.json)، ثم npm pkg set type=module.

❌ node يُظهر Warning: Failed to load the ES module ​

الظاهرة: عند تشغيل node route_ticket.js، يظهر الخطأ Failed to load the ES module: route_ticket.js. Make sure to set "type": "module" in the nearest package.json file or use the .mjs extension.

السبب: المشروع لم يُوسم كـ ES module (أو تم ضبطه على commonjs)، بينما المثال الرسمي يستخدم صيغة import.

الطريقة الصحيحة: npm pkg set type=module؛ أو اتبعًا لتلميح الخطأ، غيّر امتداد الملف إلى .mjs.

❌ حضّرت البيئة وفق «Node 20+» لكنك ثبّتت إصدار SDK جديدًا يتطلب 22+ ​

السبب: صفحة البدء السريع الرسمية تقول في تبويب JavaScript «Node.js 20 or later»، لكن أحدث إصدار للـ SDK على npm حاليًا (0.7.0) engines هو node >=22، وسجل التغييرات في الإصدار v0.7.0 يوضح أيضًا أنه تغيير كاسر «require Node.js 22 or newer». أما تاريخيًا فالإصداران 0.5.7 / 0.6.0 كانا يدعمان 20+ — فجملة البدء السريع تلك تعود إلى الإصدارات القديمة.

الطريقة الصحيحة: تحقق أولًا بـ node --version، وإن لم يكن كافيًا لـ 22 فقم بترقية Node، أو تحول إلى مسار uv أو curl في هذا الدرس.

❌ بعد uv add لا يزال python route_ticket.py يظهر ModuleNotFoundError ​

السبب: python الموجود في النظام ليس البيئة التي يديرها uv، فالـ SDK مثبت في .venv الخاص بالمشروع.

الطريقة الصحيحة: اتبع المثال الرسمي واستخدم دائمًا uv run route_ticket.py (فهو يتأكد أولًا من مزامنة .venv مع ملف القفل)؛ أو حدد صراحةً .venv/bin/python route_ticket.py.

نصائح متقدمة (اختياري) ​

يدير الـ SDK الضغط نيابةً عنك أيضًا. يستخدم Python SDK افتراضيًا ضغط zstd لجسم الطلب بدءًا من الإصدار v0.7.5؛ بينما يضغط JavaScript SDK تلقائيًا أجسام الطلبات الأكبر من 1 KiB على Node 22.15+، ولإيقاف ذلك مرّر compression: false. أما Python 3.13 والإصدارات الأقدم فتتطلب إضافة extras صراحةً: uv add "typesafe-sdk[zstd]" (وهناك أيضًا extras إضافيان هما http2 وpil).

اللغات التي لا يوجد لها SDK رسمي. Go وJava وRust…… فقط أرسل POST /v1/systemone وفق بنية الخطوة 3، وتعريفات حقول state / questions / answers موجودة في مرجع API السريع.

قبل دفع الحل المباشر إلى الإنتاج. ضمّن إعادة المحاولة بالتراجع الأُسّي لـ 429 / 529 في عميل HTTP الخاص بك — هذا مطلب صريح من صفحة errors الرسمية لمستخدمي الاتصال المباشر، أما مسار SDK فلا يلزمه ذلك.

خلاصة هذا الدرس ​

✅ مسار uv: uv init --bare + uv add typesafe-sdk، أمران فقط لتثبيت SDK الخاص بـ TypeSafe، ثم uv run للتشغيل مباشرةً.

✅ مسار npm: npm install @typesafe-ai/sdk + npm pkg set type=module، تشغيل نفس المثال في JavaScript وTypeScript (تشغيل مباشر على 22.18+).

✅ مسار curl: --fail-with-body للاتصال المباشر بـ API، ورؤية JSON الخام الكامل مع confidence وprobabilities.

مراجعة حقول الإعداد الأساسية:

الحقلالقيمة الموصى بهاالشرح
اسم حزمة Pythontypesafe-sdkنفس الحزمة لـ pip / uv؛uv add typesafe-sdk
اسم حزمة JS@typesafe-ai/sdkالتثبيت عبر npm؛ بدءًا من v0.7.0 يتطلب Node 22+
ES moduletype=moduleأمثلة JS / TS الرسمية تستخدم import، ويجب ضبطه
نقطة النهايةPOST https://api.typesafe.ai/v1/systemoneمشتركة بين المسارات الثلاثة
المصادقةAuthorization: Bearer <Key>يضيفها الـ SDK تلقائيًا؛ وcurl يستخدم $TYPESAFE_API_KEY
متغير البيئةTYPESAFE_API_KEYمشترك بين المسارات الثلاثة، ولا تُكتب المفتاح في الكود

استعراض الدرس التالي ​

بعد إتمام المسارات الثلاثة يتبقى خطوة أخيرة كشبكة أمان: ماذا تفعل إذا فشل التثبيت أو التشغيل: استكشاف أخطاء البداية.

ستتعلم:

  • باستخدام 3 أوامر، تحديد في أقل من 60 ثانية أي حلقة هي المشكلة: البيئة أم المفتاح أم الشبكة
  • 400 / 401 / 413 / 422 / 429 — ماذا يعني كل رمز حالة وكيفية التعامل معه
  • أي الأخطاء يعيد الـ SDK محاولتها تلقائيًا (429 / 529)، وكيف تكتبها بنفسك عند الاتصال المباشر
  • عند الإبلاغ عن خطأ، كيف ترفق request_id وأصغر كود لإعادة الإنتاج عند طرح السؤال
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.