أوامر سطر الأوامر

توفر Trackio مجموعة شاملة من أوامر سطر الأوامل (CLI) التي تتيح لك الاستعلام عن معلومات المشاريع، والتشغيلات، والمقاييس، ومساحات HF دون الحاجة إلى تشغيل خادم MCP. تعمل الأوامر على البيانات المحلية افتراضيًا، أو على مساحة HF عن بُعد عند توفير --space. وهذا مفيد بشكل خاص لوكلاء LLM وسكربتات الأتمتة. ومع المخرجات المنظمة بصيغة JSON والوصول البرمجي إلى جميع بيانات التجارب، صُممت Trackio لدعم التجارب الآلية لتعلم الآلة التي تُشغَّل بواسطة LLMs.

استعلام عن المساحات عن بُعد

تدعم جميع أوامر list وget وquery التي تقرأ بيانات لوحة التحكم الاستعلام عن مساحة Hugging Face عن بُعد بدلاً من البيانات المحلية. مرّر علم --space مع معرّف مساحة أو عنوان URL كامل:

# Using a Space ID
trackio list projects --space username/my-space

# Using a Space URL
trackio list projects --space https://huggingface.co/proxy/username-my-space.hf.space

# Works with any list/get/query command
trackio get metric --project "my-project" --run "my-run" --metric "loss" --space username/my-space

بالنسبة إلى مساحات (Spaces) خاصة، مرّر --hf-token أو تأكد من تسجيل الدخول عبر huggingface-cli login:

trackio list projects --space username/private-space --hf-token hf_xxxxx

ملاحظة: لا تدعم الأوامر show وstatus وsync وfreeze وskills وregistry وlist spaces الخيار --space. استخدم trackio list spaces للاطلاع على لوحات تحكم Trackio على Hugging Face Hub، ثم مرّر أحد معرّفات Space تلك إلى أوامر مثل trackio list projects --space username/my-space.

أوامر السجل

أنشئ سجلاً (registry) و، عند الحاجة، عرّف مجموعة مُنمّطة (typed collection) قبل ربط العناصر بها:

trackio registry create models --description "Models we deploy"
trackio registry create-collection models/churn-model --type model --description "Churn predictor"

اربط إصدارًا لقطعة محلية، أو ترقِ إصدار مجموعة عن طريق نقل مستعار، أو ألغِ ربط إصدار:

trackio registry link models/churn-model experiments/resnet:v3 --alias staging
trackio registry promote models/churn-model production v0
trackio registry unlink models/churn-model v0

فحص المجموعات وسجل تدقيقها:

trackio registry list models
trackio registry show models/churn-model
trackio registry events models

تقبل جميع أوامر السجل --bucket-id org/bucket لسجل مدعوم بوعاء تخزين و--json لإخراج منظم. يمكن تكرار --alias. يمكن كتابة الأهداف إما على شكل models/churn-model أو registry-models/churn-model.

يحلل أمر link project/artifact:version-or-alias من بيانات Trackio المحلية؛ ويُستبعد لاحقة latest لحلّ latest. لا يزال نشر عنصر موجود فقط على Space عن بُعد يستخدم واجهة برمجة التطبيقات بلغة بايثون حتى تتمكن Trackio من تسجيل إحداثيات التخزين عن بُعد للمصدر.

أمر المزامنة

رفع مشروع محلي إلى مساحة Hugging Face:

trackio sync --project "my-project" --space-id "username/space_id"

النشر كـ Space ثابت (يقرأ من حاوية HF Bucket، ولا يتطلب خادمًا):

trackio sync --project "my-project" --space-id "username/space_id" --sdk static

تقدّم مساحات Static البيانات مباشرةً من المتصفح، ولذلك تتطلب بيانات لقطة عامة. لا يُدعم --sdk static --private؛ استخدم Gradio SDK الافتراضي للوحات التحكم الخاصة.

مزامنة جميع المشاريع التي تحتوي على بيانات غير متزامنة مع مساحاتها (Spaces) المُهيّأة:

trackio sync --all

أمر التجميد

