GitHub Repository: ibm/watson-machine-learning-samples
Path: blob/master/cpd5.2/notebooks/python_sdk/instance-management/Machine Learning artifacts export and import.ipynb
⁶⁴⁰² views

Kernel: watsonx-ai-samples-py-312

Export/Import assets with `ibm-watsonx-ai`

This notebook demonstrates an example for exporting/importing assets using watsonx.ai service. It contains steps and code to work with ibm-watsonx-ai library available in PyPI repository.

Some familiarity with Python is helpful. This notebook uses Python 3.12.

Learning goals

The learning goals of this notebook are:

Download an externally trained Keras model.
Persist an external model in watsonx.ai repository.
Export the model from the space
Import the model to another space (for Cloud Pak for Data 5.2, the space/project where assets are imported has to be empty) and deploy

This notebook contains the following parts:

1. Set up the environment

Before you use the sample code in this notebook, you must perform the following setup tasks:

Contact with your Cloud Pak for Data administrator and ask them for your account credentials

Install dependencies

Note: ibm-watsonx-ai documentation can be found here.

In [1]:

%pip install -U wget | tail -n 1
%pip install -U matplotlib | tail -n 1
%pip install -U ibm-watsonx-ai | tail -n 1

Out[1]:

Successfully installed wget-3.2
Successfully installed contourpy-1.3.2 cycler-0.12.1 fonttools-4.58.4 kiwisolver-1.4.8 matplotlib-3.10.3 numpy-2.3.1 pillow-11.2.1 pyparsing-3.2.3
Successfully installed anyio-4.9.0 certifi-2025.6.15 charset_normalizer-3.4.2 h11-0.16.0 httpcore-1.0.9 httpx-0.28.1 ibm-cos-sdk-2.14.2 ibm-cos-sdk-core-2.14.2 ibm-cos-sdk-s3transfer-2.14.2 ibm-watsonx-ai-1.3.26 idna-3.10 jmespath-1.0.1 lomond-0.3.3 pandas-2.2.3 pytz-2025.2 requests-2.32.4 sniffio-1.3.1 tabulate-0.9.0 typing_extensions-4.14.0 tzdata-2025.2 urllib3-2.5.0

Define credentials

Authenticate the watsonx.ai Runtime service on IBM Cloud Pak for Data. You need to provide the admin's username and the platform url.

In [2]:

username = "PASTE YOUR USERNAME HERE"
url = "PASTE THE PLATFORM URL HERE"

Use the admin's api_key to authenticate watsonx.ai Runtime services:

In [ ]:

import getpass
from ibm_watsonx_ai import Credentials

credentials = Credentials(
    username=username,
    api_key=getpass.getpass("Enter your watsonx.ai API key and hit enter: "),
    url=url,
    instance_id="openshift",
    version="5.2",
)

Alternatively you can use the admin's password:

In [3]:

import getpass
from ibm_watsonx_ai import Credentials

if "credentials" not in locals() or not credentials.api_key:
    credentials = Credentials(
        username=username,
        password=getpass.getpass("Enter your watsonx.ai password and hit enter: "),
        url=url,
        instance_id="openshift",
        version="5.2",
    )

Create `APIClient` instance

In [4]:

from ibm_watsonx_ai import APIClient

client = APIClient(credentials)

Create two spaces. One for export and one for import

Tip: You can refer to example for space management APIs here.

In [5]:

import uuid

space_name = str(uuid.uuid4())

Create export space

In [6]:

export_space_metadata = {
    client.spaces.ConfigurationMetaNames.NAME: "client_space_export_" + space_name,
    client.spaces.ConfigurationMetaNames.DESCRIPTION: space_name + " description",
}

space = client.spaces.store(meta_props=export_space_metadata)

export_space_id = client.spaces.get_id(space)
print(f"\nexport space_id: {export_space_id}\n")

Out[6]:

Space has been created. However some background setup activities might still be on-going. Check for 'status' field in the response. It has to show 'active' before space can be used. If it's not 'active', you can monitor the state with a call to spaces.get_details(space_id). Alternatively, use background_mode=False when calling client.spaces.store().

export space_id: 6ab1d2ce-e485-4184-98db-e9c66721cf1d

Create import space

In [7]:

import_space_metadata = {
    client.spaces.ConfigurationMetaNames.NAME: "client_space_import_" + space_name,
    client.spaces.ConfigurationMetaNames.DESCRIPTION: space_name + " description",
}

space = client.spaces.store(meta_props=import_space_metadata)

import_space_id = client.spaces.get_id(space)
print(f"\nimport space_id: {import_space_id}\n")

Out[7]:

Space has been created. However some background setup activities might still be on-going. Check for 'status' field in the response. It has to show 'active' before space can be used. If it's not 'active', you can monitor the state with a call to spaces.get_details(space_id). Alternatively, use background_mode=False when calling client.spaces.store().

import space_id: 1b6f00b0-e015-4d6c-9ba5-4641c56039a4

2. Download externally created Keras model and data

In this section, you will download externally created Keras model for MNIST dataset.

In [8]:

import os
import wget

model_path = "mnist-keras-model.h5.zip"
if not os.path.isfile(model_path):
    wget.download(
        "https://github.com/IBM/watsonx-ai-samples/raw/master/cpd5.2/models/keras/mnist-keras-model.h5.zip"
    )

Download data used for training the Keras model

In [9]:

data_dir = "MNIST_DATA"
if not os.path.isdir(data_dir):
    os.mkdir(data_dir)

filename = os.path.join(data_dir, "mnist.npz")
if not os.path.isfile(filename):
    wget.download("https://s3.amazonaws.com/img-datasets/mnist.npz", out=data_dir)

In [10]:

import numpy as np

dataset = np.load(filename)
x_test = dataset["x_test"]

3. Persist externally created Keras model

In this section, you will learn how to store your model in watsonx.ai repository by using the ibm-watsonx-ai client.

3.1: Publish model

Define model name, type and software specification needed to deploy model later.

In [11]:

software_spec_id = client.software_specifications.get_id_by_name("runtime-25.1-py3.12")

In [12]:

client.set.default_space(export_space_id)

metadata = {
    client.repository.ModelMetaNames.NAME: "External Keras model",
    client.repository.ModelMetaNames.TYPE: "tensorflow_2.18",
    client.repository.ModelMetaNames.SOFTWARE_SPEC_ID: software_spec_id,
}

published_model = client.repository.store_model(model=model_path, meta_props=metadata)

3.2: Get model details

In [13]:

import json

published_model_id = client.repository.get_model_id(published_model)
model_details = client.repository.get_details(published_model_id)
print(json.dumps(model_details, indent=2))

Out[13]:

{
  "metadata": {
    "name": "External Keras model",
    "space_id": "6ab1d2ce-e485-4184-98db-e9c66721cf1d",
    "resource_key": "4e684e2a-fd59-40e0-b52a-0de88e850af4",
    "id": "c1055bff-f931-4052-87c5-e66a73de2180",
    "created_at": "2025-07-01T07:11:15Z",
    "rov": {
      "member_roles": {
        "1000331001": {
          "user_iam_id": "1000331001",
          "roles": [
            "OWNER"
          ]
        }
      }
    },
    "owner": "1000331001"
  },
  "entity": {
    "software_spec": {
      "id": "f47ae1c3-198e-5718-b59d-2ea471561e9e"
    },
    "type": "tensorflow_2.18"
  }
}

3.3 Get all models in the space

The space_id is automatically picked up from client.set.default_space() API call before

In [14]:

models_details = client.repository.list_models()

4. Export

In [15]:

help(client.export_assets.start)

Out[15]:

Help on method start in module ibm_watsonx_ai.export_assets:

start(meta_props: 'dict[str, str | bool | list]', space_id: 'str | None' = None, project_id: 'str | None' = None) -> 'dict' method of ibm_watsonx_ai.export_assets.Export instance
    Start the export. You must provide the space_id or the project_id.
    ALL_ASSETS is by default False. You don't need to provide it unless it is set to True.
    You must provide one of the following in the meta_props: ALL_ASSETS, ASSET_TYPES, or ASSET_IDS. Only one of these can be
    provided.

    In the `meta_props`:

    ALL_ASSETS is a boolean. When set to True, it exports all assets in the given space.
    ASSET_IDS is an array that contains the list of assets IDs to be exported.
    ASSET_TYPES is used to provide the asset types to be exported. All assets of that asset type will be exported.

            Eg: wml_model, wml_model_definition, wml_pipeline, wml_function, wml_experiment,
            software_specification, hardware_specification, package_extension, script

    :param meta_props: metadata,
        to see available meta names use ``client.export_assets.ConfigurationMetaNames.get()``
    :type meta_props: dict
    :param space_id: space identifier
    :type space_id: str, optional
    :param project_id: project identifier
    :type project: str, optional

    :return: Response json
    :rtype: dict

    **Example:**

    .. code-block:: python

        metadata = {
            client.export_assets.ConfigurationMetaNames.NAME: "export_model",
            client.export_assets.ConfigurationMetaNames.ASSET_IDS: ["13a53931-a8c0-4c2f-8319-c793155e7517",
                                                                    "13a53931-a8c0-4c2f-8319-c793155e7518"]}

        details = client.export_assets.start(meta_props=metadata, space_id="98a53931-a8c0-4c2f-8319-c793155e4598")

    .. code-block:: python

        metadata = {
            client.export_assets.ConfigurationMetaNames.NAME: "export_model",
            client.export_assets.ConfigurationMetaNames.ASSET_TYPES: ["wml_model"]}

        details = client.export_assets.start(meta_props=metadata, space_id="98a53931-a8c0-4c2f-8319-c793155e4598")

    .. code-block:: python

        metadata = {
            client.export_assets.ConfigurationMetaNames.NAME: "export_model",
            client.export_assets.ConfigurationMetaNames.ALL_ASSETS: True}

        details = client.export_assets.start(meta_props=metadata, space_id="98a53931-a8c0-4c2f-8319-c793155e4598")

client.export_assets has these APIs. For any help on these apis, type help(api_name) in your notebook Example: help(client.export_assets.start), help(client.export_assets.get_details)

client.export_assets.start: This starts the export job. Export job is asynchronously executed
client.export_assets.get_details: Given export_id and corresponding space_id / project_id, this gives the export job details. Usually used for monitoring the export job submitted with start API
client.export_assets.list: Prints summary of all the export jobs
client.export_assets.get_exported_content: Downloads the exported content. This information will be used by the import process
client.export_assets.delete: Deletes the given export job
client.export_assets.cancel: Cancels the given export job if running

4.1: Start the export process

Start the export process for the model created. Either ASSET_IDS or ASSET_TYPES or ALL_ASSETS can be provided. If you have more than one model ids, you need to provide them as array like client.export_assets.ConfigurationMetaNames.ASSET_IDS: [model_id1, model_id2] Refer to the help api above to see different usages and details

In [16]:

metadata = {
    client.export_assets.ConfigurationMetaNames.NAME: "export_model",
    client.export_assets.ConfigurationMetaNames.ASSET_IDS: [published_model_id],
}

details = client.export_assets.start(meta_props=metadata, space_id=export_space_id)
print(json.dumps(details, indent=2))

export_job_id = details["metadata"]["id"]

Out[16]:

