كيفية إضافة إفصاح الذكاء الاصطناعي إلى واجهة برمجة التطبيقات الخاصة بك؟

تحتوي واجهة المستخدم للدردشة الخاصة بك على شارة صغيرة "تم إنشاؤها بواسطة الذكاء الاصطناعي" أسفل كل رد. جيد. الآن يقوم فريق شريك باستدعاء نقطة النهاية /summarize الخاصة بك من مهمة دفعية، ويكتب المخرجات في قاعدة بيانات، ويعرضها داخل تقرير موجه للعملاء. لم تساعد شارتك أحدًا.

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

منذ 2 أغسطس 2026، جعلت المادة 50 من قانون الاتحاد الأوروبي للذكاء الاصطناعي هذا الأمر ملموسًا للعديد من الفرق. يضع موفرو النماذج مثل Anthropic علامة على مخرجاتهم على مستوى النموذج، ولكن واجب إخبار الأشخاص بأنهم يتعاملون مع الذكاء الاصطناعي يقع على عاتق من يقوم بنشر النظام. إذا كان واجهة برمجة التطبيقات (API) الخاصة بك تقع بين الاثنين، فأنت السبب في أن المتصلين بك يمكنهم الامتثال أو لا يمكنهم.

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

ما الذي يتضمنه الرد

ثلاثة أشياء، وتجيب على ثلاثة أسئلة مختلفة.

هل تم إنشاء هذا؟ قيمة منطقية (boolean)، أو الأفضل من ذلك، تعداد (enum). ai_generated: true بداية جيدة، لكن generation: "synthetic" | "assisted" | "human" أكثر فائدة، لأن "كلود قام بتعديل مسودة بشرية" و "كلود كتب كل شيء" يختلفان اختلافًا حقيقيًا، وتعامل استثناءات المادة 50 معهما بشكل مختلف.

بواسطة ماذا؟ معرف البائع والنموذج. قد يكون لدى المتصلين بك سياسات نموذج خاصة بهم، والتراجع الذي يبدل النماذج يغير ما يُسمح لهم بفعله بالمخرجات.

ماذا نعرف بالفعل؟ حالة المصدر، إذا قمت بالتحقق. اجعل هذا منفصلاً عن علامة الإنشاء، لأن "لقد أنشأنا هذا" حقيقة تمتلكها و "لقد تحققنا من بيان C2PA" هي ملاحظة قمت بها.

شكل ثابت وموثوق:

{
  "id": "sum_4f81a2",
  "content": "The incident affected two regions for 41 minutes...",
  "ai": {
    "generation": "synthetic",
    "vendor": "anthropic",
    "model": "claude-opus-5",
    "human_review": false,
    "generated_at": "2026-08-11T09:14:22Z"
  },
  "provenance": {
    "status": "unchecked",
    "standard": null
  }
}

تفصيلان يستحقان الدفاع عنهما.

يوجد human_review لأن المادة 50(4) تعتمد عليه. يجب الإفصاح عن النصوص التي يتم إنشاؤها بواسطة الذكاء الاصطناعي والمنشورة لإبلاغ الجمهور بشأن مسائل المصلحة العامة، ما لم تخضع لمراجعة بشرية أو رقابة تحريرية من قبل شخص يمتلك مسؤولية تحريرية. إذا سجلت منصتك أن إنسانًا وافق على مسودة، فإن هذه الحقيقة تنتمي إلى الرد، لأنها الفارق بين حاجة المتصل إلى تسمية أو عدم حاجته.

يحتوي provenance.status على أكثر من حالتين. فـ verified و absent و invalid و unchecked كلها تعني أشياء مختلفة، ودمجها في قيمة منطقية (boolean) يلغي القيم المفيدة. لا يجب أن يبدو انقطاع في خدمة التحقق الخاصة بك مماثلاً لنتيجة نظيفة.

الرؤوس أم المحتوى؟

كلاهما، لمستهلكين مختلفين.

المحتوى يحمل الحقيقة. إنه ما يتم تخزينه وتسجيله وإعادة تشغيله وتمريره إلى المراحل التالية. إذا احتفظ المتصل فقط بـ JSON المحلل، يجب أن يكون الإفصاح موجودًا هناك.

الرأس يساعد على الأطراف. يمكن للوكيل (proxy) أو البوابة (gateway) أو طبقة التسجيل (logging layer) التي لا تحلل محتواك أبدًا أن توجه أو تسجل رأسًا. كما أنه المكان المعقول الوحيد للإفصاح في استجابة ليست بتنسيق JSON، مثل نقطة نهاية نصية بسيطة أو ثنائية.