إنشاء لقطة ثابتة للقراءة فقط من مساحة Gradio نشطة:

trackio freeze --space-id "username/my-space" --project "my-project"

تحديد مساحة وجهة مخصصة:

trackio freeze --space-id "username/my-space" --project "my-project" --new-space-id "username/my-snapshot"

ملاحظة: يجب أن يكون المصدر مساحة Gradio مع تثبيت دلو عند /data. إذا كانت مساحة الوجهة موجودة مسبقًا وليست مساحة Trackio ثابتة، فسيرفض freeze تجاوزها. المساحة المجمّدة هي لقطة. المقاييس المتزامنة لاحقًا مع مساحة Gradio الأصلية لن تظهر في المساحة الثابتة المجمّدة ما لم تُشغّل freeze مرة أخرى. تتطلب اللقطات الثابتة المجمّدة بيانات وجهة عامة، لذا لا يُدعم trackio freeze --private.

Bump

ترقية مساحة Trackio موجودة إلى إصدار Trackio المثبّت محليًا:

trackio bump username/my-space

trackio bump --space username/my-space يؤدي نفس الشيء.

تُوقف المساحة مؤقتًا أثناء ترقية، لذا تستمر مهام التدريب في تسجيل البيانات إلى صندوق الوارد الخاص بالمساحة. يتم نسخ قواعد بياناتها احتياطيًا إلى trackio-backups/ في نفس الدلو، ويُحدَّث تثبيت Trackio الخاص بها، ثم تُعاد تشغيلها بحيث تنقل النسخة الجديدة البيانات. إذا فشلت المساحة المُحدَّثة في البدء أو أبلغت عن عدد صفوف أقل مما كان عليه سابقًا، يتم استعادة النسخة الاحتياطية وملفات المساحة السابقة.

لإبقاء المساحة الأصلية دون تغيير، انسخها مع دلوها إلى مساحة جديدة تعمل بالإصدار المحلي بدلاً من ذلك:

trackio bump username/my-space --new-space username/my-space-v2 --new-bucket username/my-space-v2-bucket

ملاحظة: يدعم bump مساحات Gradio التي تعمل بإصدار Trackio 0.21.0 أو أحدث مع وجود دلو (bucket) مُثبَّت في /data، ولا يُجري أي ترقية عكسية (downgrade) للمساحة. كانت المساحات الأقدم تخزّن بياناتها في مجموعة بيانات Hugging Face بدلاً من الدلو.

أوامر القائمة

عرض جميع المشاريع

list_projects

trackio list projects

```json { "translation": "الإخراج بتنسيق JSON:" } ```

trackio list projects --json

قائمة مساحات Trackio

list لوحات تحكم Trackio الخاصة بـ Spaces التي تملكها حسابك ومنظماتك على Hugging Face:

trackio list spaces

```json { "translation": "الإخراج بتنسيق JSON:" } ```

trackio list spaces --json

قائمة مساحات Trackio تحت نطاق مستخدم أو منظمة محددة:

trackio list spaces --author "username-or-org"

تقييد عدد المساحات المُعاد:

trackio list spaces --limit 10

بالنسبة إلى مساحات (Spaces) خاصة، مرّر --hf-token أو تأكد من تسجيل الدخول عبر huggingface-cli login.

عرض قائمة التشغيلات لمشروع

list_runs

trackio list runs --project "my-project"

```json { "translation": "الإخراج بتنسيق JSON:" } ```

trackio list runs --project "my-project" --json

قائمة مقاييس تشغيل

قائمة بجميع المقاييس التي يتم تتبعها في تشغيل محدد:

trackio list metrics --project "my-project" --run "my-run"

```json { "translation": "الإخراج بتنسيق JSON:" } ```

trackio list metrics --project "my-project" --run "my-run" --json

قائمة مقاييس النظام لتشغيل

list جميع مقاييس النظام (مثل مقاييس GPU) لتشغيل محدد:

trackio list system-metrics --project "my-project" --run "my-run"

```json { "translation": "الإخراج بتنسيق JSON:" } ```

trackio list system-metrics --project "my-project" --run "my-run" --json

قائمة التقارير

