تسليم دفتر ملاحظات Jupyter: المخرجات المحفوظة وحالة النواة والتشغيل من جديد

تخيّل أنك تتلقى دفتر ملاحظات Jupyter يحتوي على رسم بياني مقنع. لقد تغيّرت خلية المعامل الموجودة فوقه منذ إنشاء الرسم. هذا تسليم افتراضي، لكن السؤال عملي: ما الذي يثبته الملف فعلًا؟

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

يستخدم هذا الدليل «التسليم وفق الحالات الثلاث» لتوضيح هذا الاختيار. وهو قائمة تحقق تحريرية، وليس ميزة في Jupyter أو شهادة اعتماد.

ميّز بين ملف دفتر الملاحظات والنواة الحية وأدلة إعادة التشغيل

ما الذي يحتفظ به ملف .ipynb

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

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

ما الذي ينتمي إلى النواة قيد التشغيل

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

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

ما الذي يمكن أن يثبته التنفيذ التسلسلي من جديد

يدعم التنفيذ التسلسلي المكتمل والمُراجَع باستخدام نواة جديدة إفادةً محدودة: نُفّذت خلايا الشيفرة المشمولة بالنطاق المبلَّغ عنه بالترتيب، في السياق المسجّل، وبالنتيجة المبلَّغ عنها. سجّل ما استُبعد بدلًا من الإيحاء بأن كل الخلايا قد نُفّذت. توصي إرشادات PLOS لمشاركة دفاتر الملاحظات بإعادة تشغيل النواة وتنفيذ الخلايا مجددًا للتحقق من الخطوات التي ربما أُغفلت سهوًا، وليس لاعتماد صحة التحليل.

احرص على إبقاء هذه الإفادة محدودة. فقد تظل النواة الجديدة تستخدم البيئة والملفات نفسها. كما تبقى الخدمات الخارجية خارج دفتر الملاحظات. وحتى نجاح التنفيذ يترك سؤال التحليل مفتوحًا: قد تُنفّذ عملية حسابية من دون أن تنتج إجابة صحيحة أو ذات معنى.

استعرض مثالًا افتراضيًا لدفتر ملاحظات نُفّذت خلاياه بغير ترتيبها

معامل عُدّل بجوار رسم بياني أقدم

في هذا المثال الذي لم يُنفّذ، يشغّل محلل خلية معامل ويستخدمها لإعداد بيانات لرسم بياني. ثم يعدّل لاحقًا النص المصدري للمعامل ويحفظ دفتر الملاحظات من دون إعادة تشغيل الخلايا المعتمدة عليه.

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

أسئلة ينبغي حسمها قبل قبول التسليم

ابدأ بتحديد إصدار المصدر المحفوظ والمدخلات التي يستطيع المرسل تحديدها. اسأل عمّا إذا كانت أي خلايا تعتمد على حالة وحدة التحكم. والسؤال الأكثر مباشرة: هل أُعيد توليد المخرجات بعد آخر تعديل ذي صلة؟

قد تدفعك أعداد التنفيذ إلى الفحص. لكنها لا تجيب عن هذه الأسئلة بمفردها. إذا كانت إعادة التشغيل مأذونًا بها وعملية، فوثّق المحاولة. وإلا فاحتفظ بالملف المقدَّم واذكر أن مخرجاته لم تُولَّد مجددًا.

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

اختر الإجراء المناسب في JupyterLab قبل المشاركة

مسح المخرجات أم إعادة تشغيل النواة أم تشغيل الكل؟

يسرد سجل أوامر JupyterLab عمليات منفصلة. يستخدم المسح notebook:clear-all-cell-outputs، وتستخدم إعادة تشغيل النواة notebook:restart-kernel. ويستخدم «تشغيل الكل» الأمر notebook:run-all-cells، بينما تستخدم إعادة تشغيل النواة ثم التنفيذ notebook:restart-run-all.

طابِق الإجراء مع الدليل الذي تحتاج إليه

يسرد سجل الأوامر نفسه أيضًا إجراءً يجمع إعادة تشغيل النواة ومسح المخرجات، وهو notebook:restart-clear-output. لا تعني إعادة تشغيل النواة تلقائيًا أن المخرجات قد مُسحت. كما لا يخبرك اسم الأمر بأن التنفيذ قد نجح.

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

استخدم خطوات التسليم وفق الحالات الثلاث

افحص إعادة التشغيل وتحقق من الإذن بها

