متغيرات البيئة

يستخدم Trackio متغيرات البيئة (Environment Variables) لضبط جوانب مختلفة من سلوكه، لا سيما عند النشر على Hugging Face Spaces ولضمان استمرارية البيانات. تغطي هذه الدليل المتغيرات البيئية الرئيسية وكيفية استخدامها.

متغيرات البيئة الأساسية

TRACKIO_DIR

يحدد مجلداً مخصصاً لتخزين بيانات Trackio. بشكل افتراضي، تخزن Trackio البيانات في ~/.cache/huggingface/trackio/.

export TRACKIO_DIR="/path/to/trackio/data"

ملاحظة: تنطبق متغير البيئة هذا طالما أن Trackio لا يعمل في Space مع تمكين التخزين الدائم. إذا كان Trackio يعمل في Space مع تمكين التخزين الدائم (يتم اكتشاف ذلك عبر متغير البيئة PERSISTANT_STORAGE_ENABLED)، فسيتم تخزين بيانات Trackio في /data/trackio.

TRACKIO_SERVER_URL

عنوان URL الأساسي لخادم Trackio مُستضاف ذاتيًا (http:// أو https://). يمكنك تضمين write_token في سلسلة الاستعلام (كما في full_url من trackio.show())، أو إبقاء العنوان كما هو دون إضافات وإعداد TRACKIO_WRITE_TOKEN بدلاً من ذلك. عند الإعداد، تُرسل trackio.init() المقاييس إلى ذلك الخادم. يعادل تمرير server_url= إلى trackio.init().

الأولوية: إذا تم تعيين TRACKIO_SPACE_ID أيضًا (أو تم تمرير space_id في الكود)، يتم استخدام مساحة Hugging Face ويتجاهل TRACKIO_SERVER_URL. تنطبق القاعدة نفسها عند تمرير كل من space_id وserver_url: space_id هو الفائز.

راجع استضافة الخادم ذاتيًا.

export TRACKIO_SERVER_URL="http://127.0.0.1:7860"
export TRACKIO_WRITE_TOKEN="YOUR_TOKEN"

TRACKIO_WRITE_TOKEN

رمز الكتابة write token للوحة تحكم خادم Trackio المستضاف ذاتيًا (نفس قيمة معامل الاستعلام write_token في عنوان URL للوصول للكتابة). عند ضبطه على خادم Trackio، تُستخدم هذه القيمة كرمز كتابة للخادم بدلاً من توليد رمز عشوائي عند بدء التشغيل. عند ضبطه على عميل Trackio، استخدم هذا عندما يكون TRACKIO_SERVER_URL أو server_url عنوان URL أساسي بدون معاملات استعلام. يرسل العميل هذا الرمز مع كل طلب (على سبيل المثال كترويسة X-Trackio-Write-Token) حتى يتم مصادقة استهلاك المقاييس والرفع عند عدم التشغيل على Hugging Face Spaces.

TRACKIO_FRONTEND_DIR

مسار إلى مجلد واجهة أمامية ثابتة مخصص لـ Trackio. يجب أن يحتوي المجلد على index.html.

عند تعيينه، يستخدم Trackio الواجهة الأمامية المذكورة لـ trackio.show() ولعمليات النشر مثل trackio.sync() وtrackio.freeze()، ما لم يتم تمرير حجة frontend_dir / --frontend صريحة.

export TRACKIO_FRONTEND_DIR="/path/to/my-trackio-frontend"

إذا كان المجلد المُعدّ غير صالح، يتجاهل Trackio ذلك ويعود إلى منطق اختيار الواجهة الأمامية المدمج. ولا ينطبق سلوك نسخ قالب البداية التلقائي إلا عندما يشير الحجة الصريحة frontend_dir / --frontend إلى مجلد غير موجود أو فارغ.

TRACKIO_LOGO_LIGHT_URL وTRACKIO_LOGO_DARK_URL

خصص الشعارات المعروضة في لوحة تحكم Trackio لموضوعي الفاتح والداكن. يمكنك تقديم عناوين URL لشعارات مخصصة. لاحظ أنه يجب تقديم متغيري البيئة معًا؛ وإلا فسيتم استخدام الافتراضي الخاص بـ Trackio لأي متغير غير مقدم.

export TRACKIO_LOGO_LIGHT_URL="https://example.com/logo-light.png"
export TRACKIO_LOGO_DARK_URL="https://example.com/logo-dark.png"

ملاحظة: بالنسبة إلى مساحات Trackio عن بُعد، تُطبَّق متغيرات البيئة هذه فقط عند إنشاء المساحة لأول مرة عبر trackio.init(space_id=...). لتغيير الشعارات في مساحة موجودة مسبقًا، حدّث متغيرات المساحة مباشرةً في إعدادات مساحة Hugging Face.

TRACKIO_PLOT_ORDER

يتحكم في ترتيب المخططات ومجموعات المقاييس في لوحة تحكم Trackio. يجب أن تكون القيمة قائمة مفصولة بفواصل من أنماط المقاييس التي تحدد الترتيب المطلوب. تُحفظ المجموعات - إذا تم تحديد train/loss أولاً، فستظهر جميع مقاييس train/* الأخرى معًا في مجموعة train، مع ظهور train/loss أولاً داخل تلك المجموعة.

إذا لم يطابق نمط أي مقاييس، يتم تجاهله ببساطة دون التسبب في أخطاء.

export TRACKIO_PLOT_ORDER="train/loss,val/loss"


**Pattern Matching:**
- **Exact matches**: `train/loss` matches exactly `train/loss`
- **Group wildcards**: `train/*` matches all metrics starting with `train/`
- **Partial wildcards**: `*gpu*` matches any metric containing "gpu"

**Behavior:**
- Metrics are grouped first (e.g., all `train/*` metrics stay together)
- Within each group, metrics are ordered according to the specified patterns
- Groups appear in the order of their first matching pattern
- Unspecified metrics appear in alphabetical order after specified ones

> **Note:** For remote Trackio Spaces, this environment variable is only applied when the Space is first created via `trackio.init(space_id=...)`. To change the plot order on an existing Space, update the `TRACKIO_PLOT_ORDER` Space variable directly in the Hugging Face Space settings.

### `TRACKIO_THEME`

Sets the theme for the Trackio dashboard. Can be a built-in Gradio theme name or a theme from the Hugging Face Hub.

```bash
# Built-in themes
export TRACKIO_THEME="soft"
export TRACKIO_THEME="citrus"
export TRACKIO_THEME="monochrome"

# Themes from the Hub
export TRACKIO_THEME="gstaff/xkcd"
export TRACKIO_THEME="ParityError/Anime"

ملاحظة: بالنسبة إلى مساحات Trackio عن بُعد، يُطبَّق متغير البيئة هذا فقط عند إنشاء المساحة لأول مرة عبر trackio.init(space_id=...). لتغيير السمة في مساحة موجودة مسبقًا، حدّث متغير TRACKIO_THEME الخاص بالمساحة مباشرةً في إعدادات مساحة Hugging Face.

TRACKIO_COLOR_PALETTE

يُخصّص لوحة الألوان المستخدمة لخطوط الرسوم البيانية في لوحة تحكم Trackio. يجب أن تكون القيمة قائمة رموز ألوان سداسية (hex) مفصولة بفواصل. سيتم تدوير هذه الألوان عند رسم عدة تشغيلات.

export TRACKIO_COLOR_PALETTE="#FF0000,#00FF00,#0000FF,#FFFF00,#FF00FF,#00FFFF"

لوحة الألوان الافتراضية: #A8769B, #E89957, #3B82F6, #10B981, #EF4444, #8B5CF6, #14B8A6, #F59E0B, #EC4899, #06B6D4

TRACKIO_TABLE_TRUNCATE_LENGTH

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

export TRACKIO_TABLE_TRUNCATE_LENGTH="500"

TRACKIO_STORAGE_MODE

يتحكم في كيفية حفظ Trackio للبيانات محليًا. القيم المسموح بها: auto (الافتراضي)، sqlite، jsonl.

• sqlite: تكتب عمليات التدريب مباشرةً إلى قاعدة بيانات SQLite الخاصة بالمشروع (وهو السلوك التاريخي).
• jsonl: تكتب عمليات التدريب مقاطع JSONL غير قابلة للتعديل (append-only) في TRACKIO_DIR/inbox/، ملفًا واحدًا لكل عملية؛ يستورد خادم لوحة التحكم (trackio show) هذه المقاطع إلى SQLite. يتجنّب هذا النهج تمامًا وجود كتابات متزامنة على SQLite، مما يجعل Trackio آمنًا على أنظمة الملفات الشبكية (NFS، Lustre، FSx، GPFS، WekaFS، CephFS، …) حيث تكون آليات قفل SQLite وخصائص mmap غير موثوقة.
• auto: يختار jsonl تلقائيًا عند اكتشاف أن TRACKIO_DIR يقع على نظام ملفات شبكة (لنظام لينكس فقط)، وإلا يختار sqlite.

export TRACKIO_STORAGE_MODE="jsonl"

TRACKIO_INBOX_POLL_INTERVAL

التردد (بالثواني) الذي يفحص به خادم لوحة المعلومات ومساحات Trackio وجود مقاطع JSONL جديدة للاستيراد، سواء من مجلد الوارد المحلي أو من وارد Bucket على Hugging Face. القيمة الافتراضية هي 15؛ وتُضبط القيم الأقل من 5 إلى 5.

export TRACKIO_INBOX_POLL_INTERVAL="30"

TRACKIO_SQLITE_* (متقدم)

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

• TRACKIO_SQLITE_JOURNAL_MODE: أحد wal، delete، truncate، persist، memory، off. القيمة الافتراضية هي wal محليًا وdelete على Spaces.
• TRACKIO_SQLITE_MMAP_SIZE: حجم الإدخال/الإخراج المرمّز في الذاكرة (memory-mapped I/O) بالبايت. القيمة الافتراضية هي 0 (معطّل) في كل مكان، لأن عمليات القراءة المرمّزة في الذاكرة هي المحفّز المباشر لأعطال SIGBUS على أنظمة الملفات الشبكية، ولا تحقق مكسبًا يُذكر لأعباء عمل Trackio.
• TRACKIO_SQLITE_SYNCHRONOUS: أحد off، normal، full، extra. القيمة الافتراضية هي normal.
• TRACKIO_SQLITE_LOCKING_MODE: أحد normal أو exclusive. القيمة الافتراضية هي exclusive على Spaces، وnormal في أي مكان آخر.
• TRACKIO_SQLITE_TEMP_STORE: أحد default، file، memory. القيمة الافتراضية هي memory.

إعداد العنقود الموصى به: إذا كان دليل المنزل أو دليل الكاش الخاص بك موجودًا على نظام ملفات مشترك (/fsx، Lustre، NFS، GPFS، WekaFS، …)، فإما أن تُوجّه TRACKIO_DIR إلى القرص المحلي للعقدة (مثل /tmp أو $SLURM_TMPDIR)، أو تعتمد على TRACKIO_STORAGE_MODE=auto الذي يكتشف أنظمة الملفات الشبكية ويتحول إلى تسجيل مقاطع JSONL. إذا كان عليك كتابة SQLite مباشرةً على نظام ملفات مشترك، فقم بإعداد:

export TRACKIO_SQLITE_JOURNAL_MODE="delete"
export TRACKIO_SQLITE_MMAP_SIZE="0"

TRACKIO_WEBHOOK_URL

يُعيّن رابط ويبهوك (webhook) عالمي للتنبيهات. عند تعيينه، سيقوم كل استدعاء لـ trackio.alert() بإرسال حمولة التنبيه (payload) عبر طلب POST إلى هذا الرابط. يدعم روابط ويبهوك الخاصة بـ Slack و Discord بشكل أصلي (تُصيغ الحمولات تلقائيًا). يمكن تجاوز هذا الإعداد لكل تنبيه أو لكل تشغيل عبر معامل webhook_url.

export TRACKIO_WEBHOOK_URL="https://hooks.slack.com/services/T.../B.../xxx"

راجع دليل التنبيهات لمزيد من التفاصيل.

TRACKIO_WEBHOOK_MIN_LEVEL

يحدد الحد الأدنى لمستوى التنبيه الذي يجب إرساله إلى نقاط الويب (webhooks). لا تُرسل التنبيهات التي تقل عن هذا المستوى إلى وجهات الويب هوك، لكنها لا تزال تُطبع في الطرفية، وتُخزَّن في قاعدة البيانات، وتُعرض في لوحة التحكم.

القيم المسموح بها: info، warn، error.

export TRACKIO_WEBHOOK_MIN_LEVEL="warn"

مع warn، تُرسل تنبيهات WARN وERROR فقط إلى عناوين ويبهوك.

TRACKIO_CAPTURE_CONSOLE

عند ضبطه على 1 أو true، يلتقط Trackio كل ما يُكتب إلى stdout و stderr أثناء التشغيل ويعرضه على صفحة التشغيل في لوحة التحكم. يعادل ذلك تمرير capture_console=True إلى trackio.init()؛ حيث يأخذ الحُجج الصريح capture_console الأولوية.

export TRACKIO_CAPTURE_CONSOLE=1

راجع التقاط إخراج وحدة التحكم وأمر الإقلاع لمزيد من التفاصيل.

TRACKIO_HANDLE_SIGTERM

عند ضبطه على 1 أو true، يقوم trackio.init() بتثبيت مُعالج لـ SIGTERM يحوّل الإشارة إلى إنهاء عادي، بحيث يُنهي التشغيل ويُحفظ آخر مقاييسه ومخرجاته على وحدة التحكم عند إيقاف العملية بسبب حد زمني في Slurm، أو docker stop، أو طرد من Kubernetes. يبقى رمز الخروج 143. يتم تثبيت المُعالج فقط من الخيط الرئيسي وفقط عندما لا يكون هناك مُعالج آخر لـ SIGTERM مضبوطاً. يكون هذا الخيار معطلاً افتراضياً لأنه يغيّر كيفية استجابة العملية بأكملها لـ SIGTERM: على سبيل المثال، تنتظر العملية الخيوط غير الخادمة (non-daemon threads) قبل الخروج، والأطر التي تُسلسل المُعالجات الموجودة مسبقاً (مثل إعادة الطابور التلقائي في Slurm الخاصة بـ PyTorch Lightning) ستخرج بدلاً من تجاهل الإشارة.

export TRACKIO_HANDLE_SIGTERM=1

TRACKIO_BUCKET_ID

معرّف حاوية Hugging Face (مثل username/bucketname) المستخدمة لحفظ بيانات Trackio عند التشغيل على مساحة Hugging Face. يتم ضبط هذا المعرّف عادةً تلقائيًا على المساحة عند إنشائها عبر trackio.init(space_id=...) أو trackio.sync(...)؛ حيث يتم توليد حاوية تلقائيًا من معرّف المساحة ما لم يتم تقديم bucket_id صريح.

export TRACKIO_BUCKET_ID="username/my-trackio-bucket"

TRACKIO_DATASET_ID (مُتروك)

غير مدعوم: أصبح حفظ بيانات Trackio في مجموعة بيانات Hugging Face (dataset_id / TRACKIO_DATASET_ID) غير مدعوم وسيتم إزالته في إصدار مستقبلي من Trackio. استخدم حاوية Hugging Face بدلاً من ذلك (bucket_id / TRACKIO_BUCKET_ID).

معرّف مجموعة بيانات Hugging Face (مثل username/datasetname) التي تُزامن معها مساحة Trackio بياناتها عبر مجدول التزامات في الخلفية. عند ضبطه على مساحة، تُصدر Trackio تحذيرًا بالإيقاف وتواصل المزامنة مع مجموعة البيانات حاليًا.

export TRACKIO_DATASET_ID="username/my-trackio-dataset"

HF_TOKEN

رمز المصادقة الخاص بك في Hugging Face. مطلوب لإنشاء Spaces وBuckets على Hugging Face. اضبطه محليًا عند النشر إلى Spaces من جهازك. يجب أن يكون لديه صلاحيات write للمساحة الاسم (namespace) التي تنشر فيها لوحة تحكم Trackio.

export HF_TOKEN="hf_xxxxxxxxxxxxx"

متغيرات بيئة Gradio

بما أن Trackio مبني على Gradio، يمكنك استخدام متغيرات البيئة التي يستخدمها Gradio للتحكم في سلوك Trackio. فيما يلي بعض الأمثلة:

GRADIO_SERVER_PORT

يحدد المنفذ الذي سيُطلق عليه لوحة تحكم Tradio. القيمة الافتراضية هي 7860

export GRADIO_SERVER_PORT=8000

GRADIO_SERVER_NAME

يحدد اسم المضيف لخادم لوحة تحكم Trackio. لجعل لوحة التحكم قابلة للوصول من أي عنوان IP، اضبط هذا على "0.0.0.0"

export GRADIO_SERVER_NAME="0.0.0.0"

GRADIO_MCP_SERVER

تفعيل وظيفة خادم MCP (بروتوكول سياق النموذج) في Trackio. عند التفعيل، سيتم إعداد لوحة تحكم Trackio كخادم MCP وستُعرَض بعض الدوال كأدوات MCP يمكن للنماذج اللغوية الكبيرة (LLMs) استخدامها (مثل قراءة المقاييس المسجلة).

export GRADIO_MCP_SERVER="True"

راجع هذه القائمة الأكثر شمولاً لمتغيرات البيئة التي يستخدمها Gradio.