export job with id 941bdf02-a9ca-4b3c-a48b-5a986eeeb9a3 has started. Monitor status using client.export_assets.get_details api. Check 'help(client.export_assets.get_details)' for details on the api usage
{
  "entity": {
    "assets": {
      "all_assets": false,
      "asset_ids": [
        "c1055bff-f931-4052-87c5-e66a73de2180"
      ]
    },
    "format": "json",
    "skip_notification": true,
    "status": {
      "state": "pending"
    }
  },
  "metadata": {
    "created_at": "2025-07-01T07:12:52.323Z",
    "creator_id": "1000331001",
    "id": "941bdf02-a9ca-4b3c-a48b-5a986eeeb9a3",
    "name": "export_model",
    "space_id": "6ab1d2ce-e485-4184-98db-e9c66721cf1d",
    "url": "/v2/asset_exports/941bdf02-a9ca-4b3c-a48b-5a986eeeb9a3"
  }
}

4.2: Monitor the export process

In [17]:

import time

start_time = time.time()
diff_time = start_time - start_time
while diff_time < 10 * 60:
    time.sleep(3)
    response = client.export_assets.get_details(export_job_id, space_id=export_space_id)

    state = response["entity"]["status"]["state"]
    print(state)
    if state in ("completed", "error", "failed"):
        break

    diff_time = time.time() - start_time
else:
    raise TimeoutError("Export wasn't completed in 10 minutes")

print(json.dumps(response, indent=2))

Out[17]:

running
completed
{
  "entity": {
    "assets": {
      "all_assets": false,
      "asset_ids": [
        "c1055bff-f931-4052-87c5-e66a73de2180"
      ]
    },
    "format": "json",
    "skip_notification": true,
    "status": {
      "state": "completed"
    }
  },
  "metadata": {
    "created_at": "2025-07-01T07:12:52.323Z",
    "creator_id": "1000331001",
    "id": "941bdf02-a9ca-4b3c-a48b-5a986eeeb9a3",
    "name": "export_model",
    "space_id": "6ab1d2ce-e485-4184-98db-e9c66721cf1d",
    "updated_at": "2025-07-01T07:13:01.088Z",
    "url": "/v2/asset_exports/941bdf02-a9ca-4b3c-a48b-5a986eeeb9a3"
  }
}

4.3: Get the exported content

In [18]:

export_dir = "EXPORT_DATA"

if not os.path.isdir(export_dir):
    os.mkdir(export_dir)

export_file_name = f"exported_content_{uuid.uuid4()}.zip"
export_file_path = os.path.join(export_dir, export_file_name)

details = client.export_assets.get_exported_content(
    export_job_id, space_id=export_space_id, file_path=export_file_path
)

print(details)

Out[18]:

Successfully saved export content to file: 'EXPORT_DATA/exported_content_bb6e0e54-5513-43da-b03d-db12a243450a.zip'
EXPORT_DATA/exported_content_bb6e0e54-5513-43da-b03d-db12a243450a.zip

5. Import

client.import_assets has these APIs. For any help on these APIs, type help(api_name) in your notebook. Example: help(client.import_assets.start), help(client.import_assets.get_details)

client.import_assets.start: This starts the import job. Import job is asynchronously executed
client.import_assets.get_details: Given import_id and corresponding space_id / project_id, this gives the import job details. Usually used for monitoring the import job submitted with start API
client.import_assets.list: Prints summary of all the import jobs
client.import_assets.delete: Deletes the given import job
client.import_assets.cancel: Cancels the given import job if running

5.1: Start the import process

In [19]:

details = client.import_assets.start(
    file_path=export_file_path, space_id=import_space_id
)
print(json.dumps(details, indent=2))

import_job_id = details["metadata"]["id"]

Out[19]:

import job with id 258da85d-cf6f-40cf-8871-76f80064d961 has started. Monitor status using client.import_assets.get_details api. Check 'help(client.import_assets.get_details)' for details on the api usage
{
  "entity": {
    "format": "json",
    "skip_notification": true,
    "status": {
      "state": "pending"
    }
  },
  "metadata": {
    "created_at": "2025-07-01T07:14:24.839Z",
    "creator_id": "1000331001",
    "id": "258da85d-cf6f-40cf-8871-76f80064d961",
    "space_id": "1b6f00b0-e015-4d6c-9ba5-4641c56039a4",
    "url": "/v2/asset_imports/258da85d-cf6f-40cf-8871-76f80064d961"
  }
}

