Registry

Registry adalah katalog bersama untuk versi artifact terbaik Anda. Sebuah proyek mencantumkan artifact yang dihasilkan oleh eksperimen Anda; sebuah registry mencantumkan artifact terpilih melintasi proyek.

Sebuah registry berisi koleksi. Setiap koleksi mewakili satu aset — model yang Anda latih ulang dari waktu ke waktu, set evaluasi emas — dan menyimpan versi yang Anda pilih untuk dipublikasikan. Anda menghubungkan versi artefak ke dalam sebuah koleksi. Tautan adalah penunjuk ke versi sumber: tidak ada yang disalin. Anda kemudian mempromosikan versi yang ditautkan melalui tahap siklus hidup dengan memindahkan alias seperti staging dan production.

Sebagai contoh, registry bernama models mungkin berisi satu koleksi per model yang dapat di-deploy, dan registry bernama datasets berisi satu koleksi per benchmark. Cara Anda membagi aset di antara registry dan koleksi adalah terserah Anda.

Sebuah koleksi memiliki garis versinya sendiri (v0, v1, …) yang independen dari nomor versi artefak sumber, dan versinya dapat menunjuk ke artefak sumber yang berbeda di proyek yang berbeda. Alias menamai tepat satu versi per koleksi.

Registry bersifat lokal — disimpan di samping data Trackio Anda lainnya sebagai proyek bernama registry-models (awalan registry- bersifat khusus) — atau didukung oleh Hugging Face bucket, yang membuatnya dapat diakses dari mesin lain dan dari run yang mencatat ke Space. Lihat Remote registries.

Buat sebuah registry

Buat registry dengan Api.create_registry():

import trackio

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

description opsional disimpan di registry dan dapat dibaca sebagai registry.description.

Registries tidak pernah dibuat secara implisit. Menautkan ke registry yang tidak ada akan memicu error.

Gunakan Api.registry() untuk mengambil registry yang sudah ada. Metode ini juga akan memicu error jika registry tidak ada.

Buat koleksi

Koleksi adalah seperangkat versi artefak yang saling terhubung dalam sebuah registry, dengan satu riwayat versi. Versi-versi tersebut dapat berasal dari artefak sumber yang berbeda: jika model berbasis resnet dan model berbasis unet merupakan kandidat untuk produk yang dapat di-deploy yang sama, hubungkan keduanya ke dalam satu koleksi sehingga mereka menjadi versi yang berurutan dari produk tersebut. Jika keduanya merupakan produk yang terpisah, berikan masing-masing koleksinya sendiri.

Anda biasanya tidak membuat koleksi secara manual: tautan ke koleksi yang tidak ada akan membuatnya secara otomatis. Buat satu secara eksplisit ketika Anda ingin mengatur deskripsi di awal:

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

Jenis koleksi

Setiap koleksi menerima satu type artefak, yang ditetapkan saat koleksi dibuat. Type tersebut berasal dari artefak itu sendiri — field type yang Anda berikan ke trackio.Artifact atau trackio.log_artifact — sehingga koleksi yang dibuat oleh tautan pertama akan mengadopsi type artefak tersebut.

Sebagai contoh, jika Anda menautkan artefak "dataset" ke dalam koleksi yang menerima artefak "model", Trackio akan menampilkan error.

Registry itu sendiri menerima semua tipe: koleksi model dan koleksi dataset dapat berada berdampingan dalam registry yang sama.

Hubungkan versi artefak ke koleksi

Publikasikan versi artefak dengan 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"])

Path target adalah "registry-<registry>/<collection>". Segmen pertama adalah nama lengkap registry, termasuk prefiks.

link_artifact mengambil objek artifact itu sendiri, sehingga versi yang Anda pegang adalah persis versi yang dipublikasikan:

Anda juga dapat membuat tautan dari artefak itu sendiri dengan Artifact.link(), yang berguna ketika run tidak berada dalam scope:

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

Artifact.link memerlukan artefak yang sudah dicatat atau diambil — tidak akan mencatat draf untuk Anda — dan tautan tersebut tidak mencatat run penerbitan.

Artefak yang ditautkan

link_artifact mengembalikan artefak di lokasi registri-nya. name-nya adalah koleksi, project-nya adalah registri, dan version serta aliases-nya adalah milik koleksi tersebut. Kontennya — manifest, manifest_digest, size, metadata — adalah milik versi sumber, dan properti source_project, source_name, source_version, serta source_qualified_name menunjuk kembali ke sana:

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"

