From 68fdde75ccf0aec522c68b3325b59e129cdf359a Mon Sep 17 00:00:00 2001 From: Matt Watson Date: Mon, 25 Nov 2024 10:17:28 -0800 Subject: [PATCH] Improve KerasHub doc content --- scripts/hub_master.py | 44 ++++++++------ scripts/render_presets.py | 4 +- scripts/tuner_master.py | 2 +- templates/keras_hub/api/base_classes/index.md | 12 ++++ templates/keras_hub/api/index.md | 5 +- templates/keras_hub/api/metrics/index.md | 3 +- .../keras_hub/api/modeling_layers/index.md | 7 +++ templates/keras_hub/api/models/index.md | 14 ++--- .../api/preprocessing_layers/index.md | 7 +++ templates/keras_hub/api/samplers/index.md | 7 +++ templates/keras_hub/index.md | 59 +++++++++---------- templates/keras_hub/presets/index.md | 2 + templates/keras_tuner/index.md | 7 ++- 13 files changed, 106 insertions(+), 67 deletions(-) create mode 100644 templates/keras_hub/api/base_classes/index.md create mode 100644 templates/keras_hub/api/modeling_layers/index.md create mode 100644 templates/keras_hub/api/preprocessing_layers/index.md create mode 100644 templates/keras_hub/api/samplers/index.md diff --git a/scripts/hub_master.py b/scripts/hub_master.py index 8e33407148..49f854fb2d 100644 --- a/scripts/hub_master.py +++ b/scripts/hub_master.py @@ -1,6 +1,6 @@ BASE_CLASSES = { "path": "base_classes/", - "title": "Model Base Classes", + "title": "Modeling API", "toc": True, "children": [ { @@ -209,7 +209,7 @@ MODELS_MASTER = { "path": "models/", - "title": "Pretrained Models", + "title": "Model Architectures", "toc": True, "children": [ { @@ -491,7 +491,7 @@ }, { "path": "deeplab_v3/", - "title": "DeepLabV3 and DeepLabV3Plus", + "title": "DeepLabV3", "toc": True, "children": [ { @@ -1725,12 +1725,18 @@ { "path": "audio_converter", "title": "AudioConverter layer", - "generate": ["keras_hub.layers.AudioConverter"], + "generate": [ + "keras_hub.layers.AudioConverter", + "keras_hub.layers.AudioConverter.from_preset", + ], }, { "path": "image_converter", "title": "ImageConverter layer", - "generate": ["keras_hub.layers.ImageConverter"], + "generate": [ + "keras_hub.layers.ImageConverter", + "keras_hub.layers.ImageConverter.from_preset", + ], }, { "path": "start_end_packer", @@ -1848,8 +1854,8 @@ "title": "API documentation", "toc": True, "children": [ - MODELS_MASTER, BASE_CLASSES, + MODELS_MASTER, TOKENIZERS_MASTER, PREPROCESSING_LAYERS_MASTER, MODELING_LAYERS_MASTER, @@ -1860,32 +1866,32 @@ HUB_GUIDES_MASTER = { "path": "guides/", - "title": "Guides", + "title": "Developer guides", "toc": True, "children": [ { - "path": "semantic_segmentation_deeplab_v3", - "title": "Semantic Segmentation with KerasHub", + "path": "upload", + "title": "Uploading Models", }, { - "path": "transformer_pretraining", - "title": "Pretraining a Transformer from scratch with KerasHub", + "path": "stable_diffusion_3_in_keras_hub", + "title": "Stable Diffusion 3", }, { - "path": "upload", - "title": "Uploading Models with KerasHub", + "path": "segment_anything_in_keras_hub", + "title": "Segment Anything", }, { "path": "classification_with_keras_hub", - "title": "Classification with KerasHub", + "title": "Image Classification", }, { - "path": "segment_anything_in_keras_hub", - "title": "Segment Anything in KerasHub", + "path": "semantic_segmentation_deeplab_v3", + "title": "Semantic Segmentation", }, { - "path": "stable_diffusion_3_in_keras_hub", - "title": "Stable Diffusion 3 in KerasHub", + "path": "transformer_pretraining", + "title": "Pretraining a Transformer from scratch", }, ], } @@ -1902,7 +1908,7 @@ HUB_API_MASTER, { "path": "presets/", - "title": "Presets", + "title": "Pretrained models list", }, ], } diff --git a/scripts/render_presets.py b/scripts/render_presets.py index 2cbc98fd93..30b4697d74 100644 --- a/scripts/render_presets.py +++ b/scripts/render_presets.py @@ -102,8 +102,10 @@ def render_table(symbol): return None for preset in symbol.presets: metadata = symbol.presets[preset]["metadata"] + url = symbol.presets[preset]["kaggle_handle"] + url = url.replace("kaggle://", "https://www.kaggle.com/models/") table += ( - f"{preset} | " + f"[{preset}]({url}) | " f"{format_param_count(metadata)} | " f"{metadata['description']} \n" ) diff --git a/scripts/tuner_master.py b/scripts/tuner_master.py index 337a3c202c..1dba4dd28a 100644 --- a/scripts/tuner_master.py +++ b/scripts/tuner_master.py @@ -210,7 +210,7 @@ TUNER_GUIDES_MASTER = { "path": "guides/", - "title": "Guides", + "title": "Developer guides", "toc": True, "children": [ { diff --git a/templates/keras_hub/api/base_classes/index.md b/templates/keras_hub/api/base_classes/index.md new file mode 100644 index 0000000000..e741a02ed5 --- /dev/null +++ b/templates/keras_hub/api/base_classes/index.md @@ -0,0 +1,12 @@ +# KerasHub Modeling API + +The following base classes form the API for working with pretrained models +through KerasHub. These base classes can be used with the `from_preset()` +constructor to automatically instantiate a subclass with the correct model +architecture, e.g. +`keras_hub.models.TextClassifier.from_preset("bert_base_en", num_classes=2)`. + +For the full list of available pretrained model presets shipped directly by the +Keras team, see the [Pretrained Models](/keras_hub/presets/) page. + +{{toc}} diff --git a/templates/keras_hub/api/index.md b/templates/keras_hub/api/index.md index b202670f6a..e41bed4697 100644 --- a/templates/keras_hub/api/index.md +++ b/templates/keras_hub/api/index.md @@ -1,9 +1,6 @@ # KerasHub API documentation KerasHub is a toolbox of modular building blocks ranging from pretrained -state-of-the-art models, to low-level Transformer Encoder layers. For an -introduction to the library see the [KerasHub home page](/keras_hub/). For a -high-level introduction to the API see our -[getting started guide](/keras_hub/getting_started/). +state-of-the-art models, to low-level Transformer Encoder layers. {{toc}} diff --git a/templates/keras_hub/api/metrics/index.md b/templates/keras_hub/api/metrics/index.md index b9b37b27f4..4643c85eb8 100644 --- a/templates/keras_hub/api/metrics/index.md +++ b/templates/keras_hub/api/metrics/index.md @@ -1,5 +1,6 @@ # KerasHub Metrics -KerasHub metrics are `keras.Metric` subclasses for NLP-specific use cases. +KerasHub metrics are `keras.Metric` subclasses that are common to computer +vision and natural language processing workflows. {{toc}} diff --git a/templates/keras_hub/api/modeling_layers/index.md b/templates/keras_hub/api/modeling_layers/index.md new file mode 100644 index 0000000000..df7de3c0fc --- /dev/null +++ b/templates/keras_hub/api/modeling_layers/index.md @@ -0,0 +1,7 @@ +# KerasHub Modeling Layers + +KerasHub modeling layers are give `keras.layers.Layer` implementations for +building blocks common to pretrained models. They can be used to create a new +model from scratch, or to extend a pretrained model. + +{{toc}} diff --git a/templates/keras_hub/api/models/index.md b/templates/keras_hub/api/models/index.md index cf20d5d1fa..6f73ef40ab 100644 --- a/templates/keras_hub/api/models/index.md +++ b/templates/keras_hub/api/models/index.md @@ -1,15 +1,13 @@ -# KerasHub Models +# KerasHub Model Architectures -KerasHub contains end-to-end implementations of popular model architectures. -These models can be created in two ways: +The following is a list of model architectures supported by KerasHub. These +models can be created in two ways: - Through the `from_preset()` constructor, which instantiates an object with - a pre-trained configurations, vocabularies, and (optionally) weights. + a pre-trained configurations, vocabularies, and weights. - Through custom configuration controlled by the user. -For the full list of available presets shipped directly by the Keras team, see -the [Presets page](/keras_hub/presets/) - -## API Documentation +For the full list of available pretrained model presets shipped directly by the +Keras team, see the [Pretrained Models](/keras_hub/presets/) page. {{toc}} diff --git a/templates/keras_hub/api/preprocessing_layers/index.md b/templates/keras_hub/api/preprocessing_layers/index.md new file mode 100644 index 0000000000..4d7ef49c97 --- /dev/null +++ b/templates/keras_hub/api/preprocessing_layers/index.md @@ -0,0 +1,7 @@ +# KerasHub Preprocessing Layers + +KerasHub preprocessing layers can be used to create custom preprocessing +pipelines for pretrained models. Preprocessing layers are all compatible with +`tf.data`, even when running on the `jax` and `torch` backends. + +{{toc}} diff --git a/templates/keras_hub/api/samplers/index.md b/templates/keras_hub/api/samplers/index.md new file mode 100644 index 0000000000..8beb525648 --- /dev/null +++ b/templates/keras_hub/api/samplers/index.md @@ -0,0 +1,7 @@ +# KerasHub Samplers + +KerasHub samplers are used to control the sampling process when generating text +with generative models. See `keras_hub.models.CausalLM` for the high-level +generative API. + +{{toc}} diff --git a/templates/keras_hub/index.md b/templates/keras_hub/index.md index 07ca27c53a..2def9821af 100644 --- a/templates/keras_hub/index.md +++ b/templates/keras_hub/index.md @@ -6,23 +6,19 @@ and fast. The library provides [Keras 3](https://keras.io/keras_3/) implementations of popular model architectures, paired with a collection of pretrained checkpoints available on [Kaggle Models](https://kaggle.com/models/). -Models can be use for both training and inference, on any of the TensorFlow, +Models can be used for both training and inference, on any of the TensorFlow, Jax, and Torch backends. KerasHub is an extension of the core Keras API; KerasHub components are provided as `keras.layers.Layer` and `keras.Model` implementations. If you are familiar with Keras, congratulations! You already understand most of KerasHub. -See our [Getting Started guide](/guides/keras_hub/getting_started) -to start learning our API. We welcome -[contributions](https://github.com/keras-team/keras-hub/issues/1835). - --- ## Quick links * [Getting started with KerasHub](/keras_hub/getting_started/) -* [Guides](/keras_hub/guides) -* [API reference](/keras_hub/api/) +* [Developer guides](/keras_hub/guides) +* [API documentation](/keras_hub/api/) * [KerasHub on GitHub](https://github.com/keras-team/keras-hub) * [KerasHub models on Kaggle](https://www.kaggle.com/organizations/keras/models) * [Pretrained model list](/keras_hub/presets/) @@ -43,51 +39,57 @@ our nightly package. pip install --upgrade keras-hub-nightly ``` -Note that currently, installing KerasHub will always pull in TensorFlow for use -of the `tf.data` API for preprocessing. Even when pre-processing with `tf.data`, -training can still happen on any backend. Read -[Getting started with Keras](https://keras.io/getting_started/) for more -information on installing Keras 3 and compatibility with different frameworks. +Currently, installing KerasHub will always pull in TensorFlow for use of the +`tf.data` API for preprocessing. When pre-processing with `tf.data`, training +can still happen on any backend. -**Note:** We recommend using KerasHub with TensorFlow 2.16 or later, as TF 2.16 -packages Keras 3 by default. +Visit the [core Keras getting started page](https://keras.io/getting_started/) +for more information on installing Keras 3, accelerator support, and +compatibility with different frameworks. --- ## Quickstart -Below is a quick example using ResNet to predict an image, and BERT to train a -classifier: +Choose a backend: ```python +# Set a backend. import os os.environ["KERAS_BACKEND"] = "jax" # Or "tensorflow" or "torch"! +``` + +Import KerasHub and other libraries: +```python +# Import libraries. import keras import keras_hub import numpy as np import tensorflow_datasets as tfds +``` + +Load a resnet model and use it to predict a label for an image: -# Load a ResNet model. +```python classifier = keras_hub.models.ImageClassifier.from_preset( "resnet_50_imagenet", activation="softmax", ) -# Predict a label for a single image. -image_url = "https://upload.wikimedia.org/wikipedia/commons/a/aa/California_quail.jpg" -image_path = keras.utils.get_file(origin=image_url) -image = keras.utils.load_img(image_path) -batch = np.array([image]) -preds = classifier.predict(batch) +url = "https://upload.wikimedia.org/wikipedia/commons/a/aa/California_quail.jpg" +path = keras.utils.get_file(origin=url) +image = keras.utils.load_img(path) +preds = classifier.predict(np.array([image])) print(keras_hub.utils.decode_imagenet_predictions(preds)) +``` + +Load a Bert model and fine-tune it on IMDb movie reviews: -# Load a BERT model. +```python classifier = keras_hub.models.BertClassifier.from_preset( "bert_base_en_uncased", activation="softmax", num_classes=2, ) - -# Fine-tune on IMDb movie reviews. imdb_train, imdb_test = tfds.load( "imdb_reviews", split=["train", "test"], @@ -95,10 +97,7 @@ imdb_train, imdb_test = tfds.load( batch_size=16, ) classifier.fit(imdb_train, validation_data=imdb_test) -# Predict two new examples. -preds = classifier.predict( - ["What an amazing movie!", "A total waste of my time."] -) +preds = classifier.predict(["What an amazing movie!", "A total waste of time."]) print(preds) ``` diff --git a/templates/keras_hub/presets/index.md b/templates/keras_hub/presets/index.md index e51dacf5ad..0dc1bdcce8 100644 --- a/templates/keras_hub/presets/index.md +++ b/templates/keras_hub/presets/index.md @@ -1,3 +1,5 @@ +# KerasHub pretrained models + Below, we list all presets available in the KerasHub library. For more detailed usage, browse the docstring for a particular class. For an in depth introduction to our API, see the [getting started guide](/keras_hub/getting_started/). diff --git a/templates/keras_tuner/index.md b/templates/keras_tuner/index.md index b8ad48d3d5..b081927b48 100644 --- a/templates/keras_tuner/index.md +++ b/templates/keras_tuner/index.md @@ -14,8 +14,8 @@ experiment with new search algorithms. ## Quick links * [Getting started with KerasTuner](/keras_tuner/getting_started/) -* [Guides](/keras_tuner/guides) -* [API reference](/keras_tuner/api/) +* [Developer guides](/keras_tuner/guides) +* [API documentation](/keras_tuner/api/) * [KerasTuner on GitHub](https://github.com/keras-team/keras-tuner) @@ -74,7 +74,8 @@ tuner.search(x_train, y_train, epochs=5, validation_data=(x_val, y_val)) best_model = tuner.get_best_models()[0] ``` -To learn more about KerasTuner, check out [this starter guide](https://keras.io/guides/keras_tuner/getting_started/). +To learn more about KerasTuner, check out the +[getting stated guide](https://keras.io/guides/keras_tuner/getting_started/). ---