AI Notebooks - Getting started

If you already have created an AI Notebook using the Control Panel (UI) on this Public Cloud project, you can directly go to the next step Launch your first AI Notebook.

However, if this is the first time you are using the AI Products on your Public Cloud project, you will need to complete an authorization process before using the AI API, ovhai CLI, or Python SDK. To do so, please follow these steps:

Log in to the OVHcloud Control Panel, and navigate to the Public Cloud section, in the horizontal menu at the top of the website. Select the Public Cloud project you want to use. Then, click on the AI & Machine Learning category in the left-hand vertical menu to access the AI Notebooks section.

From there, click the Create a Notebook button. The authorization process will take place silently in the background.

Once you have clicked this button, you can leave this page and continue to follow this documentation to launch your AI Notebook using the CLI, API, or SDK as desired. Indeed, you do not need to complete the entire Notebook creation process in the Control Panel. Clicking the Create a Notebook button is sufficient.

If you prefer to use the command line interface to launch your AI Notebook, please follow these steps:

First, you will need to install the ovhai CLI and log into it. Please follow this documentation.

After installation and successful login, visit this second documentation to learn how to create your AI Notebook using commands.

To create an AI Notebook using the OVHcloud AI API, follow these steps:

First, navigate to the AI API link for the desired region among the ones that are available for the AI Products usage:

• GRA AI API, for Gravelines, France.
• BHS AI API, for Beauharnois, Canada.

Upon visiting the API URL, you will notice various endpoint categories on the left side of the screen. Click the Notebook category to display the endpoints related to AI Notebooks.

Among them, you will find a Submit a new notebook POST method. This is the endpoint for submitting a new AI Notebook.

The exact link for this endpoint on GRA region is as follows: https://gra.training.ai.cloud.ovh.net/#/operations/notebookNew.

In the Submit a new notebook endpoint page, you will find the detailed schema for the Notebook Specification and its various possible parameters. Examples of responses (200, 400, 401, 402, 403) are also provided in case of success or different error scenarios.

Before using this method to create an AI Notebook, you will need to authenticate. This can be done by providing a bearer token, which you can create through the AI Dashboard or by using the ovhai CLI. For more detailed instructions on creating a token, please consult the Manage access tokens documentation.

Once you have created your token, provide your token in the 'Auth' panel, on the right-hand corner of the API page.

After logging in, you may modify the body (Notebook specifications) for the AI Notebook you wish to create. A default example is provided. Feel free to adjust it.

Once your body is filled, click the Send API request button. If your body is correctly written, the Notebook will be created on the Public Cloud project from which the bearer token used for identification originates. You will receive all the necessary information about the created Notebook (ID, access URL, etc.) in the Responses field.

In addition to the API interface, the API provides Python code examples to help you use the endpoint and reproduce the same result programmatically. However, for an efficient Python experience, we recommend using the ovhai Python SDK.

The ovhai library is a Python client that allows developers to easily use the OVHcloud AI API. With this SDK, you can run, manage, automate your AI Notebooks.

To launch an AI Notebook using the ovhai Python SDK, you first need to install the ovhai library. You can do this using pip. Open your terminal and run the following command:

pip install ovhai

Once installed, we invite you to follow the instructions provided in the ovhai PyPI page to learn how to create a token for authentication, understand the SDK's functionality, and launch an AI Notebook using the ovhai Python SDK.

Here is a basic example of how to do it, making it easy for you to get started:

from ovhai import AuthenticatedClient
from ovhai.api.notebook import notebook_new
from ovhai.models import NotebookSpec, Notebook
from ovhai.ovhai_types import Response

client = AuthenticatedClient(
base_url="https://gra.training.ai.cloud.ovh.net",
token="YOUR_AI_TOKEN",
)

# Define notebook parameters
editor_id = "jupyterlab"
framework_id = "conda"
framework_version = "conda-py311-cudaDevel11.8"
nb_cpu = 2

# Create the notebook creation request
notebook_specs = {
"env": {"editorId": editor_id, "frameworkId": framework_id, "frameworkVersion": framework_version},
"resources": {"cpu": nb_cpu},
}

