مخطط التخزين والاستعلامات المباشرة

تخزّن Trackio كل مشروع في قاعدة بيانات SQLite خاصة به، ويمكنها تصدير تلك البيانات إلى parquet للمزامنة، ومساحات Spaces الثابتة، والتحليل المباشر. توثّق هذه الصفحة مخطط SQLite المباشر، وتخطيط parquet المشتق، والأمر الجديد trackio query لتنفيذ استعلامات SQL للقراءة فقط.

مكان تخزين البيانات

• توجد قواعد بيانات المشاريع المحلية في TRACKIO_DIR، والتي تكون افتراضيًا ~/.cache/huggingface/trackio.
• يُخزَّن كل مشروع كملف SQLite منفصل: {project}.db.
• تُخزَّن الوسائط والملفات المرفوعة تحت TRACKIO_DIR/media/.
• يُكتب كل مسار (trace) أيضًا كملف جلسة وكيل قابل للعرض على Hub تحت TRACKIO_DIR/traces/ (على Space، بادئة traces/ الخاصة بالحاوية). هذه ملفات عرض مخصصة لعارض مسارات الوكلاء على Hub؛ بينما تبقى جدول traces هو المرجع المعتمد. راجع المسارات (Traces).
• عند المزامنة مع Hugging Face، يقوم Trackio بتصدير ملفات parquet من قاعدة بيانات SQLite قبل الرفع.

استعلام البيانات مباشرة

استخدم سطر الأوامر عندما تحتاج إلى استعلام شامل لا تغطيه أوامر trackio list أو trackio get بالفعل:

trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name ORDER BY last_step DESC"

أضف --json للحصول على مخرجات قابلة للقراءة آليًا:

trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name" --json

يعمل الأمر نفسه مع مساحة (Space) عن بُعد:

trackio query project --project "my-project" --sql "SELECT COUNT(*) AS num_alerts FROM alerts" --space username/my-space --json

يقبل trackio query فقط استعلامات SELECT وWITH للقراءة فقط، واستعلامات PRAGMA الآمنة للمخطط، بما في ذلك قراءة PRAGMA user_version.

مخطط SQLite

يُعرَّف المخطط الحي في trackio/sqlite_storage.py بواسطة SQLiteStorage.init_db().

المقاييس

الفهارس:

• idx_metrics_run_step على (run_name, step)
• idx_metrics_run_timestamp على (run_name, timestamp)
• idx_metrics_log_id فهرس جزئي فريد على log_id
• idx_metrics_pending فهرس جزئي على space_id

إعدادات

الفهارس والقيود:

• UNIQUE(run_name)
• idx_configs_run_name على (run_name)

system_metrics

الفهارس:

• idx_system_metrics_run_timestamp على (run_name, timestamp)
• idx_system_metrics_log_id فهرس جزئي فريد على log_id
• فهرس جزئي idx_system_metrics_pending على space_id

تتبعات

الفهارس:

• idx_traces_run_step على (run_id, step)
• idx_traces_run_timestamp على (run_id, timestamp)
• idx_traces_search على search_text

project_metadata

pending_uploads

تنبيهات

الفهارس:

• idx_alerts_run على (run_name)
• idx_alerts_timestamp على (timestamp)
• idx_alerts_alert_id فهرس جزئي فريد على alert_id

artifacts

الفهارس والقيود:

• UNIQUE(name)

artifact_versions

الفهارس والقيود:

• UNIQUE(artifact_id, version)
• UNIQUE(artifact_id, manifest_digest)

artifact_aliases

الفهارس والقيود:

• PRIMARY KEY (artifact_id, alias)

run_artifact_links

الفهارس والقيود:

• CHECK(direction IN ('input', 'output'))
• idx_run_artifact_links_run على (run_id, run_name)
• idx_run_artifact_links_version على (artifact_version_id)
• idx_run_artifact_links_unique فهرس فريد على (run_id, artifact_version_id, direction)

جداول السجل

قواعد بيانات Registry — وهي مشاريع تُسمّى registry-<name>، وتُنشأ بواسطة Api.create_registry — تحتوي على الجداول القياسية المذكورة أعلاه بالإضافة إلى الجداول الأربعة أدناه، والمعرّفة في trackio/registry_storage.py بواسطة RegistryStorage.init_registry_db(). تأتي أرقام إصدارات المجموعات من collections.next_version، وهو يتقدّم فقط: لا يُعاد استخدام إصدار المجموعة أبداً، حتى بعد فكّ الارتباط. كما أن كل تعديل على السجلّ يضيف صفّاً إلى registry_events ضمن نفس المعاملة.

collections

collection_links

قيود:

• UNIQUE(collection_id, source_project, source_artifact, source_version) — يُربط إصدار المصدر مرة واحدة كحد أقصى لكل مجموعة
• UNIQUE(collection_id, collection_version)

collection_aliases

قيود:

• PRIMARY KEY (collection_id, alias) — نسخة واحدة لكل مستعار في كل مجموعة

registry_events

السجل هو الشكل الرسمي للقيود: الجداول أعلاه هي طيّ له. مخزن القيود المدعوم بالحاويات يخزّن الأحداث نفسها ككائن واحد لكل حدث (انظر دليل القيود) ويحوّل هذه الجداول محليًا.

كيف تُخزَّن حمولات المقاييس