Menautkan artefak yang tertaut akan menautkan versi sumbernya secara langsung (dengan peringatan), sehingga tautan tidak pernah berantai.

Konsumen menyelesaikan lokasi registry secara langsung dengan use_artifact, tanpa mengetahui proyek atau artefak mana yang menghasilkannya:

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

Spesifikasi setelah koleksi menerima versi koleksi ("v1"), alias ("production"), atau kosong untuk versi terbaru yang terhubung. Mengunduh artefak yang terhubung akan mengambil byte dari versi sumber yang ditunjuknya.

Lokasi registry saat ini hanya dapat dipecahkan oleh eksekusi lokal, dan hanya ketika artefak sumber tersedia secara lokal. Sumber yang disimpan di Space, di bucket, atau di server self-hosted dapat dipublikasikan ke registry berbasis bucket, tetapi resolusi tautan tersebut dalam proses berikutnya belum didukung. Artefak terkait yang dikembalikan secara langsung oleh link_artifact mempertahankan sumber Space atau self-hosted-nya dan dapat mengunduh darinya.

Versi koleksi

Setiap tautan baru mendapatkan nomor versi berikutnya dalam koleksi, dimulai dari v0. Versi koleksi independen dari nomor versi artefak sumbernya sendiri, karena versi yang ditautkan biasanya berasal dari artefak dan proyek yang berbeda.

Menggabungkan versi sumber yang sudah ada dalam koleksi tidak akan membuat versi baru. Anda akan mendapatkan versi yang sudah ada, dan semua aliases yang Anda berikan tetap akan berpindah. Nomor versi tidak pernah digunakan ulang, sehingga my-model:v3 yang telah dipublikasikan tidak akan pernah berubah maknanya secara diam-diam.

Promosikan versi dengan alias

Alias merujuk pada satu versi per koleksi. Menugaskan alias yang sudah dipegang oleh versi lain akan memindahkannya — pemindahan tersebut adalah promosi. Konsumen yang menyelesaikan my-model:production mengikuti alias, sehingga tidak ada perubahan di hilir saat alias berpindah.

Sebagian besar promosi terjadi pada saat publikasi: Anda menautkan versi baru dan menempatkan alias dalam panggilan yang sama.

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

Untuk mempromosikan versi yang sudah ada dalam koleksi, hubungkan ulang dengan alias. Menghubungkan ulang tidak membuat apa pun yang baru — Anda akan mendapatkan kembali versi koleksi yang ada, dan alias yang Anda berikan akan dipindahkan ke sana. Cari sumber versi tersebut di tautan koleksi, ambil, lalu hubungkan lagi:

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

Anda juga dapat mengambilnya langsung dari registry:

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

Mengembalikan alias ke versi yang lebih lama bekerja dengan cara yang sama.

Trackio mengelola alias latest untuk Anda: alias ini selalu menunjuk ke versi teranyar yang terhubung.

Membatalkan tautan versi

Hapus tautan dengan Artifact.unlink(), yang dipanggil pada artefak yang ditautkan:

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

Artefak sumber dan file-filenya tidak diubah — hanya keanggotaan koleksi yang dihapus. Alias apa pun pada tautan ikut terhapus, dan nomor versi koleksi tidak pernah digunakan ulang, sehingga my-model:v0 tidak bisa berarti sesuatu yang lain di kemudian hari. Jika versi yang Anda hapus memegang latest, alias tersebut berpindah ke versi tersisa tertinggi, sehingga latest tetap menunjuk ke versi terbaru dalam koleksi.

Registrari jarak jauh

Registry lokal hanya ada di mesin yang menuliskannya. Untuk berbagi katalog antar mesin — atau untuk menerbitkan dari run yang mencatat ke Space atau server self-hosted — gunakan Hugging Face bucket sebagai backend registry dengan meneruskan bucket_id:

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

Bucket dibuat (privat) jika belum ada. Atur TRACKIO_REGISTRY_BUCKET_ID untuk menjadikannya default untuk setiap panggilan registry dalam proses, sehingga skrip tidak perlu meneruskannya.

Mengambil, memeriksa, dan menerbitkan semuanya menggunakan argumen yang sama:

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

Semua orang yang memiliki akses ke bucket menulis langsung ke bucket tersebut dengan kredensial Hugging Face mereka sendiri — tidak ada server di jalur tersebut, sehingga registry tidak terikat pada satu Space tertentu dan bertahan lebih lama dari semua Space. Artifact.link dan Artifact.unlink menerima bucket_id dengan cara yang sama, dan artefak yang terhubung mengingat bucket asalnya, sehingga linked.unlink() kembali ke registry yang tepat.

