Skip to content

Doc updates to switch branding to Keras 3 #1259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 5, 2023
Merged

Doc updates to switch branding to Keras 3 #1259

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 59 additions & 52 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,25 @@
# KerasNLP: Modular NLP Workflows for Keras
[![](https://github.com/keras-team/keras-nlp/workflows/Tests/badge.svg?branch=master)](https://github.com/keras-team/keras-nlp/actions?query=workflow%3ATests+branch%3Amaster)
![Python](https://img.shields.io/badge/python-v3.8.0+-success.svg)
![Tensorflow](https://img.shields.io/badge/tensorflow-v2.5.0+-success.svg)
![Python](https://img.shields.io/badge/python-v3.9.0+-success.svg)
[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/keras-team/keras-nlp/issues)

KerasNLP is a natural language processing library that works natively
with TensorFlow, JAX, or PyTorch. Built on [Keras Core](https://keras.io/keras_core/announcement/),
these models, layers, metrics, callbacks, etc., can be trained and serialized
in any framework and re-used in another without costly migrations. See "Using
KerasNLP with Keras Core" below for more details on multi-framework KerasNLP.

KerasNLP supports users through their entire development cycle. Our workflows
are built from modular components that have state-of-the-art preset weights and
architectures when used out-of-the-box and are easily customizable when more
control is needed.

This library is an extension of the core Keras API; all high-level modules are
[`Layers`](https://keras.io/api/layers/) or
[`Models`](https://keras.io/api/models/) that receive that same level of polish
as core Keras. If you are familiar with Keras, congratulations! You already
understand most of KerasNLP.
KerasNLP is a natural language processing library that works natively
Copy link
Member Author

@mattdangerw mattdangerw Sep 27, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed trailing spaces, but I think that is making this diff look a lot bigger than it is.

Copy link
Contributor

@jbischof jbischof Sep 28, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, there's something crazy going on with the diff here. Even identical paragraphs are marked as deleted.

with TensorFlow, JAX, or PyTorch. Built on [multi-backend Keras](https://keras.io/keras_core/announcement/)
(Keras 3), these models, layers, metrics, and tokenizers can be trained and
serialized in any framework and re-used in another without costly migrations.

KerasNLP supports users through their entire development cycle. Our workflows
are built from modular components that have state-of-the-art preset weights when
used out-of-the-box and are easily customizable when more control is needed.

See our [Getting Started guide](https://keras.io/guides/keras_nlp/getting_started)
for example usage of our modular API starting with evaluating pretrained models
and building up to designing a novel transformer architecture and training a
tokenizer from scratch.
This library is an extension of the core Keras API; all high-level modules are
[`Layers`](https://keras.io/api/layers/) or
[`Models`](https://keras.io/api/models/) that receive that same level of polish
as core Keras. If you are familiar with Keras, congratulations! You already
understand most of KerasNLP.

We are a new and growing project and welcome [contributions](CONTRIBUTING.md).
See our [Getting Started guide](https://keras.io/guides/keras_nlp/getting_started)
to start learning our API. We welcome [contributions](CONTRIBUTING.md).

## Quick Links

Expand Down Expand Up @@ -59,41 +52,16 @@ pip to install directly from the master branch on github:
```
pip install git+https://github.com/keras-team/keras-nlp.git --upgrade
```
## Using KerasNLP with Keras Core

As of version `0.6.0`, KerasNLP supports multiple backends with Keras Core out
of the box. There are two ways to configure KerasNLP to run with multi-backend
support:

1. Via the `KERAS_BACKEND` environment variable. If set, then KerasNLP will be
using Keras Core with the backend specified (e.g., `KERAS_BACKEND=jax`).
2. Via the `.keras/keras.json` and `.keras/keras_nlp.json` config files (which
are automatically created the first time you import KerasNLP):
- Set your backend of choice in `.keras/keras.json`; e.g., `"backend": "jax"`.
Copy link
Member Author

@mattdangerw mattdangerw Sep 27, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've dropped any mention of .keras json files for now. There is too much to focus on!

Let's only document KERAS_BACKEND environment variable for now, and try to make that less confusing. After Keras 3 is out, we can go back to documenting persistent settings.

- Set `"multi_backend": True` in `.keras/keras_nlp.json`.

Once that configuration step is done, you can just import KerasNLP and start
using it on top of your backend of choice:

```python
import keras_nlp

gpt2_lm = keras_nlp.models.GPT2CausalLM.from_preset("gpt2_base_en")
gpt2_lm.generate("My trip to Yosemite was", max_length=200)
```

Until Keras Core is officially released as Keras 3.0, KerasNLP will use
`tf.keras` as the default backend. To restore this default behavior, simply
`unset KERAS_BACKEND` and ensure that `"multi_backend": False` or is unset in
`.keras/keras_nlp.json`. You will need to restart the Python runtime for changes
to take effect.

## Quickstart

Fine-tune BERT on a small sentiment analysis task using the
Fine-tune BERT on a small sentiment analysis task using the
[`keras_nlp.models`](https://keras.io/api/keras_nlp/models/) API:

```python
import os
os.environ["KERAS_BACKEND"] = "jax" # Or "tensorflow", or "torch".
Copy link
Member Author

@mattdangerw mattdangerw Sep 27, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All our guides and examples show setting KERAS_BACKEND, it seems consistent to do so here as well.


import keras_nlp
import tensorflow_datasets as tfds

Expand All @@ -107,6 +75,7 @@ imdb_train, imdb_test = tfds.load(
classifier = keras_nlp.models.BertClassifier.from_preset(
"bert_base_en_uncased",
num_classes=2,
activation="softmax",
)
# Fine-tune on IMDb movie reviews.
classifier.fit(imdb_train, validation_data=imdb_test)
Expand All @@ -116,6 +85,44 @@ classifier.predict(["What an amazing movie!", "A total waste of my time."])

For more in depth guides and examples, visit https://keras.io/keras_nlp/.

## Configuring your backend

**Keras 3** is an upcoming release of the Keras library which supports
TensorFlow, Jax or Torch as backends. This is supported today in KerasNLP,
but will not be enabled by default until the official release of Keras 3. If you
`pip install keras-nlp` and run a script or notebook without changes, you will
be using TensorFlow and **Keras 2**.

If you would like to enable a preview of the Keras 3 behavior, you can do
so by setting the `KERAS_BACKEND` environment variable. For example:

```shell
export KERAS_BACKEND=jax
```

Or in Colab, with:

```python
import os
os.environ["KERAS_BACKEND"] = "jax"

import keras_nlp
```

> [!IMPORTANT]
> Make sure to set the `KERAS_BACKEND` before import any Keras libraries, it
> will be used to set up Keras when it is first imported.

Until the Keras 3 release, KerasNLP will use a preview of Keras 3 on PyPI named
[keras-core](https://pypi.org/project/keras-core/).

> [!IMPORTANT]
> If you set `KERAS_BACKEND` variable, you should `import keras_core as keras`
> instead of `import keras`. This is a temporary step until Keras 3 is out!

To restore the default **Keras 2** behavior, `unset KERAS_BACKEND` before
importing Keras and KerasNLP.

## Compatibility

We follow [Semantic Versioning](https://semver.org/), and plan to
Expand Down