احتفظ بدفتر الملاحظات المستلَم قبل تعديله. راجع الخلايا بحثًا عن العمليات التي تتعامل مع الملفات أو قواعد البيانات، وتحقق من طلبات الشبكة والمدخلات الحساسة واستدعاءات الخدمات المدفوعة. توضّح إرشادات أمان Jupyter Server القدرة الأساسية: يتيح Jupyter تنفيذ شيفرة برمجية اعتباطية. فتح دفتر ملاحظات لا يعني الإذن بتشغيل كل ما بداخله.

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

سجّل السياق ونفّذ عن قصد

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

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

تحتاج الخلايا التي تكتب في قواعد البيانات إلى مراجعة منفصلة للمعاملات. يشرح دليل الحفظ مقابل تثبيت المعاملة في DBeaver هذا التمييز في عميل قواعد بيانات. انقل هذا السؤال إلى مراجعة دفتر الملاحظات: حفظ الدفتر لا يثبت أن معاملة قاعدة البيانات قد ثُبّتت أو جرى التراجع عنها بأمان.

المخطط التالي أداة مساعدة للتخطيط. وهو لا يسجّل تنفيذًا مرصودًا.

راجع، واحفظ بصورة منفصلة، واذكر الحدود

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

تسجّل خطة القياس أدناه الأدلة بدلًا من الدرجات. فهي تسأل عمّا حدث وما يستطيع المستلم فحصه، من دون اختلاق نتائج أداء.

يمكن لملخص قابل للقراءة آليًا أن يحافظ على اتساق السجل. هذا النموذج توضيحي؛ وقيمه النائبة ليست أدلة تنفيذ.

{
  "framework": "three-state-handoff",
  "example_only": true,
  "source_artifact": "not-recorded",
  "execution_context": "not-recorded",
  "rerun_status": "not-recorded",
  "saved_artifact": "not-recorded",
  "limitations": ["no-execution-evidence"]
}

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

خطّط للتنفيذ باستخدام nbclient من دون المبالغة في قدرات الأتمتة

سياق التنفيذ وسياسة الأخطاء

يصف هذا القسم تصميمًا للأتمتة يستند إلى الوثائق. وهو ليس تنفيذًا برمجيًا جاهزًا للتشغيل. لم يُنفَّذ أي دفتر ملاحظات ولم تُثبَّت أي اعتماديات لإعداد هذا الدليل. ولم تُجرَ أي استدعاءات لواجهات برمجة تطبيقات الذكاء الاصطناعي.

يعرض دليل التنفيذ باستخدام nbclient كيفية تهيئة NotebookClient بنواة محددة ودليل تنفيذ قبل استدعاء execute(). اقرأ إعداداته بعناية. يتحكم timeout=600 في المثال بمهلة تنفيذ الخلية، لا المهمة بأكملها. ولا يُعدّ kernel_name='python3' أو الدليل notebooks/ توصية عامة تصلح لكل الحالات.

يوثّق دليل معالجة الأخطاء في nbclient أن allow_errors=False هو الإعداد الافتراضي. مع allow_errors=True، يمكن أن يستمر التنفيذ رغم استثناءات الخلايا. حدّد الأخطاء التي تجعل التسليم غير مقبول قبل جدولة الأتمتة. الوصول إلى الخلية الأخيرة لا يعني النجاح بحد ذاته.

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

حفظ المخرجات مسؤولية منفصلة

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

تحدّد إرشادات العناصر التفاعلية في nbclient حدًا مفيدًا آخر: لا يعرض التنفيذ العناصر التفاعلية في متصفح. لذلك لا تثبت حالة العناصر التفاعلية المخزنة أن مخرجًا تفاعليًا يعمل في العارض المقصود. تحقّق من تلك المخرجات فيه، أو أدرجها ضمن ما لم يُختبر.

تجنّب الأخطاء التي لا يصلحها تنفيذ كامل من جديد

أخطاء شائعة عند التسليم

من السهل الخلط بين رسم محفوظ وتنفيذ حالي. ويصعب اكتشاف متغير غير موثَّق في وحدة التحكم، لكنه يخلق المشكلة العملية نفسها: يضطر المستلم إلى تخمين كيفية إنتاج النتيجة. واعتبار «تشغيل الكل» إعادةً لضبط الحالة يضيف افتراضًا آخر بلا سند.

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

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

حدود قابلية إعادة الإنتاج والثقة والخدمات الخارجية

يقدّم مقال PLOS المنشور عام 2019 بعنوان عشر قواعد بسيطة لكتابة التحليلات الحاسوبية ومشاركتها في دفاتر ملاحظات Jupyter خلفية منهجية عن توثيق الاعتماديات والبيانات وخطوات التحليل. استخدمه لهذا الغرض. فهو ليس دليلًا على إصدار منتج حالي أو عملية نشر لدى Optijara.

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

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

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