عرض تقارير Markdown في مشروع (عبر جميع التشغيلات):

trackio list reports --project "my-project"

قائمة تقارير Markdown لتشغيل محدد:

trackio list reports --project "my-project" --run "my-run"

```json { "translation": "الإخراج بتنسيق JSON:" } ```

trackio list reports --project "my-project" --run "my-run" --json

قائمة التتبعات

قائمة التتبعات (جلسات الوكيل أو المحادثة) عبر جميع التشغيلات في المشروع:

trackio list traces --project "my-project"

تعرض كل صف حالة التتبع، زمن التأخير الفعلي، التكلفة، عدد العمليات، وطلب المستخدم الذي بدأه. قم بالتصفية حسب التشغيل أو الخطوة أو النص:

trackio list traces --project "my-project" --run "production"
trackio list traces --project "my-project" --step 12
trackio list traces --project "my-project" --search "rate limit"

تبحث المطابقة في محتوى الرسالة، وبيانات التتبع الوصفية، واسم كل نطاق، ونوعه، ونموذجه، وحالته، وخطؤه. تحكّم في الترتيب والتصفّح:

trackio list traces --project "my-project" --sort step_desc --limit 100 --offset 50

يقبل --sort القيم request_time_desc (الافتراضي)، وrequest_time_asc، وstep_asc، وstep_desc. عند إضافة --json، يتم تضمين ملخص summary لكل تتبّع.

الحصول على الأوامر

الحصول على التتبع

اعرض أثرًا واحدًا مع شجرة التنفيذ الكاملة الخاصة به:

trackio get trace --project "my-project" --trace-id "fe04ed264a8a4bd6afcf266b56d9297e"

Trace fe04ed264a8a4bd6afcf266b56d9297e
  Run:      production
  Totals:   error | 25.0s | $0.33 | 101338 in / 1804 out tokens | 21 operation(s)

Execution:
  answer-research-question [span]  25.0s
    generate-research-response [span]  23.7s
      acquire-sandbox [span]  914ms
      dispatch-model-request [span]  2.18s
        provider-request [generation]  2.18s  my-model  8347->239 tok  $0.03
      ERROR run-bash-command [tool]  168ms
        -> {"exit_code": 2, "stderr": "hf datasets list: error: unrecognized arguments: --full"}

يقبل --trace-id المعرّف المختصر الذي يطبعه trackio list traces أو المعرّف الكامل المخزّن. أضف --json للحصول على التتبع الكامل، بما في ذلك مدخلات ومخرجات الأجزاء.

الحصول على ملخص التتبع

اجمع كل نطاق حسب اسم العملية لمعرفة أين تذهب زمن الاستجابة والرموز والتكلفة، وأي العمليات التي تفشل:

trackio get trace-summary --project "my-project"

operation                  | kind       | calls | errors | avg_ms  | max_ms  | input_tokens | output_tokens | cost_usd
provider-request           | generation | 205   | 0      | 3380.8  | 5535.0  | 2915829      | 63020         | 9.6928
run-bash-command           | tool       | 157   | 25     | 818.4   | 1548.0  | 0            | 0             | 0.0
acquire-sandbox            | span       | 48    | 0      | 2438.6  | 10615.0 | 0            | 0             | 0.0

حدّد الأمر على تشغيل واحد باستخدام --run، أو اطبع صفوفًا قابلة للقراءة آليًا باستخدام --json. بالنسبة لأي شيء لا تغطيه عملية التجميع، استعلم مباشرةً عن جدول traces باستخدام trackio query project — عمود spans هو عمود JSON، لذا يعمل json_each.

الحصول على ملخص المشروع

احصل على ملخص مفصّل لمشروع، بما في ذلك عدد التشغيلات والنشاط الأخير:

trackio get project --project "my-project"

```json { "translation": "الإخراج بتنسيق JSON:" } ```

trackio get project --project "my-project" --json

يتضمن الملخص:

• اسم المشروع
• عدد مرات التشغيل
• قائمة بجميع التشغيلات
• آخر نشاط (الخطوة القصوى عبر جميع التشغيلات)