5.2: Monitor the import process

In [20]:

import time

start_time = time.time()
diff_time = start_time - start_time
while diff_time < 10 * 60:
    time.sleep(3)
    response = client.import_assets.get_details(import_job_id, space_id=import_space_id)

    state = response["entity"]["status"]["state"]
    print(state)
    if state in ("completed", "error", "failed"):
        break

    diff_time = time.time() - start_time
else:
    raise TimeoutError("Import wasn't completed in 10 minutes")

print(json.dumps(response, indent=2))

Out[20]:

running
completed
{
  "entity": {
    "format": "json",
    "skip_notification": true,
    "status": {
      "state": "completed"
    }
  },
  "metadata": {
    "created_at": "2025-07-01T07:14:24.839Z",
    "creator_id": "1000331001",
    "id": "258da85d-cf6f-40cf-8871-76f80064d961",
    "space_id": "1b6f00b0-e015-4d6c-9ba5-4641c56039a4",
    "updated_at": "2025-07-01T07:14:33.640Z",
    "url": "/v2/asset_imports/258da85d-cf6f-40cf-8871-76f80064d961"
  }
}

Display the list of models in the import space

In [21]:

client.set.default_space(import_space_id)

print("\nList of models:\n")
client.repository.list_models()
details = client.repository.get_model_details()

for obj in details["resources"]:
    if obj["metadata"]["name"] == "External Keras model":
        model_id_for_deployment = obj["metadata"]["id"]

print(f"\nmodel id for deployment: {model_id_for_deployment}")

Out[21]:

List of models:

model id for deployment: 16ed9c67-8daa-4ca2-a107-bcc9a0c9175e

List the import jobs

In [22]:

client.import_assets.list(space_id=import_space_id)

Out[22]:

List the export jobs

In [23]:

client.export_assets.list(space_id=export_space_id)

Out[23]:

6. Deploy and score the imported model

6.1: Create model deployment

Create online deployment for published model

In [24]:

metadata = {
    client.deployments.ConfigurationMetaNames.NAME: "Deployment of external Keras model",
    client.deployments.ConfigurationMetaNames.ONLINE: {},
}

created_deployment = client.deployments.create(
    model_id_for_deployment, meta_props=metadata
)

Out[24]:

######################################################################################

Synchronous deployment creation for id: '16ed9c67-8daa-4ca2-a107-bcc9a0c9175e' started

######################################################################################


initializing
Note: online_url is deprecated and will be removed in a future release. Use serving_urls instead.
...........................
ready


-----------------------------------------------------------------------------------------------
Successfully finished deployment creation, deployment_id='22f8e767-9589-4b82-b6ba-e9e69fb6e6a5'
-----------------------------------------------------------------------------------------------

In [25]:

deployment_id = client.deployments.get_id(created_deployment)

Now you can print an online scoring endpoint.

In [ ]:

scoring_endpoint = client.deployments.get_scoring_href(created_deployment)
print(scoring_endpoint)

You can also list existing deployments.

In [27]:

client.deployments.list()

Out[27]:

6.2: Get deployment details

In [ ]:

details = client.deployments.get_details(deployment_id)
print(json.dumps(details, indent=2))

6.3: Score

You can use below method to do test scoring request against deployed model.

Let's first visualize two samples from dataset, we'll use for scoring. You must have matplotlib package installed

In [29]:

%matplotlib inline
import matplotlib.pyplot as plt

In [30]:

for i, image in enumerate([x_test[0], x_test[1]]):
    plt.subplot(2, 2, i + 1)
    plt.axis("off")
    plt.imshow(image, cmap=plt.cm.gray_r, interpolation="nearest")

