In the previous section you use a Guild file to define a
train operation. In this section, you enhance the project by adding a real-world classifier.
Download Classifier Script
plot_iris_exercise.py and save it to the
The script, which is adapted from scikit-learn SVM Exercise, trains a model on the Iris benchmark data set.
guild-start directory should look like this:
iris-svm Model to guild.yml
guild-start directory, modify
guild.yml by adding the
iris-svn model below.
The final modified
guild.yml should be:
- model: sample description: A sample model operations: train: description: Sample training script main: train flags-import: all output-scalars: '(\key): (\value)' - model: iris-svm description: Iris classifier using a support vector machine (SVM) operations: train: description: Train SVM model on Iris data set main: plot_iris_exercise flags: kernel: description: SVM kernel type default: rbf choices: [linear, poly, rbf] test_split: description: Percentage of examples held out for test default: 0.2 random_seed: description: Seed used for shuffling data default: 0 degree: description: Degree of the poly kernel function default: 3 gamma: description: Kernel coefficient for rbf and poly default: 10 output-scalars: train_accuracy: 'Train accuracy: (\value)' test_accuracy: 'Test accuracy: (\value)'
guild.yml after adding
The file defines two models:
sample model provides the
train operation from the previous step. The
iris-svm is a new model, which you add in this section.
Highlight Use models to group related sets of operations. Models generally correspond to the structures that you train and test with data, though you’re free to define models for other purposes. For more information, see Models.
The Guild file format changes from a mapping of operations, known as operation only format, to a list of top-level objects, known as full format. Guild supports these two formats to accommodate different requirements. Use operation only format when starting to keep your Guild file as simple as possible. Migrate to full format as needed to support more configuration.
Below is a description of the
||A description of the operation.|
||The Python module that implements the operation.|
||A mapping of flag name to flag definition. Each flag provides a description, which is used in help text, and a default value. The
||Patterns used to capture output scalars. In this case, the capture patterns are different from those of
Highlight Rather than require changes to
plot_iris_exercise.pyto support Guild-specific output patterns, you change
guild.yml. This keeps your project source code independent of external tooling.
Verify that the operations are available:
iris-svm:train Train SVM model on Iris data set sample:train Generate a sample loss
If you don’t see
iris-svm:fit in the list, verify that
guild.yml is the same as above and that you’re running the command from the
Show the project models:
iris-svm Iris classifier using a support vector machine (SVM) sample A sample model
Show help for the project:
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'. MODELS iris-svm Iris classifier using a support vector machine (SVM) Operations: train Train SVM model on Iris data set Flags: degree Degree of the poly kernel function (default is 3) gamma Kernel coefficient for rbf and poly (default is 10) kernel SVM kernel type (default is rbf) Choices: linear, poly, rbf random_seed Seed used for shuffling data (default is 0) test_split Percentage of examples held out for test (default is 0.2) sample A sample model Operations: train Sample training script Flags: noise (default is 0.1) x (default is 0.1)
Highlight Use a Guild file to document your project capabilities to help others use it effectively.
Create a Guild Environment
In this section, you create a project-specific environment to keep project libraries and runs separate from other projects. For more information, see Environments.
requirements.txt to install required packages when creating an environment.
guild-start project directory, create a file named
requirements.txt that specifies the Python packages required by the project. For this project, the file should be:
requirements.txt — specifies Python packages required by the project
Your project directory should look like this:
Initialize the Environment
requirements.txt to the project, initialize a new environment in the project using
Guild prompts with the environment settings. Press Enter to create the environment.
Guild initializes a virtual environment in the project under a
Your project directory should look like this:
Activate the Environment
To use an environment, you activate it within each terminal session that uses it.
If you’re running Linux, macOS, or POSIX compliant shell, activate the environment by running:
If you’re running Windows, activate the environment by running:
Note You can always use the traditional method of activating a virtual environment created with
guild init. Guild environments are standard Python virtual environments.
When you activate an environment, Guild uses the environment Python runtime and installed libraries. Guild also stores runs within the environment.
guild check to confirm that Guild uses the activated environment:
Note the location of
guild_home — it should be located under the project directory in
List the current runs:
The list is empty because you haven’t generated any runs in current environment.
Train the Classifier
In the activated environment, run the
guild run iris-svm:train
You are about to run iris-svm:train degree: 3 gamma: 10 kernel: rbf random_seed: 0 test_split: 0.2 Continue? (Y/n)
Press Enter to start the operation.
Guild runs the operation, which is implemented by the
Guild uses the default flag values defined for the operation in
guild.yml, which you define above.
List files generated by the run:
In addition to fitting a model and printing accuracy results, the operation generates a plot showing classification results of the Iris test data set.
Open the plot using the default application for your system:
guild open -p plot.png
Guild opens the plot generate by
iris-svm:train, which shows how test samples are classified.
plot.png on Linux using Xviewer
Use an alternative program to open a file by specifying the
--cmd option. For example, to open
plot.png in GIMP, use:
guild open -p plot.png --cmd gimp
Specify the program used to open a file with
--cmd (this example requires that GIMP be installed)
Highlight Guild integrates with your favorite tools, rather than attempt to replace them.
Experiment with Different Kernels
mnist-svm:train again using each the other SVM kernels:
guild run iris-svm:train kernel='[linear,poly]'
You are about to run iris-svm:train as a batch (2 trials) degree: 3 gamma: 10 kernel: [linear, poly] random_seed: 0 test_split: 0.2 Continue? (Y/n)
Press Enter to confirm.
iris-svm:train twice — once for each specified kernel.
guild compare to compare results:
Use the right arrow key to move the cursor to view values for
test_accuracy. Note that the
linear kernel performs better the other two, at least with the default hyperparameters.
Press q to exit Guild Compare.
Compare run plots using TensorBoard:
guild tensorboard --tab images
Guild starts TensorBoard and opens the Images tab. TensorBoard shows each plot generated by the three runs. To improve image quality, select Show actual image size in the upper-left of the display.
Compare run-generated images using TensorBoard
Highlight Guild automatically shows run-generated images in TensorBoard so you don’t need to log them as summaries. This is a useful way to compare run plots and other images side-by-side.
Return to the command terminal and press Ctrl-C to stop TensorBoard.
In this section you add
iris-svm to your project. The model defines a
train operation, which runs the Python module
plot_iris_exercise to fit a support vector machine to the Iris data set.
Congratulations — you completed this introduction to Guild AI!
Highlights In this introduction, you cover fundamental concepts and practices:
Now that you’re familiar with Guild, try using it for your own work.