המאגר הוא הרשומה הטכנית הקבועה של הפרויקט וחלק מהתוצר המוגש. הוא צריך לאפשר לכל אחד להבין, לבחון, לשחזר, לסקור, ולהמשיך את העבודה.
מאגר טוב מאפשר לסטודנט, חוקר, מרצה, או מפתח אחר:
מאגר אינו רק אחסון; הוא נבחן על בהירות, שלמות, ארגון, ושחזוריות.
חמישה עשר חלקים, משם ומבנה ועד שחזוריות ורשימת התיוג הסופית.
תנו למאגר שם משמעותי שמשקף את הפרויקט.
הוסיפו תיאור קצר שמכסה את הבעיה, הגישה המרכזית, והפלט המרכזי.
project-name/
|
|-- README.md
|-- requirements.txt
|-- environment.yml
|-- LICENSE
|
|-- slides/
| |-- proposal.pptx / proposal.pdf
| |-- midterm.pptx / midterm.pdf
| |-- final.pptx / final.pdf
|
|-- src/
| |-- data/ models/ training/ evaluation/ utils/
|
|-- notebooks/
| |-- 01_data_exploration.ipynb
| |-- 02_baseline.ipynb
| |-- 03_experiments.ipynb
|
|-- data/
| |-- raw/ processed/ samples/
|
|-- configs/
|-- results/
| |-- metrics/ predictions/ experiment_logs/
|
|-- visuals/
| |-- visual_abstract.png pipeline.png result_figures/
|
|-- tests/המבנה המדויק יכול להשתנות, אבל הוא חייב להיות הגיוני וקל לניווט.
הסבירו את הבעיה בעולם האמיתי, מדוע היא חשובה, מי ייהנה מפתרונה, ומדוע הפתרונות הקיימים אינם מספקים. שמרו על תמציתיות אך היו ספציפיים.
הגדירו את הקלט, הפלט, המשימה הטכנית, מקרה השימוש המיועד, והאילוצים החשובים. הוסיפו דוגמאות מייצגות של קלט ופלט.
הוסיפו איור אחד ברור שמסכם את הפרויקט: הקלט, שלבי העיבוד המרכזיים, המודל או המערכת, הפלט, והשימוש המעשי. הוא צריך להיות מובן בלי לקרוא את כל המאגר.
עבור כל מאגר נתונים, תעדו:
עבור נתונים שנוצרו או תויגו, תארו גם את תהליך הייצור או האיסוף, הוראות התיוג, בדיקות האיכות, ותהליך האימות.
אל תעלו נתונים רגישים, מוגבלים, או מוגני זכויות יוצרים ללא רשות. כאשר לא ניתן לכלול את מאגר הנתונים המלא, ספקו קובצי דוגמה, הוראות הורדה, סקריפטים להכנה, ואת מבנה התיקיות הצפוי.
תארו את הזרימה המלאה: המודלים שבהם השתמשתם, התפקיד של כל אחד, עיבוד מקדים, אימון, היסק, ועיבוד לאחר מכן. כללו תרשים של צינור העיבוד, ולכל מודל מרכזי הסבירו מדוע הוא נבחר וכיצד הוגדר.
תעדו:
שמרו במאגר את הפרומפטים, ההגדרות, וסקריפטי הייצור החשובים.
תעדו:
ספקו פקודות מדויקות, לדוגמה:
python -m src.training.train \
--config configs/baseline.yamlהסבירו את בניית מערך המבחן, מדדי ההערכה, שיטות הבסיס, מודלי ההשוואה, סקריפטי ההערכה, תהליך ההערכה האיכותנית, והערכה אנושית כאשר נעשה בה שימוש.
ספקו פקודות מדויקות, לדוגמה:
python -m src.evaluation.evaluate \
--config configs/final_model.yamlהציגו את התוצאות המרכזיות בטבלאות קריאות.
| מודל | דיוק | Macro-F1 | זמן תגובה |
|---|---|---|---|
| בסיס | 0.78 | 0.65 | 20 ms |
| Model A | 0.84 | 0.76 | 35 ms |
| מודל סופי | 0.88 | 0.81 | 42 ms |
קשרו לתוצאות מפורטות בפורמט CSV או JSON, קובצי חיזוי, יומני ניסויים, ואיורים. המספרים ב-README, במצגות, ובקובצי התוצאות חייבים להיות זהים.
המאגר חייב לאפשר לאדם אחר להריץ את הפרויקט. כללו:
השתמשו בנתיבים יחסיים ובקובצי הגדרות; אל תסתמכו על תיקיות מקומיות לא מתועדות.
לעולם אל תעלו:
השתמשו במשתני סביבה וספקו קובץ .env.example.
הקוד צריך להיות מאורגן במודולים משמעותיים, קריא, מתועד במידת הצורך, נקי מקבצים שאינם בשימוש ומנתיבים מקומיים קשיחים, עקבי בשמות, וניתן להרצה מסביבה נקייה.
מחברות (notebooks) צריכות לרוץ מלמעלה למטה, לכלול כותרות ברורות, להפריד בין חקירה לניסויים הסופיים, להימנע מפלט מוגזם, ולהסביר החלטות חשובות.
פרטו כל חבר צוות ואת תחומי האחריות שלו, עם תרומות קונקרטיות כמו איסוף מאגר נתונים, תיוג, מימוש מודל, ניסויים, הערכה, פיתוח ממשק, ותיעוד.
מכל חבר צוות מצופה להבין את כל הפרויקט, לא רק את הקבצים שלו.
הגשה חזקה מציגה גם את איכות הפרויקט וגם את המקצועיות של הצוות.
שימו דוגמאות קונקרטיות ב-README, וקשרו אליהן מהמצגת: דוגמאות נתונים (תמונות או טקסט), כיצד הנתונים נוצרים, שלבי המודל, קלט ופלט אמיתיים של המודל, וכמה מקרי שגיאה ברורים.
זוהי בדיקה סופית מהירה, לא תחליף למדריך המלא. קראו קודם את הדרישות המלאות שלמעלה, ואז השתמשו בעשרת הפריטים האלה כדי לוודא שהחלקים המרכזיים נמצאים במקומם לפני ההגשה.