---
title: "واجهة برمجة تطبيقات مهلوسة"
type: "ai-smell"
slug: "hallucinated-api"
url: "http://localhost:3000/ar/ai-smells/hallucinated-api.md"
category: "الصحة"
description: "الكود البرمجي المولد بالذكاء الاصطناعي الذي يستدعي دوالاً أو أساليب أو معاملات أو مفاتيح إعداد أو حزم تبدو معقولة ولكنها غير موجودة في الإصدار الفعلي للمكتبة التي تعتمد عليها."
---
# واجهة برمجة تطبيقات مهلوسة

> الكود البرمجي المولد بالذكاء الاصطناعي الذي يستدعي دوالاً أو أساليب أو معاملات أو مفاتيح إعداد أو حزم تبدو معقولة ولكنها غير موجودة في الإصدار الفعلي للمكتبة التي تعتمد عليها.

## Signs and Symptoms

يكتشف المراجع واجهة برمجة تطبيقات مهلوسة عندما يقرأ الكود بسلاسة ويبدو وكأنه استخدام نموذجي للمكتبة، ومع ذلك لا يمكن العثور على الاستدعاء أو الخيار أو الاستيراد المحدد في الواجهة الحقيقية لتلك المكتبة. العلامات المميزة:

* أسلوب أو خيار يكون اسمه _مريحاً ومناسباً جداً_ — يقوم بالضبط بما طلبته في نص التوجيه، مع اسم يدمج بين واجهتي برمجة تطبيقات حقيقيتين (مثل `findLastWhere`، و `includesAll`، و `parseDateSafe`).
* اختراع **معاملات** في دالة حقيقية (المتغير الخطير — غالباً ما يجمع الكود بنجاح ويفشل فقط في وقت التشغيل، أو يتجاهل الخيار بصمت).
* استيراد (`import`) حزمة غير موجودة في `package.json` / `requirements.txt`، أو استيراد مسمى لا تصدره الوحدة البرمجية أبداً.
* أشكال واجهة برمجة تطبيقات تخلط بين الإصدارات: كاستدعاء توقيع الإصدار v2 على عميل من الإصدار v5، أو أسلوب تم حذفه أو تغيير اسمه منذ عدة إصدارات.
* تعليقات مدمجة واثقة تؤكد أن الاستدعاء صحيح (مثل "// تعيد الرسوم المستردة").

```js
// مولد بالذكاء الاصطناعي — سلس، ومعقول، وخاطئ
import { formatRelative } from 'date-fns';

// roundingMethod مخترع — لا توفر date-fns مثل هذا الخيار، ويتم تجاهله بصمت
const label = formatRelative(date, new Date(), { roundingMethod: 'floor' });

// findLastWhere غير موجود في المصفوفة (Array) — خطأ نوع في وقت التشغيل (TypeError)
const lastActive = items.findLastWhere(i => i.active);

// استدعاء SDK مختلط: الشكل الحقيقي لـ Stripe هو stripe.refunds.create({ charge })
await stripe.charges.refund(chargeId, { amount: 500 });

```

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

## Reasons for the Problem

**لماذا تنتجها النماذج؟**

