Buckets:

hf-doc-build
/

doc-dev

Files

xet

hf-doc-build/doc-dev / trackio /pr_676 /en /artifacts.html

qgallouedec

4 days ago

download

raw

75.7 kB

	<meta charset="utf-8" /><meta name="hf:doc:metadata" content="{"title":"Artifacts","local":"artifacts","sections":[{"title":"Introduction","local":"introduction","sections":[],"depth":2},{"title":"Logging an artifact","local":"logging-an-artifact","sections":[{"title":"Artifact types","local":"artifact-types","sections":[],"depth":3},{"title":"Building an artifact explicitly","local":"building-an-artifact-explicitly","sections":[],"depth":3},{"title":"Versions and aliases","local":"versions-and-aliases","sections":[],"depth":3}],"depth":2},{"title":"Using an artifact","local":"using-an-artifact","sections":[{"title":"Downloading files","local":"downloading-files","sections":[],"depth":3}],"depth":2},{"title":"Referencing external data","local":"referencing-external-data","sections":[],"depth":2},{"title":"Referencing other stores (S3, GCS, Azure)","local":"referencing-other-stores-s3-gcs-azure","sections":[{"title":"S3 ( s3:// , via boto3 )","local":"s3--s3--via-boto3-","sections":[],"depth":3},{"title":"Google Cloud Storage ( gs:// , via google-cloud-storage )","local":"google-cloud-storage--gs--via-google-cloud-storage-","sections":[],"depth":3},{"title":"Azure Blob Storage (via azure-storage-blob + azure-identity )","local":"azure-blob-storage-via-azure-storage-blob--azure-identity-","sections":[],"depth":3}],"depth":2},{"title":"Browsing artifacts in the dashboard","local":"browsing-artifacts-in-the-dashboard","sections":[],"depth":2},{"title":"Remote storage","local":"remote-storage","sections":[],"depth":2}],"depth":1}"/>
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/entry/start.BRWY-7Pk.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/BI0o03iR.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/c5epZbRJ.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/entry/app.BWp3UJuk.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/CTPvGMXu.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/Cbx9Bn2j.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/DsnmJJEf.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/CldSabhm.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/nodes/0.Cdh0K3im.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/DoyOpfDJ.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/nodes/5.B5lJohyX.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/BQnA81uy.js" rel="modulepreload">
	<!--1oozjl8--><meta name="hf:doc:metadata" content="{"title":"Artifacts","local":"artifacts","sections":[{"title":"Introduction","local":"introduction","sections":[],"depth":2},{"title":"Logging an artifact","local":"logging-an-artifact","sections":[{"title":"Artifact types","local":"artifact-types","sections":[],"depth":3},{"title":"Building an artifact explicitly","local":"building-an-artifact-explicitly","sections":[],"depth":3},{"title":"Versions and aliases","local":"versions-and-aliases","sections":[],"depth":3}],"depth":2},{"title":"Using an artifact","local":"using-an-artifact","sections":[{"title":"Downloading files","local":"downloading-files","sections":[],"depth":3}],"depth":2},{"title":"Referencing external data","local":"referencing-external-data","sections":[],"depth":2},{"title":"Referencing other stores (S3, GCS, Azure)","local":"referencing-other-stores-s3-gcs-azure","sections":[{"title":"S3 ( s3:// , via boto3 )","local":"s3--s3--via-boto3-","sections":[],"depth":3},{"title":"Google Cloud Storage ( gs:// , via google-cloud-storage )","local":"google-cloud-storage--gs--via-google-cloud-storage-","sections":[],"depth":3},{"title":"Azure Blob Storage (via azure-storage-blob + azure-identity )","local":"azure-blob-storage-via-azure-storage-blob--azure-identity-","sections":[],"depth":3}],"depth":2},{"title":"Browsing artifacts in the dashboard","local":"browsing-artifacts-in-the-dashboard","sections":[],"depth":2},{"title":"Remote storage","local":"remote-storage","sections":[],"depth":2}],"depth":1}"/><!---->
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/assets/0.tn0RQdqM.css" rel="modulepreload"> <!--[--><!--[0--><!--[--><!--[0--><!--[--><p></p> <div class="items-center shrink-0 min-w-[100px] max-sm:min-w-[50px] justify-end ml-auto flex" style="float: right; margin-left: 10px; display: inline-flex; position: relative; z-index: 10;"><div class="inline-flex rounded-md max-sm:rounded-sm"><button class="inline-flex items-center gap-1 h-7 max-sm:h-7 px-2 max-sm:px-1.5 text-sm font-medium text-gray-800 border border-r-0 rounded-l-md max-sm:rounded-l-sm border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-live="polite"><span class="inline-flex items-center justify-center rounded-md p-0.5 max-sm:p-0 hover:text-gray-800 dark:hover:text-gray-200"><svg class="sm:size-3.5 size-3" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----></span> <span>Copy page</span></button> <button class="inline-flex items-center justify-center w-6 max-sm:w-5 h-7 max-sm:h-7 disabled:pointer-events-none text-sm text-gray-500 hover:text-gray-700 dark:hover:text-white rounded-r-md max-sm:rounded-r-sm border border-l transition border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-haspopup="menu" aria-expanded="false" aria-label="Open copy menu"><svg class="transition-transform text-gray-400 overflow-visible sm:size-3.5 size-3 rotate-0" width="1em" height="1em" viewBox="0 0 12 7" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 1L6 6L11 1" stroke="currentColor"></path></svg><!----></button></div> <!--[-1--><!--]--></div><!----> <!--[0--><h1 class="relative group"><a id="artifacts" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#artifacts"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Artifacts</span></h1><!--]--><!----> <!--[1--><h2 class="relative group"><a id="introduction" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#introduction"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Introduction</span></h2><!--]--><!----> <p>An <strong>artifact</strong> is a versioned, named bundle of files attached to a project — a trained model, a dataset, a set of evaluation outputs. Logging files as artifacts (rather than leaving them on disk) gives you:</p> <ul><li><strong>Versioning</strong> — each time you log under the same name, Trackio records a new version (<code>v0</code>, <code>v1</code>, …). Identical content is de-duplicated, so re-logging unchanged files reuses the existing version.</li> <li><strong>Aliases</strong> — moving pointers such as <code>latest</code> (assigned automatically) or your own (<code>prod</code>, <code>best</code>) that always resolve to a single version.</li> <li><strong>Lineage</strong> — artifacts are linked to the runs that produced and consumed them, so you can trace which run created a model and which runs used it.</li></ul> <p>Artifacts work fully offline against local storage, and sync to a Hugging Face Space (or self-hosted server) when one is configured, exactly like metrics.</p> <!--[1--><h2 class="relative group"><a id="logging-an-artifact" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#logging-an-artifact"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Logging an artifact</span></h2><!--]--><!----> <p>The quickest way is to log a file or directory directly. This creates a new artifact, adds the path, and records it as an output of the current run:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!----><span class="hljs-keyword">import</span> trackio

	trackio.init(project=<span class="hljs-string">"my_project"</span>)

	<span class="hljs-comment"># ... training ...</span>

	trackio.log_artifact(<span class="hljs-string">"checkpoints/model.safetensors"</span>, <span class="hljs-built_in">type</span>=<span class="hljs-string">"model"</span>)<!----></pre></div><!----> <p>When you pass a path, the artifact <code>name</code> defaults to <code>run-<run_id>-<basename></code> and <code>type</code> defaults to <code>"unspecified"</code>. Pass <code>name</code> and <code>type</code> to set them explicitly:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->trackio.log_artifact(<span class="hljs-string">"checkpoints/"</span>, name=<span class="hljs-string">"my-model"</span>, <span class="hljs-built_in">type</span>=<span class="hljs-string">"model"</span>)<!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="artifact-types" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#artifact-types"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Artifact types</span></h3><!--]--><!----> <p>Artifact <code>type</code> is a free-form category string. Trackio does not enforce a fixed list of types, but common conventions are:</p> <table><thead><tr><th>Type</th><th>Use it for</th></tr></thead><tbody><tr><td><code>"model"</code></td><td>Model checkpoints, adapter weights, tokenizers, model configs</td></tr><tr><td><code>"dataset"</code></td><td>Training, validation, test, or generated datasets</td></tr><tr><td><code>"evaluation"</code></td><td>Evaluation outputs, predictions, benchmark results, score files</td></tr><tr><td><code>"report"</code></td><td>Figures, plots, tables, notebooks, or human-readable analysis bundles</td></tr><tr><td><code>"unspecified"</code></td><td>The default when no type is provided</td></tr></tbody></table> <p>Use stable type names within a project so you can filter artifacts consistently and use <code>trackio.use_artifact(..., type="...")</code> to assert that a run is consuming the expected kind of artifact.</p> <!--[2--><h3 class="relative group"><a id="building-an-artifact-explicitly" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#building-an-artifact-explicitly"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Building an artifact explicitly</span></h3><!--]--><!----> <p>For finer control — multiple files, custom logical paths, a description, or metadata — construct an <a href="/docs/trackio/pr_676/en/api#trackio.Artifact">Artifact</a>, add files to it, then log it:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->artifact = trackio.Artifact(
	name=<span class="hljs-string">"my-model"</span>,
	<span class="hljs-built_in">type</span>=<span class="hljs-string">"model"</span>,
	description=<span class="hljs-string">"Fine-tuned on the v2 dataset"</span>,
	metadata={<span class="hljs-string">"base_model"</span>: <span class="hljs-string">"bert-base"</span>, <span class="hljs-string">"epochs"</span>: <span class="hljs-number">3</span>},
	)
	artifact.add_file(<span class="hljs-string">"checkpoints/model.safetensors"</span>)
	artifact.add_file(<span class="hljs-string">"checkpoints/config.json"</span>)
	artifact.add_dir(<span class="hljs-string">"tokenizer/"</span>)

	logged = trackio.log_artifact(artifact)<!----></pre></div><!----> <p>After logging, the artifact is frozen and its <code>version</code>, <code>aliases</code>, <code>size</code>, and <code>manifest</code> are populated:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!----><span class="hljs-built_in">print</span>(logged.version) <span class="hljs-comment"># "v0"</span>
	<span class="hljs-built_in">print</span>(logged.aliases) <span class="hljs-comment"># ("latest",)</span><!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="versions-and-aliases" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#versions-and-aliases"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Versions and aliases</span></h3><!--]--><!----> <p>Each log under an existing name creates the next integer version and moves the <code>latest</code> alias onto it. Assign your own aliases with <code>aliases=</code>:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->trackio.log_artifact(artifact, aliases=[<span class="hljs-string">"prod"</span>, <span class="hljs-string">"best"</span>])<!----></pre></div><!----> <p>Aliases are moving pointers: logging a new version with the same alias re-points it. Version specifiers (<code>v0</code>, <code>v1</code>, …) are reserved and cannot be used as aliases.</p> <p>If you log content identical to an existing version, Trackio reuses that version instead of creating a new one. Any explicit <code>aliases</code> you pass still rotate onto it, but <code>latest</code> is left where it is — re-logging identical (or older) content never moves it backward.</p> <!--[1--><h2 class="relative group"><a id="using-an-artifact" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#using-an-artifact"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Using an artifact</span></h2><!--]--><!----> <p><a href="/docs/trackio/pr_676/en/api#trackio.use_artifact">use_artifact()</a> fetches an artifact and records it as an <strong>input</strong> to the current run, which is what builds lineage between a consuming run and the artifact it used:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->trackio.init(project=<span class="hljs-string">"my_project"</span>)

	artifact = trackio.use_artifact(<span class="hljs-string">"my-model"</span>) <span class="hljs-comment"># resolves to :latest</span>
	artifact = trackio.use_artifact(<span class="hljs-string">"my-model:v2"</span>) <span class="hljs-comment"># pin a version</span>
	artifact = trackio.use_artifact(<span class="hljs-string">"my-model:prod"</span>) <span class="hljs-comment"># resolve an alias</span><!----></pre></div><!----> <p>Pass <code>type</code> to assert the artifact’s type, raising if it doesn’t match:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->artifact = trackio.use_artifact(<span class="hljs-string">"my-model"</span>, <span class="hljs-built_in">type</span>=<span class="hljs-string">"model"</span>)<!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="downloading-files" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#downloading-files"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Downloading files</span></h3><!--]--><!----> <p><code>use_artifact</code> returns an <a href="/docs/trackio/pr_676/en/api#trackio.Artifact">Artifact</a> whose files you materialize with <code>download()</code>:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->artifact = trackio.use_artifact(<span class="hljs-string">"my-model:latest"</span>)
	path = artifact.download()
	<span class="hljs-comment"># files are now under ./.trackio/artifact-downloads/my_project/my-model_v2/</span><!----></pre></div><!----> <p>By default, files are written to <code>./.trackio/artifact-downloads/<project>/<name>_v<version>/</code>, keyed by project so same-named artifacts from different projects never collide; pass <code>root</code> to choose another directory. <code>download()</code> is idempotent — files already present are skipped — and when the run is backed by a Space, any file missing locally is fetched from the remote.</p> <!--[1--><h2 class="relative group"><a id="referencing-external-data" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#referencing-external-data"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Referencing external data</span></h2><!--]--><!----> <p>Some data is too large to copy, or already lives in durable storage you don’t want duplicated. <code>add_reference</code> records such data by <strong>URI</strong> in the manifest <em>without staging any bytes</em> into Trackio’s storage, so you still get versioning, de-duplication, aliases, and lineage over data that never moves:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->artifact = trackio.Artifact(name=<span class="hljs-string">"training-set"</span>, <span class="hljs-built_in">type</span>=<span class="hljs-string">"dataset"</span>)
	artifact.add_reference(<span class="hljs-string">"file:///mnt/nvme/datasets/corpus.parquet"</span>)
	artifact.add_reference(<span class="hljs-string">"file:///mnt/nvme/datasets/shards/"</span>) <span class="hljs-comment"># a directory — expands to one entry per file</span>
	artifact.add_reference(<span class="hljs-string">"https://example.com/data/eval.json"</span>)
	artifact.add_reference(<span class="hljs-string">"hf://datasets/username/my-dataset/train.parquet"</span>)
	trackio.log_artifact(artifact)<!----></pre></div><!----> <p>Built-in schemes are <code>file://</code>, <code>http(s)://</code>, and <code>hf://</code> — all served by Trackio’s existing dependencies. Any other scheme (<code>s3://</code>, <code>gs://</code>, Azure blob URLs, …) is supported by registering a custom handler; see <a href="#referencing-other-stores-s3-gcs-azure">Referencing other stores</a> below for complete S3, GCS, and Azure examples. With <code>checksum=True</code> (the default), Trackio probes the source to fill in <code>size</code> and a checksum:</p> <ul><li><code>file://</code> is stream-hashed to a sha256; its size is read from disk.</li> <li><code>hf://</code> uses the LFS sha256 (or the git blob id); <code>http(s)://</code> uses the server <code>ETag</code>.</li></ul> <p>Every checksum is stored in a single <code>digest</code> field — the sha256 for local/LFS references, or the provider’s ETag for HTTP or object-store references.</p> <p>A URI that denotes a directory (<code>file://</code>) or a repo path (<code>hf://</code>) is <strong>expanded</strong> into one reference entry per object, each named by its path relative to the prefix (nested under <code>name=</code> when given). <code>max_objects</code> (default 10,000) caps the expansion and raises if exceeded.</p> <p>When no checksum can be obtained — for example a server with no <code>ETag</code> — the reference is still recorded, using <strong>the URI itself as the <code>digest</code></strong>, and a warning is emitted. A local <code>file://</code> path that doesn’t exist is the exception: it raises rather than being recorded, since a missing local file is almost always a mistake — use <code>add_file</code> to stage a local file. Pass <code>checksum=False</code> to skip the per-object checksum — a single object then records just its URI — and <code>name=</code> to set the logical path.</p> <p>A reference’s version identity comes from its URI, size, and <code>digest</code>, so re-logging identical references de-duplicates to one version, while a changed URI, size, or checksum creates a new one — exactly like file content. When the URI is used as the <code>digest</code>, identity therefore tracks the URI and not the content.</p> <p>URIs are recorded verbatim, and manifests can be synced to a Hugging Face Dataset. A URI that embeds a credential — a presigned <code>https://</code> URL or an Azure SAS token — would expose that credential to anyone who can read the Dataset, so <code>add_reference</code> warns when a URI’s query string looks signed; prefer the object’s canonical unsigned URI (e.g. <code>s3://bucket/key</code>).</p> <p>Reference bytes are never uploaded to a Space or bucket, but they can be fetched on demand. <code>download()</code> downloads each referenced object into the directory (via <code>httpx</code>, <code>huggingface_hub</code>, or your registered handler), which can transfer a large amount of data. Before fetching, each object’s source is re-probed and its current checksum compared against the recorded one — a mismatch warns that the source may have changed but the download proceeds. Each object is written atomically, and one already present on disk is skipped without re-checking the source, so repeated calls are cheap and idempotent:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->artifact = trackio.use_artifact(<span class="hljs-string">"training-set:latest"</span>)
	path = artifact.download() <span class="hljs-comment"># downloads staged files AND referenced objects</span><!----></pre></div><!----> <p>To work with the pointers <em>without</em> downloading, read them from the artifact instead:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!----><span class="hljs-built_in">print</span>(artifact.references) <span class="hljs-comment"># [{'path': ..., 'ref': 's3://...', 'size': ..., 'digest': ...}, ...]</span>
	<span class="hljs-built_in">print</span>(artifact.get_entry_uri(<span class="hljs-string">"eval.json"</span>)) <span class="hljs-comment"># "s3://my-bucket/eval.json"</span><!----></pre></div><!----> <p>An unfetchable reference (a missing local file, an unreachable URL, or a scheme with no registered handler) raises when <code>download()</code> reaches it.</p> <!--[1--><h2 class="relative group"><a id="referencing-other-stores-s3-gcs-azure" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#referencing-other-stores-s3-gcs-azure"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Referencing other stores (S3, GCS, Azure)</span></h2><!--]--><!----> <p>Trackio deliberately ships no cloud-vendor SDKs. To reference objects in a store it doesn’t handle natively, subclass <code>trackio.ReferenceHandler</code> and register an instance with <code>trackio.register_reference_handler</code>. A handler implements four methods:</p> <ul><li><code>matches(scheme, uri)</code> — whether this handler owns the URI. Registered handlers are consulted <em>before</em> the built-ins, so a handler may also claim specific <code>https://</code> hosts (as the Azure example below does) ahead of the generic HTTP handler.</li> <li><code>resolve(uri, checksum, max_objects)</code> — probe the source and return a list of <code>trackio.ResolvedReference</code> entries: one entry with <code>relkey=None</code> for a single object, or one entry per object (with <code>relkey</code> set to the object’s path relative to the prefix) when the URI denotes a prefix. Set <code>size</code> and <code>digest</code> when the source can be probed (the provider’s ETag works fine as a digest — Trackio treats reference digests as opaque tokens); return them as <code>None</code> to record the reference un-checksummed, in which case Trackio falls back to the URI as the digest and warns.</li> <li><code>fetch(uri, dest)</code> — download the single object at <code>uri</code> to the local path <code>dest</code> (called by <code>Artifact.download()</code>).</li> <li><code>hint()</code> — a one-line actionable message shown in the warning when <code>resolve</code> produced no checksum.</li></ul> <p>Keys discovered during prefix expansion should be percent-encoded when synthesizing each entry’s <code>uri</code> (and decoded in <code>fetch</code>), since manifest URIs may not contain spaces.</p> <!--[2--><h3 class="relative group"><a id="s3--s3--via-boto3-" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#s3--s3--via-boto3-"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>S3 ( s3:// , via boto3 )</span></h3><!--]--><!----> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!----><span class="hljs-keyword">from</span> urllib.parse <span class="hljs-keyword">import</span> quote, unquote, urlsplit

	<span class="hljs-keyword">import</span> boto3

	<span class="hljs-keyword">import</span> trackio


	<span class="hljs-keyword">class</span> <span class="hljs-title class_">S3Handler</span>(trackio.ReferenceHandler):
	<span class="hljs-keyword">def</span> <span class="hljs-title function_">matches</span>(<span class="hljs-params">self, scheme, uri</span>):
	<span class="hljs-keyword">return</span> scheme == <span class="hljs-string">"s3"</span>

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

	<span class="hljs-keyword">def</span> <span class="hljs-title function_">fetch</span>(<span class="hljs-params">self, uri, dest</span>):
	parts = urlsplit(uri)
	<span class="hljs-keyword">with</span> <span class="hljs-built_in">open</span>(dest, <span class="hljs-string">"wb"</span>) <span class="hljs-keyword">as</span> f:
	boto3.client(<span class="hljs-string">"s3"</span>).download_fileobj(
	parts.netloc, unquote(parts.path.lstrip(<span class="hljs-string">"/"</span>)), f
	)

	<span class="hljs-keyword">def</span> <span class="hljs-title function_">hint</span>(<span class="hljs-params">self</span>):
	<span class="hljs-keyword">return</span> <span class="hljs-string">"Configure AWS credentials so the object can be probed for an ETag."</span>


	trackio.register_reference_handler(S3Handler())

	artifact = trackio.Artifact(name=<span class="hljs-string">"training-set"</span>, <span class="hljs-built_in">type</span>=<span class="hljs-string">"dataset"</span>)
	artifact.add_reference(<span class="hljs-string">"s3://my-bucket/shards/"</span>) <span class="hljs-comment"># expands to one entry per object</span>
	trackio.log_artifact(artifact)<!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="google-cloud-storage--gs--via-google-cloud-storage-" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#google-cloud-storage--gs--via-google-cloud-storage-"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Google Cloud Storage ( gs:// , via google-cloud-storage )</span></h3><!--]--><!----> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!----><span class="hljs-keyword">from</span> urllib.parse <span class="hljs-keyword">import</span> quote, unquote, urlsplit

	<span class="hljs-keyword">from</span> google.cloud <span class="hljs-keyword">import</span> storage

	<span class="hljs-keyword">import</span> trackio


	<span class="hljs-keyword">class</span> <span class="hljs-title class_">GcsHandler</span>(trackio.ReferenceHandler):
	<span class="hljs-keyword">def</span> <span class="hljs-title function_">matches</span>(<span class="hljs-params">self, scheme, uri</span>):
	<span class="hljs-keyword">return</span> scheme == <span class="hljs-string">"gs"</span>

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

	<span class="hljs-keyword">def</span> <span class="hljs-title function_">fetch</span>(<span class="hljs-params">self, uri, dest</span>):
	parts = urlsplit(uri)
	key = unquote(parts.path.lstrip(<span class="hljs-string">"/"</span>))
	storage.Client().bucket(parts.netloc).blob(key).download_to_filename(
	<span class="hljs-built_in">str</span>(dest)
	)

	<span class="hljs-keyword">def</span> <span class="hljs-title function_">hint</span>(<span class="hljs-params">self</span>):
	<span class="hljs-keyword">return</span> <span class="hljs-string">"Configure GCP credentials so the object can be probed for an ETag."</span>


	trackio.register_reference_handler(GcsHandler())<!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="azure-blob-storage-via-azure-storage-blob--azure-identity-" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#azure-blob-storage-via-azure-storage-blob--azure-identity-"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Azure Blob Storage (via azure-storage-blob + azure-identity )</span></h3><!--]--><!----> <p>Azure blobs are addressed by plain <code>https://</code> URLs (<code>https://<account>.blob.core.windows.net/<container>/<blob></code>), so this handler claims them by host suffix — registering it makes it win over Trackio’s generic HTTP handler:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!----><span class="hljs-keyword">from</span> urllib.parse <span class="hljs-keyword">import</span> quote, unquote, urlsplit

	<span class="hljs-keyword">from</span> azure.identity <span class="hljs-keyword">import</span> DefaultAzureCredential
	<span class="hljs-keyword">from</span> azure.storage.blob <span class="hljs-keyword">import</span> BlobServiceClient

	<span class="hljs-keyword">import</span> trackio


	<span class="hljs-keyword">class</span> <span class="hljs-title class_">AzureHandler</span>(trackio.ReferenceHandler):
	<span class="hljs-keyword">def</span> <span class="hljs-title function_">matches</span>(<span class="hljs-params">self, scheme, uri</span>):
	<span class="hljs-keyword">return</span> scheme <span class="hljs-keyword">in</span> (<span class="hljs-string">"http"</span>, <span class="hljs-string">"https"</span>) <span class="hljs-keyword">and</span> urlsplit(
	uri
	).netloc.lower().endswith(<span class="hljs-string">".blob.core.windows.net"</span>)

	<span class="hljs-keyword">def</span> <span class="hljs-title function_">_split</span>(<span class="hljs-params">self, uri</span>):
	parts = urlsplit(uri)
	container, _, blob_name = parts.path.lstrip(<span class="hljs-string">"/"</span>).partition(<span class="hljs-string">"/"</span>)
	<span class="hljs-keyword">return</span> <span class="hljs-string">f"<span class="hljs-subst">{parts.scheme}</span>://<span class="hljs-subst">{parts.netloc}</span>"</span>, container, unquote(blob_name)

	<span class="hljs-keyword">def</span> <span class="hljs-title function_">_service</span>(<span class="hljs-params">self, account_url</span>):
	<span class="hljs-keyword">return</span> BlobServiceClient(account_url, credential=DefaultAzureCredential())

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

	<span class="hljs-keyword">def</span> <span class="hljs-title function_">fetch</span>(<span class="hljs-params">self, uri, dest</span>):
	account_url, container, blob_name = <span class="hljs-variable language_">self</span>._split(uri)
	downloader = (
	<span class="hljs-variable language_">self</span>._service(account_url)
	.get_blob_client(container, blob_name)
	.download_blob()
	)
	<span class="hljs-keyword">with</span> <span class="hljs-built_in">open</span>(dest, <span class="hljs-string">"wb"</span>) <span class="hljs-keyword">as</span> f:
	downloader.readinto(f)

	<span class="hljs-keyword">def</span> <span class="hljs-title function_">hint</span>(<span class="hljs-params">self</span>):
	<span class="hljs-keyword">return</span> <span class="hljs-string">"Configure Azure credentials so the blob can be probed for an ETag."</span>


	trackio.register_reference_handler(AzureHandler())<!----></pre></div><!----> <p>These handlers raise when the source can’t be probed; if you’d rather record an un-checksummed reference in that case (for example, when cataloging data behind auth you can’t reach at log time), catch the provider error inside <code>resolve</code> and return <code>[trackio.ResolvedReference(relkey=None, uri=uri)]</code> — Trackio will fall back to the URI as the digest and warn, using your <code>hint()</code>.</p> <p>Register handlers in every process that adds <em>or downloads</em> such references: <code>Artifact.download()</code> needs the handler to fetch the bytes, and a URI whose scheme has no registered handler raises.</p> <!--[1--><h2 class="relative group"><a id="browsing-artifacts-in-the-dashboard" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#browsing-artifacts-in-the-dashboard"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Browsing artifacts in the dashboard</span></h2><!--]--><!----> <p>The dashboard’s <strong>Artifacts</strong> tab (shown once a project has artifacts) lists artifacts grouped by type, with each version’s aliases, size, and file count. Selecting a version shows its file manifest — click a file to download it — plus its metadata and lineage: the run that produced it and the runs that used it, each linking to the run’s detail page.</p> <p>Each version also has a <strong>Lineage</strong> section showing an interactive graph of the version’s lineage: artifact versions and runs as nodes, with arrows from a run to the artifacts it logged and from an artifact to the runs that used it. The selected version is highlighted. To keep large graphs readable, five or more similar nodes with identical connections (for example, the many checkpoints a single run logged) are grouped into a single <strong>cluster</strong> node showing the count — click the cluster to search its members and extract individual ones back into the graph. Drag to pan, use Ctrl/Cmd + scroll (or the +/− buttons) to zoom, and click any node to open a summary with a link to that run or artifact version.</p> <p>Run detail pages show the same lineage from the other direction, with <strong>Output artifacts</strong> and <strong>Input artifacts</strong> sections linking back to the Artifacts tab.</p> <!--[1--><h2 class="relative group"><a id="remote-storage" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#remote-storage"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Remote storage</span></h2><!--]--><!----> <p>When your run targets a Hugging Face Space or self-hosted server (see <a href="track">Track</a>), artifact files are content-addressed and uploaded once: Trackio skips blobs the server already has, so re-logging shared files is cheap. Artifact metadata and blobs are persisted alongside your other run data to the configured HF Dataset or bucket.</p> <a class="!text-gray-400 !no-underline text-sm flex items-center not-prose mt-4" href="https://github.com/gradio-app/trackio/blob/main/docs/source/artifacts.md" target="_blank"><svg class="mr-1" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M31,16l-7,7l-1.41-1.41L28.17,16l-5.58-5.59L24,9l7,7z"></path><path d="M1,16l7-7l1.41,1.41L3.83,16l5.58,5.59L8,23l-7-7z"></path><path d="M12.419,25.484L17.639,6.552l1.932,0.518L14.351,26.002z"></path></svg><!----> <span><span class="underline">Update</span> on GitHub</span></a><!----> <p></p><!--]--><!----><!--]--><!--]--><!--]--> <!--[-1--><!--]--><!--]-->

	<script>
	{
	__sveltekit_1fjrczi = {
	base: "/docs/trackio/v0.36.0/en",
	assets: "/docs/trackio/v0.36.0/en"
	};

	const element = document.currentScript.parentElement;

	Promise.all([
	import("/docs/trackio/v0.36.0/en/_app/immutable/entry/start.BRWY-7Pk.js"),
	import("/docs/trackio/v0.36.0/en/_app/immutable/entry/app.BWp3UJuk.js")
	]).then(([kit, app]) => {
	kit.start(app, element, {
	node_ids: [0, 5],
	data: [null,null],
	form: null,
	error: null
	});
	});
	}
	</script>

Xet Storage Details

Size:: 75.7 kB
Xet hash:: eeab954901a0682e8eb22ad115b35793a56d9141132847d565b6760cb04e9eb0

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.