Skip to content
View as Markdown

Publish to HuggingFace Hub

Once you have a merged model or PEFT adapter on disk, publish_to_hf_hub uploads it to a Hub repository, optionally with a generated model card.

You need a HuggingFace token with write access. publish_to_hf_hub reads HF_TOKEN or the cached login from hf auth login; pass token= to override.

Publish

from tinker_cookbook import weights

url = weights.publish_to_hf_hub(
    model_path="./merged_model",
    repo_id="my-org/my-finetuned-qwen3",
)
# -> https://huggingface.co/my-org/my-finetuned-qwen3

Repositories are created private by default. Pass private=False to make one public.

The same call works for an adapter directory. When model_path contains adapter_config.json, the generated model card detects the PEFT format automatically (library_name: peft, peft and lora tags, and a PeftModel usage snippet).

Add a model card

ModelCardConfig holds standard HuggingFace metadata. Pass it as model_card= and a README.md is generated and included in the upload. If the directory already has a README.md, the existing file is kept and a warning is logged.

from tinker_cookbook.weights import ModelCardConfig

card = ModelCardConfig(
    base_model="Qwen/Qwen3.5-4B",
    datasets=["my-org/my-sft-dataset"],
    tags=["sft", "chat"],
    license="apache-2.0",
    language=["en"],
)

url = weights.publish_to_hf_hub(
    model_path="./peft_adapter",
    repo_id="my-org/my-qwen3-lora",
    model_card=card,
    private=False,
)

The generated card carries the metadata as YAML front matter (tinker and tinker-cookbook tags are always added, plus peft and lora for adapters), a usage snippet for the detected format, and the framework versions used.

To preview a card without uploading anything:

from tinker_cookbook.weights import generate_model_card

print(generate_model_card(config=card, repo_id="my-org/my-qwen3-lora"))

See publish_to_hf_hub for the full parameter list.

Push straight from Tinker with the CLI

If you only need the adapter on the Hub, you can skip the local build entirely. tinker checkpoint push-hf takes a Tinker checkpoint path and uploads it as a PEFT adapter, creating a model card unless you pass --no-model-card:

tinker checkpoint push-hf tinker://<run_id>/sampler_weights/final \
    --repo my-org/my-qwen3-lora

# Public repo, opened as a pull request instead of a push to main
tinker checkpoint push-hf tinker://<run_id>/sampler_weights/final \
    --repo my-org/my-qwen3-lora --public --create-pr

Next steps