تتبع

مقدمة

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

التهيئة

لبدء تتبع تجربة باستخدام Trackio، تحتاج أولاً إلى تهيئة مشروع باستخدام دالة init():

import trackio

trackio.init(project="my_project")

• إذا كان المشروع موجودًا بالفعل، فسيتم تحميله.
• وإذا لم يكن كذلك، سيقوم Trackio بإنشاء مسار جديد.

في الحالتين، يبدأ تشغيل جديد تلقائيًا، وجاهز لتسجيل البيانات.

تسمية تشغيلك

من الجيد منح كل تشغيل اسمًا ذي معنى لتسهيل التنظيم والإشارة إليه لاحقًا. يمكنك تعيين اسم باستخدام معامل name:

trackio.init(project="my_project", name="my_first_run")

إذا لم يتم تقديم اسم، فإن Trackio يولّد اسمًا افتراضيًا.

تجميع التشغيلات

يمكنك تنظيم التشغيلات ذات الصلة في مجموعات باستخدام معامل group. وهذا مفيد بشكل خاص عند تشغيل عدة تجارب بإعدادات مختلفة لكنك ترغب في مقارنتها معًا:

# Group runs by experiment type
trackio.init(project="my_project", name="baseline_run_1", group="baseline")
trackio.init(project="my_project", name="augmented_run_1", group="augmented")
trackio.init(project="my_project", name="tuned_run_1", group="tuned")

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

التسجيل عن بُعد (مساحة Hugging Face أو خادم مُستضاف ذاتيًا)

بشكل افتراضي، تُخزَّن المقاييس محليًا وتُفتح لوحة التحكم على جهازك. يمكنك بدلاً من ذلك إرسال المقاييس إلى:

• من خلال مساحة Hugging Face، عن طريق تمرير space_id (أو تعيين TRACKIO_SPACE_ID). يمكن لـ Trackio إنشاء مساحة أو إعادة استخدامها ومزامنة البيانات فيها.
• خادم Trackio مُستضاف ذاتيًا (HTTP أو HTTPS)، عن طريق تمرير server_url (أو تعيين TRACKIO_SERVER_URL). استخدم رابط الوصول للكتابة من trackio.show() (اختياريًا مع write_token في الاستعلام)، أو رابط أساسي مع TRACKIO_WRITE_TOKEN. يصادق العميل باستخدام رمز الكتابة نفسه الذي تستخدمه لوحة التحكم (وليس رمز Hugging Face الخاص بك).

إذا تم تكوين مساحة (Space) وعنوان URL مُستضاف ذاتيًا معًا (space_id / TRACKIO_SPACE_ID إلى جانب server_url / TRACKIO_SERVER_URL)، فإن المساحة لها الأولوية ويُتجاهل عنوان URL المُستضاف ذاتيًا. الخيارات مثل dataset_id (غير مستحسنة؛ استخدم bucket_id بدلاً منها) وbucket_id تنطبق على نشرات Hugging Face؛ عند سريان server_url فقط، قم بتكوين التخزين على المضيف الذي يشغّل الخادم (انظر متغيرات البيئة).

للحصول على خطوات الإعداد (تشغيل trackio show، والارتباط بـ 0.0.0.0، وكتابة الرموز)، راجع استضافة الخادم ذاتيًا.

يستطلع لوحة التحكم المدمجة عمليات التشغيل الجديدة والمقاييس كل ثانية واحدة على localhost و كل ثانيتين عند فتحها على مساحة Hugging Face (*.hf.space)، لتخفيف حدود المعدل على عنوان المساحة.

تسجيل البيانات

بمجرد تهيئة تشغيلك، يمكنك البدء في تسجيل البيانات باستخدام دالة log():

trackio.log({"loss": 0.05})

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

يزيد كل استدعاء لـ log() عدّاد الخطوات تلقائيًا. إذا كنت ترغب في تسجيل عدة مقاييس في وقت واحد، فمررها معًا:

trackio.log({
    "loss": 0.05,
    "accuracy": 0.95,
})

جداول التسجيل

يمكنك تسجيل البيانات الجدولية باستخدام فئة Table. وهذا مفيد لتتبع النتائج مثل التنبؤات، أو أي بيانات منظمة. يمكن أن تتضمن الجداول أعمدةً للصور باستخدام فئة Image.

