This example demonstrates a basic movie recommendation system. The following capabilities are demonstrated:

  1. Training a model using the MovieLens dataset
  2. Saving the trained model to a Volume
  3. Retrieving the trained model from a Volume during inference
  4. Deploying a REST API that accepts a user ID and returns customized recommendations for that user

Defining the runtime

This is the runtime our code will run in. We’ll define the compute settings and Python packages to install.
from beam import App, Runtime, Image, Output, Volume

inference_app = App(
            python_packages=["numpy", "torch", "pandas", "matplotlib"],
    volumes=[Volume(name="trained_models", path="./trained_models")],

Using Volumes to save trained models

We’re going to mount a Volume, which is a writable data store.

  • During training, we will save our models to this volume.
  • During inference, we will retrieve our trained model.

We will access the volume at this path: ./trained_models

volumes=[Volume(name="trained_models", path="./trained_models")],

Training the model

We use an embedding layer for both the user and movie, to compress the respective one-hot encoded vectors into rich, compact representations that are easier to model.

These two representations are concatenated into a single vector and then passed into a simple fully connected neural network.

There’s a lot going on here, but the main thing to note is the code at the end, which saves the trained model to a Volume.

We’ve wrapped this function in a run(), which will let us run it asynchronously on Beam.
def run_training_pipeline():
    # Trains a model and saves the state_dict to the persistent volume
    trained_model = train()
    persistent_volume_path = "/volumes/trained_models/", persistent_volume_path)

Running the training script

Running the training script is straightforward — just enter your shell, and kick off a run:

beam run

This command will containerize your app and run it on a remote container. Feel free to close your terminal window, if you wish. The app will continue running on Beam remotely.

You’ll see the training logs stream to your shell. This will look something like this:

(.venv) user@MacBook movie-recommendations % beam run
 i  Using cached image.
 ✓  App initialized.
 i  Uploading files...
 ✓  Container scheduled, logs will appear below.
⠴ Starting container... 29s (Estimated: 5m0s)
Starting app...
Loading handler in ''...
Running task: a22e62e1-97f4-4381-9a47-426aacd3b5a2
Loaded 158499 training samples and 39937 test samples
Loaded 158499 training samples and 39937 test samples
Train epoch: 0, avg loss: 0.674729
Test set: avg loss: 0.6624, hit rate: 301/20417 (1.47%)

Train epoch: 1, avg loss: 0.625152
Test set: avg loss: 0.6426, hit rate: 399/20417 (1.95%)

Making Predictions

The whole point of a recommendation system is to make predictions dynamically, and that requires us to deploy an API.

We’ll write a function that takes in a user ID, and returns a list of movies that the user is predicted to enjoy watching.


We’re going to deploy the app as a REST API, which will allow us to generate movie recommendations for users in real-time.

Above the run_inference function, add a rest_api decorator:
def run_inference(**inputs):

Now, go back to the shell and run this command to deploy the app. Make sure to customize this with the actual name of the file that has the run_inference function you created:

beam deploy

You’ll see some logs appear in your shell, showing the deployment status:

Calling the API

If you navigate to the link in the last line of the shell output, you’ll be able to login to your Beam web dashboard and view the details of your deployment.

In the dashboard, you’ll be able to copy a cURL request which you can use to make predictions to the API. We’ll pass in a user ID, and ask for 3 movie recommendations in response.

  curl -X POST --compressed "" \
   -H 'Accept: */*' \
   -H 'Accept-Encoding: gzip, deflate' \
   -H 'Authorization: Basic [YOUR_AUTH_TOKEN]' \
   -H 'Connection: keep-alive' \
   -H 'Content-Type: application/json' \
   -d '{"user_id": 42, "number_of_recommendations": 3}'

The movie recommendations will be returned as JSON:

  "recommendations": [
      "title": "Raiders of the Lost Ark (Indiana Jones and the Raiders of the Lost Ark) (1981)",
      "genres": "Action|Adventure",
      "movie_id": 1198,
      "score": 0.9955273270606995
      "title": "Mrs. Doubtfire (1993)",
      "genres": "Comedy|Drama",
      "movie_id": 500,
      "score": 0.9951636791229248
      "title": "Toy Story (1995)",
      "genres": "Adventure|Animation|Children|Comedy|Fantasy",
      "movie_id": 1,
      "score": 0.9950186014175415

Was this page helpful?