Onboard a Custom Model from Hugging Face#
The Custom Models section of the Model Catalog lets you bring your own model from Hugging Face into a project. Instead of choosing from the curated AIM Catalog, you point the AMD AI Workbench at a Hugging Face repository, confirm what it found, choose a supported container image, and start onboarding. Once onboarding completes, your model appears alongside the other custom models in the project and can be deployed like any other model.
This page walks through the two parts of that workflow:
Preview — inspect a Hugging Face source before committing to it.
Onboard — confirm the metadata, select a container image, and import the model into your project.
Note
This page covers previewing and onboarding a model. Tuning the runtime profile in depth — engine arguments, environment variables, and other profile overrides — is covered separately in the custom profile settings documentation.
Before You Begin#
You need access to a project in the AMD AI Workbench. The model is onboarded into the project you currently have selected.
Have the Hugging Face repository ready, either as a repository ID (for example,
example-org/example-model) or as a full Hugging Face URL (for example,https://huggingface.co/example-org/example-model). You can include a revision in the URL (for example,https://huggingface.co/example-org/example-model/tree/<branch-or-tag>); otherwise the repository’s default branch is used.For private or gated repositories, you need a Hugging Face access token stored as a project secret. See Secrets for how to create one. You can also add a token directly from the wizard while previewing.
Open the Onboarding Wizard#
Go to the Models page and open the Custom Models tab.
Select Import model in the top-right toolbar.
This opens the Add new model wizard, which guides you through three steps: Model source, Model information, and Runtime profile.
Step 1: Preview the Model Source#
In the Model source step, enter the repository ID or Hugging Face URL of the model you want to onboard.
If the repository is private or gated, expand Hugging Face authentication and select an existing token secret, or add a new one. Public repositories do not require a token.
Select Preview model to fetch the repository’s details from Hugging Face. Preview is read-only — nothing is imported or changed in your project yet. When the source resolves successfully, the wizard advances to Model information with the details it found filled in for you to confirm: the resolved canonical name, a suggested display name and description from the model card, and the model’s tags.
Important
When a Hugging Face token is needed: Gated and private repositories require a Hugging Face token to read their metadata and download their weights. If you preview a gated model without a token, the Workbench cannot access it and asks you to provide one. Public models work without a token.
Step 2: Confirm Model Information#
The Model information step shows the canonical name as read-only — this comes from the source and cannot be changed. Below it, you can review and adjust the display properties that the preview suggested:
Model display name — the human-readable title shown on the model card. It is prefilled from the model card and must not be empty. You can keep the suggestion or replace it.
Description — a short catalog description, prefilled from the model card.
Tags — comma-separated labels used for search and filtering.
Note
Display properties can be updated after onboarding from the model’s settings, so you don’t have to get them perfect here.
Continue to the runtime profile step when you are satisfied with the metadata.
Step 3: Select a Container Image and Runtime Profile#
In the Runtime profile step, choose the container image that will serve your model and the hardware profile it runs on. The wizard presets these from the options detected for your cluster, so for most models you can review the suggested values and continue. Under Profile parameters you select:
Container image — the image that serves your model.
Container version — the image version (shown when the selected image offers versions).
Accelerator type and Accelerator — the hardware your model runs on.
Accelerator count — how many accelerators to use.
Model precision — the numeric precision for the model.
The step also includes optional Engine arguments and Environment variables sections for advanced tuning. You can leave these empty to start onboarding and adjust them later.
Tip
For most models, selecting a supported container image and accepting the suggested profile parameters is enough to start onboarding. You can refine engine arguments, environment variables, and other overrides later. The full set of runtime options is covered in the custom profile settings documentation.
Start Onboarding#
Select Save and start onboarding to begin. The Workbench validates your selections, re-checks the source against Hugging Face, and then imports the model’s weights in the background. You are returned to the Custom Models tab, where your new model appears with its onboarding in progress.
Onboarding can take a while for large models because the weights are downloaded and copied into your project’s storage. You don’t need to keep the wizard open — the import continues on its own.
Track Onboarding Status#
Each custom model card shows its current status:
Importing — the model’s weights are being downloaded into your project. This is expected right after you start.
Onboarding — the model is being prepared after the import finishes.
Failed — onboarding did not complete. See Troubleshooting below.
When a model is ready to deploy, its card shows no status pill and the Deploy button is enabled.
Once a model is ready, you can deploy it as an inference service and connect to it like any other model — see Deploy a Custom Model.
Troubleshooting: Common Situations#
Gated or Private Models#
If a model is gated, you must first request and be granted access on Hugging Face for the account that owns your token. Even with a token, onboarding fails if that account has not been approved for the repository. Confirm access on Hugging Face, then preview and onboard again.
Access or Authentication Errors#
If preview or onboarding reports that the model cannot be accessed:
Check that the repository ID or URL is spelled correctly and points to a model repository.
For gated or private models, confirm you selected a Hugging Face token secret, and that the token is valid and still has access.
If you recently created or rotated your token, add the updated token as a new secret and select it.
Note
A private or gated repository can appear as “not found” when your token is missing, invalid, or lacks access to it — the repository is simply not visible to that token. If you’re sure the repository exists, check your token before assuming the source is wrong.
See Secrets for managing Hugging Face token secrets.
Duplicate Display Names#
Reusing an existing custom model’s display name does not create a separate model. When you import a model under a name that already exists and points to the same source, the existing model’s settings are overwritten. If the name is reused for a different source, the save is rejected so the wrong model is not modified.
Important
Known limitation: the Model information step warns you when the display name you entered already belongs to another custom model in the project. The warning does not block you, but saving may overwrite that model’s settings or be rejected — choose a different display name if you want to keep both models. This is a known restriction; custom models are not yet versioned the way the Standard Catalog is.
Stale Preview#
The Workbench pins the exact version of the repository it showed you during preview. If the repository changes on Hugging Face between previewing and onboarding, onboarding is rejected so you never import a different version than the one you reviewed. If this happens, preview the model again to refresh the details, then onboard from the updated preview.
Onboarding Failed#
If a model shows a Failed status, the weight import did not complete — often due to a revoked token, lost access to a gated repository, or a network interruption while downloading. Confirm access and your token, then re-onboard the model. You can also delete the failed model and start again.