Our goal with this series is to set up a Vespa application for personalized news recommendations on Vespa Cloud. We will do this in stages, starting with a simple news search system and gradually adding functionality as we go through the tutorial parts.
The parts are:
In this part, we will start with a minimal Vespa application to get used to some basic operations for deploying and running an application on Vespa Cloud. In the next part of the tutorial, we'll start developing our application.
Prerequisites:
curl to download the dataset.In upcoming parts of this series, we will have some additional Python dependencies - we use PyTorch to train vector representations for news and users and train machine learning models for use in ranking.
This tutorial uses Vespa-CLI, Vespa CLI is the official command-line client for Vespa.ai. It is a single binary without any runtime dependencies and is available for Linux, macOS, and Windows.
$ brew install vespa-cli
In this tutorial it is possible to use either a local or global Vespa CLI configuration mode for configuration variables. Using local configuration mode is generally recommended when working with multiple distinct Vespa applications, but most parts of this tutorial uses the same configuration values which makes it easier to use global configuration mode. The global configuration mode is useful because you don't have to reapply the same Vespa configurations for each part of this tutorial series:
$ vespa config set default_config_scope global
This tutorial has a companion sample application.
Throughout the tutorial, we will be using support code from this application.
Also, the final state of each tutorial can be found in the various app-... subdirectories.
Let's start by cloning the sample application:
$ vespa clone -f news news && cd news
The above downloads the news directory from the Vespa
sample apps repository and
places the contents in a folder called news. Use --help to see documentation
for the vespa-cli utility:
$ vespa clone --help
In the news directory, several pre-configured application packages are available.
The app-1-getting-started directory contains a minimal Vespa application.
There are two files there:
services.xml - defines the services that the application consists ofschemas/news.sd - defines the schema for searchable content.We will revisit these files in the next part of the tutorial.
Configure the Vespa CLI to use Vespa Cloud, and set the application name.
Replace tenant-name with your tenant name from console.vespa-cloud.com:
$ vespa config set target cloud $ vespa config set application tenant-name.news
Usually its better to use local configuration for each application, but this tutorial uses global configuration to avoid having to set the configuration values for each part of the tutorial.
Authenticate with Vespa Cloud:
$ vespa auth login
Follow the browser instructions to complete authentication.
Next, add a certificate for data plane access to the application:
$ vespa auth cert app-1-getting-started
This application doesn't contain much at the moment, but let's deploy it to Vespa Cloud anyway to get used to the basic operations. The first deployment may take a few minutes while nodes are provisioned:
$ vespa deploy --wait 600 app-1-getting-started
The command uploads the application and verifies the content. If anything is wrong with the application, this step will fail with a failure description; otherwise, this switches the application to a live status.
Whenever you have a new version of your application, run the same command to deploy the application. In most cases, there is no need to restart services. Vespa takes care of reconfiguring the system.
In the upcoming parts of the tutorials, we'll frequently deploy the application changes in this manner.
We must index data before we can search for it. This is called "feeding", and we'll get back to that in more detail in the next part of the tutorial. For now, to test that everything is up and running, we'll feed in a single test document:
$ vespa feed doc.json
The -v option will make vespa-cli print the http request:
$ vespa document -v doc.json
We can also feed using Vespa document api directly.
Once the feed operation is acknowledged by Vespa, the operation is visible in search.
We can query the endpoint using the vespa-cli's support for performing queries.
It uses the Vespa query api to query vespa,
including -v in the command, we can see the exact endpoint and url request parameters used.
$ vespa query -v 'yql=select * from news where true'
This example uses YQL (Vespa Query Language) to
search for all documents of type news. This query request will return 1 result, which is the document we fed above.
$ vespa query \ 'yql=select * from news where userQuery()' \ 'query=hello world' \ 'default-index=title'
Another query language example that searches for hello or world in the title.
$ vespa query \
'yql=select * from news where title contains phrase("hello","world")'
Another query language example that searches for the phrase "hello world" in the title. In the next part of the tutorial we'll demonstrate more query examples, and also ranking and grouping of results.
Run the following to remove the document from the index:
$ vespa document -v remove id:news:news::1
Well done!
Application instances in the dev zone will by default keep running for 14 days after the last deployment. You can control this in the console.
The Vespa Cloud console can also be used to delete the application instance.
Our simple application should now be up and running. In the next part of the tutorial, we'll start building from this foundation.