Last modified 2025-06-16

Start an AI/ML Training Run (Tutorial)

At a Glance

This document explains how to use the HISE SDK and a Python script to launch a remote, resource-configurable training job for an AI/ML model. Now you can use Pixi environments for AI/ML training runs, and your training images take less time to build and deploy,

NOTE

If you want Pixi to manage dependencies for your training run, use a Pixi IDE and don’t set requirements_file_path when calling start_training_run(). Setting requirements_file_path causes the build to use that requirements file instead of the Pixi environment.

These jobs consume significant resources. Before you begin, make sure you have approval from your manager or project lead to use this SDK, and confirm that you have a large enough quota to accommodate the necessary training runs.

Method Signature

hp.start_training_run(
    provider: str = 'ray',
    cpu_count: int = 1,
    gpu_count: int = 0,
    memory_size: int = 10,
    worker_count: int = 0,
    training_job_file_path: str,
    title: str,
    description: str,
    file_set_id: str,
    project: str,
    additional_dirs: list = [],
    additional_files: list = [],
    requirements_file_path: str = None,
    image_id: str = None,
    use_conda: bool = False,
    output_file_size: int = 5,
)

Parameters

Parameter	Data type	Required or optional	Default (if any)	Description
`training_job_file_path`	`string`	required	NA	Path to training job script
`title`	`string`	required	NA	Training job title
`description`	`string`	required	NA	Training job description
`file_set_id`	`string`	required	NA	File set ID used as the training job input
`provider`	`string`	optional	`'ray'`	Compute resource provider or backend for the training run
`cpu_count`	`integer`	optional	1	Number of CPUs allocated to the training job
`gpu_count`	`integer`	optional	0	Number of GPUs allocated to the training job
`memory_size`	`integer`	optional	10	Amount of memory (GB) allocated to the training job
`worker_count`	`integer`	optional	0	Number of worker nodes for distributed training
`project`	`string`	optional	Project selected on IDE creation	Short name of project that the Ray job cost will be billed under
`additional_dirs`	`list`	optional	`[]`	Additional directories your script requires
`additional_files`	`list`	optional	`[]`	Additional files your script requires
`requirements_file_path`	`string`	optional	`None`	Path to the `requirements.in` file (to install additional Python packages) NOTE: This parameter must be set to `NONE` if you want to use a Pixi environment. See the note in the At a Glance section of this document.
`image_id`	`string`	optional	`None`	Image ID (e.g., Docker) for the training job
`use_conda`	`boolean`	optional	`False` (pip)	Indicator of whether to use Conda environment for training
`output_file_size`	`integer`	optional	`5`	Estimated output file size (GB)

Get Help

If you get stuck during a start_training_run() call, refer to the steps of this tutorial. To use the baked-in help in your IDE, try one of the following commands. Still not working? Click Support to file a ticket.

Python	Output
`help(hp.start_training_run)`	Function signature, list of parameters, class, and a brief description of the method in a compact plain-text format
`hp.start_training_run?`	Method signature, docstring (description), file location, and file type in more readable format
`hp.start_training_run??`	Signature, docstring, file path, a verbose set of metadata, and the source code for the method

Instructions

TIPS

Explore the HISE AI/ML dashboard before you start. From the top navigation menu in HISE, choose RESEARCH > AI/ML.
In your Python script, include a main() function that handles every step in order—loading your data, training the model, and saving results.
Test your script end to end by running it locally with test data.

Import libraries

To get started, set up your environment to interact with HISE programmatically and access all available SDK functions. For details, see Use Hise SDK Methods.

1. Navigate to HISE, and use your organizational email address to sign in.

2. Open an IDE. For instructions, see Create Your First HISE IDE (Tutorial).

3. Install the HISE SDK if you haven't already done so.

# Use pip to install the SDK
!pip install hisepy

4. To import hisepy, enter the following code into a new cell in your IDE.

# Import the Python SDK to enable programmatic access to HISE functions
import hisepy as hp

Prepare your script

1. Prepare your script, as in the following example.

# Ray is a unified open-source framework for scaling AI and Python applications. 
The time module provides various time-related functions. 
The random module provides functions for generating pseudo-random numbers and performing random operations.

import ray
import time
import random

def compute_square(x):
time.sleep(random.uniform(0.5, 1.5)) # Simulate some delay
return x * x

