Artefaktlar

Giriş

Bir artifact, bir projeye bağlı, sürüm numaralı ve adlandırılmış dosya demetidir — eğitim görmüş bir model, bir veri seti, bir değerlendirme çıktıları kümesi. Dosyaları artifact olarak kaydetmek (diskte bırakmak yerine) size şunları sağlar:

• Sürümleme — aynı ad altında her kayıt yaptığınızda Trackio yeni bir sürüm kaydeder (v0, v1, …). Aynı içerikler tekilleştirildiğinden, değiştirilmemiş dosyaları yeniden kaydettiğinizde mevcut sürüm yeniden kullanılır.
• Aliasler — latest (otomatik atanır) veya kendi tanımladıklarınız (prod, best) gibi, her zaman tek bir sürüme çözümlenen işaretçileri taşımak.
• Köken — artefaktler, bunları üreten ve tüketen çalıştırmalara bağlanır; böylece bir modelin hangi çalıştırma tarafından oluşturulduğunu ve hangi çalıştırmaların onu kullandığını izleyebilirsiniz.

Artifacts, yerel depolama ile tamamen çevrimdışı çalışır ve yapılandırıldığında, metrikler gibi bir Hugging Face Space'e (veya kendi barındırdığınız sunucuya) eşitlenir.

Bir artefaktı günlüğe kaydetme

En hızlı yol, bir dosya veya dizini doğrudan günlüğe kaydetmektir. Bu işlem yeni bir artefakt oluşturur, yolu ekler ve onu mevcut çalıştırmanın bir çıktısı olarak kaydeder:

import trackio

trackio.init(project="my_project")

# ... training ...

trackio.log_artifact("checkpoints/model.safetensors", type="model")

Bir yol geçirdiğinizde, artefakt name değeri varsayılan olarak run-<run_id>-<basename> ve type değeri varsayılan olarak "unspecified" olur. Bunları açıkça belirlemek için name ve type parametrelerini geçirin:

trackio.log_artifact("checkpoints/", name="my-model", type="model")

Artefakt türleri

Artefakt type serbest biçimli bir kategori dizgesidir. Trackio, sabit bir tür listesi uygulamaz ancak yaygın kurallar şunlardır:

Bir proje içinde tutarlı bir şekilde artefaktları filtreleyebilmek ve trackio.use_artifact(..., type="...") ile bir çalışmanın beklenen türde artefaktı tükettiğini doğrulayabilmek için kararlı tip adları kullanın.

Bir artefaktı açıkça oluşturma

Daha ince kontrol için — birden çok dosya, özel mantıksal yollar, bir açıklama veya meta veri — bir Artifact oluşturun, dosyaları ekleyin ve ardından günlüğe kaydedin:

artifact = trackio.Artifact(
    name="my-model",
    type="model",
    description="Fine-tuned on the v2 dataset",
    metadata={"base_model": "bert-base", "epochs": 3},
)
artifact.add_file("checkpoints/model.safetensors")
artifact.add_file("checkpoints/config.json")
artifact.add_dir("tokenizer/")

logged = trackio.log_artifact(artifact)

Kayıt işleminden sonra artefakt dondurulur ve version, aliases, size ile manifest alanları doldurulur:

print(logged.version)   # "v0"
print(logged.aliases)   # ("latest",)

Sürümler ve takma adlar

Mevcut bir ad altında oluşturulan her kayıt, bir sonraki tamsayı sürümünü oluşturur ve latest takma adını ona taşır. Kendi takma adlarınızı aliases= ile atayın:

trackio.log_artifact(artifact, aliases=["prod", "best"])

Alias'ler hareketli işaretçilerdir: aynı alias ile yeni bir sürüm kaydettiğinizde, alias yeniden yönlendirilir. Sürüm belirteçleri (v0, v1, …) ayrılmıştır ve alias olarak kullanılamaz.

Mevcut bir sürümle aynı içeriği kaydettiyseniz, Trackio yeni bir sürüm oluşturmak yerine o sürümü yeniden kullanır. Geçerli aliases parametresi olarak ilettiğiniz her şey yine de bu sürüme yönlendirilir, ancak latest olduğu yerde kalır — aynı (veya daha eski) içeriğin yeniden kaydedilmesi onu geriye asla taşımaz.

Bir artefakt kullanma

use_artifact() bir artefaktı alır ve onu mevcut çalıştırma için bir girdi olarak kaydeder; bu da tüketen çalıştırma ile kullandığı artefakt arasındaki soy kütüğünü oluşturur:

trackio.init(project="my_project")

