Skip to content

Commit f86b356

Browse files
ToucheSirToucheSir
authored
Merge pull request #1980 from lfenzo/docs/gpu-common-workflows
Added Common GPU Workflows in Docs
2 parents a162245 + f6907be commit f86b356

File tree

2 files changed

+123
-36
lines changed

2 files changed

+123
-36
lines changed

‎docs/make.jl‎

Lines changed: 46 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,50 @@
11
using Documenter, Flux, NNlib, Functors, MLUtils, BSON
22

3+
34
DocMeta.setdocmeta!(Flux, :DocTestSetup, :(using Flux); recursive = true)
4-
makedocs(modules = [Flux, NNlib, Functors, MLUtils, BSON],
5-
doctest = false,
6-
sitename = "Flux",
7-
pages = ["Home" => "index.md",
8-
"Building Models" =>
9-
["Overview" => "models/overview.md",
10-
"Basics" => "models/basics.md",
11-
"Recurrence" => "models/recurrence.md",
12-
"Model Reference" => "models/layers.md",
13-
"Loss Functions" => "models/losses.md",
14-
"Regularisation" => "models/regularisation.md",
15-
"Advanced Model Building" => "models/advanced.md",
16-
"NNlib" => "models/nnlib.md",
17-
"Functors" => "models/functors.md"],
18-
"Handling Data" =>
19-
["One-Hot Encoding" => "data/onehot.md",
20-
"MLUtils" => "data/mlutils.md"],
21-
"Training Models" =>
22-
["Optimisers" => "training/optimisers.md",
23-
"Training" => "training/training.md"],
24-
"GPU Support" => "gpu.md",
25-
"Saving & Loading" => "saving.md",
26-
"The Julia Ecosystem" => "ecosystem.md",
27-
"Utility Functions" => "utilities.md",
28-
"Performance Tips" => "performance.md",
29-
"Datasets" => "datasets.md",
30-
"Community" => "community.md"],
31-
format = Documenter.HTML(
32-
analytics = "UA-36890222-9",
33-
assets = ["assets/flux.css"],
34-
prettyurls = get(ENV, "CI", nothing) == "true"),
35-
)
365

37-
deploydocs(repo = "github.com/FluxML/Flux.jl.git",
38-
target = "build",
39-
push_preview = true)
6+
makedocs(
7+
modules = [Flux, NNlib, Functors, MLUtils, BSON],
8+
doctest = false,
9+
sitename = "Flux",
10+
pages = [
11+
"Home" => "index.md",
12+
"Building Models" => [
13+
"Overview" => "models/overview.md",
14+
"Basics" => "models/basics.md",
15+
"Recurrence" => "models/recurrence.md",
16+
"Model Reference" => "models/layers.md",
17+
"Loss Functions" => "models/losses.md",
18+
"Regularisation" => "models/regularisation.md",
19+
"Advanced Model Building" => "models/advanced.md",
20+
"NNlib" => "models/nnlib.md",
21+
"Functors" => "models/functors.md"
22+
],
23+
"Handling Data" => [
24+
"One-Hot Encoding" => "data/onehot.md",
25+
"MLUtils" => "data/mlutils.md"
26+
],
27+
"Training Models" => [
28+
"Optimisers" => "training/optimisers.md",
29+
"Training" => "training/training.md"
30+
],
31+
"GPU Support" => "gpu.md",
32+
"Saving & Loading" => "saving.md",
33+
"The Julia Ecosystem" => "ecosystem.md",
34+
"Utility Functions" => "utilities.md",
35+
"Performance Tips" => "performance.md",
36+
"Datasets" => "datasets.md",
37+
"Community" => "community.md"
38+
],
39+
format = Documenter.HTML(
40+
analytics = "UA-36890222-9",
41+
assets = ["assets/flux.css"],
42+
prettyurls = get(ENV, "CI", nothing) == "true"
43+
),
44+
)
45+
46+
deploydocs(
47+
repo = "github.com/FluxML/Flux.jl.git",
48+
target = "build",
49+
push_preview = true
50+
)

‎docs/src/gpu.md‎

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# GPU Support
22

