Merge pull request #199 from vespa-engine/tgm/doc-stateless

Document stateless apps and include more detailed deploy to vespa cloud quick-start
vespa-engine · Sep 3, 2021 · 9289e16 · 9289e16
2 parents 3d8280b + 59c717f
commit 9289e16
Show file tree

Hide file tree

Showing 4 changed files with 198 additions and 4 deletions.
diff --git a/docs/sphinx/source/deploy-vespa-cloud.ipynb b/docs/sphinx/source/deploy-vespa-cloud.ipynb
@@ -0,0 +1,161 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Deploy to Vespa Cloud\n",
+    "\n",
+    "> How to host your Vespa application in the cloud\n",
+    "\n",
+    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/vespa-engine/pyvespa/blob/master/docs/sphinx/source/deploy-vespa-cloud.ipynb)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Define your application package"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This tutorial assumes you have defined your Vespa application package and stored it in the variable `app_package`. To illustrate this tutorial, we will use a basic question answering app from our gallery."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from vespa.gallery import QuestionAnswering\n",
+    "\n",
+    "app_package = QuestionAnswering()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setup your Vespa Cloud account"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "1. Sign-in or sign-up:\n",
+    "  * To deploy `app_package` on Vespa Cloud, you need to [login into your account](https://cloud.vespa.ai/) first. You can create one and give it a try for free.\n",
+    "2. Choose a tenant:\n",
+    "  *  You either create a new tenant or use an existing one. That will be the `TENANT_NAME` env variable in the example below. \n",
+    "3. Get your user key:\n",
+    "  * Once you are on your chosen tenant dashboard, you can generate and download a user key under the key tab. Set the `USER_KEY` env variable to be the path to the downloaded user key. \n",
+    "4. Create a new application under your tenant\n",
+    "  * Within the tenant dashboard, you can also create a new application associated with that tenant and set the `APPLICATION_NAME` env variable below to the name of the application. \n",
+    "  \n",
+    "That is all that needs to be setup on the Vespa Cloud dashboard before deployment."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Create a VespaCloud instance"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {
+    "nbsphinx": "hidden"
+   },
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "os.environ[\"WORK_DIR\"] = \"/Users/tmartins/projects/vespa/pyvespa/\"\n",
+    "os.environ[\"VESPA_CLOUD_USER_KEY\"] = \"-----BEGIN PRIVATE KEY-----\\nMIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgfuuKjPOWBQIrT9gd\\n1eezkuzqk9IIiwJnSMpFS7jZLAShRANCAAQg5CR0IhuADhVnEVwizXEWmmDcc2ML\\ni3VmInWOHsYrNSzEXNepXuvgo2w/WpCIxQPfntx+J239+Qqw2bc07huF\\n-----END PRIVATE KEY-----\"\n",
+    "\n",
+    "os.environ[\"TENANT_NAME\"] = \"vespa-team\"\n",
+    "os.environ[\"APPLICATION_NAME\"] = \"pyvespa-integration\"\n",
+    "with open(os.path.join(os.getenv(\"WORK_DIR\"), \"key.pem\"), \"w\") as f:\n",
+    "    f.write(os.getenv(\"VESPA_CLOUD_USER_KEY\").replace(r\"\\n\", \"\\n\"))\n",
+    "os.environ[\"USER_KEY\"] = os.path.join(os.getenv(\"WORK_DIR\"), \"key.pem\")\n",
+    "os.environ[\"INSTANCE_NAME\"] = \"test\"\n",
+    "os.environ[\"DISK_FOLDER\"] = os.path.join(os.getenv(\"WORK_DIR\"), \"sample_application\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from vespa.deployment import VespaCloud\n",
+    "\n",
+    "vespa_cloud = VespaCloud(\n",
+    "    tenant=os.getenv(\"TENANT_NAME\"),\n",
+    "    application=os.getenv(\"APPLICATION_NAME\"),\n",
+    "    key_location=os.getenv(\"USER_KEY\"),\n",
+    "    application_package=app_package,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Deploy to the Cloud"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can have multiple instances of the same application, we can then chose a valid `INSTANCE_NAME` to identify the instance created here and set the `DISK_FOLDER` to a local path to hold deployment related files such as certifications and Vespa config files."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "app = vespa_cloud.deploy(\n",
+    "    instance=os.getenv(\"INSTANCE_NAME\"), disk_folder=os.getenv(\"DISK_FOLDER\")\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "That is it, you can now interact with your deployed application through the `app` instance."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/sphinx/source/quickstart.rst b/docs/sphinx/source/quickstart.rst
@@ -9,3 +9,4 @@ by clicking on the badge at the top of the tutorial.
    connect-to-vespa-instance
    create-and-deploy-vespa-cloud
    create-and-deploy-vespa-docker
+   deploy-vespa-cloud
diff --git a/docs/sphinx/source/reference-api.rst b/docs/sphinx/source/reference-api.rst
@@ -1,8 +1,8 @@
 Reference API
 =============
 
-Define application
-******************
+Define stateful application
+***************************
 
 Create an Application Package
 -----------------------------
@@ -108,9 +108,34 @@ QueryProfile
    :members:
    :special-members: __init__
 
+Define stateless application
+****************************
+
+Create tasks
+------------
+
+SequenceClassification
+++++++++++++++++++++++
+
+.. autoclass:: vespa.ml.SequenceClassification
+   :members:
+   :special-members: __init__
+
+Create model server
+-------------------
+
+ModelServer
++++++++++++
+
+.. autoclass:: vespa.package.ModelServer
+   :members:
+   :special-members: __init__
+
 Deploy your application
 ***********************
 
+Deploy your stateful or stateless applications.
+
 VespaDocker
 -----------
 

diff --git a/vespa/ml.py b/vespa/ml.py
@@ -103,9 +103,16 @@ def __init__(
         """
         Sequence Classification task.
 
+        It takes a text input and returns an array of floats depending on which
+        model is used to solve the task.
+
         :param model_id: Id used to identify the model on Vespa applications.
-        :param model: Id of the model as used by the model hub.
-        :param tokenizer: Id of the tokenizer as used by the model hub.
+        :param model: Id of the model as used by the model hub. Alternatively, it can
+            also be the path to the folder containing the model files, as long as
+            the model config is also there.
+        :param tokenizer: Id of the tokenizer as used by the model hub. Alternatively, it can
+            also be the path to the folder containing the tokenizer files, as long as
+            the model config is also there.
         :param output_file: Output file to write output messages.
         """
         super().__init__(