import pandas as pd

df = pd.DataFrame(
    {
        "prompt": ["Trackio", "Logging is"],
        "completion": ["is great!", "easy and fun!"],
        "reward": [0.123, 0.456],
    }
)
trackio.log(
    {
        ...
        "texts": trackio.Table(dataframe=df),
    }
)

تقارير التسجيل (Markdown)

يمكنك تسجيل تقارير باستخدام فئة Markdown. تُعرض التقارير في صفحة التقارير في لوحة التحكم، حيث يظهر أحدث تقرير أولاً.

trackio.log(
    {
        "training_report": trackio.Markdown(
            """# Training Report

Final validation accuracy: **0.92**

- Best epoch: 18
- Early stopping: enabled
"""
        )
    }
)

يمكنك تسجيل التقارير عدة مرات أثناء التشغيل (على سبيل المثال، تقرير واحد لكل نقطة تحقق)، وسيتولى Trackio الاحتفاظ بالتاريخ الكامل عبر الخطوات.

للحصول على سكربت قابل للتشغيل بالكامل، راجع examples/training-with-report.py.

تسجيل الصور

يمكنك تسجيل الصور باستخدام فئة Image.

trackio.log({"image": trackio.Image(value="path/to/image.png", caption="Image caption")})

يمكن تسجيل الصور من مسار، أو مصفوفة numpy، أو صورة PIL.

تسجيل مقاطع الفيديو

يمكنك تسجيل مقاطع الفيديو باستخدام فئة Video.

import trackio
import numpy as np

# Create a simple video from numpy array
frames = np.random.randint(0, 255, (10, 3, 64, 64), dtype=np.uint8)
video = trackio.Video(frames, caption="Random video", fps=30)
trackio.log({"my_video": video})

# Create a batch of videos
batch_frames = np.random.randint(0, 255, (3, 10, 3, 64, 64), dtype=np.uint8)
batch_video = trackio.Video(batch_frames, caption="Batch of videos", fps=15)
trackio.log({"batch_videos": batch_video})

# Create video from file path
video = trackio.Video("path/to/video.mp4", caption="Video from file")
trackio.log({"file_video": video})

يمكن تسجيل مقاطع الفيديو من مسار ملف أو من مصفوفة numpy.

متطلبات مصفوفة Numpy:

• يجب أن يكون من النوع np.uint8 مع قيم RGB في المدى [0, 255]
• يجب أن يكون الشكل أحد ما يلي:
  • (frames, channels, height, width) لفيديو واحد
  • (batch, frames, channels, height, width) لعدة مقاطع فيديو (سيتم ترتيبها في شبكة)

تسجيل الصوت

يمكنك تسجيل الصوت باستخدام فئة Audio.

import trackio
import numpy as np

# Generate a 1-second 440 Hz sine wave (mono)
sr = 16000
t = np.linspace(0, 1, sr, endpoint=False)
wave = 0.2 * np.sin(2 * np.pi * 440 * t)
audio = trackio.Audio(wave, caption="A4 sine", sample_rate=sr, format="wav")
trackio.log({"tone": audio})

# Stereo from numpy array (shape: samples, 2)
stereo = np.stack([wave, wave], axis=1)
audio = trackio.Audio(stereo, caption="Stereo", sample_rate=sr, format="mp3")
trackio.log({"stereo": audio})

# From an existing file
audio = trackio.Audio("path/to/audio.wav", caption="From file")
trackio.log({"file_audio": audio})

يمكن تسجيل الصوت من مسار ملف أو من مصفوفة numpy.

متطلبات مصفوفة Numpy:

• يجب أن يكون الشكل إما (samples,) للصوت أحادي القناة أو (samples, 2) للصوت ثنائي القناة
• يجب تقديم sample_rate عند التسجيل من مصفوفة numpy
• قد تكون القيم من نوع float أو integer؛ حيث تُطبَّع القيم العشرية (floats) وفق الذروة وتُحوَّل إلى PCM بدقة 16 بت
• format يمكن أن يكون "wav" أو "mp3" عند التسجيل من مصفوفة numpy (الافتراضي "wav")

تسجيل الكائنات ثلاثية الأبعاد

استخدم Object3D مع واجهة trackio.log() البرمجية نفسها المستخدمة في وسائط أخرى:

import numpy as np
import trackio

