Hugging Face's logo

Buckets:
hf-doc-build
/
doc-dev

Files
xet
hf-doc-build/doc-dev / kernels /pr_673 /en /builder /github-actions.html
HuggingFaceDocBuilder's picture
HuggingFaceDocBuilder
download
raw
32.7 kB
<meta charset="utf-8" /><meta name="hf:doc:metadata" content="{&quot;title&quot;:&quot;Building and testing kernels with GitHub Actions&quot;,&quot;local&quot;:&quot;building-and-testing-kernels-with-github-actions&quot;,&quot;sections&quot;:[{&quot;title&quot;:&quot;Prerequisites&quot;,&quot;local&quot;:&quot;prerequisites&quot;,&quot;sections&quot;:[],&quot;depth&quot;:2},{&quot;title&quot;:&quot;Building on push&quot;,&quot;local&quot;:&quot;building-on-push&quot;,&quot;sections&quot;:[{&quot;title&quot;:&quot;kernel-builder-job inputs&quot;,&quot;local&quot;:&quot;kernel-builder-job-inputs&quot;,&quot;sections&quot;:[],&quot;depth&quot;:3}],&quot;depth&quot;:2},{&quot;title&quot;:&quot;Testing on a GPU&quot;,&quot;local&quot;:&quot;testing-on-a-gpu&quot;,&quot;sections&quot;:[{&quot;title&quot;:&quot;hf-jobs-action inputs&quot;,&quot;local&quot;:&quot;hf-jobs-action-inputs&quot;,&quot;sections&quot;:[],&quot;depth&quot;:3}],&quot;depth&quot;:2},{&quot;title&quot;:&quot;Choosing a flavor&quot;,&quot;local&quot;:&quot;choosing-a-flavor&quot;,&quot;sections&quot;:[],&quot;depth&quot;:2}],&quot;depth&quot;:1}">
 <link href="/docs/kernels/pr_673/en/_app/immutable/assets/0.e3b0c442.css" rel="modulepreload">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/entry/start.9eec61bd.js">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/chunks/scheduler.f3b1e791.js">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/chunks/singletons.abb4c4ca.js">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/chunks/paths.dea514cb.js">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/entry/app.5a3c00a6.js">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/chunks/preload-helper.98f59650.js">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/chunks/index.023a9934.js">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/nodes/0.0ef10933.js">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/chunks/each.e59479a4.js">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/nodes/10.13d01adb.js">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/chunks/MermaidChart.svelte_svelte_type_style_lang.b7cac204.js">
 <link rel="modulepreload" href="/docs/kernels/pr_673/en/_app/immutable/chunks/CodeBlock.725c80b2.js"><!-- HEAD_svelte-u9bgzb_START --><meta name="hf:doc:metadata" content="{&quot;title&quot;:&quot;Building and testing kernels with GitHub Actions&quot;,&quot;local&quot;:&quot;building-and-testing-kernels-with-github-actions&quot;,&quot;sections&quot;:[{&quot;title&quot;:&quot;Prerequisites&quot;,&quot;local&quot;:&quot;prerequisites&quot;,&quot;sections&quot;:[],&quot;depth&quot;:2},{&quot;title&quot;:&quot;Building on push&quot;,&quot;local&quot;:&quot;building-on-push&quot;,&quot;sections&quot;:[{&quot;title&quot;:&quot;kernel-builder-job inputs&quot;,&quot;local&quot;:&quot;kernel-builder-job-inputs&quot;,&quot;sections&quot;:[],&quot;depth&quot;:3}],&quot;depth&quot;:2},{&quot;title&quot;:&quot;Testing on a GPU&quot;,&quot;local&quot;:&quot;testing-on-a-gpu&quot;,&quot;sections&quot;:[{&quot;title&quot;:&quot;hf-jobs-action inputs&quot;,&quot;local&quot;:&quot;hf-jobs-action-inputs&quot;,&quot;sections&quot;:[],&quot;depth&quot;:3}],&quot;depth&quot;:2},{&quot;title&quot;:&quot;Choosing a flavor&quot;,&quot;local&quot;:&quot;choosing-a-flavor&quot;,&quot;sections&quot;:[],&quot;depth&quot;:2}],&quot;depth&quot;:1}"><!-- HEAD_svelte-u9bgzb_END --> <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> </div> <h1 class="relative group"><a id="building-and-testing-kernels-with-github-actions" 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-and-testing-kernels-with-github-actions"><span><svg class="" 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 and testing kernels with GitHub Actions</span></h1> <p data-svelte-h="svelte-s9excn">Compiling a kernel is CPU-intensive and testing it requires an accelerator (such as a GPU), two things that GitHub’s standard runners do not provide cheaply. Instead of maintaining self-hosted runners, you can offload both steps to <a href="https://huggingface.co/docs/huggingface_hub/guides/jobs" rel="nofollow">Hugging Face Jobs</a> directly from a GitHub Actions workflow.</p> <p data-svelte-h="svelte-8tyxhx">Two prebuilt actions make this possible:</p> <ul data-svelte-h="svelte-1ua20xp"><li><a href="https://github.com/huggingface/kernel-builder-job" rel="nofollow"><code>huggingface/kernel-builder-job</code></a> runs the Nix kernel builder on a CPU flavor and publishes the built kernel to the Hub.</li> <li><a href="https://github.com/huggingface/hf-jobs-action" rel="nofollow"><code>huggingface/hf-jobs-action</code></a> runs an arbitrary script on any flavor (including GPUs), which is convenient for testing the kernel you just built. This also helps to test the kernel across different hardware.</li></ul> <p data-svelte-h="svelte-1nkgmyn">A typical setup has two workflows: one that <strong>builds</strong> the kernel on push, and one that <strong>tests</strong> it on a GPU. They communicate through the Hub, the build uploads artifacts, the test pulls them back down.</p> <h2 class="relative group"><a id="prerequisites" 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="#prerequisites"><span><svg class="" 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>Prerequisites</span></h2> <ul data-svelte-h="svelte-mdict8"><li>An <a href="https://huggingface.co/settings/tokens" rel="nofollow">HF access token</a> with the <code>job.write</code> permission. If the test job loads gated models, the token also needs read access to them.</li> <li>The token stored as a repository secret named <code>HF_TOKEN</code> (<strong>Settings → Secrets and variables → Actions</strong>).</li> <li>A kernel repository on the Hub to upload to, with kernel-creation access for the owning user or org (see <a href="build#uploading-your-kernel-to-the-hub">Building kernels</a>).</li></ul> <blockquote class="note" data-svelte-h="svelte-1j4xyj4"><p>Jobs run under the <code>namespace</code> you specify (your username or an org) and
count against that namespace’s compute quota.</p></blockquote> <h2 class="relative group"><a id="building-on-push" 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-on-push"><span><svg class="" 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 on push</span></h2> <p data-svelte-h="svelte-fjjjt5">The build action checks out nothing by itself, your script clones the exact commit and invokes the Nix builder. Compilation happens on the HF Jobs CPU flavor, and <code>build-and-upload</code> pushes the finished variants to the Hub.</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 class="" 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-yaml "><!-- HTML_TAG_START --><span class="hljs-comment"># .github/workflows/build-kernel.yml</span>
<span class="hljs-attr">name:</span> <span class="hljs-string">Build</span> <span class="hljs-string">Kernel</span>
<span class="hljs-attr">on:</span>
 <span class="hljs-attr">push:</span>
 <span class="hljs-attr">branches:</span> [<span class="hljs-string">main</span>]
 <span class="hljs-attr">paths:</span>
 <span class="hljs-bullet">-</span> <span class="hljs-string">&quot;csrc/**&quot;</span>
 <span class="hljs-bullet">-</span> <span class="hljs-string">&quot;torch-ext/**&quot;</span>
 <span class="hljs-bullet">-</span> <span class="hljs-string">build.toml</span>
 <span class="hljs-bullet">-</span> <span class="hljs-string">flake.nix</span>
 <span class="hljs-bullet">-</span> <span class="hljs-string">flake.lock</span>
 <span class="hljs-attr">workflow_dispatch:</span>
<span class="hljs-attr">jobs:</span>
 <span class="hljs-attr">build:</span>
 <span class="hljs-attr">runs-on:</span> <span class="hljs-string">ubuntu-latest</span>
 <span class="hljs-attr">steps:</span>
 <span class="hljs-bullet">-</span> <span class="hljs-attr">uses:</span> <span class="hljs-string">actions/checkout@v4</span>
 <span class="hljs-bullet">-</span> <span class="hljs-attr">name:</span> <span class="hljs-string">Build</span> <span class="hljs-string">kernel</span> <span class="hljs-string">via</span> <span class="hljs-string">HF</span> <span class="hljs-string">Jobs</span>
 <span class="hljs-attr">uses:</span> <span class="hljs-string">huggingface/kernel-builder-job@main</span>
 <span class="hljs-attr">with:</span>
 <span class="hljs-attr">token:</span> <span class="hljs-string">${{</span> <span class="hljs-string">secrets.HF_TOKEN</span> <span class="hljs-string">}}</span>
 <span class="hljs-attr">namespace:</span> <span class="hljs-string">your-username</span>
 <span class="hljs-attr">flavor:</span> <span class="hljs-string">cpu-xl</span>
 <span class="hljs-attr">timeout:</span> <span class="hljs-string">&quot;21600&quot;</span>
 <span class="hljs-attr">script:</span> <span class="hljs-string">|
 # The container starts with `set -x`; disable tracing so the
 # token below is not echoed into the streamed logs.
 set +x
 export HF_TOKEN=&quot;${{ secrets.HF_TOKEN }}&quot;
 # Rebuild artifacts, so skip pulling existing LFS blobs.
 export GIT_LFS_SKIP_SMUDGE=1
</span>
 <span class="hljs-string">git</span> <span class="hljs-string">clone</span> <span class="hljs-string">&quot;$<span class="hljs-template-variable">{{ github.server_url }}</span>/$<span class="hljs-template-variable">{{ github.repository }}</span>&quot;</span> <span class="hljs-string">kernel</span>
 <span class="hljs-string">cd</span> <span class="hljs-string">kernel</span>
 <span class="hljs-string">git</span> <span class="hljs-string">checkout</span> <span class="hljs-string">&quot;$<span class="hljs-template-variable">{{ github.sha }}</span>&quot;</span>
<span class="hljs-string">nix</span> <span class="hljs-string">run</span> <span class="hljs-string">github:huggingface/kernels#kernel-builder</span> <span class="hljs-string">--</span> <span class="hljs-string">build-and-upload</span> <span class="hljs-string">\</span>
 <span class="hljs-string">--max-jobs</span> <span class="hljs-number">4</span> <span class="hljs-string">\</span>
 <span class="hljs-string">--cores</span> <span class="hljs-number">8</span> <span class="hljs-string">\</span>
 <span class="hljs-string">--repo-id</span> <span class="hljs-string">your-username/your-kernel</span><!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-1ql1fp1">The path filter keeps the build from running on unrelated commits, and <code>workflow_dispatch</code> lets you trigger it by hand from the <strong>Actions</strong> tab. The upload destination is taken from <code>--repo-id</code> (or, if omitted, from the <code>repo-id</code>/<code>version</code> fields in <code>build.toml</code>).</p> <blockquote class="tip" data-svelte-h="svelte-1k9k30z"><p>Builds can take a long time on the first run because every PyTorch and CUDA
variant is compiled. Set a generous <code>timeout</code> (the example allows six hours)
and rely on the <a href="build#using-the-hugging-face-binary-cache">Hugging Face binary cache</a>
to keep subsequent builds fast.</p></blockquote> <p data-svelte-h="svelte-2k8asc">You can speed up builds by tuning how much work runs in parallel. <code>--max-jobs</code>
sets how many kernel variants are built concurrently, while <code>--cores</code> sets how
many CPU cores each of those jobs may use. Pick values that fit the chosen CPU
<code>flavor</code>: a larger flavor (such as <code>cpu-xl</code>) has more cores to spread across
jobs, so raising <code>--max-jobs</code> and <code>--cores</code> together shortens the total build
time. Setting them too high for the flavor only adds scheduling overhead.</p> <h3 class="relative group"><a id="kernel-builder-job-inputs" 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="#kernel-builder-job-inputs"><span><svg class="" 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>kernel-builder-job inputs</span></h3> <table data-svelte-h="svelte-1ojltpm"><thead><tr><th>Input</th> <th>Required</th> <th>Default</th> <th>Description</th></tr></thead> <tbody><tr><td><code>token</code></td> <td>yes</td> <td></td> <td>HF token with <code>job.write</code> permission.</td></tr> <tr><td><code>namespace</code></td> <td>yes</td> <td></td> <td>HF namespace (username or org) that owns the job.</td></tr> <tr><td><code>script</code></td> <td>yes</td> <td></td> <td>Shell script to run in the container.</td></tr> <tr><td><code>flavor</code></td> <td>no</td> <td><code>cpu-upgrade</code></td> <td>Hardware flavor (e.g. <code>cpu-xl</code>).</td></tr> <tr><td><code>image</code></td> <td>no</td> <td>Nix + cachix image</td> <td>Container image to run the build in.</td></tr> <tr><td><code>timeout</code></td> <td>no</td> <td><code>1200</code></td> <td>Maximum seconds to wait for the job.</td></tr></tbody></table> <p data-svelte-h="svelte-1tjghwi">The action exposes <code>job_id</code> and <code>job_url</code> outputs that link to the run on huggingface.co.</p> <h2 class="relative group"><a id="testing-on-a-gpu" 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="#testing-on-a-gpu"><span><svg class="" 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>Testing on a GPU</span></h2> <p data-svelte-h="svelte-1hyjlv7">Once the kernel is on the Hub, the generic jobs action runs a test script on a GPU flavor. The <code>files</code> input copies repository files into the container (under <code>/tmp/files</code> by default), and a <a href="https://docs.astral.sh/uv/guides/scripts/" rel="nofollow"><code>uv</code> script</a> with inline dependencies keeps the environment self-contained.</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 class="" 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-yaml "><!-- HTML_TAG_START --><span class="hljs-comment"># .github/workflows/run-tests.yml</span>
<span class="hljs-attr">name:</span> <span class="hljs-string">Run</span> <span class="hljs-string">tests</span>
<span class="hljs-attr">on:</span>
 <span class="hljs-attr">push:</span>
 <span class="hljs-attr">branches:</span> [<span class="hljs-string">main</span>]
 <span class="hljs-attr">paths:</span>
 <span class="hljs-bullet">-</span> <span class="hljs-string">scripts/test.py</span>
 <span class="hljs-attr">workflow_dispatch:</span>
<span class="hljs-attr">jobs:</span>
 <span class="hljs-attr">run:</span>
 <span class="hljs-attr">runs-on:</span> <span class="hljs-string">ubuntu-latest</span>
 <span class="hljs-attr">steps:</span>
 <span class="hljs-bullet">-</span> <span class="hljs-attr">uses:</span> <span class="hljs-string">actions/checkout@v4</span>
 <span class="hljs-bullet">-</span> <span class="hljs-attr">name:</span> <span class="hljs-string">Run</span> <span class="hljs-string">test.py</span> <span class="hljs-string">on</span> <span class="hljs-string">an</span> <span class="hljs-string">HF</span> <span class="hljs-string">Jobs</span> <span class="hljs-string">GPU</span>
 <span class="hljs-attr">uses:</span> <span class="hljs-string">huggingface/hf-jobs-action@main</span>
 <span class="hljs-attr">with:</span>
 <span class="hljs-attr">token:</span> <span class="hljs-string">${{</span> <span class="hljs-string">secrets.HF_TOKEN</span> <span class="hljs-string">}}</span>
 <span class="hljs-attr">namespace:</span> <span class="hljs-string">your-username</span>
 <span class="hljs-attr">flavor:</span> <span class="hljs-string">rtx-pro-6000</span>
 <span class="hljs-attr">image:</span> <span class="hljs-string">ghcr.io/astral-sh/uv:python3.10-bookworm</span>
 <span class="hljs-attr">timeout:</span> <span class="hljs-string">&quot;3600&quot;</span>
 <span class="hljs-attr">files:</span> <span class="hljs-string">scripts/test.py</span>
 <span class="hljs-attr">script:</span> <span class="hljs-string">|
 set +x
 export HF_TOKEN=&quot;${{ secrets.HF_TOKEN }}&quot;
 uv run /tmp/files/test.py</span><!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-185d696">The test script pulls the kernel straight from the Hub with the <a href="../basic-usage"><code>kernels</code></a> library, so it always runs against the artifacts the build workflow just published:</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 class="" 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 "><!-- HTML_TAG_START --><span class="hljs-comment"># scripts/test.py</span>
<span class="hljs-comment"># /// script</span>
<span class="hljs-comment"># dependencies = [&quot;kernels&quot;, &quot;torch&quot;]</span>
<span class="hljs-comment"># ///</span>
<span class="hljs-keyword">from</span> kernels <span class="hljs-keyword">import</span> get_kernel
kernel = get_kernel(<span class="hljs-string">&quot;your-username/your-kernel&quot;</span>)
<span class="hljs-comment"># ... exercise the kernel and assert on the results ...</span><!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-pdls8t">Run the build workflow before the test workflow so the Hub has a fresh kernel to pull. For tightly coupled steps, you can also have one workflow trigger the other, or combine both jobs in a single workflow with a <code>needs:</code> dependency.</p> <h3 class="relative group"><a id="hf-jobs-action-inputs" 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="#hf-jobs-action-inputs"><span><svg class="" 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>hf-jobs-action inputs</span></h3> <table data-svelte-h="svelte-69b27n"><thead><tr><th>Input</th> <th>Required</th> <th>Default</th> <th>Description</th></tr></thead> <tbody><tr><td><code>token</code></td> <td>yes</td> <td></td> <td>HF token with <code>job.write</code> permission.</td></tr> <tr><td><code>namespace</code></td> <td>yes</td> <td></td> <td>HF namespace (username or org) that owns the job.</td></tr> <tr><td><code>image</code></td> <td>yes</td> <td></td> <td>Container image to run.</td></tr> <tr><td><code>script</code></td> <td>yes</td> <td></td> <td>Shell script to execute in the container.</td></tr> <tr><td><code>flavor</code></td> <td>no</td> <td><code>cpu-basic</code></td> <td>Hardware flavor (e.g. <code>rtx-pro-6000</code>).</td></tr> <tr><td><code>files</code></td> <td>no</td> <td></td> <td>Newline-separated repo files to copy into the job.</td></tr> <tr><td><code>files_dest</code></td> <td>no</td> <td><code>/tmp/files</code></td> <td>Directory the files are copied to inside the container.</td></tr> <tr><td><code>env</code></td> <td>no</td> <td><code>{}</code></td> <td>Environment variables as a JSON object.</td></tr> <tr><td><code>timeout</code></td> <td>no</td> <td><code>1200</code></td> <td>Maximum seconds to wait for the job.</td></tr></tbody></table> <h2 class="relative group"><a id="choosing-a-flavor" 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="#choosing-a-flavor"><span><svg class="" 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>Choosing a flavor</span></h2> <p data-svelte-h="svelte-c3a1ta">Flavors map to the machine types available on Hugging Face Jobs, CPU flavors such as <code>cpu-upgrade</code> and <code>cpu-xl</code> for builds, and GPU flavors such as <code>l4x1</code>, <code>a100-large</code>, <code>h200</code>, or <code>rtx-pro-6000</code> for tests. Pick the most reasonable GPU that fits your model to keep jobs low cost. The current list and pricing are in the <a href="https://huggingface.co/docs/huggingface_hub/guides/jobs" rel="nofollow">Hugging Face Jobs documentation</a>.</p> <blockquote class="note" data-svelte-h="svelte-17oidf7"><p>HF Jobs currently only offers a few CPU architectures, so the kernel is built
for whatever architecture the available CPU flavors provide. This is a current
limitation to keep in mind if you need to target a specific architecture.</p></blockquote> <blockquote class="warning" data-svelte-h="svelte-bb8xuy"><p>HF Jobs containers start with shell tracing enabled (<code>set -x</code>). Always run
<code>set +x</code> before exporting <code>HF_TOKEN</code> so the token does not leak into the
streamed build logs.</p></blockquote> <a class="!text-gray-400 !no-underline text-sm flex items-center not-prose mt-4" href="https://github.com/huggingface/kernels/blob/main/docs/source/builder/github-actions.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 data-svelte-h="svelte-zjs2n5"><span class="underline">Update</span> on GitHub</span></a> <p></p>
<script>
 {
 __sveltekit_azffng = {
 assets: "/docs/kernels/pr_673/en",
 base: "/docs/kernels/pr_673/en",
 env: {}
 };
 const element = document.currentScript.parentElement;
 const data = [null,null];
 Promise.all([
 import("/docs/kernels/pr_673/en/_app/immutable/entry/start.9eec61bd.js"),
 import("/docs/kernels/pr_673/en/_app/immutable/entry/app.5a3c00a6.js")
 ]).then(([kit, app]) => {
 kit.start(app, element, {
 node_ids: [0, 10],
 data,
 form: null,
 error: null
 });
 });
 }
 </script>

Xet Storage Details

Size:
32.7 kB
·
Xet hash:
57db2480d779e54e3e36c781060e81c3514c53c8547ad5e492d4fa46c73a0dc0

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