Kayıt Defteri

registry, en iyi artefakt sürümlerinizin paylaşılan kataloğudur. Bir proje, deneylerinizin ürettiği artefaktları listeler; bir registry ise çeşitli projelerden seçilen artefaktları listeler.

Bir kayıt defteri koleksiyonlar içerir. Her koleksiyon bir varlığı temsil eder — zaman içinde yeniden eğittiğiniz bir model, altın bir değerlendirme seti — ve yayınlamayı seçtiğiniz sürümlerini barındırır. Bir artefakt sürümünü bir koleksiyona bağlarsınız. Bağlantı, kaynak sürüme işaret eden bir imleçtir: hiçbir şey kopyalanmaz. Ardından, staging ve production gibi takma adları taşıyarak bağlantılı bir sürümü yaşam döngüsü aşamaları boyunca ilerletirsiniz.

Örneğin, models adlı bir kayıt defteri, dağıtılabilir her model için bir koleksiyon; datasets adlı bir kayıt defteri ise her benchmark için bir koleksiyon içerebilir. Varlıkların kayıt defterleri ve koleksiyonlar arasında nasıl bölündüğü size kalmıştır.

Bir koleksiyonun, kaynak artefaktların sürüm numaralarından bağımsız olan kendi sürüm hattı (v0, v1, …) vardır ve sürümleri, farklı projelerdeki farklı kaynak artefaktlara işaret edebilir. Takma adlar, koleksiyon başına tam olarak bir sürüm adlandırır.

Bir kayıt defteri ya da yereldir — diğer Trackio verilerinizin yanında registry-models adlı bir proje olarak saklanır (registry- öneki ayrılmıştır) — ya da bir Hugging Face kovasına dayanır; bu da onu diğer makinelerden ve bir Space'e kayıt yapan çalışmalardan erişilebilir kılar. Uzak kayıt defterleri bölümüne bakın.

Bir kayıt defteri oluşturun

Api.create_registry() ile bir kayıt defteri oluşturun:

import trackio

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

İsteğe bağlı description, kayıt defterinde saklanır ve registry.description olarak okunabilir.

Kayıt defterleri asla örtük olarak oluşturulmaz. Var olmayan bir kayıt defterine bağlanmaya çalışmak bir hata oluşturur.

Mevcut bir kayıt defterini almak için Api.registry() kullanın. Kayıt defteri mevcut değilse bu yöntem bir hata fırlatır.

Bir koleksiyon oluşturun

Koleksiyon, bir kayıt defteri içinde tek bir sürüm geçmişine sahip bağlantılı artefakt sürümlerinin bir kümesidir. Sürümler farklı kaynak artefaktlardan gelebilir: resnet tabanlı ve unet tabanlı modeller aynı dağıtılabilir ürün için adaysa, bunları tek bir koleksiyona bağlayın ve bu koleksiyonun ardışık sürümleri haline gelsinler. Ayrı ürünlerse, her birine kendi koleksiyonunu verin.

Genellikle koleksiyonları manuel olarak oluşturmazsınız: var olmayan bir koleksiyona bağlantı oluşturulduğunda koleksiyon otomatik olarak oluşturulur. Bir açıklama baştan ayarlamak istediğinizde koleksiyonu açıkça oluşturun:

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

Koleksiyon türleri

Her koleksiyon, koleksiyon oluşturulurken belirlenen tek bir type türünde artefaktı kabul eder. Tür, artefaktın kendisinden gelir — trackio.Artifact veya trackio.log_artifact fonksiyonlarına ilettiğiniz type alanı — bu nedenle ilk bağlantıyla oluşturulan bir koleksiyon, o artefaktın türünü benimser.

Örneğin, "model" artefaktlarını kabul eden bir koleksiyona "dataset" artefaktı bağlarsanız, Trackio bir hata oluşturur.

Kayıt defteri (registry) her türü kabul eder: bir model koleksiyonu ve bir veri seti koleksiyonu aynı kayıt defterinde yan yana bulunabilir.