with client as client:
response: Response[Notebook] = notebook_new.sync_detailed(
client=client, body=NotebookSpec.from_dict(notebook_specs)
)

import json
response_content = response.content.decode('utf-8')  # Decode bytes to a string
response_dict = json.loads(response_content)

status_code = response.status_code
id_ = response_dict['id']
spec = response_dict['spec']
status = response_dict['status']
state = status['state']
info = status['info']
url = response_dict['status']['url']

print(f"Status code: {status_code}")
print(f"ID: {id_}")
print(f"Spec: {spec}")
print(f"State: {state}")
print(f"Info: {info}")
print(f"URL: {url}")

Please make sure to replace YOUR_AI_TOKEN with a bearer token. Bearer tokens can be created through the AI Dashboard or by using the ovhai CLI. For more detailed instructions on creating a token, please consult the Manage access tokens documentation.

Running this code will launch a new AI Notebook based on the specifications you provided. Feel free to adjust the specifications based on the Notebook you want to create.

In the previous step, you ordered the creation of your Notebook. This should have displayed the URL of your Notebook in your terminal, allowing you to access it:

If you no longer have the Notebook UUID and URL displayed in your terminal, you can easily list all your existing AI Notebooks by running:

ovhai notebook list

This will allow you to retrieve the URL of the Notebook you want to access.

You can also get all the information related to a Notebook (Specifications, Access Url, Monitoring URL, ...) by running:

ovhai notebook get <NOTEBOOK_UUID>

Just make sure to replace the <NOTEBOOK_UUID> with the actual UUID of the Notebook you want to retrieve the information for.

In the previous step, you ordered the creation of your Notebook. This should have displayed the URL of your Notebook in the 'Response' panel, allowing you to access it:

If you no longer have the Notebook UUID and URL displayed in the API page, you can list all your AI Notebooks by using the Paginated list of notebooks GET endpoint method, in the Notebook category.

This will allow you to retrieve the URL of the Notebook you want to access.

You can also get all the information related to a Notebook (Specifications, Access Url, Monitoring URL, ...) by using the Get notebook information GET endpoint method. You will just have to provide the UUID of the notebook from which you want to obtain information.

If you no longer have the Notebook UUID and URL displayed in your Python IDE, you can easily list all your AI Notebooks by running:

from ovhai.api.notebook import notebook_get_all
from ovhai.models import NotebookList
from ovhai.ovhai_types import Response

from ovhai import AuthenticatedClient

client = AuthenticatedClient(
base_url="https://gra.training.ai.cloud.ovh.net",
token="YOUR_AI_TOKEN",
)

with client as client:
response: Response[NotebookList] = notebook_get_all.sync_detailed(client=client)
import json
response = json.loads(response.content.decode())
for notebook_info in response["items"]:
print(f"ID: {notebook_info['id']}")
print(f"Name: {notebook_info['spec']['name']}")
print(f"Status: {notebook_info['status']['state']}")
print(f"Framework: {notebook_info['spec']['env']['frameworkId']}")
print(f"Framework version: {notebook_info['spec']['env']['frameworkVersion']}")
print(f"Editor: {notebook_info['spec']['env']['editorId']}")
print(f"Access link: {notebook_info['status']['url']}")
print("---------------")

This will allow you to retrieve the URL of the Notebook you want to access. Just make sure you are using the right API url, and replace YOUR_AI_TOKEN with your actual AI token.

You can also get all the information related to a Notebook (Specifications, Access Url, Monitoring URL, ...) by running the following code:

from ovhai.api.notebook import notebook_get
from ovhai import AuthenticatedClient
import json

client = AuthenticatedClient(
base_url="https://gra.training.ai.cloud.ovh.net",
token="YOUR_AI_TOKEN",
)
id = "YOUR_NOTEBOOK_UUID"

with client as client:
response = notebook_get.sync_detailed(
id=id, client=client
)

print(json.loads(response.content.decode()))

Using a token is an effective way to share the AI Notebook with anyone, without requiring them to have the credentials of one of your Public Cloud project users. This is useful when you want to provide access to the Notebook outside your Public Cloud project.

To authenticate using an access token, please follow these steps:

