السجل

التسجيل registry هو فهرس مشترك لأفضل إصدارات من منتجاتك. يعرض المشروع المنتجات التي أنتجتها تجاربك؛ بينما يعرض التسجيل المنتجات المختارة عبر المشاريع.

تحتوي السجل على مجموعات. تمثل كل مجموعة أصلًا واحدًا — نموذج تعيد تدريبه مع مرور الوقت، أو مجموعة تقييم مرجعية — وتحتفظ بالإصدارات منه التي اخترت نشرها. تقوم بـربط إصدار من الأصول بمجموعة. الرابط هو مؤشر إلى الإصدار المصدر: لا يتم نسخ أي شيء. ثم ترقّي الإصدار المرتبط عبر مراحل دورة الحياة عن طريق نقل المستعرات مثل staging وproduction.

على سبيل المثال، قد يحتوي سجل باسم models على مجموعة واحدة لكل نموذج قابل للنشر، بينما قد يحتوي سجل باسم datasets على مجموعة واحدة لكل معيار تقييم. وتترك لك حرية تقسيم الأصول عبر السجلات والمجموعات.

يتميز كل مجموعة بسلسلة إصدارات خاصة بها (v0، v1، …) مستقلة عن أرقام إصدارات العناصر المصدرية، وقد تشير إصداراتها إلى عناصر مصدرية مختلفة في مشاريع مختلفة. يحدد كل مستعار إصدارًا واحدًا بالضبط لكل مجموعة.

يكون السجل إما محليًا — حيث يُخزَّن بجانب بيانات Trackio الأخرى الخاصة بك كمشروع باسم registry-models (البادئة registry- محجوزة) — أو مدعومًا بواسطة حاوية Hugging Face، وهو ما يجعله قابلًا للوصول من أجهزة أخرى ومن عمليات التسجيل في Space. راجع السجلات عن بُعد.

إنشاء سجل

أنشئ سجلاً باستخدام Api.create_registry():

import trackio

registry = trackio.Api().create_registry("models", description="Our deployable models")

يُخزَّن description الاختياري في السجل ويمكن قراءته على شكل registry.description.

لا يتم إنشاء السجلات (Registries) بشكل ضمني أبدًا. يؤدي الربط مع سجل غير موجود إلى رفع خطأ.

استخدم Api.registry() لجلب سجل موجود. كما يرمي استثناءً إذا لم يكن السجل موجودًا.

إنشاء مجموعة

المجموعة collection هي مجموعة من إصدارات العناصر المرتبطة داخل سجل، مع سجل إصدار واحد. قد تأتي الإصدارات من عناصر مصدرية مختلفة: إذا كان نموذج مبني على resnet ونموذج مبني على unet مرشحين لنفس المنتج القابل للنشر، اربطهما في مجموعة واحدة ليصبحا إصدارات متتالية له. أما إذا كانا منتجين منفصلين، امنح كل منهما مجموعته الخاصة.

عادةً لا تنشئ المجموعات يدويًا: فإجراء ربط إلى مجموعة غير موجودة ينشئها تلقائيًا. أنشئ مجموعة بشكل صريح عندما ترغب في تعيين وصف مسبقًا:

registry.create_collection("my-model", "model", description="The model we deploy")

أنواع المجموعات

تقبل كل مجموعة نوعًا واحدًا من type من القطع، يُثبَّت عند إنشاء المجموعة. يأتي النوع من القطعة نفسها — حقل type الذي تمرره إلى trackio.Artifact أو trackio.log_artifact — لذا فإن المجموعة التي تُنشأ بواسطة أول ارتباط تتبنى نوع تلك القطعة.

على سبيل المثال، إذا ربطت عنصر "dataset" بمجموعة تقبل عناصر "model"، فسيُطلق Trackio خطأً.

يقبل السجل نفسه كل الأنواع: يمكن أن تتعايش مجموعة نماذج ومجموعة بيانات جنبًا إلى جنب في نفس السجل.

ربط إصدار من الأداة مع مجموعة

انشر إصدارًا من المخرجات باستخدام Run.link_artifact():

import trackio

trackio.Api().create_registry("models")

run = trackio.init(project="my-experiments")
artifact = trackio.log_artifact("model.pt", name="resnet", type="model")

run.link_artifact(artifact, "registry-models/my-model", aliases=["staging"])

