Skip to content

Commit

Permalink
Merge pull request #623 from vespa-engine/jobergum/notebook-formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
@kkraune
kkraune committed Nov 9, 2023
2 parents 4c05339 + 77eba90 commit f887813
Showing 1 changed file with 30 additions and 17 deletions.
47 changes: 30 additions & 17 deletions docs/sphinx/source/getting-started-pyvespa-cloud.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
"\n",
"Install [pyvespa](https://pyvespa.readthedocs.io/) >= 0.35\n",
"and the [Vespa CLI](https://docs.vespa.ai/en/vespa-cli.html).\n",
"The Vespa CLI is used for key management:"
"The Vespa CLI is used for data and control plane key management ([Vespa Cloud Security Guide](https://cloud.vespa.ai/en/security/guide))."
]
},
{
Expand Down Expand Up @@ -82,7 +82,7 @@
"id": "fbed21b0",
"metadata": {},
"source": [
"Alternatively, if running in Colab, download the Vespa CLI:"
"Alternatively, if running in Colab, download the Vespa CLI from GitHub:"
]
},
{
Expand Down Expand Up @@ -157,11 +157,14 @@
"Note that the subsequent deploy-call below will add `data-plane-public-cert.pem` to the application before deploying it to Vespa Cloud, so that\n",
"you have access to both the private key and the public certificate, while Vespa Cloud only knows the public certificate. \n",
"\n",
"### Configure control-plane security \n",
"## Configure control-plane security \n",
"\n",
"Authenticate to generate a tenant level control plane API key for deploying the applications to Vespa Cloud, and save the path to it. \n",
"Authenticate to generate a tenant level control-plane API key for deploying the applications to Vespa Cloud, and save the path to it. \n",
"<div style=\"background-color: #ffcc00; padding: 10px; border: 1px solid #ff9900; font-weight: bold;\">\n",
" <strong>Warning:</strong>The generated tenant api key must be added in the Vespa Console before attemting to deploy the application.\n",
"</div>\n",
"\n",
"The generated tenant api key must be added in the Vespa Console before attemting to deploy the application. \n",
"The following step will print the following message: \n",
"\n",
"```\n",
"To use this key in Vespa Cloud click 'Add custom key' at\n",
Expand All @@ -188,7 +191,8 @@
"id": "99e82a48",
"metadata": {},
"source": [
"Follow the instrauctions from the output above and add the key in the console."
"Follow the instrauctions from the output above and add the control-plane key in the console at `https://console.vespa-cloud.com/tenant/TENANT_NAME/account/keys`\n",
"(replace TENANT_NAME with your tenant name)."
]
},
{
Expand Down Expand Up @@ -282,8 +286,8 @@
"source": [
"## Deploy to Vespa Cloud\n",
"\n",
"The text search app with fields, a fieldset to group fields together, and rank profiles\n",
"is now defined and ready to deploy.\n",
"The app with is now defined and ready to deploy to Vespa Cloud. \n",
"\n",
"Deploy `package` to Vespa Cloud, by creating an instance of\n",
"[VespaCloud](https://pyvespa.readthedocs.io/en/latest/reference-api.html#vespa.deployment.VespaCloud):"
]
Expand Down Expand Up @@ -319,7 +323,8 @@
"id": "197c0a27",
"metadata": {},
"source": [
"The following will upload the application package to Vespa Cloud Dev Zone (`aws-us-east-1c`), read more about [Vespa Zones](https://cloud.vespa.ai/en/reference/zones.html)."
"The following will upload the application package to Vespa Cloud Dev Zone (`aws-us-east-1c`), read more about [Vespa Zones](https://cloud.vespa.ai/en/reference/zones.html). PyVespa\n",
"currently only supports deploying to the Vespa Cloud Dev Zone, which is considered as a sandbox environment without high availability guarantees. "
]
},
{
Expand Down Expand Up @@ -403,8 +408,10 @@
"source": [
"Now we can feed to Vespa using `feed_iterable` which accepts any `Iterable` and an optional callback function where we can\n",
"check the outcome of each operation. The application is configured to use to use [embedding](https://docs.vespa.ai/en/embedding.html)\n",
"functionality, that produce a vector embedding using a concatenation of the title and the body input fields. This step is computionally expensive. Read more\n",
"about embedding inference in Vespa in the [Accelerating Transformer-based Embedding Retrieval with Vespa](https://blog.vespa.ai/accelerating-transformer-based-embedding-retrieval-with-vespa/).\n",
"functionality, that produce a vector embedding using a concatenation of the title and the body input fields. This step is resource intensive. \n",
"\n",
"Read more about embedding inference in Vespa in the [Accelerating Transformer-based Embedding Retrieval with Vespa](https://blog.vespa.ai/accelerating-transformer-based-embedding-retrieval-with-vespa/)\n",
"blog post.\n",
"\n",
"Default node resources in Vespa Cloud have 2 v-cpu for the Dev Zone."
]
Expand Down Expand Up @@ -442,8 +449,9 @@
"\n",
"Query the text search app using the [Vespa Query language](https://docs.vespa.ai/en/query-language.html)\n",
"by sending the parameters to the body argument of\n",
"[Vespa.query](https://pyvespa.readthedocs.io/en/latest/reference-api.html#vespa.application.Vespa.query) -\n",
"here using the `bm25` rank profile:"
"[Vespa.query](https://pyvespa.readthedocs.io/en/latest/reference-api.html#vespa.application.Vespa.query). \n",
"\n",
"First we define a simple routine that will return a dataframe of the results for prettier display in the notebook. "
]
},
{
Expand Down Expand Up @@ -646,8 +654,10 @@
"source": [
"## Example: Document operations using cert/key pair\n",
"\n",
"Above, we deployed to Vespa Cloud, and as part of that, generated a cert/key pair.\n",
"This pair can be used to access the dataplane for reads/writes to documents and running queries."
"Above, we deployed to Vespa Cloud, and as part of that, generated a data-plane mTLS cert/key pair.\n",
"\n",
"his pair can be used to access the dataplane for reads/writes to documents and running queries from many different clients. The following\n",
"demonstrates that using the `requests` library."
]
},
{
Expand Down Expand Up @@ -767,7 +777,10 @@
"id": "183bff2b",
"metadata": {},
"source": [
"A common problem is a cert mismatch - the cert/key pair used when deployed is different than the pair used when making queries. Make sure it is the same pair / re-create with `vespa auth cert -f` AND redeploy. \n",
"A common problem is a cert mismatch - the cert/key pair used when deployed is different than the pair used when making requests against Vespa. This\n",
"will cause 40x errors. \n",
"\n",
"Make sure it is the same pair / re-create with `vespa auth cert -f` AND redeploy. \n",
"\n",
"If you re-generate a mTLS certificate pair, and use that when connecting to Vespa cloud endpoint, it will fail until you have updaded the deployment with the new public certificate.\n",
"\n",
Expand Down Expand Up @@ -803,7 +816,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.5"
"version": "3.11.4"
},
"nbsphinx": {
"allow_errors": true
Expand Down

0 comments on commit f887813

Please sign in to comment.