Bir artefakt sürümünü bir koleksiyona bağlayın

Bir artefakt sürümünü Run.link_artifact() ile yayınlayın:

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"])

Hedef yol "registry-<registry>/<collection>"'dir. İlk segment, önek dahil olmak üzere kayıt defterinin tam adıdır.

link_artifact, yayınlanan sürümün elinizdeki sürümle birebir aynı olmasını sağlamak için artifact nesnesinin kendisini alır:

Ayrıca, çalıştırma kapsamda değilse kullanışlı olan Artifact.link() ile artefaktın kendisinden de bağlantı verebilirsiniz:

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

Artifact.link, artefactin zaten kaydedilmiş ya da alınmış olmasını gerektirir — taslak sizin için kaydetmez — ve bağlantı bir yayınlama çalışması kaydetmez.

Bağlantılı artefakt

link_artifact, artefakti kayıt defteri konumunda döndürür. name alanı koleksiyonu, project alanı kayıt defterini belirtirken version ve aliases alanları koleksiyonunkilerdir. İçeriği — manifest, manifest_digest, size, metadata — kaynak sürümünkidir ve source_project, source_name, source_version ile source_qualified_name özellikleri bu kaynağa geri işaret eder:

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"

Bağlı bir artefaktın bağlantısı, kaynak sürümünü doğrudan bağlar (bir uyarıyla birlikte), bu nedenle bağlantılar asla zincirleme olmaz.

Tüketiciler, hangi proje veya artefaktın ürettiğini bilmeden, bir kayıt defteri konumunu doğrudan use_artifact ile çözer:

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

Koleksiyondan sonraki spec, bir koleksiyon sürümünü ("v1"), bir takma adını ("production") veya en yeni bağlantılı sürüm için hiçbir şeyi kabul eder. Bağlı bir artefaktın indirilmesi, işaret ettiği kaynak sürümün baytlarını alır.

Kayıt yeri konumları şu anda yalnızca yerel çalıştırmalar tarafından çözümlenebilir ve yalnızca kaynak artefakt yerel olarak mevcut olduğunda. Bir Space'te, bir kovada veya kendi kendine barındırılan bir sunucuda saklanan kaynaklar, kova destekli bir kayda yayımlanabilir, ancak bu bağlantıların sonraki bir işlemde çözümlenmesi henüz desteklenmemektedir. link_artifact tarafından doğrudan döndürülen bağlantılı artefakt, Space veya kendi kendine barındırılan kaynağını korur ve ondan indirme yapabilir.

Koleksiyon sürümleri

Her yeni bağlantı, koleksiyondaki sıradaki sürüm numarasını alır ve v0 ile başlar. Koleksiyon sürümleri, kaynak artefaktların kendi sürüm numaralarından bağımsızdır çünkü bağlantılı sürümler genellikle farklı artefaktlardan ve projelerden gelir.

Koleksiyonda zaten bulunan bir kaynak sürümünü bağlamak yeni bir sürüm oluşturmaz. Mevcut sürümü geri alırsınız ve geçirdiğiniz aliases yine taşınır. Sürüm numaraları asla yeniden kullanılmaz, bu nedenle yayınlanmış bir my-model:v3 asla sessizce anlam değiştiremez.

Alias'lerle bir sürümü yükselt

Bir takma ad, her koleksiyon için bir sürüme işaret eder. Başka bir sürümün zaten sahip olduğu bir takma adı atamak, takma adı oradan taşır — bu taşıma terfi işlemidir. my-model:production çözümleyen tüketiciler takma adı takip eder, bu nedenle takma ad taşındığında aşağı akışta hiçbir şey değişmez.

Çoğu terfi yayınlama sırasında gerçekleşir: yeni bir sürüm bağlarsınız ve takma adı aynı çağrıda yerleştirirsiniz.

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

