mirror of https://github.com/tracel-ai/burn.git
1. fix broken link in getting-started.md
2. Make guide documentation and file structure consistent with examples/guide. 3. Add helpful comments in guide.
This commit is contained in:
parent
b9bd42959b
commit
a5ae89ebee
|
@ -4,7 +4,12 @@ This guide will walk you through the process of creating a custom model built wi
|
|||
train a simple convolutional neural network model on the MNIST dataset and prepare it for inference.
|
||||
|
||||
For clarity, we sometimes omit imports in our code snippets. For more details, please refer to the
|
||||
corresponding code in the `examples/guide` directory.
|
||||
corresponding code in the `examples/guide` [directory](https://github.com/tracel-ai/burn/tree/main/examples/guide)
|
||||
where this complete example is reproduced step-by-step from dataset & model definition to training.
|
||||
The demo example can be executed from burn's base directory using the command:
|
||||
```bash
|
||||
cargo run --example guide
|
||||
```
|
||||
|
||||
## Key Learnings
|
||||
|
||||
|
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
We have effectively written most of the necessary code to train our model. However, we have not
|
||||
explicitly designated the backend to be used at any point. This will be defined in the main
|
||||
entrypoint of our program, namely the `main` function below.
|
||||
entrypoint of our program, namely the `main` function defined in `src/main.rs`.
|
||||
|
||||
```rust , ignore
|
||||
use burn::optim::AdamConfig;
|
||||
|
@ -28,7 +28,8 @@ fn main() {
|
|||
You might be wondering why we use the `guide` prefix to bring the different modules we just
|
||||
implemented into scope. Instead of including the code in the current guide in a single file, we
|
||||
separated it into different files which group related code into _modules_. The `guide` is simply the
|
||||
name we gave to our _crate_, which contains the different files. Below is a brief explanation of the
|
||||
name we gave to our _crate_, which contains the different files. If you named your project crate as `my-first-burn-model`, you
|
||||
can equivalently replace all usages of `guide` above with `my-first-burn-model`. Below is a brief explanation of the
|
||||
different parts of the Rust module system.
|
||||
|
||||
A **package** is a bundle of one or more crates that provides a set of functionality. A package
|
||||
|
@ -38,13 +39,22 @@ A **crate** is a compilation unit in Rust. It could be a single file, but it is
|
|||
split up crates into multiple _modules_ and possibly multiple files. A crate can come in one of two
|
||||
forms: a binary crate or a library crate. When compiling a crate, the compiler first looks in the
|
||||
crate root file (usually `src/lib.rs` for a library crate or `src/main.rs` for a binary crate). Any
|
||||
module declared in the crate root file will be inserted in the crate for compilation.
|
||||
module declared in the crate root file will be inserted in the crate for compilation. For this demo example, we will
|
||||
define a library crate where all the individual modules(model, data, training etc.) are listed inside `src/lib.rs` as following:
|
||||
|
||||
```
|
||||
pub mod data;
|
||||
pub mod inference;
|
||||
pub mod model;
|
||||
pub mod training;
|
||||
```
|
||||
|
||||
A **module** lets us organize code within a crate for readability and easy reuse. Modules also allow
|
||||
us to control the _privacy_ of items.
|
||||
us to control the _privacy_ of items. The pub keyword used above for example, is used to make a module publicly available
|
||||
inside the crate.
|
||||
|
||||
For this guide, we defined a library crate with a single example where the `main` function is
|
||||
defined, as illustrated in the structure below.
|
||||
In our examples, demonstrating the code within this guide, we defined a library crate with a single example where the `main` function is
|
||||
defined inside the `guide.rs` file, as illustrated in the structure below.
|
||||
|
||||
```
|
||||
guide
|
||||
|
@ -60,7 +70,8 @@ guide
|
|||
```
|
||||
|
||||
The source for this guide can be found in our
|
||||
[GitHub repository](https://github.com/tracel-ai/burn/tree/main/examples/guide).\
|
||||
[GitHub repository](https://github.com/tracel-ai/burn/tree/main/examples/guide) which can be used to run this basic
|
||||
work flow example end-to-end.\
|
||||
|
||||
</details><br>
|
||||
|
||||
|
|
|
@ -9,6 +9,9 @@ To iterate over a dataset efficiently, we will define a struct which will implem
|
|||
trait. The goal of a batcher is to map individual dataset items into a batched tensor that can be
|
||||
used as input to our previously defined model.
|
||||
|
||||
Let us start by defining our dataset functionalities in a file `src/data.rs`. We shall omit some of the imports for brevity,
|
||||
but the full code for following this guide can be found at `examples/guide/` [directory](https://github.com/tracel-ai/burn/tree/main/examples/guide).
|
||||
|
||||
```rust , ignore
|
||||
use burn::{
|
||||
data::{dataloader::batcher::Batcher, dataset::vision::MNISTItem},
|
||||
|
|
|
@ -6,7 +6,7 @@ For loading a model primed for inference, it is of course more efficient to dire
|
|||
weights into the model, bypassing the need to initially set arbitrary weights or worse, weights
|
||||
computed from a Xavier normal initialization only to then promptly replace them with the stored
|
||||
weights. With that in mind, let's create a new initialization function receiving the record as
|
||||
input.
|
||||
input. This new function can be defined alongside the `init` function for the `ModelConfig` struct in `src/model.rs`.
|
||||
|
||||
```rust , ignore
|
||||
impl ModelConfig {
|
||||
|
@ -30,7 +30,7 @@ It is important to note that the `ModelRecord` was automatically generated thank
|
|||
trait. It allows us to load the module state without having to deal with fetching the correct type
|
||||
manually. Everything is validated when loading the model with the record.
|
||||
|
||||
Now let's create a simple `infer` method in which we will load our trained model.
|
||||
Now let's create a simple `infer` method in a new file `src/inference.rs` which we will use to load our trained model.
|
||||
|
||||
```rust , ignore
|
||||
pub fn infer<B: Backend>(artifact_dir: &str, device: B::Device, item: MNISTItem) {
|
||||
|
|
|
@ -26,7 +26,7 @@ Our goal will be to create a basic convolutional neural network used for image c
|
|||
will keep the model simple by using two convolution layers followed by two linear layers, some
|
||||
pooling and ReLU activations. We will also use dropout to improve training performance.
|
||||
|
||||
Let us start by creating a model in a file `model.rs`.
|
||||
Let us start by defining our model struct in a new file `src/model.rs`.
|
||||
|
||||
```rust , ignore
|
||||
use burn::{
|
||||
|
@ -281,9 +281,9 @@ network modules already built with Burn use the `forward` nomenclature, simply b
|
|||
standard in the field.
|
||||
|
||||
Similar to neural network modules, the [`Tensor`](../building-blocks/tensor.md) struct given as a
|
||||
parameter also takes the Backend trait as a generic argument, alongside its rank. Even if it is not
|
||||
parameter also takes the Backend trait as a generic argument, alongside its rank(or dimensionality). Even if it is not
|
||||
used in this specific example, it is possible to add the kind of the tensor as a third generic
|
||||
argument.
|
||||
argument. For example, a 3-dimensional Tensor of different data types(float, int, bool) would eb defined as following:
|
||||
|
||||
```rust , ignore
|
||||
Tensor<B, 3> // Float tensor (default)
|
||||
|
|
|
@ -1,7 +1,9 @@
|
|||
# Training
|
||||
|
||||
We are now ready to write the necessary code to train our model on the MNIST dataset. Instead of a
|
||||
simple tensor, the model should output an item that can be understood by the learner, a struct whose
|
||||
We are now ready to write the necessary code to train our model on the MNIST dataset.
|
||||
We shall define the code for this training section in the file: `src/training.rs`.
|
||||
|
||||
Instead of a simple tensor, the model should output an item that can be understood by the learner, a struct whose
|
||||
responsibility is to apply an optimizer to the model. The output struct is used for all metrics
|
||||
calculated during the training. Therefore it should include all the necessary information to
|
||||
calculate any metric that you want for a task.
|
||||
|
|
|
@ -165,7 +165,7 @@ Tensor {
|
|||
```
|
||||
|
||||
While the previous example is somewhat trivial, the upcoming
|
||||
[basic workflow section](./basic-workflow/) will walk you through a much more relevant example for
|
||||
[basic workflow section](./basic-workflow/README.md) will walk you through a much more relevant example for
|
||||
deep learning applications.
|
||||
|
||||
## Running examples
|
||||
|
|
Loading…
Reference in New Issue