trackio.log({"scene": trackio.Object3D("path/to/scene.glb", caption="Prediction")})

points = np.random.normal(size=(50_000, 3))
trackio.log({"point_cloud": trackio.Object3D.from_numpy(points)})

يجب أن تكون مصفوفات NumPy من إحدى هذه الأشكال:

• (N, 3) لإحداثيات XYZ.
• (N, 4) للإحداثيات XYZ مع فئة عددية صحيحة من 1 إلى 14. يطبّق Trackio لوحة ألوان حتمية للفئات.
• (N, 6) لقيم XYZ بالإضافة إلى قيم RGB الصحيحة من 0 إلى 255.

يجب أن تكون الإحداثيات قيمًا محدودة. تُقيَّد سحابة النقاط العادية بشكل حتمي إلى 300,000 نقطة مرسومة؛ وتبقى أعدادها الأصلية والمرسومة مرئية. لا يقوم Trackio بتخفيف كثافة الشبكات أو رشّات غاوس.

يجب أن تكون النماذج مكتفية ذاتياً. يتم دعم عناوين URI المضمنة لبيانات glTF، لكن الموارد الخارجية لـ glTF ومكتبات مواد OBJ ونقوش PLY غير مدعومة. يستخدم كل كيان نفس تخطيط <project>/<run>/<step>/<uuid>.<ext> المستخدم للصور والفيديو والصوت.

تعمل الكائنات ثلاثية الأبعاد أيضًا في الجداول:

table = trackio.Table(
    columns=["sample", "reconstruction"],
    data=[["chair", trackio.Object3D("chair.gltf")]],
)
trackio.log({"reconstructions": table})

تسجيل HTML والرسوم

يمكنك تسجيل HTML باستخدام فئة Html.

trackio.log({"report": trackio.Html("<h1>Results</h1>")})

تُحوَّل رسوميات Matplotlib وPlotly إلى HTML:

import plotly.express as px

fig = px.line(x=[1, 2, 3], y=[4, 5, 6])
trackio.log({"plot": fig})

تسجيل مقاييس النظام

يمكن لـ Trackio تسجيل مقاييس النظام تلقائيًا في الخلفية. وهو يدعم كلاً من وحدات معالجة الرسوميات من NVIDIA وأجهزة Mac التي تعمل بمعالجات Apple Silicon (سلسلة M).

التثبيت:

# NVIDIA GPU monitoring
pip install trackio[gpu]

# Apple Silicon system monitoring
pip install trackio[apple-gpu]

التسجيل التلقائي (الافتراضي):

عند تثبيت الحزمة المناسبة واكتشاف العتاد المتوافق، تُسجَّل مقاييس النظام تلقائيًا في الخلفية (كل 10 ثوانٍ افتراضيًا):

import trackio

# Auto-enabled when hardware is detected
trackio.init(project="my_project")

for step in range(100):
    # ... training code ...
    trackio.log({"loss": loss})
# System metrics are logged automatically in the background

trackio.finish()

يمكنك تخصيص الفاصل الزمني أو تعطيل التسجيل التلقائي:

# Custom interval
trackio.init(project="my_project", gpu_log_interval=5.0)

# Disable auto-logging
trackio.init(project="my_project", auto_log_gpu=False)

التسجيل اليدوي:

يمكنك أيضًا تسجيل مقاييس النظام يدويًا في أوقات محددة باستخدام log_gpu():

import trackio

trackio.init(project="my_project", auto_log_gpu=False)

for step in range(100):
    # ... training code ...
    trackio.log({"loss": loss})
    trackio.log_gpu()  # Log system metrics at current time

trackio.finish()

مقاييس وحدات معالجة الرسوميات من NVIDIA:

مقاييس لكل وحدة معالجة رسومية (gpu/{i}/{metric}):