artifact = trackio.use_artifact("my-model")          # resolves to :latest
artifact = trackio.use_artifact("my-model:v2")       # pin a version
artifact = trackio.use_artifact("my-model:prod")     # resolve an alias

Sanığın türünü doğrulamak için type parametresini iletin; eşleşmezse hata fırlatılır:

artifact = trackio.use_artifact("my-model", type="model")

Dosyaları indirme

use_artifact, dosyalarını download() ile somutlaştırdığınız bir Artifact döndürür:

artifact = trackio.use_artifact("my-model:latest")
path = artifact.download()
# files are now under ./.trackio/artifact-downloads/my_project/my-model_v2/

Varsayılan olarak dosyalar, farklı projelerden gelen aynı adlı artefaktların asla çakışmaması için proje anahtarına göre ./.trackio/artifact-downloads/<project>/<name>_v<version>/ dizinine yazılır; başka bir dizin seçmek için root parametresini iletin. download() idempotenttir — zaten mevcut olan dosyalar atlanır — ve çalıştırma bir Space tarafından destekleniyorsa, yerel olarak eksik olan herhangi bir dosya uzaktan alınır.

Harici verilere atıfta bulunma

Bazı veriler kopyalanacak kadar büyük değildir veya zaten kopyalanmasını istemediğiniz kalıcı depolamada bulunur. add_reference, bu tür verileri Trackio depolamasına hiçbir bayta aktarmadan manifestte URI ile kaydeder; böylece asla yer değiştirmeyen veriler üzerinde sürümleme, yinelenenlerin kaldırılması, takma adlar ve soy ağacı özelliklerinden hâlâ yararlanabilirsiniz:

artifact = trackio.Artifact(name="training-set", type="dataset")
artifact.add_reference("file:///mnt/nvme/datasets/corpus.parquet")
artifact.add_reference("file:///mnt/nvme/datasets/shards/")            # a directory — expands to one entry per file
artifact.add_reference("https://example.com/data/eval.json")
artifact.add_reference("hf://datasets/username/my-dataset/train.parquet")
trackio.log_artifact(artifact)

Yerleşik şemalar file://, http(s):// ve hf://’dir — tümü Trackio’nun mevcut bağımlılıkları tarafından sağlanır. Diğer herhangi bir şema (s3://, gs://, Azure blob URL’leri, …) özel bir işleyici kaydedilerek desteklenir; tam S3, GCS ve Azure örnekleri için aşağıdaki Diğer depolara atıfta bulunma bölümüne bakın. checksum=True (varsayılan) ile Trackio, size ve bir checksum doldurmak için kaynağı sorgular:

• file:// bir sha256 olarak akış üzerinden özetlenir; boyutu diskten okunur.
• hf://, LFS sha256'yi (veya git blob kimliğini) kullanır; http(s)://, sunucu ETag'ini kullanır.

Her checksum tek bir digest alanında saklanır — yerel/LFS referansları için sha256, HTTP veya nesne deposu referansları için ise sağlayıcının ETag değeri.