def main():
inputs = list(range(10))

# Launch tasks in a list comprehension
results = [compute_square(x) for x in inputs]

# write some random output
with open("/home/workspace/output/empty.txt", "w") as f:
pass
print("Results:", results)

if __name__ == "__main__":

Note on Ray Integration

The code transformation workflow has been updated so that your app.py scripts are automatically adapted for Ray. An AI agent now converts scripts into Ray-compliant code for execution in the Ray cluster, enabling functions like compute_square to run in parallel for improved scaling and faster results. Here's how your script is adapted for Ray:

Transformed app.py for Ray Execution

import ray
import time
import random

# Decorate function so it can run in parallel as a Ray task
@ray.remote
def compute_square(x):
    time.sleep(random.uniform(0.5, 1.5))
    return x * x

def main():
    ray.init()  # Initialize Ray
    
    inputs = list(range(10))
          # Launch distributed Ray tasks
    futures = [compute_square.remote(x) for x in inputs]
    results = ray.get(futures)
    
    with open("/home/workspace/output/empty.txt", "w") as f:
        pass
    print("Results:", results)

if __name__ == "__main__":
    main()

Call start_training_run()

1. In a new cell in your IDE, call hp.start_training_run() with all required and optional parameters.

hp.start_training_run(
  provider='ray',
  cpu_count=1,
  gpu_count=0,
  memory_size=4,
  worker_count=1,
  training_job_file_path="/home/workspace/app.py",
  title="Training Run Example",
  description="Simplified example of an AI/ML training run.",
  file_set_id="60b4e815-85e6-4aaa-84c2-000b48f5fff5",
  additional_dirs=[],
  additional_files=[]
)

A. If the run is successful, you receive a message similar to this one.

Using default project: aifiDevTest
Ray-conformant code written to: /home/workspace/.artifacts/app.py

B. At the prompts, make any necessary changes to the decorators.

i. Answer the prompts. If you're not sure, choose 2) None.

The following methods now have ray decorators: ['compute_square']. Please select the methods from which you want to remove the Ray decorators
 1) compute_square
 2) None

[1 - 2]

The following methods now have ray decorators: ['compute_square']. Please select the methods whose Ray decorator parameters you want to edit
 1) compute_square
 2) None

[1 - 2]

ii. You receive a final success notification like this one.

{
'workflowName': 'hise-ray-workflow',
'executionId': '009bfa68-2748-4a71-9056-9c4969935714',
'status': 'ACTIVE',
'message': 'Execution Created',
'trainingJobId': '00000000-0000-0000-0000-000000000000',
'trainingImageId': '00000000-0000-0000-0000-000000000000',
'providerDashboard': 'https://stage.allenimmunology.org/orchestrate/ray/dashboard/workflow/be7327a2-6644-4bbb-8fc8-d94dba2c63eb',
'executionDetails': 'https://console.cloud.google.com/workflows/workflow/us-west1/hise-ray-workflow/execution/be7327a2-6644-4bbb-8fc8-d94dba2c63eb/summary?inv=1&invt=Abx65A&project=stage-pipeline-internal&supportedpurview=project'
}

C. If you encounter any issues, check the error message, and see the following Troubleshooting tips.

TROUBLESHOOTING

Do not list hisepy in your requirements.in file. It’s a platform SDK and should not be managed as a dependency.
If you're NOT using a Pixi environment, use the correct, full path to your script and requirements files—use /private/your-folder/app.py if running outside that folder, or just app.py if running from within. If you ARE using Pixi, the requirements_file_path must be set to NONE.
Ensure you enter a valid file_set_id (UUID) in the SDK call. Using a placeholder or short string will cause an “Invalid UUID length” error. For details, see Save Your Input File or File Set to a Study (Tutorial).
If you see a "No matching distribution found" or "Could not find a version" error, check your requirements.in for typos or packages that aren’t available on PyPI.
If you get a permissions error, make sure your script and data are located in an allowed, writable directory (such as /private).

Monitor your run

1. To watch your job start, view logs, iterate on your script, and track progress, go to RESEARCH > AI/ML > Training Runs, and click View Details. To see the most recent runs, sort by date. For details, see Review an AI/ML Training Run (Tutorial).

Related Resources

Review an AI/ML Training Run (Tutorial)

Navigate the AI/ML Hub

Submit a Help Ticket