Skip to content

docs: model files build locally — hub-referenced models not supported (#1495) #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
LukasWodka wants to merge 3 commits into
base: develop
Choose a base branch
from
Draft

docs: model files build locally — hub-referenced models not supported (#1495) #77

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c1b215a
docs: model files build locally — hub-referenced models not supported…
LukasWodka Aug 4, 2026
cb81211
docs: state what the hub gate actually enforces, not more (#1495)
LukasWodka Aug 28, 2026
33d99be
chore: merge develop (action pins)
LukasWodka Sep 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 38 additions & 2 deletions join-use-case/model-optimization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,34 @@ model/
- model_weights.pkl
```

## Models build locally (no external hubs)

Your model file must build its architecture from local code. tracebloc does not
fetch models, weights, tokenizers, or configs from an external hub (such as
HuggingFace) while training — a training pod has no such egress. In practice your
model file must **not**:

- call `*.from_pretrained("<hub-id>")` for a model, tokenizer, or config, or
- call `torch.hub.load(...)`, or reach the same functions indirectly via
`getattr(X, "from_pretrained")`.

These are refused at upload by the model-validation check, not merely
discouraged. Setting `model_id`, `tokenizer_id` or `hf_token` is a separate
matter — see the note under [Additional variables](#additional-variables).

To start from a pretrained model, download its weights once, build the same
architecture in your model file, and upload the weights alongside it (see
[Use pre-trained weights](#use-pre-trained-weights)). For text and other NLP
tasks, also ship a `tokenizer.json` — pass it with
`user.upload_model(..., tokenizer="tokenizer.json")` or place it next to your
model file.

<Note>
The uploaded weights file is loaded into the architecture your model file builds,
matching parameter names and shapes exactly. Build the same architecture you
produced the weights from, or the load will fail.
</Note>

## Model Code Formats

Model code can be:
Expand Down Expand Up @@ -75,8 +103,16 @@ Each format must contain these variables on the main file:

Some additional variables are required for specific categories
* **num_feature_points** : number of keypoints or feature points for which this model file is created. This variable is used only for keypoint_detection and generic_classification category.
* **model_id** : model id using which this model file is created. This variable is used only for text_classification category.
* **hf_token** : hf token using which this model file is created. This variable is used only for text_classification category.

<Note>
`model_id`, `tokenizer_id` and `hf_token` are **still accepted** by the SDK and
the API — they are not rejected at upload. What changed is that they can no
longer achieve a hub fetch: a training pod has no egress to an external hub, and
the hub-fetching calls themselves are refused (see
[Models build locally (no external hubs)](#models-build-locally-no-external-hubs)).
So supplying them has no effect on where your architecture or tokenizer comes
from — build locally and upload weights instead.
</Note>

<Warning>
* The framework variable is compulsory and should always be placed at the top of your code just after the imports, before any other variable.
Expand Down