Out[30]:

Prepare scoring payload with records to score.

In [31]:

score_0 = x_test[0].reshape(28, 28, 1)
score_1 = x_test[1].reshape(28, 28, 1)

In [32]:

scoring_payload = {"input_data": [{"values": [score_0, score_1]}]}

Use client.deployments.score() method to run scoring.

In [33]:

predictions = client.deployments.score(deployment_id, scoring_payload)

In [34]:

print(json.dumps(predictions, indent=2))

Out[34]:

{
  "predictions": [
    {
      "fields": [
        "prediction"
      ],
      "id": "y_hat",
      "values": [
        [
          2.1161436052352656e-06,
          9.53357170985214e-10,
          4.728389346730921e-10,
          3.943275572737548e-08,
          0.00011951127089560032,
          1.438263979025578e-07,
          2.1252301252161487e-08,
          0.9995545744895935,
          8.875564958543691e-07,
          0.0003227672423236072
        ],
        [
          0.021077046170830727,
          0.1209486722946167,
          0.8552001714706421,
          0.0012876029359176755,
          4.0436454582959414e-05,
          0.0004892426659353077,
          0.00048998644342646,
          9.553693234920502e-05,
          0.00018569448729977012,
          0.00018568598898127675
        ]
      ]
    }
  ]
}

In [35]:

for i, prediction in enumerate(predictions["predictions"][0]["values"]):
    plt.bar(range(10), prediction)
    plt.title("Digit probability")
    plt.xlabel("Digit")
    plt.ylabel("Probability")
    plt.xticks(range(10))
    plt.yscale("log")
    plt.show()

Out[35]:

As you can see, predicted values are the same one as displayed above from test dataset.

7. Clean up

In [36]:

client.export_assets.delete(export_job_id, space_id=export_space_id)
client.import_assets.delete(import_job_id, space_id=import_space_id)

client.spaces.delete(export_space_id)
client.spaces.delete(import_space_id)

Out[36]:

Export job deleted
Import job deleted
DELETED
DELETED

'SUCCESS'

If you want to clean up all created assets:

experiments
trainings
pipelines
model definitions
models
functions
deployments

please follow up this sample notebook.

8. Summary and next steps

You successfully completed this notebook! You learned how to use export/import assets client apis.

Check out our Online Documentation for more samples, tutorials, documentation, how-tos, and blog posts.

Authors

Mithun - [email protected], Software Engineer

Export/Import assets with `ibm-watsonx-ai`

Learning goals

Contents

1. Set up the environment

Install dependencies

Define credentials

Create `APIClient` instance

Create two spaces. One for export and one for import

2. Download externally created Keras model and data

3. Persist externally created Keras model

3.1: Publish model

3.2: Get model details

3.3 Get all models in the space

4. Export

4.1: Start the export process

4.2: Monitor the export process

4.3: Get the exported content

5. Import

5.1: Start the import process

5.2: Monitor the import process

6. Deploy and score the imported model

6.1: Create model deployment

Create online deployment for published model

6.2: Get deployment details

6.3: Score

7. Clean up

8. Summary and next steps

Authors

Product

Resources

Company

Export/Import assets with ibm-watsonx-ai

Learning goals

Contents

1. Set up the environment

Install dependencies

Define credentials

Create APIClient instance

Create two spaces. One for export and one for import

2. Download externally created Keras model and data

3. Persist externally created Keras model

3.1: Publish model

3.2: Get model details

3.3 Get all models in the space

4. Export

4.1: Start the export process

4.2: Monitor the export process

4.3: Get the exported content

5. Import

5.1: Start the import process

5.2: Monitor the import process

6. Deploy and score the imported model

6.1: Create model deployment

Create online deployment for published model

6.2: Get deployment details

6.3: Score

7. Clean up

8. Summary and next steps

Authors

Export/Import assets with `ibm-watsonx-ai`

Create `APIClient` instance