المسار المستهدف هو "registry-<registry>/<collection>". الجزء الأول هو الاسم الكامل للسجل، بما في ذلك البادئة.

يقبل link_artifact كائن الأداة (artifact) نفسه، لذا فإن النسخة التي تحتفظ بها هي بالضبط النسخة التي سيتم نشرها:

يمكنك أيضًا إنشاء رابط من الكائن نفسه باستخدام Artifact.link()، وهو أمر مفيد عندما لا يكون التشغيل ضمن النطاق:

artifact.link("registry-models/my-model", aliases=["staging"])

يتطلب Artifact.link أن يكون العنصر مسجلاً أو مسترجعاً مسبقاً — فهو لن يسجل مسودة نيابةً عنك — ولا يسجل الرابط أي عملية نشر.

القطعة المرتبطة

يعيد link_artifact العنصر في موقعه ضمن السجل. يكون name الخاص به هو المجموعة، وproject الخاص به هو السجل، بينما version وaliases هما الخاصيتان بالمجموعة. أما محتواه — manifest، manifest_digest، size، metadata — فهو الخاص بالإصدار المصدر، وتُشير الخصائص source_project، source_name، source_version، وsource_qualified_name إليه:

linked = run.link_artifact(artifact, "registry-models/my-model")
linked.qualified_name         # "registry-models/my-model:v0"
linked.source_qualified_name  # "my-experiments/resnet:v0"

إنشاء ارتباط لمنتج مرتبط يربط إصداره المصدر مباشرةً (مع تحذير)، لذا لا تتسلسل الروابط أبداً.

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

model = run.use_artifact("registry-models/my-model:production")
model.download()  # fetches the source version's files

يقبل المواصفة بعد المجموعة إصدار المجموعة ("v1")، أو مستعارًا ("production")، أو لا شيء للإصدار المرتبط الأحدث. عند تنزيل عنصر مرتبط، يتم جلب بايتات الإصدار المصدر الذي يشير إليه.

يمكن حاليًا حل مواقع السجل فقط عبر التشغيلات المحلية، وذلك فقط عندما يكون المصنوع المصدر متاحًا محليًا. يمكن نشر المصادر المخزنة في مساحة (Space) أو في دلو (bucket) أو على خادم مُستضاف ذاتيًا إلى سجل مدعوم بدلو، لكن حل تلك الروابط في عملية لاحقة غير مدعوم بعد. يحتفظ المصنوع المرتبط الذي تُرجعه link_artifact مباشرةً بمصدره الخاص بالمساحة أو الخادم المُستضاف ذاتيًا، ويمكن تنزيله من ذلك المصدر.

إصدارات المجموعات

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

إن ربط إصدار مصدر موجود مسبقًا في المجموعة لا يُنشئ إصدارًا جديدًا. تحصل على الإصدار الموجود، وتبقى أي aliases مرّرتها تتحرك كما هي. لا يُعاد استخدام أرقام الإصدارات أبدًا، لذا لا يمكن لإصدار منشور مثل my-model:v3 أن يتغير معناه بصمت.

ترقية إصدار مع مستعرات

يشير الاسم المستعار إلى إصدار واحد لكل مجموعة. عند إسناد اسم مستعار يحمله إصدار آخر بالفعل، يتم نقله — وهذا النقل هو الترقية. المستهلكون الذين يحلون my-model:production يتبعون الاسم المستعار، لذا لا يتغير أي شيء في المراحل اللاحقة عند نقله.

تحدث معظم عمليات الترقية عند النشر: حيث تربط إصدارًا جديدًا وتضع الاسم المستعار في نفس الاستدعاء.

run.link_artifact(artifact, "registry-models/my-model", aliases=["staging"])

لترقية إصدار موجود مسبقًا في المجموعة، أعد ربطه باستخدام الاسم المستعار. لا يُنشئ إعادة الربط شيئًا جديدًا — بل تحصل على إصدار المجموعة الموجود، وتنتقل الأسماء المستعارة التي تمررها إليه. ابحث عن مصدر الإصدار في روابط المجموعة، واحصل عليه، ثم اربطه مرة أخرى:

registry.collection("my-model").links
# [..., {"collection_version": 1, "source_project": "my-experiments",
#        "source_artifact": "resnet", "source_version": 3, ...}]

candidate = run.use_artifact("resnet:v3")
run.link_artifact(candidate, "registry-models/my-model", aliases=["production"])

يمكنك أيضًا جلبه مباشرةً من السجل:

candidate = run.use_artifact("registry-models/my-model:v1")
run.link_artifact(candidate, "registry-models/my-model", aliases=["production"])

يعمل التراجع عن الاسم المستعار إلى إصدار أقدم بنفس الطريقة.

يدير Trackio لك المستعار latest: فهو يشير دائمًا إلى أحدث إصدار مرتبط.

فك ارتباط إصدار

احذف رابطًا باستخدام Artifact.unlink()، الذي يُستدعى على المصنوع المرتبط:

linked = run.link_artifact(artifact, "registry-models/my-model")
linked.unlink()

تبقى الأداة المصدرية وملفاتها دون أي تغيير — حيث يُزال فقط انتماء المجموعة. وتُزال أي مستعرات على الرابط معها، كما لا يُعاد استخدام رقم إصدار المجموعة أبدًا، لذا لا يمكن أن يعني my-model:v0 شيئًا آخر لاحقًا. إذا كان الإصدار الذي تزيله يحمل latest، فإن هذا المستعار ينتقل إلى أعلى الإصدارات المتبقية، بحيث يستمر latest في الإشارة إلى أحدث إصدار في المجموعة.

سجلات عن بُعد

لا يوجد سجل محلي إلا على الجهاز الذي قام بإنشائه. لمشاركة فهرس بين أجهزة متعددة — أو للنشر من تشغيل يسجّل في مساحة (Space) أو خادم مُستضاف ذاتيًا — يجب دعم السجل بـ حاوية Hugging Face عن طريق تمرير bucket_id:

registry = trackio.Api().create_registry(
    "models", description="Our deployable models", bucket_id="my-org/models-registry"
)

يتم إنشاء الدلو (خاص) إذا لم يكن موجودًا. اضبط TRACKIO_REGISTRY_BUCKET_ID لجعله الافتراضي لكل استدعاء سجل في العملية، حتى لا يضطر السكربتات إلى تمريره.

تتشارك عمليات الجلب والفحص والنشر في نفس الحجة:

registry = trackio.Api().registry("models", bucket_id="my-org/models-registry")

run = trackio.init(project="my-experiments", space_id="my-org/my-dashboard")
artifact = trackio.log_artifact("model.pt", name="resnet", type="model")

run.link_artifact(
    artifact,
    "registry-models/my-model",
    aliases=["staging"],
    bucket_id="my-org/models-registry",
)

يكتب كل من لديه وصول إلى الدلو مباشرةً فيه باستخدام بيانات اعتماد Hugging Face الخاصة به — لا يوجد خادم في المسار، لذا لا يرتبط السجل بأي Space واحد ويبقى قائماً بعد انتهاء جميعها. تقبل Artifact.link وArtifact.unlink المعامل bucket_id بالطريقة نفسها، ويتذكر العنصر المرتبط الدلو الذي جاء منه، لذا يعود linked.unlink() إلى السجل الصحيح.

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

ما يوجد في الدلو

تُخزَّن كل طفرة ككائن غير قابل للتغيير واحد، والحالة هي طيّ لذلك السجل:

trackio/registries/<registry>/registry.json            name, description, created_at
trackio/registries/<registry>/events/<event_uid>.json  one object per mutation

تقوم قراءة سجل عن بُعد بدمج تلك الأحداث في قاعدة بيانات إسقاط محلية تحت registry-cache/، وهي ذاكرة مؤقتة: احذفها وستُعاد بنائها من الدلو عند القراءة التالية.

التزامن

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

• تُمنح أرقام الإصدارات بواسطة الطيّ، وليس بواسطة الكاتب. تُرتَّب الروابط المتزامنة حسب معرّف الحدث (الطابع الزمني، ثم الكاتب، ثم الترتيب)، لذا يحصل كل رابط على رقم مميز لا يُعاد استخدامه أبداً. قد يتغير الإصدار الذي يبلغه كاتب واحد مرة واحدة بعد دمج أحداث كاتب متزامن آخر.
• تُحسم عمليات نقل الاسم على أساس أن آخر كاتب هو الفائز وفق ذلك الترتيب نفسه، بما في ذلك latest. يتم حسم حالة قيام شخصين بترقية production في اللحظة نفسها بناءً على ترتيب الأحداث.