* **معقولية الرمز التالي، وليس البحث الحقيقي.** يتنبأ نموذج اللغة الكبيرة بالتكملة الأكثر احتمالاً إحصائياً، والتي تعتبر عملياً _متوسط_ كل واجهة برمجة تطبيقات مشابهة رآها. هذا المتوسط هو غالباً أسلوب _ينبغي_ أن يكون موجوداً — فيصدر النموذج "الاسم الأكثر ملاءمة وسهولة" بدلاً من الاسم الحقيقي. تجد دراسات ترشيح واجهات برمجة التطبيقات أن **58.1% - 84.1% من واجهات برمجة التطبيقات المقترحة غير موجودة في الحزمة المحددة**، والخطأ السائد هو أسماء أساليب غير موجودة ([arXiv 2404.00971](https://arxiv.org/pdf/2404.00971)، [ACM TOSEM 2025](https://dl.acm.org/doi/pdf/10.1145/3728894)).
* **خلط الإصدارات.** تخلط مجموعات بيانات التدريب بين إصدارات متعددة لمكتبة ما، وبالتالي يدمج النموذج توقيعات الإصدار v2 والإصدار v5 في توقيع واحد لا يطابق أياً منهما. هذه "الهلوسات المتعارضة مع المعرفة الحقيقية" (مثل المعاملات غير الموجودة) هي على وجه الخصوص النوع الذي **يفلت من أدوات الفحص (linters) ويفشل في وقت التشغيل**.
* **تاريخ انتهاء التدريب (Training-cutoff staleness).** يستخدم النموذج بثقة واجهات برمجة تطبيقات تم تغيير اسمها أو إهمالها أو إزالتها منذ تاريخ انتهاء تدريبه، ويلجأ إلى ما ظهر أكثر في مجموعة البيانات — وهو ما تشير Ox Security إلى أنه يعني **التوصية بإصدارات حزم أقدم، وربما تكون ضعيفة أمنياً** ([OX report, Oct 2025](https://www.ox.security/blog/ai-code-security-common-threats-and-best-practices-for-securing-ai-generated-code/)).
* **غياب سياق المستودع/التبعية.** بدون ملف `package.json` أو المصدر الفعلي للموديول، يبتكر النموذج دوالاً مساعدة "يشعر" أنها تنتمي إلى تقنياتك البرمجية.
* **التملق / التلهف للإجابة.** نادراً ما يقول المساعد "لست متأكداً من وجود هذا الأسلوب" — بل ينتج كوداً واثقاً يبدو قابلاً للتشغيل، مما يقلل من شكوك المراجعين.
* **الحتمية تجعل الهلوسة قابلة للاستغلال.** هلوسة الحزم ليست ضوضاء عشوائية: عبر 16 نموذجاً و2.23 مليون عملية توليد كود، تبين أن **19.7% من الحزم الموصى بها كانت خيالية (205,474 اسماً فريداً)، وتكررت 58% من الهلوسات خلال 10 محاولات توجيه** ([USENIX Security 2025; SecurityWeek summary](https://www.securityweek.com/ai-hallucinations-create-a-new-software-supply-chain-threat/)).

**لماذا يسبب ضرراً؟**

* **الصحة.** المعاملات المخترعة والخيارات المتجاهلة بصمت تنتج سلوكاً خاطئاً في مسارات كود نادراً ما تغطيها الاختبارات؛ ويظهر الفشل في الإنتاج الفعلي، وليس في وقت التجميع.
* **الأمان / سلسلة التوريد.** اسم الحزمة المهلوس هو هدف جاهز للتسجيل: ينشر المهاجمون برمجيات خبيثة تحت الاسم المتوقع، وبالتالي فإن المطور التالي الذي يقبل اقتراح الذكاء الاصطناعي سيقوم بتثبيت برمجيات خبيثة — وهو ما يُعرف بهجوم **slopsquatting** (مصطلح صاغه سيث لارسون من مؤسسة بايثون). يعيد متغير التقادم تقديم واجهات برمجة تطبيقات مهملة أو تحتوي على ثغرات أمنية (CVEs) بصمت.
* **عبء المراجعة.** يلقي الكود الذي يبدو معقولاً بعبء التحقق من كل استدعاء غير مألوف مقابل الوثائق الرسمية على عاتق المراجعين؛ والأسلوب السلس في الكتابة يقلل من احتمالية إجراء هذا التحقق.
* **تراكم الديون التقنية.** غالباً ما يقوم المطورون بلصق الكود المهلوس "شبه الجاهز" ويرقعون حوله بدلاً من إصلاح الاستدعاء الجذري — مما يغذي الاتجاه الأوسع في عصر الذكاء الاصطناعي المتمثل في ارتفاع النسخ/اللصق وانخفاض إعادة الهيكلة ([GitClear 2025: الكتل المكررة ارتفعت بنحو 8 أضعاف، والسطور المنقولة بفعل إعادة الهيكلة انخفضت من 25% إلى أقل من 10%](https://www.gitclear.com/ai%5Fassistant%5Fcode%5Fquality%5F2025%5Fresearch)). هذا النمط مصنف الآن ضمن روائح الكود الخاصة بالذكاء الاصطناعي ([arXiv 2509.20491](https://arxiv.org/abs/2509.20491)).

## Treatment

**تكتيكات المراجعة وصياغة سير العمل**

* **ربط النموذج بالواجهات الحقيقية.** الصق ملفات تعريف الأنواع الفعلية، أو صفحة الوثائق ذات الصلة، أو كود المصدر للإصدار المثبت في سياق النموذج، أو استخدم أداة استرجاع الوثائق (من نوع Context7 أو RAG). أخبر النموذج بالإصدارات _الدقيقة_ للتبعيات من ملف القفل الخاص بك.
* **اطلب استشهادات وتوثيقاً.** اطلب من النموذج تسمية الوثيقة الرسمية أو توقيع النوع لكل استدعاء لجهة خارجية يستخدمه. قاعدة ذهبية للممارسين: _يجب تتبع كل استدعاء أسلوب لمكتبة خارجية والرجوع لوثائقه الرسمية قبل الموافقة على طلب السحب (PR)._
* **اجعله يشغل الكود في حلقة التقييم.** اطلب نجاح تشغيل `tsc` / `mypy` / `pylint` / عملية بناء الكود ومجموعة الاختبارات، واطلب من الوكيل البرمجي تنفيذ `npm install` / `pip install` فعلياً حتى تفشل الحزم المهلوسة سريعاً قبل أن تصل إلى مرحلة المراجعة.
* **اطلب منه إعادة الاستخدام، وليس الاختراع.** قدم له نتائج `grep` للموديلات الحالية ووجهه لاستدعاء الدوال المساعدة المتوفرة (مثل `أعد استخدام الدوال المساعدة في utils/http.ts`) بدلاً من استحضار دوال جديدة — وهذا يواجه أيضاً رائحة تكرار _الدوال المساعدة المعاد اختراعها_.
* **بوابة القيود على التبعيات.** استخدم ملف القفل + قائمة سماح للتثبيت وماسحاً أمنياً لسلسلة التوريد (Socket/Snyk) قبل إضافة أي حزمة جديدة، حتى لا تتسلل الأسماء المستغلة عبر هجوم slopsquatting.

**إعادة هيكلة الكود**

استبدل الاستدعاء المخترع بالاستدعاء الحقيقي المتحقق منه. إذا كنت تريد فعلاً التسهيل الذي تخيله النموذج، فقم بتطبيقه مرة واحدة مقابل واجهة برمجة التطبيقات الحقيقية خلف غلاف **استخراج الدالة (Extract Function)** بدلاً من نشر الاستدعاء الزائف في أماكن متعددة.

```ts
// قبل — معامل مهلوس + شكل SDK مختلط
async function refundLast(chargeId: string) {
  // stripe.charges.refund وشكل هذا الخيار غير موجودين
  return stripe.charges.refund(chargeId, { amount: 500, reason: 'requested' });
}

// بعد — متحقق منه مقابل وثائق/أنواع Stripe SDK المثبتة،
// وتم تغليف "التسهيل" مرة واحدة حتى لا يتكرر استدعاء واجهة برمجة التطبيقات الحقيقية
async function refundCharge(chargeId: string, amountCents: number) {
  return stripe.refunds.create({
    charge: chargeId,
    amount: amountCents,
    reason: 'requested_by_customer',
  });
}

```

بالنسبة لمتغير التقادم، تعامل مع استدعاء مهمل مميز كمهمة ترقية حقيقية: انتقل إلى واجهة برمجة التطبيقات الحالية وثبت إصدارها، بدلاً من مجرد كتم التحذير.

**الحدود القياسية.** تلتقط مصححات الأنواع وأدوات الحلول المجموعة الفرعية _القابلة للحل_ (الكائنات المحددة بالنوع، الاستيرادات غير المحلولة). أما الجزء الديناميكي/غير المحدد بالنوع — مثل الخيارات المخترعة على متغيرات من نوع `any`، أو مفاتيح الإعداد النصية، أو حقول بيانات REST — فليس له **مكتشف تلقائي موثوق** ويجب التحقق منه بواسطة مطور بشري مقابل الوثائق الحقيقية.

## Detected by

- **eslint-plugin-import** `import/no-unresolved` — استيراد غير محلول (Unresolved import) (https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/no-unresolved.md)
- **eslint-plugin-import** `import/named` — تصدير مسمى غير موجود (Non-existent named export) (https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/named.md)
- **typescript-eslint** `@typescript-eslint/no-deprecated` — استخدام واجهة برمجة تطبيقات مهملة (حقيقية ولكنها قديمة) (https://typescript-eslint.io/rules/no-deprecated/)
- **Pylint** `no-member (E1101)` — الوصول إلى عضو غير معرف (Access to undefined member) (https://pylint.readthedocs.io/en/stable/user_guide/messages/error/no-member.html)
- **mypy** `attr-defined` — الخاصية/الأسلوب غير معرف على النوع (https://mypy.readthedocs.io/en/stable/error_code_list.html#check-that-attribute-exists-attr-defined)