Skip to main content

Migrate to weights

model_cache is superseded by the new BDN (Baseten Delivery Network), which offers faster cold starts through multi-tier caching (in-cluster + node-level).Use truss migrate to automatically convert your configuration:
Terminal
See Baseten Delivery Network (BDN) for the new approach.When model_cache may still be needed:
  • Quantization workflows where you need to process weights after download
  • Custom download timing through lazy_data_resolver.block_until_download_complete()
  • Prototyping and iterating using direct downloads.

Cold starts

“Cold start” is a term used to describe the time taken when a request is received when the model is scaled to 0 until it is ready to handle the first request. This process is a critical factor in allowing your deployments to be responsive to traffic while maintaining your SLAs and lowering your costs. To optimize cold starts, we will go over the following strategies: Downloading them in a background thread in Rust that runs during the module import, caching weights in a distributed filesystem, and moving weights into the docker image.In practice, this reduces the cold start for large models to just a few seconds. For example, Stable Diffusion XL can take a few minutes to boot up without caching. With caching, it takes just under 10 seconds.

Enable prefetching for a model

To enable caching, simply add model_cache to your config.yaml with a valid repo_id. The model_cache has a few key configurations:
  • repo_id (required): The repo name from Hugging Face or bucket/container from GCS, S3, or Azure.
  • revision (required for Hugging Face): The revision of the huggingface repo, such as the sha or branch name such as refs/pr/1 or main. Not needed for GCS, S3, or Azure.
  • use_volume: Boolean flag to determine if the weights are downloaded to the Baseten Distributed Filesystem at runtime (recommended) or bundled into the container image (legacy, not recommended).
  • volume_folder: string, folder name under which the model weights appear. Setting it to my-llama-model will mount the repo to /app/model_cache/my-llama-model at runtime.
  • allow_patterns: Only cache files that match specified patterns. Utilize Unix shell-style wildcards to denote these patterns.
  • ignore_patterns: Conversely, you can also denote file patterns to ignore, hence streamlining the caching process.
  • runtime_secret_name: The name of your secret containing the credentials for a private repository or bucket, such as a hf_access_token or gcs_service_account.
  • kind: The storage provider type for the model weights.
    • "hf" (default): Hugging Face
    • "gcs": Google Cloud Storage
    • "s3": AWS S3
    • "azure": Azure Blob Storage
Here is an example of a well written model_cache for Stable Diffusion XL. Note how it only pulls the model weights that it needs using allow_patterns.
config.yaml
Many Hugging Face repos have model weights in different formats (.bin, .safetensors, .h5, .msgpack, etc.). You usually need only one format. To minimize cold starts, cache only the weights you need.

Weight pre-fetching

With model_cache, weights are pre-fetched by downloading your weights ahead of time in a dedicated Rust thread. This means, you can perform all kinds of preparation work (importing libraries, jit compilation of torch/triton modules), until you need access to the files. In practice, executing statements like import tensorrt_llm typically take 10-15 seconds. By that point, the first 5-10GB of the weights will have already been downloaded.
To use the model_cache config with truss, we require you to actively interact with the lazy_data_resolver. Before using any of the downloaded files, you must call the lazy_data_resolver.block_until_download_complete(). This will block until all files in the /app/model_cache directory are downloaded & ready to use. This call must be either part of your __init__ or load implementation.
model.py

Private repositories/cloud storage

Private Hugging Face repositories

For any public Hugging Face repo, you don’t need to do anything else. Adding the model_cache key with an appropriate repo_id should be enough. However, if you want to deploy a model from a gated repo like Gemma to Baseten, there are a few steps you need to take:
1

Get Hugging Face API Key

Grab an API key from Hugging Face with read access. Make sure you have access to the model you want to serve.
2

Add it to Baseten Secrets Manager

Paste your API key in your secrets manager in Baseten under the specified key, such as hf_access_token. You can read more about secrets here.
3

Update Config

In your Truss’s config.yaml, add the secret key under runtime_secret_name:
config.yaml
On the recommended weights API, runtime_secret_name becomes the per-source auth block (auth_method: CUSTOM_SECRET, auth_secret_name). See the migration mapping.
Once your truss is pushed, we resolve the sha behind your branch (main), and protect the deployment against changes on this branch.
If you continue to hit issues, contact Baseten support.

Private GCS buckets

If you want to deploy a model from a private GCS bucket to Baseten, there are a few steps you need to take:
1

Get GCS Service Account Key

Create a service account key in your GCS account for the project which contains the model weights.
2

Add it to Baseten Secrets Manager

Paste the contents of the service_account.json in your secrets manager in Baseten under the specified key, for example, gcs_service_account. You can read more about secrets here.At a minimum, you should have these credentials:
gcs_service_account
3

Update Config

In your Truss’s config.yaml, make sure to add the runtime_secret_name to your model_cache matching the above secret name:
config.yaml
Note: S3/Azure/GCS Buckets are immutable. Once the truss is pushed, you may no longer delete or modify files as they are referenced as required files for a model startup.
If you continue to hit issues, contact Baseten support.

Private S3 buckets

If you want to deploy a model from a private S3 bucket to Baseten, there are a few steps you need to take:
1

Get S3 credentials

Get your aws_access_key_id and aws_secret_access_key in your AWS account for the bucket that contains the model weights.
2

Add them to Baseten Secrets Manager

Paste the following json in your secrets manager in Baseten under the specified key, for example, aws_secret_json. You can read more about secrets here.
aws_secret_json
3

Update Config

In your Truss’s config.yaml, make sure to add the runtime_secret_name to your model_cache matching the above secret name:
config.yaml
Note: S3/Azure/GCS Buckets are immutable. Once the truss is pushed, you may no longer delete or modify files as they are referenced as required files for a model startup.
If you continue to hit issues, contact Baseten support.

Private Azure containers

If you want to deploy a model from a private Azure container to Baseten, there are a few steps you need to take:
1

Get Azure credentials

Get your account key from the Azure portal under Security + networking > Access keys for the storage account that holds the model weights.
2

Add them to Baseten Secrets Manager

Paste the following json in your secrets manager in Baseten under the specified key, for example, azure_secret_json. You can read more about secrets here.
azure_secret_json
3

Update Config

In your Truss’s config.yaml, make sure to add the runtime_secret_name to your model_cache matching the above secret name:
config.yaml
Note: S3/Azure/GCS Buckets are immutable. Once the truss is pushed, you may no longer delete or modify files as they are referenced as required files for a model startup.
If you continue to hit issues, contact Baseten support.

model_cache within Chains

To use model_cache for chains - use the Assets specifier. In the example below, we will download llama-3.2-1B. As this model is a gated huggingface model, we are setting the mounting token as part of the assets chains.Assets(..., secret_keys=["hf_access_token"]). The model is quite small - in many cases, we will be able to download the model while from transformers import pipeline and import torch are running.
chain_cache.py

model_cache for custom servers

If you are not using Python’s model.py and custom servers such as vllm, TEI or sglang, you are required to use the truss-transfer-cli command, to force population of the /app/model_cache location. The command will block until the weights are downloaded. Here is an example for how to use text-embeddings-inference on a L4 to populate a jina embeddings model from huggingface into the model_cache.
config.yaml