HTTP/1.1 200 OK
Content-Type: application/json
X-AI-Generated: synthetic
X-AI-Model: anthropic/claude-opus-5

قاعدتان للرؤوس. حافظ على اتساقها عبر كل نقطة نهاية، لأن الرأس الذي يظهر في بعض المسارات أسوأ من الذي لا يظهر في أي منها. ولا تتعامل أبدًا مع الرأس كسلطة نهائية إذا اختلف المحتوى؛ اختر أحدهما كمرجع أساسي، ووثّق أي منهما، واجعل اختباراتك تفرض ذلك.

بالنسبة للاستجابات المتدفقة (streaming responses)، ضع الإفصاح في الحدث الأول أو في رؤوس الاستجابة. لا ينبغي للمتصل الذي يبدأ في عرض الرمز المميز الأول أن يضطر إلى الانتظار للحصول على معلومات إضافية لمعرفة ما يعرضه. إذا كنت جديدًا في تصميم الرؤوس بشكل عام، فإن ما هي رؤوس HTTP يغطي الأساسيات.

ضعه في المواصفات

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

components:
  schemas:
    AiDisclosure:
      type: object
      required: [generation]
      properties:
        generation:
          type: string
          enum: [synthetic, assisted, human]
          description: >
            synthetic = produced by a model with no human authoring.
            assisted = a human authored the content and a model edited,
            translated, or summarised it.
            human = no model involvement.
        vendor:
          type: string
          example: anthropic
        model:
          type: string
          example: claude-opus-5
        human_review:
          type: boolean
          description: >
            True when a person reviewed the output before it was returned
            and an identifiable party holds editorial responsibility.
        generated_at:
          type: string
          format: date-time

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

فائدتان مترتبتان. توثيقك المُنشأ يشرح الآن الحقل لكل مستهلك دون أن يكتب أحد صفحة ويكيبيديا. وسيكتشف التحقق من المواصفات اليوم الذي يختفي فيه، وهو وضع الفشل الذي يحدث بالفعل. كيفية التحقق من مواصفات OpenAPI يغطي جانب التحقق، و OpenAPI diff لمنع التغييرات الجذرية في CI سيكشف من يجعل الحقل اختياريًا بهدوء.

المسارات التي ينساها الناس

تختفي حقول الإفصاح في المسارات التي لا يفكر بها أحد. أربعة للتحقق منها بشكل صريح.

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

استجابات الخطأ والجزئية. المهلة التي تعيد ملخصًا جزئيًا لا تزال تعيد مخرجات النموذج. إذا كان غلاف الخطأ الخاص بك له شكل مختلف، فإنه يحتاج إلى الحقل أيضًا.

حمولات الدفعات وخطافات الويب (webhooks). غالبًا ما يستخدم التسليم غير المتزامن مخططًا أبسط تم بناؤه بواسطة تعليمات برمجية مختلفة. هذا هو المكان الأكثر شيوعًا الذي يفتقد فيه هذا الحقل.

مسارات التراجع. عندما يفشل النموذج الأساسي وتتراجع، يجب أن تتبع قيمة model. سلسلة نصية لنموذج مبرمجة في كتلة إفصاح هي كذبة تنتظر الحدوث.

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

اختبره كضمان

حقل الإفصاح هو وعد للمتصلين بك. الوعود التي لا يتم اختبارها هي مجرد توثيق.

خمسة تأكيدات تغطي معظم الأمر، وهي اختبارات API عادية.

1. الحقل موجود في كل مسار مدعوم بالذكاء الاصطناعي.

const body = pm.response.json();
pm.test("response carries AI disclosure", function () {
    pm.expect(body).to.have.property("ai");
    pm.expect(body.ai.generation).to.be.oneOf(["synthetic", "assisted", "human"]);
});

2. يتطابق الرأس مع المحتوى.

pm.test("header and body agree", function () {
    pm.expect(pm.response.headers.get("X-AI-Generated")).to.eql(body.ai.generation);
});

3. يتطابق النموذج المبلغ عنه مع ما استدعيته بالفعل. هذا هو الذي يكشف التراجعات الصامتة. يعتمد ما إذا كانت المخرجات موسومة بعلامة مائية في المرحلة الأولية على معرف النموذج، وهذا هو السبب في أن العلامة المائية لـ API من Claude تجعل تثبيت النموذج تفصيلاً للامتثال بدلاً من كونه تفصيلاً للأداء.

4. المسار المخزن مؤقتًا لا يزال يفصح. استدعِ مرتين، تأكد أن الاستجابة الثانية، التي جاءت من ذاكرة التخزين المؤقت، تحتوي على نفس الإفصاح مثل الأولى.