• تُخزَّن مقاييس المستخدم كنص JSON في metrics.metrics.
• تُخزَّن مقاييس النظام كنص JSON في system_metrics.metrics.
• يُخزَّن تكوين التشغيل كنص JSON في configs.config.
• تقوم واجهات برمجة التطبيقات الأعلى مستوى في Trackio بإلغاء تسلسل هذه الكتل JSON قبل إعادتها.

نمط الاستعلام المباشر الشائع:

trackio query project --project "my-project" --sql "SELECT timestamp, step, metrics FROM metrics WHERE run_name = 'run-1' ORDER BY step DESC LIMIT 5"

مثال على فحص المخطط:

trackio query project --project "my-project" --sql "PRAGMA table_info(metrics)"

تخطيط Parquet

يستمد Trackio ملفات parquet من SQLite عن طريق تسطيح أعمدة JSON إلى أعمدة عادية.

تصدير ملفات parquet محلية

SQLiteStorage.export_to_parquet() يكتب:

• {project}.parquet من metrics
• {project}_system.parquet من system_metrics
• {project}_configs.parquet من configs
• {project}_traces.parquet من traces
• {project}_{table}.parquet لكل جدول من جداول المخرجات (artifacts، artifact_versions، artifact_aliases، run_artifact_links)

تحتفظ ملفات parquet المسطحة بالأعمدة الهيكلية مثل timestamp وrun_name وstep، ثم تضيف عمودًا واحدًا لكل مفتاح موجود في حمولة JSON.

التصدير إلى Static Space ومجموعات البيانات

SQLiteStorage.export_for_static_space() يكتب:

• metrics.parquet
• aux/system_metrics.parquet
• aux/configs.parquet
• aux/traces.parquet
• aux/artifacts.parquet، aux/artifact_versions.parquet، aux/artifact_aliases.parquet، وaux/run_artifact_links.parquet
• runs.json
• settings.json

ينسخ النشر الثابت ملفات الوسائط إلى media/ وملفات الحزم إلى artifacts/blobs/sha256/{prefix}/{digest} إلى جانب هذه التصديرات، بحيث يمكن للوحة التحكم المخصصة للمتصفح فقط تقديم تنزيلات الحزم مباشرةً من مجموعة البيانات أو الدلو.

هذا هو التخطيط المستخدم للمساحات الثابتة والمجموعات البيانات المصدَّرة.

أمثلة استعلامات مفيدة

قوائم الجداول:

trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name"

ابحث عن أحدث خطوة لكل تشغيل:

trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name ORDER BY last_step DESC"

فحص التنبيهات الأخيرة:

trackio query project --project "my-project" --sql "SELECT timestamp, run_name, level, title, step FROM alerts ORDER BY timestamp DESC LIMIT 20"

فحص الإعدادات المخزنة:

trackio query project --project "my-project" --sql "SELECT run_name, created_at, config FROM configs ORDER BY created_at DESC"

إصدارات المخطط والهجرة

تسجّل قاعدة بيانات كل مشروع إصدار مخططها في PRAGMA user_version:

trackio query project --project "my-project" --sql "PRAGMA user_version"

SQLiteStorage.init_db() يرفع قاعدة البيانات إلى SCHEMA_VERSION (المعرّفة في trackio/sqlite_storage.py) كلما فُتحت للكتابة، وينقل خادم Trackio كل قاعدة بيانات مشروع عند بدء تشغيله. قواعد البيانات المكتوبة قبل وجود نظام الإصدارات تُبلّغ عن الإصدار 0 وتُرفع إلى الإصدار 1 عبر عبارات CREATE TABLE IF NOT EXISTS وALTER TABLE ... ADD COLUMN الإضافية في init_db(). يمنح الإصدار 2 قواعد البيانات المكتوبة قبل Trackio 0.24 قيمة run_id في كل جدول مرتبط بتشغيل: إذ كانت تلك الإصدارات تحدد التشغيل باسمه فقط، لذا يصبح كل اسم تشغيل تشغيلًا واحدًا بمعرّف جديد.

لتغيير المخطط أو إعادة كتابة البيانات الموجودة بطريقة لا تستطيع تلك العبارات التعبير عنها، أضف خطوة إلى _SCHEMA_MIGRATIONS وزِد قيمة SCHEMA_VERSION:

def _split_loss_column(cursor):
    cursor.execute("ALTER TABLE metrics ADD COLUMN loss REAL")
    cursor.execute("UPDATE metrics SET loss = json_extract(metrics, '$.loss')")


SCHEMA_VERSION = 3
_SCHEMA_MIGRATIONS = {2: _migrate_add_run_ids, 3: _split_loss_column}

_SCHEMA_MIGRATIONS[n] يحدّث قاعدة البيانات من الإصدار n - 1 إلى n. يُنفَّذ كل خطوة في نقطة حفظ خاصة بها معًا مع رفع رقم الإصدار، بحيث إذا فشلت خطوة ما تبقى قاعدة البيانات عند آخر إصدار اكتمل. تُترك قاعدة البيانات التي يكون إصدارها أحدث مما تعرفه Trackio قيد التشغيل دون أي تغيير.

يعتمد trackio bump على هذا: بعد إعادة تشغيل مساحة على النسخة المحلية من Trackio، يتحقق من أن كل قاعدة بيانات مشروع تُبلّغ عن SCHEMA_VERSION المحلي. ينفّذ اختبار النهاية إلى النهاية في tests/e2e-spaces/test_space_bump.py كل هجرة على بيانات كُتبت بواسطة Trackio 0.21.0 و 0.37.1.

ملاحظات حول الاستقرار

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