# Deploy any Hugging Face model as an API

Go from a Hugging Face model ID to a live, autoscaling endpoint with one Python file. Beam builds the container, manages the GPUs, and caches your weights between requests.

```
deply
$ beam deploy app.py:predict
=> Building image
=> Using cached image
=> Syncing files
=> Deployed
=> https://hf-inference-abc123.app.beam.cloud

# first cold start — on_start pulls weights from the Hub
Downloading Qwen/Qwen2.5-1.5B-Instruct → volume ./weights

# every boot after — cache hit, skip the download
Loaded weights from ./weights in 1.2s
```

## Why Beam

### The shortest path from Hub to production

No Dockerfiles, no serving framework to stand up. Declare your dependencies in Python and Beam handles the rest.

**One file, no Dockerfiles**  
Declare Python packages and base images inline. Beam builds and caches the container for you.

**Load once, serve many**  
on_start runs when the container boots, so models load once and every request hits warm weights.

**Weights cached on volumes**  
Snapshot a model into a persistent volume once and skip the Hub download on every boot. Storage is included, free.

**Gated & private models**  
Store your Hugging Face token with Beam's secrets manager and pull gated repos like Llama securely.

**Live-reload development**  
beam serve runs your endpoint in the cloud while you edit locally — the same environment you'll ship to production.

**Autoscaling built in**  
Endpoints scale with request volume and back to zero when idle — no capacity planning required.

## How it works

### Ship a model in three steps

01
### Pick a model
Reference any Hub model ID from transformers, diffusers, or sentence-transformers — or bring your own weights.

02
### Wrap it in an endpoint
Add the @endpoint decorator with your GPU and image. Load the model in on_start so it stays warm.

03
### Serve, then deploy
Iterate with beam serve's live reload, then beam deploy gives you a production HTTPS endpoint.

```
terminal
# Develop against the cloud with live reload
$ beam serve app.py:predict
=> Watching for changes...

# Deploy to production
$ beam deploy app.py:predict
=> Deployed 🎉
=> https://hf-inference-abc123.app.beam.cloud

$ curl -X POST https://hf-inference-abc123.app.beam.cloud \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -d '{"prompt": "Explain serverless GPUs"}'
```

## FAQ

### Which libraries are supported?  
Anything pip-installable: transformers, diffusers, sentence-transformers, ultralytics, or your own packages. You define the image in Python and Beam builds it.

### Can I deploy gated or private models?  
Yes. Save your Hugging Face token with beam secret create HF_TOKEN and the container authenticates to the Hub securely.

### Do weights re-download on every cold start?  
Not if you cache them. Download weights to a persistent volume once, and every container loads from disk instead of the Hub.

### How do I pick the right GPU?  
Start small — a T4 handles many models under a few billion parameters — and watch real-time GPU utilization in the Beam dashboard to right-size from there.

### What about chat models with an OpenAI-style API?  
Use Beam's vLLM integration: it serves any compatible Hub model behind an OpenAI-compatible API, so existing clients work unchanged.