Bucket milik registry secara sengaja tidak sama dengan bucket dari run: sebuah registry adalah katalog lintas proyek, sehingga Anda menamainya secara eksplisit alih-alih mewarisi ke mana pun metrik kebetulan diarahkan.

Apa yang ada di dalam bucket

Setiap mutasi disimpan sebagai satu objek immutable, dan state adalah fold dari log tersebut:

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

Membaca registri jarak jauh melipatgandakan peristiwa-peristiwa tersebut ke dalam basis data proyeksi lokal di bawah registry-cache/, yang merupakan cache: hapus folder ini dan pembacaan berikutnya akan membangunnya kembali dari bucket.

Kesejajaran

Penyimpanan objek tidak memiliki compare-and-swap, sehingga penulis tidak dapat mengambil kunci — mereka hanya dapat menambahkan objek yang tidak sedang ditulis oleh orang lain. Dua konsekuensinya, keduanya memang dirancang demikian:

• Nomor versi ditetapkan oleh proses fold, bukan oleh writer. Link konkuren diurutkan berdasarkan event id (timestamp, lalu writer, lalu sequence), sehingga masing-masing mendapatkan nomor yang unik dan tidak pernah digunakan ulang. Versi yang dilaporkan oleh satu writer dapat bergeser setelah event dari writer konkuren di-fold.
• Alias moves bersifat last-writer-wins berdasarkan urutan yang sama, termasuk latest. Dua orang yang mempromosikan production pada saat yang bersamaan akan diselesaikan berdasarkan urutan event.

Tautan tetap menjadi penunjuk murni: tidak ada yang disalin ke bucket registry, sehingga penyimpanan proyek sumber harus tetap dapat diakses. Resolusi tautan yang sumbernya masih remote belum didukung. Menyalin (mem-pin) byte versi ke dalam registry adalah tindak lanjut yang direncanakan.

Periksa sebuah registry

Registry menangani daftar koleksi dan versi yang terkait. Baca mengembalikan snapshot 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"], ...}]

Setiap tautan mencatat asal versi (source_project, source_artifact, source_version), koordinat penyimpanan sumbernya jika bukan lokal (source_space_id, source_bucket_id, atau source_server_base_url), serta alias yang saat ini ada di atasnya. Tautan adalah penunjuk murni ke versi sumber tersebut.

Antarmuka baris perintah

Perintah trackio registry mencakup alur kerja penerbitan dan inspeksi yang sama tanpa memerlukan skrip Python:

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 menyelesaikan sumbernya dari data Trackio lokal. Menerima versi atau alias eksplisit dan secara default menggunakan latest jika sufiks diabaikan. Registry masih dapat didukung oleh bucket; berikan --bucket-id my-org/models-registry ke perintah apa pun. Gunakan --json untuk output terstruktur yang cocok untuk skrip.

CLI menerima baik models/churn-model maupun sintaks target lengkap registry-models/churn-model dari API Python. Lihat Perintah CLI untuk referensi perintah lengkap.

Jelajahi registri di dasbor

Luncurkan dasbor registry mandiri yang hanya dapat dibaca untuk menelusuri deskripsi registry, koleksi, versi yang terhubung, alias, lokasi sumber, dan peristiwa audit:

trackio show registry

Atau jalankan dari Python dengan trackio.show(dashboard="registry"). Dashboard registry dipisahkan dari dashboard proyek karena registry mengatalogkan artefak di berbagai proyek.

Sumber Local menampilkan registri yang disimpan di mesin dashboard. Pilih HF Bucket untuk memilih bucket Hugging Face yang dapat diakses atau masukkan id bucket seperti my-org/models-registry. Pada Space, akses bucket privat menggunakan kredensial Hugging Face dari penampil yang masuk. Dashboard self-hosted hanya menggunakan token Hugging Face yang tersimpan untuk penampil yang membuka URL akses tulisnya. Dashboard baca-saja publik tidak pernah mengekspos bucket melalui token yang dimiliki server. Penjelajahan registri tidak disertakan dalam snapshot dashboard statis.

Riwayat audit

Setiap mutasi menambahkan sebuah event ke log audit registry: pembuatan registry dan koleksi (create), link, promote, perubahan deskripsi (update), dan unlink. Log ini menjawab pertanyaan seperti “versi mana yang ada di produksi bulan lalu, dan run mana yang menerbitkannya?”:

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 dan promote events mencatat run penerbitan. Promote events juga mencatat versi asal alias yang dipindahkan.