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
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
The project directory should look like this:
The Guild file defines how Guild runs the
Below is a description of each setting.
||This value appears when listing the operation and in project help. See Get Project Info below.|
||Guild loads the specified Python module when running the operation. By default, Guild uses the operation name. We could omit
||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.|
||Numeric results like loss and accuracy are called scalars. Guild detects scalars written as script output (e.g. using
Refer to Guild File Reference for details about the Guild file format and available configuration options.
Note The values for
output-scalarsused 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:
train Sample training script
guild help to show project information:
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
help. This supports project reuse and reproducibility. Operations are easy to recall, run, and compare.
Run the Operation
guild run train
You are about to run train noise: 0.1 x: 0.1 Continue? (Y/n)
.pyextension) 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.
train, which is equivalent to the operations you’ve run to this point, but is explicitly defined in
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.
In this section, you create a Guild file to explicitly define a
- 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.