• gpu/0/utilization - نسبة استخدام وحدة معالجة الرسوميات
• gpu/0/memory_utilization - نسبة استخدام وحدة التحكم بالذاكرة
• gpu/0/allocated_memory - الذاكرة المُخصَّصة بالجيجابايت
• gpu/0/total_memory - إجمالي الذاكرة بالجيجابايت
• gpu/0/memory_usage - نسبة استخدام الذاكرة (0-1)
• gpu/0/temp - درجة الحرارة بالسيليز
• gpu/0/power - استهلاك الطاقة بالواط
• gpu/0/power_percent - الطاقة كنسبة مئوية من الحد الأقصى
• gpu/0/power_limit - حد الطاقة بالواط
• gpu/0/sm_clock - سرعة ساعة SM بالهرتز
• gpu/0/memory_clock - سرعة ساعة الذاكرة بالهرتز
• gpu/0/fan_speed - سرعة المروحة %
• gpu/0/performance_state - حالة الأداء (P0-P15)
• gpu/0/energy_consumed - الطاقة المستهلكة منذ بدء التشغيل بالجول
• gpu/0/pcie_tx - عرض نطاق إرسال PCIe بمقياس ميغابايت/ثانية
• gpu/0/pcie_rx - عرض نطاق الاستقبال عبر PCIe بمقياس ميغابايت/ثانية
• gpu/0/throttle_thermal - خفض السرعة بسبب الحرارة (0/1)
• gpu/0/throttle_power - خفّض الطاقة (0/1)
• gpu/0/throttle_hw_slowdown - إبطاء العتاد (0/1)
• gpu/0/throttle_apps - خفّض سرعة الساعة للتطبيقات (0/1)
• gpu/0/corrected_memory_errors - أخطاء الذاكرة المصححة بواسطة ECC
• gpu/0/uncorrected_memory_errors - أخطاء ECC غير القابلة للإصلاح

المقاييس المجمّعة:

• gpu/mean_utilization - متوسط استخدام وحدة المعالجة الرسومية عبر جميع وحدات المعالجة الرسومية
• gpu/total_allocated_memory - إجمالي الذاكرة المستخدمة عبر جميع وحدات معالجة الرسومات بالجيجابايت
• gpu/total_power - إجمالي استهلاك الطاقة عبر جميع وحدات معالجة الرسوميات
• gpu/max_temp - أقصى درجة حرارة عبر جميع وحدات معالجة الرسوميات

مقاييس Apple Silicon:

• cpu/utilization - نسبة استخدام المعالج المركزي الإجمالية
• cpu/{i}/utilization - نسبة استخدام المعالج لكل نواة %
• cpu/frequency - تردد المعالج المركزي الحالي بالميغاهرتز
• cpu/frequency_max - أقصى تردد للمعالج المركزي بالميغاهرتز
• memory/used - الذاكرة المستخدمة بالجيجابايت
• memory/total - إجمالي الذاكرة بالجيجابايت
• memory/available - الذاكرة المتاحة بالجيجابايت
• memory/percent - نسبة استخدام الذاكرة
• swap/used - مساحة الذاكرة الافتراضية المستخدمة بالجيجابايت
• swap/total - إجمالي مساحة التبادل بالجيجابايت
• swap/percent - نسبة استخدام الذاكرة المؤقتة
• temp/{label} - قراءات مستشعر درجة الحرارة بالسيليزيوس (إن كانت متاحة)
• gpu/detected - ما إذا تم اكتشاف معالج رسومي من Apple (0/1)

التقاط إخراج وحدة التحكم وأمر الإقلاع

يسجّل Trackio الأمر المستخدم لإطلاق كل تشغيل (على سبيل المثال python train.py --lr 1e-3) ويعرضه في أعلى صفحة التشغيل في لوحة التحكم، مع زر لنسخه. تُستبدل قيم الحُجج التي تبدو أسماءها كأسرار (مثل --hub_token، --api-key، أو password=...) بـ REDACTED. يُخزَّن الأمر في إعدادات التشغيل تحت المفتاح المحجوز _Command.

يمكن لـ Trackio أيضًا التقاط كل ما يكتبه سكربت إلى stdout وstderr، بما في ذلك استدعاءات print()، ومخرجات logging، وسجلات الأخطاء (tracebacks)، مما يتيح لك متابعة سجلات التشغيل من لوحة التحكم عندما تكون بعيدًا عن الطرفية. التقاط وحدة التحكم معطّل افتراضيًا. فعّله باستخدام capture_console=True:

import logging

import trackio

logging.basicConfig(level=logging.INFO)

trackio.init(project="my_project", capture_console=True)

for step in range(100):
    loss = ...
    logging.info("step %d loss=%.4f", step, loss)
    trackio.log({"loss": loss})

trackio.finish()

