Get Started: Create a Guild File

Documentation Get Started
1

Overview

Up to this point, you run train.py directly without providing additional information about the script.

When Guild runs an operation, it determines the following:

  • How the script reads user-provided values, or flags
  • How the script communicates numeric results, or scalars, such as training loss and accuracy

Unless configured otherwise, Guild uses default rules to determine this information.

You can configure this information explicitly using a Guild file. A Guild file is a human-readable text file named guild.yml located in a project directory.

Create a Guild File

In the guild-start project directory, create a file named guild.yml that contains this YAML code:

train:
  description: Sample training script
  main: train
  flags-import: all
  output-scalars: '(\key): (\value)'

Project Guild file train.yml

The project directory should look like this:

guild-start
archived-runs
guild.yml
train.py

The Guild file defines how Guild runs the train operation.

Below is a description of each setting.
description This value appears when listing the operation and in project help. See Get Project Info below.
main Guild loads the specified Python module when running the operation. By default, Guild uses the operation name. We could omit main in this case but include it here to illustrate its use. For more information, see Python Based Operations.
flags-import When a Guild file is used, Guild does not automatically import flags from the main module. You must explicitly import flags or define them for the operation. In this case, we tell Guild to import all detected flags from the main module.
output-scalars Numeric results like loss and accuracy are called scalars. Guild detects scalars written as script output (e.g. using print or log functions in Python) and those that are logged explicitly. By default, Guild captures scalars written to output in the format KEY: VALUE. We could omit output-scalars in this case but include it here for illustration. For more information, see Output Scalars.

Refer to Guild File Reference for details about the Guild file format and available configuration options.

Note The values for flags-import and output-scalars used in the Guild file above are equivalent to the defaults used by Guild. They can be omitted without changing the behavior of the operation. We define them here for illustration purposes.

Get Project Info

Save your changes to guild.yml above. Use guild operations to show operations defined for the project:

guild operations

train  Sample training script

Use guild help to show project information:

guild help
Output 
OVERVIEW

    You are viewing help for operations defined in the current directory.

    To run an operation use 'guild run OPERATION' where OPERATION is one
    of options listed below. If an operation is associated with a model,
    include the model name as MODEL:OPERATION.

    To list available operations, run 'guild operations'.

    Set operation flags using 'FLAG=VALUE' arguments to the run command.
    Refer to the operations below for a list of supported flags.

    For more information on running operations, try 'guild run --help'.
    For general information, try 'guild --help'.

BASE OPERATIONS

    train
      Sample training script

      Flags:
        noise  (default is 0.1)
        x      (default is 0.1)

Press q to exit help.

Highlight In addition to configuring operations, Guild files define the user interface for a project. The interface is discovered with Guild commands like operations and help. This supports project reuse and reproducibility. Operations are easy to recall, run, and compare.

Run the Operation

Run the train operation:

guild run train

You are about to run train
  noise: 0.1
  x: 0.1
Continue? (Y/n)

Important Use train rather than train.py here. train (without the .py extension) is the operation defined in the Guild file. train.py (with the extension) refers to the Python script directly. Guild supports both methods: running operations defined in Guild files and running scripts directly.

Press Enter to start the operation.

Guild runs train, which is equivalent to the operations you’ve run to this point, but is explicitly defined in guild.yml.

Tip While it’s convenient to run scripts directly in Guild, we recommend that you use a Guild file to explicitly define operations for your day-to-day workflow. Guild file operations are configured explicitly and discoverable as show above. They support a wide range of features that are not available when running scripts directly. For more information, see Guild File Reference.

Summary

In this section, you create a Guild file to explicitly define a train operation.

Highlights

  • Guild files let you control and customize Guild support without modifying your code. This ensures that your code and your tools remain independent.
  • Guild files let you and your colleagues more effectively use a project because operations are well-defined and discoverable.

In the next section, you create a real-world classifier and use Guild to track and compare results.

Next: Add a Classifier