Getting Started

Vespa Cloud is at the moment invite only.

Vespa is used for online Big Data serving, which means ranking (large) data sets using query data. Below is an example of how to rank music albums using a user profile - match albums with scores for a set of categories with a user's preference.

User profile

{
  { cat:pop  }: 0.8,
  { cat:rock }: 0.2,
  { cat:jazz }: 0.1
}
Albums
{
  "fields": {
    "album": "A Head Full of Dreams",
    "artist": "Coldplay",
    "year": 2015,
    "category_scores": {
      "cells": [
        { "address": { "cat": "pop"},  "value": 1  },
        { "address": { "cat": "rock"}, "value": 0.2},
        { "address": { "cat": "jazz"}, "value": 0  }
      ]
    }
  }
}

{
  "fields": {
    "album": "Love Is Here To Stay",
    "artist": "Diana Krall",
    "year": 2018,
    "category_scores": {
      "cells": [
        { "address": { "cat": "pop" },  "value": 0.4 },
        { "address": { "cat": "rock" }, "value": 0   },
        { "address": { "cat": "jazz" }, "value": 0.8 }
      ]
    }
  }
}

{
  "fields": {
    "album": "Hardwired...To Self-Destruct",
    "artist": "Metallica",
    "year": 2016,
    "category_scores": {
      "cells": [
        { "address": { "cat": "pop" },  "value": 0 },
        { "address": { "cat": "rock" }, "value": 1 },
        { "address": { "cat": "jazz" }, "value": 0 }
      ]
    }
  }
}
Rank profile

A rank profile calculates a relevance score per document. This is defined by the application author - in this case, it is the tensor product. The data above is represented using tensors. As the tensor is one-dimensional (the cat dimension), this a vector, hence this is the dot product of the user profile and album categories:

rank-profile rank_albums inherits default {
    first-phase {
        expression: sum(query(user_profile) * attribute(category_scores))
    }
}
Hence, the expected scores are:
Album pop rock jazz total
A Head Full of Dreams 0.8*1.00.2*0.20.1*0.00.84
Love Is Here To Stay 0.8*0.40.2*0.00.1*0.80.4
Hardwired...To Self-Destruct0.8*0.00.2*1.00.1*0.00.2
Build and test the application, and validate that the document's relevance (i.e. score) is the expected value, and the results are returned in descending relevance order.


Prerequisites for the sample apps are git and a X.509 certificate. See Security Model for keys and certificates. A certificate is also generated below.

  1. Create a Vespa Cloud application

    This requires a Google account. Go to console.vespa.ai/, click "Create application", enter application name.

  2. Copy repo using github.com/vespa-engine/sample-apps/generate, or download the repo with the album-recommendation sample app

    $ git clone https://github.com/vespa-engine/sample-apps.git && cd sample-apps/vespa-cloud/album-recommendation
    

  3. Create a self-signed certificate

    This certificate and key will be used to send requests to Vespa Cloud later.

    $ openssl req -x509 -nodes -days 14 -newkey rsa:4096 \
      -subj "/CN=cloud.vespa.example" \
      -keyout data-plane-private-key.pem -out data-plane-public-cert.pem
    
    Alternatively, copy an existing key to current working directory, if you have one. More details in Data Plane, see Client certificate.

  4. Create the application package

    $ mkdir -p src/main/application/security && cp data-plane-public-cert.pem src/main/application/security/clients.pem
    $ cd src/main/application && zip -r ../../../application.zip . && cd ../../..
    

  5. Deploy the application

    In the Vespa console, click Deploy on the application created in the start of this guide. In the "Deploy to dev" section, upload application.zip - click Deploy.

    Now is a good time to read automated-deployments, as first time deployments takes a few minutes. Track progress in Deploy application and Install application panes. Seeing CERTIFICATE_NOT_READY / PARENT_HOST_NOT_READY / LOAD_BALANCER_NOT_READY is normal. The endpoint URL is printed in the Install application section when the deployment is successful - copy this for the next step.

  6. Click Instances at the top, then endpoints

    Try the endpoint to validate it is up (also see using a browser):

    $ ENDPOINT=https://end.point.name
    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem $ENDPOINT
    

  7. Feed documents

    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \
      -H "Content-Type:application/json" --data-binary @src/test/resources/A-Head-Full-of-Dreams.json \
      $ENDPOINT/document/v1/mynamespace/music/docid/1
    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \
      -H "Content-Type:application/json" --data-binary @src/test/resources/Love-Is-Here-To-Stay.json \
      $ENDPOINT/document/v1/mynamespace/music/docid/2
    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \
      -H "Content-Type:application/json" --data-binary @src/test/resources/Hardwired...To-Self-Destruct.json \
      $ENDPOINT/document/v1/mynamespace/music/docid/3
    

  8. Recommend albums

    Send user profile in query, find recommended albums in the result set:

    $ curl --cert data-plane-public-cert.pem --key data-plane-private-key.pem \
    "$ENDPOINT/search/?ranking=rank_albums&yql=select%20%2A%20from%20sources%20%2A%20where%20sddocname%20contains%20%22music%22%3B&ranking.features.query(user_profile)=%7B%7Bcat%3Apop%7D%3A0.8%2C%7Bcat%3Arock%7D%3A0.2%2C%7Bcat%3Ajazz%7D%3A0.1%7D"
    


Next steps:

  1. Explore a sample app with custom java code

    Try album-recommendation-java.

  2. Implement a system and staging test

    Vespa Cloud has a secure, feature-rich, continuous deployment pipeline - read more in automated deployments.

  3. Deploy to a production zone

    Deploy a secure production application.

Troubleshooting

  • Slow deployments: First time deployments takes a few minutes, seeing CERTIFICATE_NOT_READY / PARENT_HOST_NOT_READY / LOAD_BALANCER_NOT_READY is normal. "Installation succeeded!" in the bottom pane indicates success
  • HTTP: 502 — Bad Gateway: This means the endpoint is not ready, or failing. A Vespa software upgrade will cause this — the application will then be unavailable for 15 minutes or so, as dev instances are not redundant. Look for stopping services in logs to check for this.
  • Retrying — request failed: Java heap space: If this happens when deploying from the laptop, mvn runs out of memory. Use export MAVEN_OPTS=-Xmx3g to increase the heap size to 3G (or larger as needed).