Click the Login with token button, located below the user and password fields. This will switch the access mode to use a token-based authentication method instead.

Make sure to use a token that you have created either from the AI Dashboard or from the ovhai CLI, API, or SDK. You can use tokens that were created without a label selector. If you specified a label selector during the Notebook creation, you can also use the token that matches the label selector specified. For more information on how to create an access token, please refer to this documentation.

Enter the access token in the 'Access Token' field, as shown in the screenshot below.

Click the Connect button to log in to your AI Notebook.

You can easily stop your Notebook using the following command:

ovhai notebook stop <NOTEBOOK_UUID>

Make sure to replace <NOTEBOOK_UUID> with the Notebook UUID you want to stop.

If you do not know its UUID, remember that you can easily list all your existing AI Notebooks by running:

ovhai notebook list

Select the Stop a running notebook endpoint, which is a PUT method. Provide the UUID of the Notebook you wish to stop as an input parameter. Then, click the Send API request button to send the request.

If the request is successful, the Notebook will be stopped and a 'No content' message will be displayed in the 'Response' panel. If the request is unsuccessful, an error message will be displayed there.

Here is an example of how to stop a running Notebook using the Python SDK:

from ovhai.api.notebook import notebook_stop
from ovhai import AuthenticatedClient
client = AuthenticatedClient(
base_url="https://gra.training.ai.cloud.ovh.net",
token="YOUR_AI_TOKEN",
)
id = "YOUR_NOTEBOOK_UUID"

with client as client:
response = notebook_stop.sync_detailed(client=client, id=id)

Please replace YOUR_AI_TOKEN with your actual AI token and YOUR_NOTEBOOK_UUID with the UUID of the Notebook you want to stop.

Use the following command and replace <NOTEBOOK_UUID> with your Notebook UUID to restart your stopped Notebook:

ovhai notebook start <NOTEBOOK_UUID>

Select the Start a stopped notebook endpoint, which is a PUT method. Provide the UUID of the Notebook you wish to restart as an input parameter. Then, click the Send API request button to send the request.

If the request is successful, the Notebook will be restarted and a 'No content' message will be displayed in the 'Response' panel. If the request is unsuccessful, an error message will be displayed there.

Here is an example of how to stop a running Notebook using the Python SDK:

from ovhai.api.notebook import notebook_start
from ovhai import AuthenticatedClient
client = AuthenticatedClient(
base_url="https://gra.training.ai.cloud.ovh.net",
token="YOUR_AI_TOKEN",
)
id = "YOUR_NOTEBOOK_UUID"

with client as client:
response = notebook_start.sync_detailed(
id=id, client=client
)

Please replace YOUR_AI_TOKEN with your actual AI token and YOUR_NOTEBOOK_UUID with the UUID of the Notebook you want to stop.

If you want to completely delete your AI Notebook, just run the following command:

ovhai notebook delete <NOTEBOOK_UUID>

If the Notebook is still RUNNING, a confirmation message will appear, asking you to confirm the action. Confirm only if you're sure you want to delete the Notebook.

Select the Delete permanently a notebook endpoint, which is a DELETE method. Provide the UUID of the Notebook you wish to delete. Use the force parameter if your Notebook is not STOPPED and still RUNNING. Then, click the Send API request button to send the request.

If the request is successful, the Notebook will be restarted and a 'No content' message will be displayed in the 'Response' panel. If the request is unsuccessful, an error message will be displayed there.

Here is an example of how to delete a Notebook using the Python SDK:

from ovhai.api.notebook import notebook_delete
from ovhai import AuthenticatedClient

client = AuthenticatedClient(
base_url="https://gra.training.ai.cloud.ovh.net",
token="YOUR_AI_TOKEN",
)
id = "YOUR_NOTEBOOK_UUID"

with client as client:
response = notebook_delete.sync_detailed(
id=id, client=client, force=False
)

print(response.content.decode())

Please replace YOUR_AI_TOKEN with your actual AI token and YOUR_NOTEBOOK_UUID with the UUID of the Notebook you want to delete. If the Notebook is still RUNNING, you will need to set the force parameter to True to delete the Notebook.