5. مسار الخطأ لا يزال يفصح. فرض مهلة زمنية أو فشل في المسار السفلي وتأكد من أن الغلاف لا يزال يحمل الحقل.

اجمع هذه في سيناريو اختبار، أضف التحقق من المخطط مقابل تعريف OpenAPI الخاص بك، وقم بتشغيله من apidog-cli في CI (التكامل المستمر):

apidog run --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$DISCLOSURE_SCENARIO_ID" -e "$APIDOG_ENV_ID" -r cli,html

تخرج بقيمة غير صفرية عندما يفشل تأكيد، لذا فإن دمجًا يسقط الحقل سيفشل البناء بدلاً من الشحن. إعداد البايبلاين الكامل موجود في أتمتة اختبارات API في GitHub Actions، وأنماط التأكيد العامة موجودة في تأكيدات API. قم بتنزيل Apidog لبناء السيناريو مقابل نقاط النهاية الخاصة بك.

وثقه حيث يبحث المتصلون

جمهورين، مكانان.

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

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

كن محددًا بشأن القيود. إذا قمت بتمرير مخرجات Claude، فإن النص يحمل علامة مائية مدمجة لا يمكنك التحقق منها بنفسك ولم تفتح Anthropic الكشف عنها. قول ذلك أفضل من الإيحاء بقدرة تحقق لا تمتلكها. المنطق موجود في كيفية اكتشاف العلامة المائية لـ Claude.

تساعد الوثائق التفاعلية هنا أكثر من المعتاد، لأن المتصل يمكنه رؤية حقل الإفصاح في استجابة حية بدلاً من الثقة بجدول. استضافة وثائق API تفاعلية مع وحدة تحكم تجريبية تغطي هذا الإعداد.

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

هل رأس X-AI-Generated معيار قياسي؟ لا. لا يوجد رأس قياسي مصدق عليه للإفصاح عن الذكاء الاصطناعي. اختر اسمًا، وثقه، وحافظ على اتساقه، واعتبره جزءًا من عقدك.

هل يجب أن يكون الإفصاح في الرأس أم في المحتوى؟ كلاهما. المحتوى هو ما يتم تخزينه وتمريره. يخدم الرأس الوكلاء (proxies)، والبوابات (gateways)، والسجلات (logs)، والاستجابات غير بتنسيق JSON. وثّق أي منهما هو الأساسي إذا اختلفا.

هل يجب علي فعل ذلك قانونياً؟ يعتمد ذلك على دورك والمحتوى. تقع التزامات المادة 50 على عاتق مقدمي الخدمات وناشريها بشكل مختلف، وتختص المادة 50(4) بالصور والفيديوهات المزيفة (deepfakes) والنصوص ذات المصلحة العامة مع استثناء للرقابة التحريرية البشرية. المادة 50 من قانون الذكاء الاصطناعي للاتحاد الأوروبي لمطوري API تشرح ذلك بالتفصيل. القرار القانوني يعود لمستشارك؛ أما التنفيذ الفني فهو مسؤوليتك.

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

ماذا عن الاستجابات المتدفقة؟ ضع الإفصاح في رؤوس الاستجابة أو في الحدث الأول. يقوم المتصلون بالعرض فور وصول الرموز المميزة ولا ينبغي لهم الانتظار حتى النهاية.

كيف أتعامل مع المحتوى الذي قام إنسان بتعديله بعد الإنشاء؟ لهذا الغرض توجد assisted و human_review. تحتوي المادة 50(4) على استثناء للمحتوى الذي يخضع للمراجعة البشرية مع مسؤولية تحريرية، لذا فإن تسجيله بدقة يستحق أكثر من مجرد قيمة منطقية واحدة.

هل يجب أن أقوم بتحديد إصدار لهذا الحقل؟ إنه جزء من مخطط استجابتك، لذا قم بتحديد إصدار له تمامًا مثل الباقي. إضافة قيمة تعداد (enum) هو تغيير يحتاج المتصلون لديك إلى معرفته، وسيقوم فرق المواصفات في CI بإخبارهم بذلك.

الخلاصة

يفشل الإفصاح عن الذكاء الاصطناعي كميزة لواجهة المستخدم وينجح كعقد. ضع حقلًا مطلوبًا في الاستجابة، واجعله منعكسًا في الرأس، وعرفه مرة واحدة في مواصفات OpenAPI الخاصة بك، وتأكد من وجوده في مسارات التخزين المؤقت، والخطأ، والدُفعات، والمسارات الاحتياطية حيث يختفي دائمًا.

ربما يستغرق هذا عمل فترة ما بعد الظهيرة، ويحول ادعاء في تسويقك إلى شيء يمكن للمتصلين البناء عليه ويمكن لاختباراتك فرضه.

زر