ماذا تفعل إذا فشل التثبيت أو لم يعمل: استكشاف أخطاء البداية
إذا لم يعمل طلبك الأول، فغالباً العائق في ثلاث نقاط: بيئة مثبّتة على Python خاطئ، أو مفتاح لم يُضبط جيداً، أو نص طلب لا يطابق القواعد. في هذا الدرس نمر على أخطاء TypeSafe الشائعة واحداً واحداً وفق «نص الخطأ» مع السبب والحل — ابدأ بالفحص السريع خلال 60 ثانية ثم طابِق خطأك. جميع أخطاء Python هنا أُعيد إنتاجها فعلياً على typesafe-sdk v0.7.5 وPython 3.12.
ماذا ستستطيع فعله بعد الدرس
- تحديد أي حلقة بها مشكلة — البيئة أم المفتاح أم الشبكة — بـ 3 أوامر خلال 60 ثانية
- مطابقة أخطاء TypeSafe: في أي حلقة حدثت، وما سببها، وكيف تُصلحها
- فهم ما يقوله كل واحد من 7 رموز حالة HTTP (400/401/413/415/422/429/529)
- طباعة
statusوrequest_idفي الكود باستخدامexcept TypeSafeAPIErrorلإرفاق الأدلة عند طرح الأسئلة - معرفة أين تطلب المساعدة: وحدة التحكم، الوثائق الرسمية، GitHub Issues، Discord
مأزقك الحالي
- انتهيت من pip، وبمجرد التشغيل يظهر
ModuleNotFoundError— هل لم يُثبَّت، أم استخدمت Python خاطئاً، أم ثبّتَ حزمة خاطئة بالاسم نفسه؟ - المفتاح مضبوط فعلاً، ومع ذلك يظهر 401، وقد أعدت نسخه ثلاث مرات
- رسالة الخطأ كتلة JSON، ولا تدري أي حقل هو مصدر المشكلة
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- إصلاح الأخطاء العالقة في الطلب الأول أو طرق التثبيت البديلة
- قبل كتابة الكود الخاص بك، أن تعرف أين تقع الأخطاء غالباً وما الإشارات التي تنظر إليها عند حدوثها
ولا تريد:
- أن تذهب إلى المنتديات وتنتظر الردود عند كل خطأ؛ فالفحص السريع خلال 60 ثانية يوفّر معظم الانتظار
- أن تخلط بين «خطأ في الكود» و«مشكلة في المفتاح/الحصة/الخادم»، فتعدّل الكود ساعات بلا جدوى
🎒 التحضير قبل البدء
- أن تكون قد جرّبت التثبيت والطلب الأول (لا بأس إن علقت، فهذا الدرس مخصص لحل العلق)
- أن يعمل Bash في الطرفية (macOS / Linux / Windows WSL — الأوامر الرسمية مكتوبة لهذه البيئة)
- متصفح مسجّل الدخول إلى وحدة تحكم TypeSafe (ستحتاج للعودة إليه في مشكلات المفتاح)
الفكرة الأساسية
حدّد الحلقة أولاً، ثم انظر إلى الخطأ. استدعاء Jev واحد يمر بأربع مراحل، ولكل مرحلة أخطاء مختلفة الشكل:
| المرحلة | ماذا تفحص | الأخطاء النموذجية |
|---|---|---|
| 1. البيئة | إصدار Python وصحة الحزمة المثبتة | ModuleNotFoundError |
| 2. المصادقة | هل المفتاح موجود وصحيح | 401 / 403 (الاتصال المباشر دون ترويسة مصادقة، من الاختبار الفعلي) / TypeSafeError (يُرمى عند إنشاء العميل) |
| 3. نص الطلب | قواعد JSON وتعريف المسألة | 400 / 422 |
| 4. الخادم | تحديد المعدل والتحميل الزائد | 429 / 529 |
يعترض الـ SDK بعض الأخطاء محليًا. اعتبارًا من الإصدار v0.7.1، يُرمى TypeSafeError عند إنشاء العميل إذا كان المفتاح غير صالح، فلا يُرسل الطلب إطلاقًا؛ ونقص criteria في تعريف المشكلة يُعترض عليه محليًا أيضًا. لذا فحتى مع نفس TypeSafeError، بعض الأخطاء لا تصل إلى الخادم أصلًا — ميّز أولًا بين «الاعتراض المحلي» و«الإرجاع من الخادم»، فاتجاه استكشاف الأخطاء مختلف تمامًا.
**جدول رموز الحالة. ** الأخطاء التي يُرجعها الخادم تحمل رموز حالة HTTP قياسية (docs/api/errors.md):
| رمز الحالة | المعنى | بجملة واحدة |
|---|---|---|
400 Bad Request | انتهاك قواعد الطلب (UTF-8، وعدد مستويات التداخل، والأرقام غير المنتهية، ومتن مضغوط تالف)؛ max_tokens_exceeded = تجاوز السياق | عدّل متن الطلب |
401 Unauthorized | المفتاح مفقود أو غير صالح | تحقق من المفتاح |
413 Payload Too Large | متن الطلب يتجاوز 32 MiB | قلّل الحجم |
415 Unsupported Media Type | Content-Encoding غير مدعوم أو الضغط يتجاوز مستوى واحدًا | عدّل الضغط |
422 Unprocessable Entity | فشل التحقق من الحقول، ويحدد المتن الحقل | أكمل الحقل |
429 Too Many Requests | تجاوز حد المعدل | أعد المحاولة مع التراجع |
529 Overloaded | TypeSafe حمل زائد مؤقت | أعد المحاولة مع التراجع |
💡 أرفق request_id عند طرح سؤالك
كائن أخطاء API الخاص بالـ SDK يحتوي على request_id (من ترويسة الاستجابة x-typesafe-request-id). عند تقديم ملاحظات رسمية أرفقه، فيتمكن الطرف الآخر من العثور على ذلك الطلب مباشرة. مدخل مجتمع Discord: discord.gg/typesafe.
الاستكشاف الأول: فحص سريع في 60 ثانية
شغّل الأوامر الثلاثة بالترتيب للتحقق تباعًا من الحزمة والمفتاح والشبكة والمصادقة، مع الإشارة إلى المخرجات المتوقعة لكل أمر.
# 1. 包装对了吗?——应该看到 0.7.5(或更高)
.venv/bin/python -c "import typesafe_sdk; print(typesafe_sdk.__version__)"
# 若报 ModuleNotFoundError:装的环境和跑的环境不是同一个,或装错了包(见下方排错)
# 2. Key 设置了吗?——应该看到完整 Key 字符串
echo "$TYPESAFE_API_KEY"
# 空的:export TYPESAFE_API_KEY="your-api-key" 再跑(新开终端要重新 export)
# 3. Key 真的有效吗?——应该看到 HTTP 401(说明网络通、你还没用真 Key)
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
-H "Authorization: Bearer $TYPESAFE_API_KEY"
# 200 = 认证通过;401 = Key 无效(见下方排错)ينبغي أن ترى: الأمر رقم 1 يطبع رقم الإصدار، والأمر رقم 2 يطبع المفتاح، والأمر رقم 3 يُرجع 200 (عند صلاحية المفتاح) أو رمز حالة يمكن التعرف عليه. أي أمر يفشل ابدأ الإصلاح منه.
استكشاف المشكلات الشائعة
مشكلات البيئة والتثبيت
"ModuleNotFoundError: No module named 'typesafe_sdk'"
السبب: ثُبّتت الحزمة في .venv، لكن التشغيل تم باستخدام Python الخاص بالنظام (أو بيئة أخرى) — المفسّران في الجهتين ليسا نفسهما. احتمال آخر: pip install typesafe ثبّت حزمة خاطئة بنفس الاسم (انظر القسم التالي).
الحل:
- شغّل دائمًا باستخدام مفسّر venv (كما في الأمثلة الرسمية):
.venv/bin/python route_ticket.py- أو فعّل البيئة أولًا ثم شغّل (الاستخدام المعتاد لـ venv):
source .venv/bin/activate
python route_ticket.py- إن لم ينجح ذلك فتأكد من أن الحزمة مثبتة فعلًا: أعد تنفيذ
.venv/bin/pip install typesafe-sdkوتحقق من وجودSuccessfully installedفي المخرجات.
ينبغي أن ترى: ثلاثة أسطر من المخرجات technical / 0.67 / 0.99 (تتغير القيم مع الإصدار، المهم أن يصحّ الهيكل).
"ImportError: cannot import name 'TypeSafeClient' from 'typesafe'"
السبب: pip install typesafe (بإسقاط -sdk)لا يُبلغ عن خطأ — فهو يثبّت مكتبة خارجية غير ذات صلة بنفس الاسم typesafe 0.9.1 ("formal type asserting decorators"، بقلم Krister Hedfors، ولا علاقة لها إطلاقًا بـ TypeSafe AI)، وبالطبع لا تحتوي على TypeSafeClient. فيرمي from typesafe import TypeSafeClient خطأ ImportError؛ بينما يرمي import typesafe_sdk في نفس البيئة خطأ ModuleNotFoundError المذكور أعلاه.
الحل:
- أزل الحزمة المثبتة خطأً وثبّت الحزمة الصحيحة (اسم التثبيت هو بشرطة
typesafe-sdk):
.venv/bin/pip uninstall -y typesafe
.venv/bin/pip install typesafe-sdk- تحقق من الاستيراد (اسم الاستيراد هو بشرطة سفلية
typesafe_sdk):
.venv/bin/python -c "from typesafe_sdk import TypeSafeClient; print('ok')"ينبغي أن ترى: ok؛ وتحتوي مخرجات pip على Successfully installed ... typesafe-sdk-0.7.5.
إصدار Python أقل من 3.10
السبب: يشترط الـ SDK الرسمي Python 3.10 أو أحدث (docs/introduction/quickstart.md: "Requires Python 3.10 or later"، وبيانات PyPI الوصفية requires-python = ">=3.10").
الحل:
- تحقق من الإصدار الحالي:
python3 --version- إذا كان الإصدار أقل من 3.10: ثبّت 3.10+ ثم أعد بناء venv باستخدامه (venv القديم مرتبط بالمفسّر القديم، ويجب إعادة بنائه):
python3.10 -m venv .venv # 或你装好的更高版本
.venv/bin/pip install typesafe-sdkينبغي أن ترى: يطبع .venv/bin/python --version Python 3.10 أو أحدث.
"zstd compression requires Python 3.14+ or the typesafe-sdk[zstd] extra."
السبب: لقد مرّرت صراحةً compression='zstd'، لكن عند Python < 3.14 يكون دعم zstd في الحزمة الإضافية الاختيارية، ولا تتضمنها التثبيتات الافتراضية.
الحل (خياران):
الخيار 1 (تثبيت الحزمة الإضافية، موصى به):
.venv/bin/pip install "typesafe-sdk[zstd]"الخيار 2 (تعطيل الضغط):
client = TypeSafeClient(compression=False)⚠️ الضغط مفعّل افتراضيًا في v0.7.5
اعتبارًا من v0.7.5 يضغط الـ SDK افتراضيًا بـ zstd أجسام الطلبات التي تبلغ ≥1 KiB (بحسب سجل التغييرات الرسمي: قد لا تدعم واجهات API غير الرسمية ذلك فورًا). الأمر الرسمي لـ «ضمان توفر zstd» هو uv add "typesafe-sdk[zstd]". في الاختبار الفعلي، التثبيت الافتراضي (بدون الحزمة الإضافية) لا يرمي خطأً عند إنشاء الكائن — يُستخدم الضغط إن كان متاحًا، وإذا لم يكن فلا ضغط، ولا يُرمى هذا الخطأ إلا عند طلب zstd صراحةً.
"ImportError: Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using pip install httpx[socks]."
السبب: البيئة مهيأة بوكيل SOCKS (متغيرات بيئة الوكيل)، وتحتاج طبقة HTTP في الـ SDK (httpx2) إلى الحزمة socksio لاستخدام SOCKS، ولا تتضمنها التثبيتات الافتراضية — فيُرمى هذا الخطأ عند إنشاء العميل ولا يُرسل الطلب.
الحل: قم بتثبيت socksio ثم أعد إنشاء العميل:
.venv/bin/pip install socksioيجب أن ترى: إنشاء العميل بنجاح (اختبار فعلي: بعد تثبيت socksio، وبنفس إعداد وكيل SOCKS، تم إنشاء العميل بشكل طبيعي). الاقتراح pip install httpx[socks] في رسالة الخطأ هو تلميح عام لعائلة httpx؛ يستخدم SDK مكتبة httpx2، لذا يكفي تثبيت socksio مباشرة.
فشل تثبيت pip / عدم العثور على الحزمة (مشاكل الشبكة)
السبب: لا توفر الوثائق الرسمية حلًا مخصصًا لفشل تثبيت TypeSafe؛ الحالة الشائعة هي عدم الاتصال بمستودع PyPI المصدر، أو خطأ إملائي في اسم الحزمة أدى إلى تثبيت حزمة أخرى (انظر أعلاه).
الحل:
- استبعد أولًا مشكلة اسم الحزمة: الأمر الصحيح هو
pip install typesafe-sdk، وعند التثبيت الصحيح يحتوي الناتج علىSuccessfully installed ... typesafe-sdk-0.7.5. - عالج مشكلة الشبكة حسب بيئتك (الوكيل ومستودعات المرايا معرفة عامة بـ pip، ولم تقدم الوثائق الرسمية حلًا مخصصًا لـ TypeSafe).
- مع Python أقدم من 3.10 قد يرفض pip التثبيت مباشرة (الحد الأدنى الرسمي 3.10)، فأصلح الإصدار أولًا حسب النقطة السابقة.
مشاكل المصادقة والمفاتيح
"No API key was provided. Pass api_key or set the TYPESAFE_API_KEY environment variable."
السبب: لم يتم تمرير المعامل api_key ولم يتم ضبط متغير البيئة أيضًا — اعترض SDK عند إنشاء العميل مباشرة. ملاحظة: تمرير مفتاح فارغ صراحةً لا يجعله يرجع إلى متغير البيئة، فـ api_key='' يعادل عدم تمريره.
الحل:
- حل متغير البيئة (التوصية الرسمية، بدون كتابة المفتاح في الكود):
export TYPESAFE_API_KEY="your-api-key"- أو تمرير المعامل صراحةً في الكود:
from typesafe_sdk import TypeSafeClient
client = TypeSafeClient(api_key="your-api-key")يجب أن ترى: إنشاء العميل بنجاح، دون رفع TypeSafeError بعد الآن.
"Cannot authenticate with the server. Please check your API key and try again."
السبب: HTTP 401 — وصل الطلب إلى الخادم لكن المفتاح غير صالح. يرفع SDK استثناء TypeSafeAuthenticationError (str(e) يأتي بصيغة POST https://api.typesafe.ai/v1/systemone: 401 Cannot authenticate... (request_id=req_...)).
الحل:
- ارجع إلى صفحة Keys في لوحة التحكم وأعد نسخ المفتاح مرة أخرى (النسخ اليدوي عرضة للأخطاء).
- أعد الضبط وتحقق:
export TYPESAFE_API_KEY="<重新复制的Key>"
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
-H "Authorization: Bearer $TYPESAFE_API_KEY"يجب أن ترى: يعيد الأمر 200 و JSON ({"models":[...]}، يسرد النماذج والأسماء البديلة المتاحة لحسابك).
"Must supply an API key! Check your request and try again."
السبب: عند الاتصال المباشر عبر HTTP (curl / fetch) لم يُرفق إطلاقًا ترويسة Authorization — رفضت واجهة API الطلب مباشرة وأعادت 403 (اختبار فعلي: طلب /v1/models دون أي ترويسة مصادقة أعاد 403 وهذه الرسالة؛ جدول رموز الحالة الرسمي لا يذكر 403، وفئة الاستثناء المقابلة في جانب SDK هي TypeSafePermissionDeniedError). لا يواجه مستخدمو SDK هذا عادةً: عند ضبط المفتاح بشكل صحيح يرفع SDK الترويسة تلقائيًا.
الحل: أرسل الطلب مع ترويسة مصادقة Bearer:
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
-H "Authorization: Bearer $TYPESAFE_API_KEY"يجب أن ترى: إذا كان المفتاح صالحًا يعيد 200 و {"models":[...]}؛ وإذا كان غير صالح يتحول إلى 401 (انظر النقطة السابقة).
"API key must contain only printable ASCII characters without whitespace."
السبب: يحتوي المفتاح على مسافات داخلية أو محارف تحكم أو محارف غير ASCII (يزيل SDK فقط المسافات في البداية والنهاية، أما المحارف المشكلة في الداخل فيرفضها مباشرة).
الحل: أعد نسخ المفتاح كاملًا من جديد، دون تجميع أو تعديل يدوي. انتبه عند اللصق ألا يتخلل سطر جديد منتصفه.
رفض نص الطلب (400 / 413 / 415 / 422)
"422 Unprocessable Entity"
السبب: فشل التحقق من حقول نص الطلب — مثلًا نقص state أو تنسيق حقل خاطئ. اجتاز الطلب التحقق المحلي لـ SDK وأُرسل إلى الخادم، فأعاد الخادم 422؛ يشير متن الاستجابة إلى الحقل: loc هو الموضع، و msg هو السبب (مثل Field required).
الحل:
- التقط
TypeSafeAPIErrorفي الكود واطبع المتن الكامل لرؤية الحقل (المشكلة في المثال تحملinstructions، فتجتاز التحقق المحلي وتصل فعلًا إلى الخادم):
from typesafe_sdk import Noul, TypeSafeClient, TypeSafeAPIError
with TypeSafeClient() as client:
try:
client.system_one("I was charged twice.", {
"billing": Noul(instructions="Is this about billing?")
})
except TypeSafeAPIError as error:
print(error.status) # 服务器返回的状态码;422 = 字段校验失败
print(error.body) # 422 时里边 loc/msg 指明哪个字段
print(error.request_id) # 反馈给官方时带上- أكمل الحقل الذي أشار إليه
locثم أعد الإرسال.
يجب أن ترى: عند صحة الطلب يعيد النتيجة بشكل طبيعي؛ وإذا أعاد الخادم 422، يحتوي error.body على تلميحات على مستوى الحقول بصيغة loc: ["body", "state"] و msg: "Field required" (مثال OpenAPI الرسمي). الشكل الفعلي لظهور 422 من جانب الخادم يعتمد على القاعدة التي خالفها الطلب، والمرجع هو ما يعيده المتن فعليًا.
💡 كثير من 422 لا يصل إلى الخادم أصلًا
عند إنشاء Noul() دون كتابة instructions، يرفع SDK محليًا TypeSafeError: Noul question "q2" has neither instructions nor criteria; at least one is required.؛ ونقص criteria في أسئلة Score/Choice يُحظر محليًا كذلك: TypeSafeError: Question "broken" requires "criteria". (broken هو اسم مفتاح سؤالك أنت). ما يُرفع هنا من الفئة الأساسية TypeSafeError وليس TypeSafeAPIError — يكفي تعديل الكود، ولا داعي للشك في الشبكة.
"413 Payload Too Large"
السبب: تجاوز نص الطلب 32 MiB (الترويسات لا تُحتسب)؛ يسري هذا الحد على المضغوط وغير المضغوط معًا.
الحل: قلّص state، أو قسّم المواد الكبيرة إلى عدة طلبات.
"415 Unsupported Media Type"
السبب: استخدام ترميز غير مدعوم في Content-Encoding، أو تكديس أكثر من طبقة ضغط (gzip / x-gzip / zstd طبقة واحدة فقط لكل منها).
الحل: عند الاتصال المباشر عبر HTTP استخدم طبقة ضغط واحدة فقط؛ مستخدمو SDK لا يواجهون هذا عادةً (يتعامل SDK مع الضغط بنفسه).
"max_tokens_exceeded"
السبب: تجاوز الطلب حد السياق للنموذج — 64k لكل طلب (state + جميع الأسئلة) / 32k لكل سؤال (state + سؤال واحد)، وكلاهما يشمل state.
الحل (ثلاثة خيارات، من الأقل إلى الأعلى تكلفة):
الخيار 1 (تقليص المواد، موصى به): رشّح state وأرسل الحقول التي يحتاجها السؤال فقط — يوفر المال ويرفع الدقة معًا.
الخيار 2 (السياق الطويل): أضف ترويسة الطلب للطلبات التي تحتاجها (يصبح كلا السياقين 262k، وأبطأ وأقل دقة، والسعر دون تغيير):
-H "TypeSafe-Danger-Zone-Long-Context: true"الخيار 3 (تقليل عدد الأسئلة أو تقسيم الطلبات): حد per-request يشمل جميع الأسئلة، فإذا كانت الأسئلة كثيرة قسّمها أولًا.
تقييد المعدل ومشاكل جانب الخادم
"429 Too Many Requests"
السبب: تم تجاوز حد المعدل على مستوى المؤسسة (مؤشران: tokens/s + requests/s، يُحسب لكل مؤسسة).
الحل:
- استخدم SDK (يأتي افتراضيًا بإعادة محاولة مع تراجع أُسّي، ويحترم
retry-after) — لا تحتاج إلى فعل أي شيء:
from typesafe_sdk import RetryPolicy, TypeSafeClient
# 默认就是自动重试;按需自定义(默认 max_retries=2、退避 0.5→5s、总预算 30s)
client = TypeSafeClient(retry=RetryPolicy(max_retries=3))- الاتصال المباشر عبر HTTP هو وحده ما يتطلب كتابة تراجع أُسّي بنفسك، فلا تُعِد إرسال الطلب كما هو فورًا.
- تُفحص الحصص في صفحة rate-limits في وحدة التحكم؛ وإذا احتجت حدًا أعلى فاتبع مسار custom/enterprise (نموذج الطلب support.typesafe.ai/forms/rate-limit-increase-request).
"529 Overloaded"
السبب: TypeSafe يعاني من حمل زائد مؤقت، وهو من فئة «انتظر قليلًا ثم أعد المحاولة» مثل 429.
الحل: مثل 429 — يقوم SDK تلقائيًا بإعادة المحاولة مع التراجع؛ وعند الاتصال المباشر اكتب التراجع بنفسك. وإذا تكرر ظهوره فاذهب إلى Discord أو صفحة الحالة لمعرفة ما إذا كان هناك عطل واسع النطاق.
مشكلات متعلقة بـ Agent Skill
"The agent isn't using the skill"
السبب: لم يقم coding agent بتحميل TypeSafe skill — لم يُستدعَ بالاسم، أو ثُبّت على agent خاطئ، أو لم يُعاد تشغيله بعد التثبيت.
الحل (الخطوات الثلاث الرسمية في docs/agent-skill.md):
- في Claude Code استدعِ
/typesafe:typesafe-aiمباشرة من الإضافة؛ أما بقية الـ agents فاذكر"use the TypeSafe skill"بالاسم في الـ prompt. - إذا لم ينجح ذلك: تأكد أنك اخترت أثناء التثبيت الـ agent الذي تستخدمه فعلًا (
npx skills addيثبّت على مستوى المشروع افتراضيًا، وللتثبيت على المستوى العام أضف-g). - أعد تشغيل الـ agent ثم جرّب مجددًا.
"The agent invents request or response fields"
السبب: نسخة الـ skill قديمة، وما يعلّمها إياه هو الواجهة القديمة.
الحل: حدّث الـ skill ثم أعد المحاولة (Claude Code):
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-aiثم أعد تشغيل Claude Code أو شغّل /reload-plugins.
ما زال لا يعمل؟
اجمع الأدلة قبل طرح السؤال. مقطع كود أدنى قابل لإعادة الإنتاج + نص رسالة الخطأ الأصلية + request_id أنفع من مئة جملة وصف:
# catch_report.py:复现问题并打印关键信息
from typesafe_sdk import Noul, TypeSafeClient, TypeSafeAPIError
with TypeSafeClient() as client:
try:
client.system_one("I was charged twice.", {
"billing": Noul(instructions="Is this about billing?")
})
except TypeSafeAPIError as error:
print("status:", error.status)
print("body:", error.body)
print("endpoint:", error.endpoint)
print("request_id:", error.request_id) # 提问必带
except Exception as error: # 本地拦截(Key/问题定义),没到服务器
print(type(error).__name__, str(error))عند الحاجة إلى سجلات أكثر تفصيلًا، ارفع مستوى سجلات SDK (تُخفَّى ترويسات المصادقة، لكن لا تُخفى أجساد الطلبات/الاستجابات — احرص على عدم نشر محتوى حساس في أماكن عامة):
export TYPESAFE_LOG_LEVEL=debugإلى أين تذهب لتسأل:
| القناة | متى تذهب |
|---|---|
| صفحة Keys / rate-limits في وحدة التحكم | مشكلات Key والحصص، افحصها بنفسك أولًا |
| وثائق الأخطاء الرسمية | دلالات رموز الحالة وتفاصيل القواعد |
| مرجع API السريع | هذا الموقع: مرجع سريع للطلبات/الاستجابات/رموز الحالة |
| GitHub Issues | عيوب SDK (مستودع Python SDK) |
| مجتمع Discord | تقول الجهة الرسمية «Tell us what you build, and what breaks» — إذا تعطل شيء فأبلغ عنه مباشرة |
نقاط التحقق ✅
- 60 ثانية/فحص سريع: لقد شغّلت الأوامر الثلاثة وأعرف عند أي مرحلة أعلقت
- أستطيع التمييز بين
TypeSafeErrorالمحلي الاعتراض (Key، تعريف المشكلة) وTypeSafeAPIErrorالعائد من الخادم - عند 401 أعود إلى وحدة التحكم لإعادة نسخ الـ Key، ثم أتحقق باستخدام curl
/v1/models - عند 429/529 أعرف أن SDK يعيد المحاولة تلقائيًا مع التراجع افتراضيًا، فلا أحتاج لكتابته بنفسي
- عند طرح الأسئلة أرفق كودًا أدنى لإعادة الإنتاج مع
request_id
الأسئلة الشائعة
Jev كيفية تعيين مفتاح الواجهة البرمجية (API Key)
التوصية الرسمية هي استخدام متغيرات البيئة وعدم كتابة المفتاح في الكود: export TYPESAFE_API_KEY="your-api-key"، ولاحظ أنه يجب إعادة تنفيذ export عند فتح طرفية جديدة. يمكن أيضًا تمرير المعلمة صراحةً في الكود: TypeSafeClient(api_key="your-api-key"). لاحظ أن تمرير مفتاح فارغ صراحةً لا يجعله يرجع إلى متغير البيئة، فـ api_key='' يعادل عدم تمريره — راجع قسم «مشاكل المصادقة والمفتاح» أعلاه.
تم تعيين المفتاح لكنه ما زال 401 فماذا أفعل؟
401 يعني أن الطلب وصل إلى الخادم لكن المفتاح غير صالح. ارجع إلى صفحة Keys في وحدة التحكم وانسخ المفتاح كاملًا مرة أخرى (النسخ اليدوي عرضة للأخطاء، ولا يمكن أن يحتوي المفتاح على مسافات داخلية أو أحرف غير ASCII)، وبعد إعادة تعيينه تحقق بطلب curl إلى /v1/models؛ إذا كانت الاستجابة 200 فذلك يعني أن المفتاح صالح.
أين الوثائق الرسمية لـ TypeSafe AI؟
للاطلاع على دلالات رموز الحالة وتفاصيل القواعد، راجع وثائق الأخطاء الرسمية docs.typesafe.ai/api/errors.md. للمشكلات المتعلقة بالمفتاح والحصة، تحقق أولاً بنفسك عبر وحدة التحكم، ولعيوب SDK قدّمها في GitHub Issues، وإذا تعطل كل شيء يمكنك الإبلاغ مباشرة عبر Discord.
خلاصة الدرس
✅ في استكشاف الأخطاء حدّد المرحلة أولًا: البيئة (Python/الحزم) → المصادقة (Key) → جسم الطلب (القواعد) → الخادم (تحديد المعدل/الحمل الزائد).
✅ مررنا بأخطاء TypeSafe الرئيسية: ModuleNotFoundError استخدم المفسّر الصحيح، 401 أعد نسخ الـ Key، 422 انظر إلى حقل loc، 429/529 اتركها لإعادة المحاولة الافتراضية في SDK.
✅ طريقة طرح الأسئلة: إعادة إنتاج أدنى + نص الخطأ الأصلي + request_id، واذهب إلى Discord أو GitHub Issues.
مراجعة الحقائق الرئيسية:
| الإشارة | في أي طبقة | الخطوة الأولى |
|---|---|---|
ModuleNotFoundError | البيئة | التشغيل باستخدام .venv/bin/python |
ImportError: cannot import name 'TypeSafeClient' from 'typesafe' | البيئة (حزمة مثبتة خطأ) | أزِل typesafe وثبّت typesafe-sdk |
إنشاء العميل يرمي TypeSafeError | المصادقة (محلي) | أضِف TYPESAFE_API_KEY |
401 + TypeSafeAuthenticationError | المصادقة (الخادم) | عُد إلى وحدة التحكم وأعد نسخ الـ Key |
422 | جسم الطلب | انظر إلى loc/msg في الـ body |
429 / 529 | الخادم | اتركها لإعادة محاولة SDK؛ وعند الاتصال المباشر اكتب التراجع |
استعراض الدرس التالي
بهذا ينتهي استكشاف أخطاء البداية — بيئتك أصبحت مستقرة. الخطوة التالية هي الدخول إلى الاستخدام اليومي: إتقان الطرق الخمس لطرح الأسئلة على Jev.
ستتعلم:
- حالة State: ما المواد التي تعطيها لـ Jev
- كيف تختار بين أنواع الأسئلة الثلاثة Choice / Score / Noul
- كيف تستخدم Confidence (الثقة) مع عتبة لاتخاذ مسارات مختلفة
- كيف تُرسل الصور داخل الطلب