Koleksiyonda zaten bulunan bir sürümü ilerletmek için, onu takma adla yeniden bağlayın. Yeniden bağlama işlemi yeni bir şey oluşturmaz; mevcut koleksiyon sürümünü geri alırsınız ve ilettiğiniz takma adlar ona taşınır. Sürümün kaynağını koleksiyonun bağlantılarında bulun, onu getirin ve yeniden bağlayın:

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"])

Bunu doğrudan kayıt defterinden de alabilirsiniz:

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

Bir takma adın (alias) eski bir sürüme geri alınması aynı şekilde çalışır.

Trackio, latest takma adını sizin için yönetir: her zaman en yeni bağlantılı sürüme işaret eder.

Bir sürümü bağlantısını kaldır

Bağlı artefakt üzerinde çağrılan Artifact.unlink() ile bir bağlantı kaldırın:

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

Kaynak artefakt ve dosyaları dokunulmaz kalır — yalnızca koleksiyon üyeliği kaldırılır. Bağlantıdaki tüm takma adlar da onunla birlikte gider ve koleksiyon sürüm numarası asla yeniden kullanılmaz, bu nedenle my-model:v0 daha sonra başka bir şeyi ifade edemez. Kaldırdığınız sürüm latest takma adını içeriyorsa, bu takma ad en yüksek kalan sürüme taşınır, böylece latest koleksiyondaki en yeni sürüme işaret etmeye devam eder.

Uzak kayıt defterleri

Yerel bir kayıt defteri yalnızca onu yazan makinede bulunur. Bir kataloğu makineler arasında paylaşmak — veya bir Space'e veya kendi barındırdığınız bir sunucuya kayıt tutan bir çalışmadan yayınlamak — için kayıt defterini bucket_id parametresini geçirerek Hugging Face bucket ile destekleyin:

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

Var olmayan bir varlık kovası oluşturulur (özel). Bir işlemdeki tüm kayıt defteri çağrılarının varsayılanı olarak ayarlamak için TRACKIO_REGISTRY_BUCKET_ID değerini belirleyin; böylece betiklerin bunu ayrıca iletmesine gerek kalmaz.

Alma, inceleme ve yayınlama işlemlerinin tümü aynı argümanı alır:

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",
)

Buckete erişimi olan herkes, kendi Hugging Face kimlik bilgileriyle doğrudan ona yazar — yolda bir sunucu olmadığından, bir kayıt defteri herhangi bir Space'e bağlı değildir ve hepsinden uzun ömürlüdür. Artifact.link ve Artifact.unlink, bucket_id parametresini aynı şekilde kabul eder ve bağlantılı bir artefakt, geldiği bucketı hatırlar; bu nedenle linked.unlink() doğru kayıt defterine geri döner.

Kayıt defterinin kendi kovası, çalıştırmanın kovasıyla aynı değildir: bir kayıt defteri proje arası bir kataloğudur, bu nedenle metriklerin nereye gittiğini devralmak yerine adını açıkça belirtirsiniz.

Kova içinde neler var

Her mutasyon, tek bir değiştirilemez nesne olarak saklanır ve durum, bu günlüğün katlanmasıdır:

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

Uzak bir kayıt defterini okumak, bu olayları registry-cache/ altındaki yerel bir projeksiyon veritabanına katlar; bu bir önbellektir: silerseniz, sonraki okuma onu bucket'tan yeniden oluşturur.

Eşzamanlılık

Nesne depolamasında karşılaştırma ve değiştirme (compare-and-swap) yoktur, bu nedenle yazarlar kilit alamaz — yalnızca başka birinin yazmadığı nesneleri ekleyebilirler. İki sonuç, ikisi de tasarım gereği:

• Sürüm numaraları, yazar tarafından değil, katlama işlemi tarafından atanır. Eşzamanlı bağlantılar, olay kimliklerine göre sıralanır (zaman damgası, ardından yazar, ardından sıra numarası), bu nedenle her birine benzersiz ve asla yeniden kullanılmayan bir numara verilir. Bir yazarın bildirdiği bir sürüm, eşzamanlı bir yazarın olayları katlandığında bir kez kayabilir.
• Alias taşımaları son yazar kazanır kuralı, aynı sıralamaya göre, latest dahil olmak üzere uygulanır. İki kişinin aynı anda production ortamına yükseltme yapması, olay sırasına göre çözümlenir.

Bağlantılar saf işaretçiler olarak kalır: kayıt defteri kovasına hiçbir şey kopyalanmaz, bu nedenle kaynak projenin depolaması erişilebilir kalmalıdır. Kaynağı uzak olan bağlantıların çözümlenmesi henüz desteklenmemektedir. Bir sürümün baytlarını kayıt defterine kopyalama (sabitleme) işlemi planlanan bir sonraki adım olarak ele alınacaktır.

Bir kayıt defterini denetleyin

Registry handle, koleksiyonları ve bunlara bağlı sürümleri listeler. Okumalar Collection anlık görüntülerini döndürür:

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"], ...}]

Her bağlantı, sürümün nereden geldiğini (source_project, source_artifact, source_version), yerel değilse kaynağın depolama koordinatlarını (source_space_id, source_bucket_id veya source_server_base_url) ve üzerinde bulunan geçerli takma adları kaydeder. Bir bağlantı, o kaynak sürümüne giden saf bir işaretçidir.

Komut satırı arayüzü

trackio registry komutları, bir Python betiği gerektirmeden aynı yayınlama ve inceleme iş akışını kapsar:

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, kaynağını yerel Trackio verisinden çözer. Açık bir sürüm veya takma ad kabul eder ve sonek atlandığında varsayılan olarak latest kullanılır. Kayıt defteri yine de bucket destekli olabilir; herhangi bir komuta --bucket-id my-org/models-registry parametresini iletin. Betikler için uygun yapılandırılmış çıktı almak için --json kullanın.

CLI hem models/churn-model hem de Python API’sinin tam registry-models/churn-model hedef sözdizimini kabul eder. Tam komut referansı için CLI Komutları bölümüne bakın.

Panelde kayıt defterlerini görüntüle

Kayıt açıklamalarını, koleksiyonları, bağlantılı sürümleri, takma adları, kaynak konumlarını ve denetim olaylarını görüntülemek için bağımsız, salt okunur kayıt panosunu başlatın:

trackio show registry

Veya Python'dan trackio.show(dashboard="registry") ile başlatın. Kayıt defteri panosu, kayıt defterlerinin projeler arası artefaktları kataloglaması nedeniyle proje panosundan ayrıdır.

Local kaynağı, gösterge paneli makinesinde saklanan kayıt defterlerini gösterir. Erişilebilir bir Hugging Face kovasını seçmek için HF Bucket seçeneğini işaretleyin veya my-org/models-registry gibi bir kova kimliği girin. Bir Space’te özel kova erişimi, oturum açan izleyicinin Hugging Face kimlik bilgilerini kullanır. Kendi kendine barındırılan bir gösterge paneli, yalnızca yazma erişim URL’sini açan izleyiciler için kayıtlı Hugging Face jetonunu kullanır. Halka açık salt okunur gösterge panelleri, kovaları sunucu tarafından sahip olunan bir jeton aracılığıyla asla ifşa etmez. Kayıt defteri gezintisi, statik gösterge paneli anlık görüntülerine dahil değildir.

Denetim geçmişi

Her mutasyon, kayıt defterinin denetim günlüğüne bir olay ekler: kayıt defteri ve koleksiyon oluşturma (create), link, promote, açıklama değişiklikleri (update) ve unlink. Günlük, “geçen ay üretimde hangi sürüm vardı ve bu sürümü hangi çalıştırma yayınladı?” gibi soruları yanıtlar:

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, ...}}]

Link ve promote olayları, yayınlama çalışmasını kaydeder. Promote olayları ayrıca, takma adın hangi sürümden taşındığını da kaydeder.