الحصول على ملخص التشغيل

احصل على ملخص مفصّل لتشغيل محدد، بما في ذلك المقاييس والإعدادات:

trackio get run --project "my-project" --run "my-run"

```json { "translation": "الإخراج بتنسيق JSON:" } ```

trackio get run --project "my-project" --run "my-run" --json

يتضمن الملخص:

• أسماء المشاريع والتشغيل
• عدد إدخالات السجل
• الخطوة الأخيرة
• قائمة بجميع المقاييس
• إعدادات التشغيل (باستثناء الحقول الداخلية)

الحصول على قيم المقاييس

احصل على جميع القيم لمقياس محدد في تشغيل:

trackio get metric --project "my-project" --run "my-run" --metric "loss"

```json { "translation": "الإخراج بتنسيق JSON:" } ```

trackio get metric --project "my-project" --run "my-run" --metric "loss" --json

يشمل المخرجات:

• رقم الخطوة
• الطابع الزمني
• قيمة المقياس

التصفية حسب الخطوة أو الوقت

يمكنك تصفية قيم المقاييس إلى خطوة محددة أو نافذة زمنية حول خطوة/طابع زمني. وهذا مفيد لفحص المقاييس حول الوقت الذي صدر فيه تنبيه.

# Get metric at exactly step 200
trackio get metric --project "my-project" --run "my-run" --metric "loss" --step 200

# Get metrics in a window around step 200 (±10 steps, the default)
trackio get metric --project "my-project" --run "my-run" --metric "loss" --around 200

# Get metrics in a window around step 200 (±50 steps)
trackio get metric --project "my-project" --run "my-run" --metric "loss" --around 200 --window 50

# Get metrics within ±60 seconds of a timestamp
trackio get metric --project "my-project" --run "my-run" --metric "loss" --at-time "2025-06-01T12:05:30" --window 60

الحصول على لقطة للمقاييس

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

# All metrics at step 200
trackio get snapshot --project "my-project" --run "my-run" --step 200 --json

# All metrics in a window around step 200 (±5 steps)
trackio get snapshot --project "my-project" --run "my-run" --around 200 --window 5 --json

# All metrics within ±60 seconds of a timestamp
trackio get snapshot --project "my-project" --run "my-run" --at-time "2025-06-01T12:05:30" --window 60 --json

مثال على مخرجات JSON:

{
  "project": "my-project",
  "run": "my-run",
  "around": 200,
  "window": 5,
  "metrics": {
    "loss": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.42},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.45}
    ],
    "accuracy": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.88},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.87}
    ],
    "lr": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.0001},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.0001}
    ]
  }
}

الحصول على قيم مقاييس النظام

احصل على قيم مقاييس النظام لتشغيل. إذا لم يتم تقديم اسم مقياس، تُعاد جميع مقاييس النظام:

# Get all system metrics
trackio get system-metric --project "my-project" --run "my-run"

# Get a specific system metric
trackio get system-metric --project "my-project" --run "my-run" --metric "gpu_utilization"

```json { "translation": "الإخراج بتنسيق JSON:" } ```

trackio get system-metric --project "my-project" --run "my-run" --metric "gpu_utilization" --json

الحصول على محتوى التقرير

اطبع إدخالات تقرير Markdown لاسم تقرير محدد في تشغيل:

trackio get report --project "my-project" --run "my-run" --report "training_report"

```json { "translation": "الإخراج بتنسيق JSON:" } ```

trackio get report --project "my-project" --run "my-run" --report "training_report" --json

أمر الاستعلام

