Is this page helpful?

How to Understand Project Specification#

This section provides an overview of the project specification, concerns, and example project specification files so you can understand what it is and how to use it.

Overview of the Project Specification#

A Workbench project is just a Git repository with some metadata files that provided information to drive automation and the overall user experience.

The central file for the metadata is the spec.yaml specification file, i.e. /project/.project/spec.yaml.

You do not need to know anything about the specification file to use Workbench, but you must be very careful if you decide to edit it.

The important things to consider when you’re editing the spec.yaml specification file are:

  • Workbench reads and writes to this spec.yaml file

  • It is a yaml file, and is thus very particular about formatting

  • It has a schema that you must follow

  • It has required fields and optional fields

  • You can edit the file but you cannot delete it

  • If you edit the file and things break, they aren’t broken permanently. You are responsible for fixing the file.

Project Specification Concerns#

The specification has four main concerns broken into sections.

You can see and edit the following sections in the /project/.project/spec.yaml file:

  • meta: Basic metadata about the project like name and description

  • layout: Directory structure and how versioning backends are applied

  • environment: Information about the container image and environment, including configured applications

  • execution: Runtime information for the project container

There are some things that aren’t concerns of the specification:

  • Git history or the git remote being used

  • The individual files in the project, except potentially the compose.yaml file

To view the full description and example usage for each field, see AI Workbench Project Spec Definition.

How to Customize the Project Container#

If you want to change the behavior of the container environment for a single project, you can manually edit the metadata contained in the spec.yaml file. First you modify your spec.yaml file as described below and then you rebuild your project environment.

Note

If you want to use one of the pre-built containers and make simple customizations, such as adding packages, see Walkthrough: Customize Your Environment and AI Workbench Project Containers instead.

If you want to create a fully-custom container that you can use for you own projects, or that you can publish and share with other AI Workbench users, see Use a Custom Container Image instead. This is an advanced scenario.

Use the following list below to determine what changes you want to make to your specification file:

Change Required

Contains the changes that must occur to customize the project container. Without these changes, your project will not build correctly.

Change Recommended

The best-practice changes that you should make to the project container. These are fields that are used by the NVIDIA AI Workbench client software. If these aren’t included, your project might still build, and components might still function; however, your experience working on the project inside the AI Workbench UI might be negatively impacted.

Change Optional

Change these fields only if they are relevant to your project.

To customize your container, navigate to the /project/.project/spec.yaml file of your project, and scroll to the environment section. Use the information in the following table to edit your specification file.

For more information about example project specification files, see Container Specification.