Planter is a modular framework for realizing one-click in-network machine learning algorithms. All you need to provide to Planter are a configuration file (Name_data.py) and a dataset. Planter will take it from there and offload your machine learning classification task into a programmable data plane. This is the artifact for the paper "Planter: Rapid Prototyping of In-Network Machine Learning Inference" in SIGCOMM CCR [video] (with early arXiv version named "Automating In-Network Machine Learning".)
💡 Please check Planter's user manual PDF (strongly recommended).
Planter requires python3+, with the packages listed in requirements_pip3.txt. To install the aforementioned packages, start your working environment and execute the following command:
pip3 install -r ./src/configs/requirements_pip3.txt
Some packages need to be installed using sudo python3:
sudo pip3 install -r ./src/configs/requirements_sudo_pip3.txt
- Common Issues in Environment Setup wiki.
First, prepare a working environment as described in the previous section Link.
Run the following command to start Planter in manual configuration mode.
python3 Planter.py -m
Use help (-h) to see additional command options, e.g., -t, and -d.
💡 A detailed getting started tutorial Link (strongly recommended).
- Planter Supported Algorithms wiki
- Planter Supported Architectures wiki
- Planter Supported Targets wiki
- Planter Supported Use Cases wiki
- Planter Supported Datasets wiki
Model training, model conversion (table generation), and (python based) checking of generated table entries, are all done by a table_generator.py file. The file is located under the src/models folder, within each model_name/type_n folder. For example, /src/models/RF/Type_EB. All the table entries, registers, and constants needed in the pipeline are generated by this file, which is unique per machine learning model mapping.
Planter supports multiple target architectures architectures. Architectures are located under src/architectures/. In each architecture's folder, there is a file called p4_generator.py that manages and calls all the files required to generate code MODEL.usecase_datasetp4 for a switch model.
Specifically, two essential files are called. The first one is common_p4.py (located under the use-case folder src/use_cases/<use_case_name>.
This file includes the common P4 code (What is P4?) that is used by this use case.
The second file is dedicate_p4.py under the model folder ./src/models/<model_name>/<type_n>.
The essential p4 code required by the chosen model is stored in this file.
A generated p4 file will be compiled and loaded to the target using dedicated targets scripts under /src/targets/<target_name>. The compiler will further load the generated M/A table entries (or registers) to the target device. The model tester (test_model.py under the same folder) will send packets to the target to verify its functionality.
A detailed tutorial wiki, provides an example step-by-step guide of running a sample RF model on BMv2.
Generally, each test will have three classification performance matrix outputs. Each matrix has a similar structure, as shown below:
precision recall f1-score support
0 1.0000 1.0000 1.0000 13
1 0.9500 0.9500 0.9500 20
2 0.9167 0.9167 0.9167 12
accuracy 0.9556 45
macro avg 0.9556 0.9556 0.9556 45
weighted avg 0.9556 0.9556 0.9556 45
- The first matrix: The classification performance of the scikit-learn model in Python (i.e., on a host).
- The second matrix: The classification performance of the pipeline logic by using the generated table entries in Python (i.e., theoretical).
- The third matrix: The classification result of the generated P4 on either software/hardware programmable network devices or its emulation environment (i.e., actual).
A more detailed matrix is shown in the sample tutorial wiki
To test Planter in performance mode, configure the model by using the following table. The table shows what mapping (EB, LB, or DM) can be used in each type of model when choosing the use case performance. As manual optimization is applied, the mappings supported by performance mode consume fewer stages but only match the performance use case.
| Use case | DT | RF | XGB | IF | SVM | NB | KM | KNN | PCA | AE | NN |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Mapping | EB & DM | EB & DM | EB & DM | EB | LB | LB | LB & EB | EB | LB | LB | DM |
To test Planter's mapped models' throughput on a P4Pi-enabled BMv2, follow the throughput test wiki.
- Adding your own model wiki
- Adding your own architecture wiki
- Adding your own target wiki
- Adding your own use case wiki
- Adding your own dataset wiki
Please submit an issue with the appropriate label on Github.
The files are licensed under Apache License: LICENSE. The text of the license can also be found in the LICENSE file.
Please access the Planter project's history and recent applications through the link. If your work uses Planter, please kindly email us if possible. We will include your latest publication or project in the application list.
If you use this code, please cite our paper:
@article{zheng2024automating,
title={{Planter: Rapid Prototyping of In-Network Machine Learning Inference}},
author={Zheng, Changgang and Zang, Mingyuan and Hong, Xinpeng and Perreault, Liam and Bensoussane, Riyad and Vargaftik, Shay and Ben-Itzhak, Yaniv and Zilberman, Noa},
journal={ACM SIGCOMM Computer Communication Review},
year={2024}
}
The following people contributed to this project: Changgang Zheng, Mingyuan Zang, Xinpeng Hong, Liam Perreault, Riyad Bensoussane, Shay Vargaftik, Yaniv Ben-Itzhak, and Noa Zilberman. In addition, Peng Qian contributed to this repository. This work was partly funded by VMware and the EU Horizon SMARTEDGE (101092908, UKRI 10056403). We acknowledge support from Intel and NVIDIA.