استخدم trackio query عندما تحتاج إلى استعلام SQL للقراءة فقط شامل لا تغطيه أوامر 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 { "translation": "الإخراج بتنسيق JSON:" } ```

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

استعلام عن مساحة عن بُعد:

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

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

أمثلة شائعة على فحص المخطط:

# Inspect table columns
trackio query project --project "my-project" --sql "PRAGMA table_info(metrics)"

# Inspect indexes
trackio query project --project "my-project" --sql "PRAGMA index_list(alerts)"

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

يتضمن الاستجابة ما يلي:

• project
• query
• columns
• rows
• row_count

للحصول على تخطيط SQLite و parquet الكامل، راجع مخطط التخزين والاستعلامات المباشرة.

صيغ المخرجات

تدعم جميع أوامر list وget وquery صيغتي مخرجات:

1. قابلة للقراءة من قِبل الإنسان (الافتراضي): نص منسّق مناسب لعرضه في الطرفية
2. JSON (مع علم --json): مخرجات JSON منظمة مناسبة للاستهلاك البرمجي

معالجة الأخطاء

تشمل أوامر سطر الأوامر التحقق الشامل ومعالجة الأخطاء:

• إذا لم يكن هناك مشروع موجود، يتم عرض رسالة خطأ
• إذا لم يكن هناك تشغيل في المشروع، يتم عرض رسالة خطأ
• إذا لم يوجد مقياس في تشغيل ما، يتم عرض رسالة خطأ
• إذا لم يكن هناك تقرير موجود في تشغيل، يتم عرض رسالة خطأ
• إذا لم تكن الاستعلامات للقراءة فقط، فإن سطر الأوامر ينهي العملية مع إظهار خطأ

تُكتب جميع الأخطاء إلى stderr وتخرج الأوامر برمز خروج غير صفري.

مثال على سير عمل

إليك سير عمل نموذجي لاستكشاف بيانات Trackio الخاصة بك:

# 1. List all projects
trackio list projects

# 2. List runs in a project
trackio list runs --project "my-project"

# 3. Get project summary
trackio get project --project "my-project"

# 4. Get run summary
trackio get run --project "my-project" --run "my-run"

# 5. List metrics in the run
trackio list metrics --project "my-project" --run "my-run"

# 6. Get specific metric values
trackio get metric --project "my-project" --run "my-run" --metric "loss"

# 7. Get all metrics at a specific step (e.g. where an alert fired)
trackio get snapshot --project "my-project" --run "my-run" --step 200 --json

# 8. Get system metrics (if available)
trackio list system-metrics --project "my-project" --run "my-run"

# 9. List reports in a run
trackio list reports --project "my-project" --run "my-run"

# 10. Print report markdown in terminal
trackio get report --project "my-project" --run "my-run" --report "training_report"

# 11. Run a direct SQL query
trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name"

استعلام عن مساحة عن بُعد

يعمل نفس سير العمل مع مساحة عن بُعد — ما عليك سوى إضافة --space:

# List projects on a remote Space
trackio list projects --space username/my-space

# Get metric values from a remote Space
trackio get metric --project "my-project" --run "my-run" --metric "loss" --space username/my-space --json

حالات الاستخدام

وكلاء نماذج اللغة

تُعدّ أوامر سطر الأوامر هذه مفيدة بشكل خاص لوكلاء نماذج اللغة الكبيرة التي تحتاج إلى:

• اكتشف المشاريع والتشغيلات المتاحة
• استعلام قيم المقاييس برمجياً
• افحص المقاييس المحيطة بتنبيه باستخدام get snapshot أو get metric --around
• نفّذ SQL مباشرًا للحالات التي لا تغطيها الأوامر المهيكلة
• احصل على الملخصات دون الحاجة إلى تشغيل خادم
• تحليل مخرجات JSON منظمة لمعالجتها بشكل إضافي

سكربتات الأتمتة

يمكنك استخدام هذه الأوامر في سكربتات shell وخطوط أتمتة:

#!/bin/bash
PROJECT="my-project"
RUN="my-run"

# Get the latest loss value
LATEST_LOSS=$(trackio get metric --project "$PROJECT" --run "$RUN" --metric "loss" --json | jq -r '.values[-1].value')
echo "Latest loss: $LATEST_LOSS"

التكامل مع أدوات أخرى

يجعل تنسيق المخرجات بصيغة JSON من السهل التكامل مع أدوات أخرى:

# Pipe to jq for filtering
trackio list runs --project "my-project" --json | jq '.runs[] | select(startswith("train"))'

# Export to file
trackio get run --project "my-project" --run "my-run" --json > run_summary.json