تبقى الروابط مؤشرات خالصة: لا يتم نسخ أي شيء إلى حاوية السجل، لذا يجب أن تبقى مساحة تخزين المشروع المصدر قابلة للوصول. لا يُدعم بعد حل الروابط التي يكون مصدرها عن بُعد. يُعد نسخ (تثبيت) بايتات إصدار معين إلى السجل خطوة متابعة مخططة.

فحص سجل

تعتمد Registry على قوائم المجموعات وإصدارات المرتبطة بها. تعيد عمليات القراءة لقطات من Collection:

registry = trackio.Api().registry("models")

registry.collections()
# [Collection(name="my-model", type="model", num_links=2, latest_version=1, ...)]

registry.collection("my-model").links
# [{"collection_version": 1, "source_project": "my-experiments",
#   "source_artifact": "resnet", "source_version": 4,
#   "aliases": ["latest", "production"], ...}]

تُسجّل كل وصلة مصدر الإصدار (source_project، source_artifact، source_version)، وإحداثيات التخزين للمصدر عندما لا يكون محليًا (source_space_id، source_bucket_id، أو source_server_base_url)، بالإضافة إلى المستعarentات الحالية عليه. الوصلة هي مؤشر خالص إلى ذلك الإصدار المصدر.

واجهة سطر الأوامر

تغطي أوامر trackio registry نفس سير عمل النشر والفحص دون الحاجة إلى سكربت بلغة بايثون:

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

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

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

trackio registry unlink models/churn-model v0

link يحلّ مصدره من بيانات Trackio المحلية. يقبل إصدارًا أو مستعارًا صريحًا، ويتّخذ latest افتراضيًا عند حذف البادئة. قد لا يزال السجل مدعومًا بوعاء تخزين؛ مرّر --bucket-id my-org/models-registry إلى أي أمر. استخدم --json للحصول على مخرجات منظمة مناسبة للبرمجيات النصية.

يقبل سطر الأوامر كلًا من models/churn-model ونحو الهدف الكامل registry-models/churn-model الخاص بواجهة برمجة التطبيقات Python. راجع أوامر سطر الأوامر للاطلاع على مرجع الأوامر الكامل.

تصفّح السجلات في لوحة التحكم

شغّل لوحة معلومات السجل المستقلة للقراءة فقط لتصفح أوصاف السجل، والمجموعات، والإصدارات المرتبطة، والأسماء المستعارة، ومواقع المصدر، وأحداث التدقيق:

trackio show registry

أو شغّله من بايثون باستخدام trackio.show(dashboard="registry"). لوحة تحكم السجل منفصلة عن لوحة تحكم المشروع لأن السجلات تُفهرس المخرجات عبر المشاريع.

يُظهر مصدر Local السجلات المخزّنة على جهاز لوحة التحكم. اختر HF Bucket لاختيار حاوية Hugging Face قابلة للوصول، أو أدخل معرّف حاوية مثل my-org/models-registry. على Space، يستخدم الوصول إلى الحاويات الخاصة بيانات اعتماد Hugging Face للمشاهد المسجّل الدخول. أما لوحة التحكم المستضافة ذاتيًا فتستخدم رمز Hugging Face المحفوظ لديها فقط للمشاهدين الذين فتحوا رابط الوصول للكتابة الخاص بها. ولا تكشف لوحات التحكم العامة للقراءة فقط عن الحاويات عبر رمز مملوك للخادم. ولا يتضمن تصفّح السجلات لقطات لوحة التحكم الثابتة.

سجل التدقيق

تُضيف كل عملية تعديل حدثًا إلى سجل التدقيق الخاص بالسجل: إنشاء السجل والمجموعة (create)، وlink، وpromote، وتغييرات الوصف (update)، وunlink. يجيب السجل على أسئلة مثل “ما هو الإصدار الذي كان قيد الإنتاج في الشهر الماضي، وما هي الجولة التي نشرته؟”:

registry.events()
# [{"id": 1, "ts": "...", "kind": "create", "payload": {...}},
#  {"id": 2, "ts": "...", "kind": "link",
#   "payload": {"collection": "my-model", "collection_version": 0,
#               "source_project": "my-experiments", "run_name": "exp-1", ...}},
#  {"id": 3, "ts": "...", "kind": "promote",
#   "payload": {"alias": "staging", "collection_version": 0,
#               "previous_version": None, ...}}]

تُسجّل أحداث الربط والترويج عملية النشر. كما تسجّل أحداث الترويج الإصدار الذي انتقل منه الاسم المستعار.