Bir dizini (file://) veya bir depo yolunu (hf://) gösteren bir URI, her nesne için bir referans girdisine genişletilir; bu girdiler, önekin göreli yoluyla adlandırılır (verildiğinde name= altında iç içe geçer). max_objects (varsayılan 10.000) genişletmeyi sınırlar ve bu sınır aşılırsa hata fırlatır.

Herhangi bir checksum alınamadığında — örneğin ETag içermeyen bir sunucu — referans yine de, URI'nin kendisi digest olarak kullanılarak kaydedilir ve bir uyarı yayılır. Var olmayan yerel bir file:// yolu istisnadır: eksik bir yerel dosya neredeyse her zaman bir hataya işaret ettiğinden, kaydedilmek yerine bir hata fırlatılır — yerel bir dosyayı hazırlamak için add_file kullanın. Nesne başına checksum'u atlamak için checksum=False geçin — bu durumda tek bir nesne yalnızca URI'sini kaydeder — ve mantıksal yolu ayarlamak için name= kullanın.

Bir referansın sürüm kimliği, URI'sinden, boyutundan ve digest değerinden gelir; bu nedenle aynı referansların yeniden kaydedilmesi tek bir sürümde birleştirilirken, URI, boyut veya checksum'da yapılan bir değişiklik yeni bir sürüm oluşturur — tıpkı dosya içeriği gibi. URI, digest olarak kullanıldığında, kimlik bu nedenle içeriği değil URI'yi takip eder.

URIs olduğu gibi kaydedilir ve manifestler bir Hugging Face Dataset ile senkronize edilebilir. Kimlik bilgisi gömülü bir URI — imzalı bir https:// URL’si veya bir Azure SAS jetonu — o Dataset’i okuyabilen herkese bu kimlik bilgisini ifşa edeceğinden, add_reference bir URI’nin sorgu dizgesi imzalı görünüyorsa uyarı verir; bunun yerine nesnenin kanonik imzasız URI’sini (ör. s3://bucket/key) tercih edin.

Referans baytlar asla bir Space veya kovaya yüklenmez, ancak talep üzerine alınabilir. download(), her referans verilen nesneyi dizine indirir (httpx2, huggingface_hub veya kayıtlı işleyiciniz aracılığıyla) ve bu işlem büyük miktarda veri aktarımına neden olabilir. İndirmeden önce, her nesnenin kaynağı yeniden sorgulanır ve güncel özet değeri kaydedilen değerle karşılaştırılır — bir uyumsuzluk, kaynağın değişmiş olabileceğine dair uyarı verir ancak indirme işlemi devam eder. Her nesne atomik olarak yazılır ve diskte zaten bulunan bir nesne, kaynak yeniden kontrol edilmeden atlanır; bu nedenle tekrarlanan çağrılar ucuzdur ve idempotenttir:

artifact = trackio.use_artifact("training-set:latest")
path = artifact.download()   # downloads staged files AND referenced objects

İndirmeden işaretçilerle çalışmak için, bunları doğrudan artefaktan okuyun:

print(artifact.references)                  # [{'path': ..., 'ref': 's3://...', 'size': ..., 'digest': ...}, ...]
print(artifact.get_entry_uri("eval.json"))  # "s3://my-bucket/eval.json"

Alınamayan bir referans (eksik yerel dosya, erişilemeyen URL veya kayıtlı bir işleyicisi olmayan şema), download() bu referansa ulaştığında bir hata fırlatır.

Diğer depolara (S3, GCS, Azure) atıfta bulunma

Trackio, bilinçli olarak hiçbir bulut sağlayıcı SDK'sı dağıtmaz. Doğrudan desteklemediği bir depodaki nesnelere atıfta bulunmak için trackio.ReferenceHandler sınıfından türetip bir örneğini trackio.register_reference_handler ile kaydedin. Bir işlemci dört yöntem uygular:

• matches(scheme, uri) — bu işleyicinin URI'yi sahiplendiğini belirtir. Kayıtlı işleyiciler, yerleşkilerden önce sorgulanır; bu nedenle bir işleyici, genel HTTP işleyicisinden önce belirli https:// konaklarını da (aşağıdaki Azure örneğinin yaptığı gibi) talep edebilir.
• resolve(uri, checksum, max_objects) — kaynağı sorgular ve trackio.ResolvedReference girdilerinden oluşan bir liste döndürür: tek bir nesne için relkey=None içeren tek bir girdi, URI bir önek (prefix) belirtiyorsa ise her nesne için (nesnenin öneğe göre göreli yolunu relkey olarak ayarlayan) birer girdi. Kaynak sorgulanabiliyorsa size ve digest değerlerini ayarlayın (sağlayıcının ETag değeri bir digest olarak gayet iyi çalışır — Trackio referans digestlerini opak jetonlar olarak ele alır); referansı checksumsuz olarak kaydetmek için bunları None olarak döndürün, bu durumda Trackio digest olarak URI'ye geri döner ve bir uyarı verir.
• fetch(uri, dest) — uri adresindeki tek nesneyi dest yerel yoluna indirir (Artifact.download() tarafından çağrılır).
• hint() — resolve bir checksum üretmediğinde uyarıda gösterilen tek satırlık eyleme geçirilebilir mesaj.

Önek genişletme sırasında keşfedilen anahtarlar, her girdinin uri sentezlenirken yüzde kodlamalı olmalıdır (ve fetch içinde çözümlenmelidir), çünkü manifest URI'leri boşluk içermeyebilir.

S3 (s3://, boto3 üzerinden)

from urllib.parse import quote, unquote, urlsplit

import boto3

import trackio


class S3Handler(trackio.ReferenceHandler):
    def matches(self, scheme, uri):
        return scheme == "s3"

    def resolve(self, uri, checksum, max_objects):
        parts = urlsplit(uri)
        bucket, key = parts.netloc, unquote(parts.path.lstrip("/"))
        client = boto3.client("s3")
        if key and not key.endswith("/"):
            head = client.head_object(Bucket=bucket, Key=key)
            return [
                trackio.ResolvedReference(
                    relkey=None,
                    uri=uri,
                    size=int(head["ContentLength"]),
                    digest=head["ETag"].strip('"') if checksum else None,
                )
            ]
        base = key[: key.rfind("/") + 1]
        entries = []
        pages = client.get_paginator("list_objects_v2").paginate(
            Bucket=bucket, Prefix=key
        )
        for page in pages:
            for obj in page.get("Contents", []):
                if obj["Key"].endswith("/"):
                    continue
                if len(entries) >= max_objects:
                    raise ValueError(
                        f"{uri} expands to more than {max_objects} objects; "
                        "pass max_objects= to raise the limit."
                    )
                entries.append(
                    trackio.ResolvedReference(
                        relkey=obj["Key"][len(base):],
                        uri=f"s3://{bucket}/{quote(obj['Key'], safe='/')}",
                        size=int(obj["Size"]),
                        digest=obj["ETag"].strip('"') if checksum else None,
                    )
                )
        return entries

    def fetch(self, uri, dest):
        parts = urlsplit(uri)
        with open(dest, "wb") as f:
            boto3.client("s3").download_fileobj(
                parts.netloc, unquote(parts.path.lstrip("/")), f
            )

    def hint(self):
        return "Configure AWS credentials so the object can be probed for an ETag."


trackio.register_reference_handler(S3Handler())

artifact = trackio.Artifact(name="training-set", type="dataset")
artifact.add_reference("s3://my-bucket/shards/")   # expands to one entry per object
trackio.log_artifact(artifact)

Google Cloud Storage (gs://, google-cloud-storage üzerinden)

from urllib.parse import quote, unquote, urlsplit

from google.cloud import storage

import trackio


class GcsHandler(trackio.ReferenceHandler):
    def matches(self, scheme, uri):
        return scheme == "gs"

    def resolve(self, uri, checksum, max_objects):
        parts = urlsplit(uri)
        bucket, key = parts.netloc, unquote(parts.path.lstrip("/"))
        client = storage.Client()
        if key and not key.endswith("/"):
            blob = client.bucket(bucket).get_blob(key)
            if blob is None:
                raise ValueError(f"No such GCS object: {uri}")
            return [
                trackio.ResolvedReference(
                    relkey=None,
                    uri=uri,
                    size=blob.size,
                    digest=blob.etag.strip('"') if checksum else None,
                )
            ]
        base = key[: key.rfind("/") + 1]
        entries = []
        for blob in client.list_blobs(bucket, prefix=key):
            if blob.name.endswith("/"):
                continue
            if len(entries) >= max_objects:
                raise ValueError(
                    f"{uri} expands to more than {max_objects} objects; "
                    "pass max_objects= to raise the limit."
                )
            entries.append(
                trackio.ResolvedReference(
                    relkey=blob.name[len(base):],
                    uri=f"gs://{bucket}/{quote(blob.name, safe='/')}",
                    size=blob.size,
                    digest=blob.etag.strip('"') if checksum else None,
                )
            )
        return entries

    def fetch(self, uri, dest):
        parts = urlsplit(uri)
        key = unquote(parts.path.lstrip("/"))
        storage.Client().bucket(parts.netloc).blob(key).download_to_filename(
            str(dest)
        )

    def hint(self):
        return "Configure GCP credentials so the object can be probed for an ETag."


trackio.register_reference_handler(GcsHandler())

Azure Blob Storage (azure-storage-blob + azure-identity üzerinden)

Azure blob'ları düz https:// URL'leriyle adreslenir (https://<account>.blob.core.windows.net/<container>/<blob>), bu nedenle bu işleyici onları ana bilgisayar son ekiyle talep eder — kaydedildiğinde Trackio'nun genel HTTP işleyicisine karşı öncelik kazanır:

from urllib.parse import quote, unquote, urlsplit

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

import trackio


class AzureHandler(trackio.ReferenceHandler):
    def matches(self, scheme, uri):
        return scheme in ("http", "https") and urlsplit(
            uri
        ).netloc.lower().endswith(".blob.core.windows.net")

    def _split(self, uri):
        parts = urlsplit(uri)
        container, _, blob_name = parts.path.lstrip("/").partition("/")
        return f"{parts.scheme}://{parts.netloc}", container, unquote(blob_name)

    def _service(self, account_url):
        return BlobServiceClient(account_url, credential=DefaultAzureCredential())

    def resolve(self, uri, checksum, max_objects):
        account_url, container, blob_name = self._split(uri)
        service = self._service(account_url)
        if blob_name and not blob_name.endswith("/"):
            props = service.get_blob_client(container, blob_name).get_blob_properties()
            return [
                trackio.ResolvedReference(
                    relkey=None,
                    uri=uri,
                    size=props.size,
                    digest=props.etag.strip('"') if checksum else None,
                )
            ]
        base = blob_name[: blob_name.rfind("/") + 1]
        entries = []
        container_client = service.get_container_client(container)
        for blob in container_client.list_blobs(name_starts_with=blob_name):
            if blob.name.endswith("/"):
                continue
            if len(entries) >= max_objects:
                raise ValueError(
                    f"{uri} expands to more than {max_objects} objects; "
                    "pass max_objects= to raise the limit."
                )
            entries.append(
                trackio.ResolvedReference(
                    relkey=blob.name[len(base):],
                    uri=f"{account_url}/{container}/{quote(blob.name, safe='/')}",
                    size=blob.size,
                    digest=blob.etag.strip('"') if checksum else None,
                )
            )
        return entries

    def fetch(self, uri, dest):
        account_url, container, blob_name = self._split(uri)
        downloader = (
            self._service(account_url)
            .get_blob_client(container, blob_name)
            .download_blob()
        )
        with open(dest, "wb") as f:
            downloader.readinto(f)

    def hint(self):
        return "Configure Azure credentials so the blob can be probed for an ETag."


trackio.register_reference_handler(AzureHandler())

Bu işleyiciler, kaynak sorgulanamadığında hata fırlatır; bu durumda (örneğin, kayıt zamanında erişilemeyen, kimlik doğrulama arkasındaki verileri kataloğa alırken) checksum’sız bir referans kaydetmeyi tercih ediyorsanız, sağlayıcı hatasını resolve içinde yakalayın ve [trackio.ResolvedReference(relkey=None, uri=uri)] döndürün — Trackio, özet olarak URI’ye geri dönecek ve uyarı verecek, bunu hint() kullanarak yapacaktır.

Böyle referansları ekleyen veya indiren her işlemde işleyicileri kaydedin: Artifact.download() baytları almak için işleyiciye ihtiyaç duyar ve şeması için kayıtlı bir işleyici olmayan bir URI hata fırlatır.

Panelde artefact'ları görüntüleme

Panelin Artifacts sekmesi (bir projede artefaktlar olduğunda görünür), artefaktları türlerine göre gruplandırır; her sürümün takma adları, boyutu ve dosya sayısını listeler. Bir sürüm seçildiğinde dosya manifesti (bir dosyayı indirmek için üzerine tıklayın) ile birlikte metadata ve soy ağacı gösterilir: onu üreten çalıştırma ve onu kullanan çalıştırmalar, her biri ilgili çalıştırmanın ayrıntı sayfasına bağlantı verir.

Her sürümün, sürümün soy ağacını gösteren etkileşimli bir grafik içeren bir Soy Ağacı bölümü de vardır: düğümler olarak artefakt sürümleri ve çalıştırmalar, bir çalıştırmadan kaydettiği artefaktlara ve bir artefaktan onu kullanan çalıştırmalara giden oklar. Seçili sürüm vurgulanır. Büyük grafiklerin okunabilirliğini korumak için, aynı bağlantılara sahip beş veya daha fazla benzer düğüm (örneğin, tek bir çalıştırmanın kaydettiği birçok kontrol noktası) sayıyı gösteren tek bir küme düğümünde birleştirilir — üyelerini aramak ve bunları tek tek grafiğe geri çıkarmak için kümeye tıklayın. Sürükleyerek kaydırın, yakınlaştırmak için Ctrl/Cmd + kaydırma çubuğu (veya +/− düğmeleri) kullanın ve o çalıştırma veya artefakt sürümüne giden bağlantıyla birlikte bir özet açmak için herhangi bir düğüme tıklayın.

Çalışma detay sayfaları, Çıktı artefaktları ve Girdi artefaktları bölümleriyle Artefaktlar sekmesine geri bağlanan, diğer yönden aynı soy ağacını gösterir.

Uzak depolama

Çalışmanız bir Hugging Face Space veya kendi barındırdığınız bir sunucuyu hedeflediğinde (bkz. Track), artefakt dosyaları içerik adreslemeli (content-addressed) olarak işlenir ve yalnızca bir kez yüklenir: Trackio, sunucunun zaten sahip olduğu blob'ları atlar, bu nedenle paylaşılan dosyaların yeniden kaydedilmesi düşük maliyetlidir. Artefakt meta verileri ve blob'lar, yapılandırılan HF Dataset veya bucket ile birlikte diğer çalışma verilerinizle kalıcı olarak saklanır.