3-
NVIDIA GPU support should work out of the box on systems with CUDA and CUDNN installed. For more details see the [CUDA](https://github.com/JuliaGPU/CUDA.jl) readme.
3+
NVIDIA GPU support should work out of the box on systems with CUDA and CUDNN installed. For more details see the [CUDA.jl](https://github.com/JuliaGPU/CUDA.jl) readme.
44

55
## Checking GPU Availability
66

@@ -86,6 +86,82 @@ julia> x |> cpu
8686
0.7766742
8787
```
8888

89+
## Common GPU Workflows
90+
91+
Some of the common workflows involving the use of GPUs are presented below.
92+
93+
### Transferring Training Data
94+
95+
In order to train the model using the GPU both model and the training data have to be transferred to GPU memory. This process can be done with the `gpu` function in two different ways:
96+
97+
1. Iterating over the batches in a [DataLoader](@ref) object transfering each one of the training batches at a time to the GPU.
98+
```julia
99+
train_loader = Flux.DataLoader((xtrain, ytrain), batchsize = 64, shuffle = true)
100+
# ... model, optimizer and loss definitions
101+
for epoch in 1:nepochs
102+
for (xtrain_batch, ytrain_batch) in train_loader
103+
x, y = gpu(xtrain_batch), gpu(ytrain_batch)
104+
gradients = gradient(() -> loss(x, y), parameters)
105+
Flux.Optimise.update!(optimizer, parameters, gradients)
106+
end
107+
end
108+
```
109+
110+
2. Transferring all training data to the GPU at once before creating the [DataLoader](@ref) object. This is usually performed for smaller datasets which are sure to fit in the available GPU memory. Some possitilities are:
111+
```julia
112+
gpu_train_loader = Flux.DataLoader((xtrain |> gpu, ytrain |> gpu), batchsize = 32)
113+
```
114+
```julia
115+
gpu_train_loader = Flux.DataLoader((xtrain, ytrain) |> gpu, batchsize = 32)
116+
```
117+
Note that both `gpu` and `cpu` are smart enough to recurse through tuples and namedtuples. Other possibility is to use [`MLUtils.mapsobs`](https://juliaml.github.io/MLUtils.jl/dev/api/#MLUtils.mapobs) to push the data movement invocation into the background thread:
118+
```julia
119+
using MLUtils: mapobs
120+
# ...
121+
gpu_train_loader = Flux.DataLoader(mapobs(gpu, (xtrain, ytrain)), batchsize = 16)
122+
```
123+
124+
3. Wrapping the `DataLoader` in [`CUDA.CuIterator`](https://cuda.juliagpu.org/stable/usage/memory/#Batching-iterator) to efficiently move data to GPU on demand:
125+
```julia
126+
using CUDA: CuIterator
127+
train_loader = Flux.DataLoader((xtrain, ytrain), batchsize = 64, shuffle = true)
128+
# ... model, optimizer and loss definitions
129+
for epoch in 1:nepochs
130+
for (xtrain_batch, ytrain_batch) in CuIterator(train_loader)
131+
# ...
132+
end
133+
end
134+
```
135+
136+
Note that this works with a limited number of data types. If `iterate(train_loader)` returns anything other than arrays, approach 1 or 2 is preferred.
137+
138+
### Saving GPU-Trained Models
139+
140+
After the training process is done, one must always transfer the trained model back to the `cpu` memory scope before serializing or saving to disk. This can be done, as described in the previous section, with:
141+
```julia
142+
model = cpu(model) # or model = model |> cpu
143+
```
144+
and then
145+
```julia
146+
using BSON
147+
# ...
148+
BSON.@save "./path/to/trained_model.bson" model
149+
150+
# in this approach the cpu-transferred model (referenced by the variable `model`)
151+
# only exists inside the `let` statement
152+
let model = cpu(model)
153+
# ...
154+
BSON.@save "./path/to/trained_model.bson" model
155+
end
156+
157+
# is equivalente to the above, but uses `key=value` storing directve from BSON.jl
158+
BSON.@save "./path/to/trained_model.bson" model = cpu(model)
159+
```
160+
The reason behind this is that models trained in the GPU but not transferred to the CPU memory scope will expect `CuArray`s as input. In other words, Flux models expect input data coming from the same kind device in which they were trained on.
161+
162+
In controlled scenarios in which the data fed to the loaded models is garanteed to be in the GPU there's no need to transfer them back to CPU memory scope, however in production environments, where artifacts are shared among different processes, equipments or configurations, there is no garantee that the CUDA.jl package will be available for the process performing inference on the model loaded from the disk.
163+
164+
89165
## Disabling CUDA or choosing which GPUs are visible to Flux
90166

91167
Sometimes it is required to control which GPUs are visible to `julia` on a system with multiple GPUs or disable GPUs entirely. This can be achieved with an environment variable `CUDA_VISIBLE_DEVICES`.

0 commit comments

Comments
 (0)