From 39055f39a40cd61eaa945f6884afdd1b74b39d33 Mon Sep 17 00:00:00 2001 From: Pierre Chapuis Date: Thu, 1 Feb 2024 18:32:05 +0100 Subject: [PATCH] better home page + menu icons --- docs/assets/logo_light.png | Bin 0 -> 26013 bytes docs/concepts/adapter/index.md | 4 ++ docs/concepts/chain.md | 4 ++ docs/concepts/context.md | 4 ++ docs/getting-started/advanced.md | 13 +++++++ .../recommended.md} | 28 ++++---------- docs/home/why.md | 35 ++++++++++++++++++ docs/index.md | 27 ++++---------- mkdocs.yml | 6 ++- 9 files changed, 79 insertions(+), 42 deletions(-) create mode 100644 docs/assets/logo_light.png create mode 100644 docs/getting-started/advanced.md rename docs/{getting_started.md => getting-started/recommended.md} (65%) create mode 100644 docs/home/why.md diff --git a/docs/assets/logo_light.png b/docs/assets/logo_light.png new file mode 100644 index 0000000000000000000000000000000000000000..2a03602073379e323d247a79ca3e4b08888117b9 GIT binary patch literal 26013 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 E57N+2X8-^I literal 0 HcmV?d00001 diff --git a/docs/concepts/adapter/index.md b/docs/concepts/adapter/index.md index e7f7659..6be3f63 100644 --- a/docs/concepts/adapter/index.md +++ b/docs/concepts/adapter/index.md @@ -1,3 +1,7 @@ +--- +icon: material/tray-plus +--- + # Adapter Adapters are the final and most high-level abstraction in Refiners. They are the concept of adaptation turned into code. diff --git a/docs/concepts/chain.md b/docs/concepts/chain.md index 2a2a354..b52f930 100644 --- a/docs/concepts/chain.md +++ b/docs/concepts/chain.md @@ -1,3 +1,7 @@ +--- +icon: material/family-tree +--- + # Chain diff --git a/docs/concepts/context.md b/docs/concepts/context.md index 0704197..541b852 100644 --- a/docs/concepts/context.md +++ b/docs/concepts/context.md @@ -1,3 +1,7 @@ +--- +icon: material/comment-alert-outline +--- + # Context ## Motivation: avoiding "props drilling" diff --git a/docs/getting-started/advanced.md b/docs/getting-started/advanced.md new file mode 100644 index 0000000..6302252 --- /dev/null +++ b/docs/getting-started/advanced.md @@ -0,0 +1,13 @@ +--- +icon: material/wrench-cog-outline +--- + +# Advanced usage + +## Using other package managers (pip, Poetry...) + +We use Rye to maintain and release Refiners but it conforms to the standard Python packaging guidelines and can be used with other package managers. Please refer to their respective documentation to figure out how to install a package from Git if you intend to use the development branch, as well as how to specify features. + +## Using stable releases from PyPI + +Although we recommend using our development branch, we do [publish more stable releases to PyPI](https://pypi.org/project/refiners/) and you are welcome to use them in your project. However, note that the format of weights can be different from the current state of the development branch, so you will need the conversion scripts from the corresponding tag in GitHub, for instance [here for v0.2.0](https://github.com/finegrain-ai/refiners/tree/v0.2.0). diff --git a/docs/getting_started.md b/docs/getting-started/recommended.md similarity index 65% rename from docs/getting_started.md rename to docs/getting-started/recommended.md index 665f758..ccd84a1 100644 --- a/docs/getting_started.md +++ b/docs/getting-started/recommended.md @@ -1,16 +1,14 @@ -# Getting Started +--- +icon: material/star-outline +--- -Refiners is a micro framework on top of PyTorch with first class citizen APIs for foundation model adaptation. - -Refiners requires Python 3.10 or later, its main dependency is PyTorch. - -## Recommended usage (development branch, with Rye) +# Recommended usage Refiners is still a young project and development is active, so to use the latest and greatest version of the framework we recommend you use the `main` branch from our development repository. Moreover, we recommend using [Rye](https://rye-up.com) which simplifies several things related to Python package management, so start by following the instructions to install it on your system. -### Trying Refiners, converting weights +## Trying Refiners, converting weights To try Refiners, clone the GitHub repository and install it with all optional features: @@ -28,7 +26,7 @@ python "scripts/conversion/convert_diffusers_autoencoder_kl.py" --to "lda.safete If you need to convert weights for all models, check out `script/prepare_test_weights.py` (warning: it requires a GPU with significant VRAM and a lot of disk space). -Now let to check that it works copy your favorite 512x512 picture in the current directory as `input.png` and create `ldatest.py` with this content: +Now to check that it works copy your favorite 512x512 picture in the current directory as `input.png` and create `ldatest.py` with this content: ```py from PIL import Image @@ -53,7 +51,7 @@ python ldatest.py Inspect `output.png`: it should be similar to `input.png` but have a few differences. Latent Autoencoders are good compressors! -### Using refiners in your own project +## Using refiners in your own project So far you used Refiners as a standalone package, but if you want to create your own project using it as a dependency here is how you can proceed: @@ -74,16 +72,6 @@ rye add --dev --git "git@github.com:finegrain-ai/refiners.git" --features conver Note that you will still need to download the conversion scripts independently if you go that route. -### What next? +## What's next? We suggest you check out the [guides](/guides/) section to dive into the usage of Refiners, of the [Key Concepts](/concepts/chain/) section for a better understanding of how the framework works. - -## Advanced usage - -### Using other package managers (pip, Poetry...) - -We use Rye to maintain and release Refiners but it conforms to the standard Python packaging guidelines and can be used with other package managers. Please refer to their respective documentation to figure out how to install a package from Git if you intend to use the development branch, as well as how to specify features. - -### Using stable releases from PyPI - -Although we recommend using our development branch, we do [publish more stable releases to PyPI](https://pypi.org/project/refiners/) and you are welcome to use them in your project. However, note that the format of weights can be different from the current state of the development branch, so you will need the conversion scripts from the corresponding tag in GitHub, for instance [here for v0.2.0](https://github.com/finegrain-ai/refiners/tree/v0.2.0). diff --git a/docs/home/why.md b/docs/home/why.md new file mode 100644 index 0000000..ab9e4b0 --- /dev/null +++ b/docs/home/why.md @@ -0,0 +1,35 @@ +--- +icon: material/lightbulb-on-outline +--- + +# Why Refiners? + +## PyTorch: an imperative framework + +PyTorch is a great framework to implement deep learning models, widely adopted in academia and industry around the globe. A core design principle of PyTorch is that users write *imperative* Python code that manipulates Tensors[^1]. This code can be organized in Modules, which are just Python classes whose constructors typically initialize parameters and load weights, and which implement a `forward` method that computes the forward pass. Dealing with reconstructing an inference graph, backpropagation and so on are left to the framework. + +This approach works very well in general, as demonstrated by the popularity of PyTorch. However, the growing importance of the Adaptation pattern is challenging it. + +## Adaptation: patching foundation models + +Adaptation is the idea of *patching* existing powerful models to implement new capabilities. Those models are called foundation models; they are typically trained from scratch on amounts of data inaccessible to most individuals, small companies or research labs, and exhibit emergent properties. Examples of such models are LLMs (GPT, LLaMa, Mistral), image generation models (Stable Diffusion, Muse), vision models (BLIP-2, LLaVA 1.5, Fuyu-8B) but also models trained on more specific tasks such as embedding extraction (CLIP, DINOv2) or image segmentation (SAM). + +Adaptation of foundation models can take many forms. One of the simplest but most powerful derives from fine-tuning: re-training a subset of the weights of the model on a specific task, then distributing only those weights. Add to this a trick to significantly reduce the size of the fine-tuned weights and you get LoRA[^2], which is probably the most well-known adaptation method. However, adaptation can go beyond that and change the shape of the model or its inputs. + +## Imperative code is hard to patch cleanly + +There are several approaches to patch the code of a foundation model implemented in typical PyTorch imperative style to support adaptation, including: + +- Just duplicate the original code base and edit it in place unconditionally. This approach is often adopted by researchers today. +- Change the original code base to optionally support the adapter. This approach is often used by frameworks and libraries built on top of PyTorch and works well for a single adapter. However, as you start adding support for multiple adapters to the same foundation model the cyclomatic complexity explodes and the code becomes hard to maintain and error-prone. The end result is that adapters typically do not compose well. +- Change the original code to abstract adaptation by adding ad-hoc hooks everywhere. This approach has the advantage of keeping the foundation model independent from its adapter, but it makes the code extremely non-linear and hard to reason about - so-called "spaghetti code". + +As believers in adaptation, none of those approaches was appealing to us, so we designed Refiners as a better option. Refiners is a micro-framework built on top of PyTorch which does away with its imperative style. In Refiners, models are implemented in a *declarative* way instead, which makes them by nature easier to manipulate and patch. + +## What's next? + +Now you know *why* we wrote a declarative framework, you can check out [*how*](/concepts/chain/). It's not that complicated, we promise! + +[^1]: Paszke et al., 2019. PyTorch: An Imperative Style, High-Performance Deep Learning Library. +[^2]: Hu et al., 2022. LoRA: Low-Rank Adaptation of Large Language Models. + diff --git a/docs/index.md b/docs/index.md index 6fa5293..5947df9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,24 +1,11 @@ -# Refiners - Docs +--- +icon: material/water-outline +--- -## Why Refiners? +# ![Refiners](/assets/logo_light.png) -PyTorch is a great framework to implement deep learning models, widely adopted in academia and industry around the globe. A core design principle of PyTorch is that users write *imperative* Python code that manipulates Tensors[^1]. This code can be organized in Modules, which are just Python classes whose constructors typically initialize parameters and load weights, and which implement a `forward` method that computes the forward pass. Dealing with reconstructing an inference graph, backpropagation and so on are left to the framework. +Refiners is the simplest way to train and run [adapters](/concepts/adapter/) on top of foundation models. -This approach works very well in general, as demonstrated by the popularity of PyTorch. However, the growing importance of the Adaptation pattern is challenging it. +It is a microframework built on top of PyTorch with first-class citizen APIs for foundation model adaptation. -Adaptation is the idea of *patching* existing powerful models to implement new capabilities. Those models are called foundation models; they are typically trained from scratch on amounts of data inaccessible to most individuals, small companies or research labs, and exhibit emergent properties. Examples of such models are LLMs (GPT, LLaMa, Mistral), image generation models (Stable Diffusion, Muse), vision models (BLIP-2, LLaVA 1.5, Fuyu-8B) but also models trained on more specific tasks such as embedding extraction (CLIP, DINOv2) or image segmentation (SAM). - -Adaptation of foundational models can take many forms. One of the simplest but most powerful derives from fine-tuning: re-training a subset of the weights of the model on a specific task, then distributing only those weights. Add to this a trick to significantly reduce the size of the fine-tuned weights and you get LoRA[^2], which is probably the most well-known adaptation method. However, adaptation can go beyond that and change the shape of the model or its inputs. - -There are several approaches to patch the code of a foundation model implemented in typical PyTorch imperative style to support adaptation, including: - -- Just duplicate the original code base and edit it in place unconditionally. This approach is often adopted by researchers today. -- Change the original code base to optionally support the adapter. This approach is often used by frameworks and libraries built on top of PyTorch and works well for a single adapter. However, as you start adding support for multiple adapters to the same foundational module the cyclomatic complexity explodes and the code becomes hard to maintain and error-prone. The end result is that adapters typically do not compose well. -- Change the original code to abstract adaptation by adding ad-hoc hooks everywhere. This approach has the advantage of keeping the foundational model independent from its adapter, but it makes the code extremely non-linear and hard to reason about - so-called "spaghetti code". - -As believers in adaptation, none of those approaches was appealing to us, so we designed Refiners as a better option. Refiners is a micro-framework built on top of PyTorch which does away with its imperative style. In Refiners, models are implemented in a *declarative* way instead, which makes them by nature easier to manipulate and patch. - -Now that you know *why* we do that, you can check out [*how*](/concepts/chain/). It's not that hard, we promise! - -[^1]: Paszke et al., 2019. PyTorch: An Imperative Style, High-Performance Deep Learning Library. -[^2]: Hu et al., 2022. LoRA: Low-Rank Adaptation of Large Language Models. +Refiners is Open Source and published under the MIT License. diff --git a/mkdocs.yml b/mkdocs.yml index 3f53e2f..b233c9b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,9 +53,11 @@ extra_css: - stylesheets/extra.css nav: - Home: - - index.md + - Refiners: index.md + - home/why.md - Getting started: - - getting_started.md + - getting-started/recommended.md + - getting-started/advanced.md - Guides: - guides/index.md - Key Concepts: