From c1b215ae7fce033ded41391414a8738b7f5ebe71 Mon Sep 17 00:00:00 2001 From: Lukas Wuttke Date: Tue, 4 Aug 2026 12:59:44 +0200 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20model=20files=20build=20locally=20?= =?UTF-8?q?=E2=80=94=20hub-referenced=20models=20not=20supported=20(#1495)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the #1495 contract on the Customize Models page: a model file must build its architecture from local code; tracebloc does not fetch models, weights, tokenizers, or configs from an external hub (HuggingFace) at training time. Removes the retired model_id / hf_token 'additional variables' and adds the pretrained-weights-upload + tokenizer.json guidance and the strict weight-load note. Refs #1151. Documents #1495. Co-Authored-By: Claude Opus 4.8 --- join-use-case/model-optimization.mdx | 29 ++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/join-use-case/model-optimization.mdx b/join-use-case/model-optimization.mdx index 56ecde7..974528d 100644 --- a/join-use-case/model-optimization.mdx +++ b/join-use-case/model-optimization.mdx @@ -19,6 +19,29 @@ 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("")` for a model, tokenizer, or config, or +- declare a `model_id`, `tokenizer_id`, or `hf_token` variable. + +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. + + +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. + + ## Model Code Formats Model code can be: @@ -67,8 +90,10 @@ 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. + + +`model_id`, `tokenizer_id`, and `hf_token` are no longer supported — hub-referenced models are not accepted. See [Models build locally (no external hubs)](#models-build-locally-no-external-hubs). + * The framework variable is compulsory and should always be placed at the top of your code just after the imports, before any other variable. From cb81211776b982e59efed80a213f4471155bfc07 Mon Sep 17 00:00:00 2001 From: Lukas Wuttke Date: Fri, 28 Aug 2026 15:29:20 +0200 Subject: [PATCH 2/2] docs: state what the hub gate actually enforces, not more (#1495) Two passages overstated the contract and were contradicted by both prod branches. Measured 2026-08-28: - SDK master, tracebloc/link_model_dataset.py:83,102-104,116,127-129 -- model_id, model_id_llm, hf_token and tokenizer_id are all in the ACCEPTED validate_kwargs set and all assigned. - backend main -- Experiment.py:467 hf_token column (default TEMP_HF_TOKEN), :339 tokenizer_id; ExperimentSerializer.py:114,143 accept both; and bus_client_util.py:182 passes hf_token THROUGH to the training parameters. So "no longer supported" and "must not declare" were both false: they are not rejected at upload. What IS enforced is the hub FETCH -- the bandit plugin rejects *.from_pretrained(...), torch.hub.load and the getattr route (bandit_tracebloc_model_validation, :21-31,:352). Those names appear nowhere in that plugin, so nothing refuses a declaration. The hub-fetching section is unchanged and now lists the calls that really are refused. The Additional-variables note says the variables are still accepted and simply cannot achieve a hub fetch, which is the actionable fact. Still a DRAFT: this auto-deploys to production docs, so un-drafting is Lukas call. Co-Authored-By: Claude Opus 4.8 --- join-use-case/model-optimization.mdx | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/join-use-case/model-optimization.mdx b/join-use-case/model-optimization.mdx index 974528d..6608d9a 100644 --- a/join-use-case/model-optimization.mdx +++ b/join-use-case/model-optimization.mdx @@ -27,7 +27,12 @@ HuggingFace) while training — a training pod has no such egress. In practice y model file must **not**: - call `*.from_pretrained("")` for a model, tokenizer, or config, or -- declare a `model_id`, `tokenizer_id`, or `hf_token` variable. +- 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 @@ -92,7 +97,13 @@ 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`, `tokenizer_id`, and `hf_token` are no longer supported — hub-referenced models are not accepted. See [Models build locally (no external hubs)](#models-build-locally-no-external-hubs). +`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.