أو فعّله دون تغيير كودك من خلال تعيين متغير البيئة TRACKIO_CAPTURE_CONSOLE:

TRACKIO_CAPTURE_CONSOLE=1 python train.py

تظهر المخرجات المُلتقطة في قسم Console output من صفحة التشغيل (افتح تشغيلًا من صفحة Runs). يتم تحديثها كل 10 ثوانٍ أثناء سير التشغيل، ويحفظ زر Download السجل الكامل كملف نصي. تُخزَّن كل سطر مع وقت كتابته بتوقيت UTC؛ ويعرض لوحة التحكم ذلك بتوقيتك المحلي. تُحفظ المخرجات كل 10 ثوانٍ وعند انتهاء التشغيل، وتعمل مع التشغيلات المحلية وكذلك التشغيلات المسجَّلة على Space أو خادم مُستضاف ذاتيًا، وهي محدودة بـ 20 ميغابايت لكل تشغيل.

إذا تم إيقاف العملية باستخدام SIGTERM (سواء بسبب حد الوقت في Slurm، أو أمر docker stop، أو طرد من Kubernetes)، فإن المخرجات المكتوبة منذ آخر حفظ ستُفقد. اضبط TRACKIO_HANDLE_SIGTERM=1 لحفظها قبل خروج العملية.

يعمل التقاط وحدة التحكم عن طريق تغليف طريقة write الخاصة بـ sys.stdout و sys.stderr، لذا فإنه يلتقط أيضًا معالجات logging المُهيأة قبل استدعاء trackio.init(). أما المخرجات المكتوبة مباشرةً إلى مُعرِّفات الملفات الأساسية، مثل الرسائل الصادرة من امتدادات C أو العمليات الفرعية، فلا يتم التقاطها.

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

إنهاء تشغيل

عند اكتمال تشغيلك، قم بتثبيته باستخدام finish(). يُعلّم هذا التشغيل بأنه مكتمل ويحفظ جميع البيانات المسجلة:

trackio.finish()

استئناف تشغيل

يحدد Trackio التشغيلات داخليًا عبر run_id ثابت. لم يعد من الضروري أن يكون name المقروء للبشر فريدًا، مما يتيح لك إنشاء عدة تشغيلات تحمل نفس الاسم المعروض.

إذا كنت بحاجة إلى متابعة آخر تشغيل باسم معيّن (على سبيل المثال، بعد انقطاع)، فاستدعِ init() مرة أخرى بنفس اسم المشروع واسم التشغيل، واضبط resume="must":

trackio.init(project="my_project", name="my_first_run", resume="must")

سيؤدي هذا إلى تحميل أحدث تشغيل تم إنشاؤه بهذا الاسم حتى تتمكن من مواصلة تسجيل البيانات باستخدام run_id نفسه. ولكن إذا قمت بتعيين resume="must"، ولم يوجد تشغيل سابق بنفس الاسم، فسيُطلق Trackio خطأً.

لمزيد من المرونة، استخدم resume="allow". سيؤدي هذا إلى استئناف أحدث تشغيل يحمل ذلك الاسم إذا كان موجودًا، أو إنشاء تشغيل جديد في حال عدم وجوده.

القيمة الافتراضية هي resume="never"، والتي تنشئ دائمًا تشغيلًا جديدًا بمعرّف تشغيل run_id جديد، حتى لو كان هناك تشغيل آخر يحمل نفس name موجود بالفعل.

تتبع الإعداد

يمكنك أيضًا تتبع معاملات التهيئة لتشغيلاتك. وهذا مفيد للحفاظ على سجل للمعاملات الفائقة أو الإعدادات الأخرى المستخدمة في تجاربك. يمكنك تسجيل بيانات التهيئة باستخدام معامل config في دالة init():

for batch_size in [16, 32, 64]:
    for lr in [0.001, 0.01, 0.1]:
        trackio.init(
            project="hyperparameter_tuning",
            name=f"lr_{lr}_batch_{batch_size}_run",
            config={
                "learning_rate": lr,
                "batch_size": batch_size,
            }
        )
        # ... your training code ...
        trackio.finish()

في لوحة التحكم، يمكنك بعد ذلك التجميع حسب learning_rate أو batch_size لمقارنة التشغيلات ذات المعلمات الفائقة المختلفة بشكل أسهل.