قم بتشغيل اختبار curl هذا أولاً
قبل تغيير الكود، أزل تطبيقك من المعادلة. هذا الأمر الواحد يرسل الطلب الصحيح الأدنى إلى الـ API:
curl -i https://api.unrestrictedaiapi.com/v1/models \
-H "Authorization: Bearer YOUR_KEY"
GET /v1/models لا يكلف شيئاً، لذا فهو طريقة آمنة لاختبار المفتاح. العلم -i يطبع سطر الحالة والرؤوس.
- 200 وقائمة بالنماذج: المفتاح سليم. تطبيقك يرسل شيئاً مختلفاً، لذا انتقل إلى الأقسام الخاصة بمتغيرات البيئة وعنوان الأساس.
- 401: المفتاح أو الرأس غير صحيح. انتقل إلى القسم التالي.
- خطأ في الاتصال أو DNS: عنوان الأساس غير صحيح، وهو مشكلة مختلفة عن 401.
الصق المفتاح يدوياً في هذا الاختبار، وليس عبر متغير. بذلك تستبعد البيئة من قائمة المشتبه بهم.
السبب 1: الرأس غير صحيح تماماً
يتوقع الـ API Authorization: Bearer <key>. الانحرافات الصغيرة كلها تنتج خطأ 401 في الـ API:
Authorization: YOUR_KEYمع كلمة Bearer مفقودة.Authorization: Bearer: YOUR_KEYمع نقطتين رأسيتين (:) زائدتين.Authorization: Bearer "YOUR_KEY"مع علامات اقتباس داخل القيمة.Authorization: Bearer YOUR_KEYمع مسافتين.- رأس باسم
X-API-Keyأوapi-keyبدلاً منAuthorization. هذه اتفاقيات خاصة بخدمات أخرى.
إذا كنت تستخدم SDK الخاص بـ OpenAI، فإنك لا تكتب الرأس بنفسك. يبنيه الـ SDK من وسيط api_key. إذا رأيت 401 على أي حال، فإن القيمة المُمررة إلى الـ SDK هي المشكلة، وليس تنسيق الرأس.
السبب 2: المفتاح نفسه تالف
المفاتيح سلاسل عشوائية طويلة، لذا فإن أخطاء النسخ شائعة وصعبة الملاحظة بالعين المجردة.
- سطر جديد أو مسافة في النهاية. النسخ من طرفية الأوامر أو ملف نصي غالباً ما يضيف أحدهما. العديد من مكتبات HTTP ترسل بعد ذلك رأساً غير صالح أو مفتاحاً لا يتطابق.
- مفتاح مقطوع. النقر المزدوج يحدد جزءاً فقط من السلسلة إذا كان المفتاح يحتوي على أحرف تكسر تحديد الكلمات. استخدم زر النسخ في صفحة مفتاح API بدلاً من ذلك.
- علامات الاقتباس المنحنية. يمكن أن يؤدي اللصق عبر معالج كلمات أو تطبيق دردشة إلى استبدال علامات الاقتباس المستقيمة بعلامات منحنية.
- مفتاح قديم أو مُستبدل. إذا أنشأت مفتاحاً جديداً، فقد لا يكون المفتاح القديم هو الذي تستخدمه.
للتحقق من وجود أحرف غير مرئية في Python، اطبع تمثيل repr للقيمة:
import os
key = os.environ.get("API_KEY", "")
print(repr(key), len(key))
print(repr(key.strip()) == repr(key))
إذا طُبعت السطر الثاني بقيمة False، فهذا يعني وجود مسافات بيضاء حول المفتاح. استدعِ .strip() عند قراءته.
السبب 3: عنوان URL الأساسي الخاطئ
هذا هو الخطأ الأكثر شيوعًا عند تحويل تطبيق قائم إلى مزود جديد. مفتاحك صالح فقط على المضيف الذي أصدره. عنوان URL الأساسي لهذا الموقع هو:
{"base_url": "https://api.unrestrictedaiapi.com/v1"}
تظهر أنماط فشل متكررة مرارًا وتكرارًا:
- قمت بتعيين المفتاح الجديد لكنك تركت عنوان URL الأساسي القديم. يذهب الطلب إلى المزود القديم، الذي يرفض مفتاحًا لم يره من قبل ويعيد رمز 401. ثم يذكر نص الخطأ المزود القديم، وهو تلميح مفيد.
- قمت بتعيين عنوان URL الأساسي الجديد لكنك تركت مفتاحًا قديمًا في البيئة. يصل الطلب إلينا، ونرفض مفتاح المزود الآخر.
تحقق أيضًا من المسار. عنوان URL الأساسي ينتهي بالفعل بـ /v1، لذا تضيف مكتبات الـ SDK /chat/completions إليه. إذا قمت ببناء عنوان URL يدويًا، فإن المسار الكامل هو /v1/chat/completions، وليس /v1/v1/chat/completions.
السبب 4: متغيرات البيئة وملفات التكوين
إذا نجح curl لكن تطبيقك يفشل، فهذا يعني أن شيئًا ما يغذي التطبيق بمفتاح مختلف عما تعتقد.
- المتغير غير مُصدَّر. في وحدة التحكم (shell)، يعمل
API_KEY=abc python app.py، لكنAPI_KEY=abcفي سطر منفرد لا يصل إلى العمليات الفرعية. استخدمexport. - مُغطى بقيمة أخرى. يمكن لمكتبات الـ SDK قراءة
OPENAI_API_KEYتلقائيًا. إذا كان مفتاح قديم مُعدلاً في ملف تعريف وحدة التحكم الخاصة بك، فقد يتجاوز ما قصدته. - علامات الاقتباس في ملف .env. تحتفظ بعض أدوات التحميل بعلامات الاقتباس كجزء من القيمة. إذا وصل المفتاح مغلفاً بعلامات اقتباس، احذفها أو اختبره باستخدام فحص repr المذكور أعلاه.
- لم يتم إعادة التشغيل. تقرأ الخوادم والمذكرة (notebooks) متغيرات البيئة عند بدء التشغيل. أعد التشغيل بعد التعديل.
- بيئة مختلفة في الإنتاج. الحاويات (Containers)، والدمج المستمر (CI)، ولوحات التحكم للاستضافة تحتوي كل منها على مخزن متغيرات خاص بها. اطبع طول المفتاح، وليس المفتاح نفسه، في السجلات.
فحص Python بسيط يثبت صحة التكوين
يستخدم هذا النص البرمجي مكتبة OpenAI SDK ويبلغ بوضوح إذا فشل المصادقة:
import os
from openai import OpenAI, AuthenticationError
client = OpenAI(
base_url="https://api.unrestrictedaiapi.com/v1",
api_key=os.environ["API_KEY"].strip(),
)
try:
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Reply with the word ok."}],
max_tokens=5,
)
print("auth ok:", r.choices[0].message.content)
except AuthenticationError as e:
print("401:", e.status_code, e.response.headers.get("X-Request-Id"))
إذا طُبعت قيمة X-Request-Id، فقم بتضمينها عند الكتابة إلى الدعم، لأنها تتيح للفريق العثور على طلبك. نفس الفحص بلغات أخرى موجود في البدء السريع بخمس لغات.
خطأ 401 مقابل أخطاء أخرى
لا تقضِ وقتًا في المصادقة إذا كان الخطأ شيئًا آخر. خريطة موجزة:
| الرمز | المعنى المعتاد | أين تبحث |
|---|---|---|
| 401 | مفتاح مفقود أو غير صالح | رأس الطلب (Header)، المفتاح، عنوان URL الأساسي |
| 429 | حدّ المعدل أو الحمل الزائد المؤقت | تراجع وحاول مرة أخرى؛ انظر إلى المستندات لمعرفة الحدود |
| 400 | جسم الطلب غير صالح | JSON، اسم النموذج، المعاملات |
| 404 | المسار خاطئ | عنوان URL الأساسي ونقطة النهاية |
تحقق أيضًا من اسم النموذج. استخدم uncensored بالضبط؛ فإن معرف النموذج الخاطئ هو خطأ في الطلب وليس خطأ 401. تفاصيل الـ API، بما في ذلك نقاط النهاية والعناوين التي يقبلها الـ API، موجودة في صفحة مواصفات الـ API المتوافقة مع OpenAI.
الوكلاء، المتصفحات، والحلول الأخيرة
إعدادان يسببان أخطاء 401 تبدو غامضة.
الوكلاء والبوابات
قد يقوم الوكيل العكسي، أو بوابة API، أو غلاف بدون خادم بين تطبيقك وAPI بإسقاط أو إعادة كتابة رأس Authorization. اختبر من نفس الجهاز باستخدام curl وقارن. بعض الأطر تعمل أيضاً على تمرير الرأس فقط إلى المضيفين من نفس الأصل، لذا يمكن أن يفقد غلاف fetch المخصص هذا الرأس بصمت في استدعاء عبر أصل مختلف.
المفاتيح في كود الواجهة الأمامية
استدعاء الـ API مباشرةً من JavaScript في المتصفح يعرض المفتاح لأي شخص يفتح أدوات المطور، وقد يحظر المتصفح أيضًا الطلب لأسباب تتعلق بالأصل المختلف تبدو كأخطاء مصادقة. احتفظ بالمفتاح على خادم، واسمح للواجهة الأمامية باستدعاء نقطة النهاية الخاصة بك، والتي بدورها تستدعي الـ API مع إرفاق المفتاح. إذا تم لصق مفتاح في كود عام أو لقطة شاشة، فاستبدله.
ما زلت عالقاً
إذا عاد المفتاح المنسوخ حديثاً بخطأ 401 في اختبار curl، فقم بتوليد المفتاح مرة أخرى من صفحة مفاتيح API، والصقه مباشرة في الأمر، وحاول مرة أخرى. إذا فشل ذلك، أرسل للدعم وقت الطلب، نقطة النهاية، ورأس الاستجابة X-Request-Id. لا ترسل المفتاح الكامل في رسالة؛ فالأحرف الأربعة الأولى والأربعة الأخيرة كافية لتحديده.
