docs: add LoRA fine-tuning tutorial#3601
Draft
chiajunglien wants to merge 2 commits intoAI-Hypercomputer:jackyf/feat/lora-nnxfrom
Draft
docs: add LoRA fine-tuning tutorial#3601chiajunglien wants to merge 2 commits intoAI-Hypercomputer:jackyf/feat/lora-nnxfrom
chiajunglien wants to merge 2 commits intoAI-Hypercomputer:jackyf/feat/lora-nnxfrom
Conversation
RexBearIU
reviewed
Apr 9, 2026
docs/tutorials/posttraining/lora.md
Outdated
| @@ -0,0 +1,128 @@ | |||
| <!-- | |||
| Copyright 2023–2025 Google LLC | |||
|
|
||
| If you want to resume training from a previous run or further fine-tune an existing LoRA adapter, you can specify the LoRA checkpoint path. | ||
| - **load_parameters_path**: Points to the frozen base model weights (the original model). | ||
| - **lora_restore_path**: Points to the previous LoRA adapter weights you wish to load. |
Collaborator
There was a problem hiding this comment.
please mentioned usage of hf_lora_to_maxtext script
docs/tutorials/posttraining/lora.md
Outdated
| scan_layers=True | ||
| ``` | ||
|
|
||
| Your fine-tuned model checkpoints will be saved here: `$BASE_OUTPUT_DIRECTORY/$RUN_NAME/checkpoints`. No newline at end of file |
Collaborator
There was a problem hiding this comment.
Also instruct the usage of maxtext_lora_to_hf script
RexBearIU
requested changes
Apr 9, 2026
docs/tutorials/posttraining/lora.md
Outdated
|
|
||
| ```sh | ||
| # -- Model configuration -- | ||
| export MODEL_NAME=<MaxText Model> # e.g., 'llama3.1-8b-Instruct' |
Collaborator
There was a problem hiding this comment.
could we use PRE_TRAINED_MODEL to align sft.md?
docs/tutorials/posttraining/lora.md
Outdated
| If you already have a MaxText-compatible model checkpoint, simply set the following environment variable and move on to the next section. | ||
|
|
||
| ```sh | ||
| export MAXTEXT_CKPT_PATH=<gcs path for MaxText checkpoint> # e.g., gs://my-bucket/my-model-checkpoint/0/items |
Collaborator
There was a problem hiding this comment.
could we use PRE_TRAINED_MODEL_CKPT_PATH to align sft.md?
docs/tutorials/posttraining/lora.md
Outdated
| Refer the steps in [Hugging Face to MaxText](https://maxtext.readthedocs.io/en/maxtext-v0.2.1/guides/checkpointing_solutions/convert_checkpoint.html#hugging-face-to-maxtext) to convert a hugging face checkpoint to MaxText. Make sure you have correct checkpoint files converted and saved. Similar as Option 1, you can set the following environment and move on. | ||
|
|
||
| ```sh | ||
| export MAXTEXT_CKPT_PATH=<gcs path for MaxText checkpoint> # e.g., gs://my-bucket/my-model-checkpoint/0/items |
docs/tutorials/posttraining/lora.md
Outdated
| run_name="${RUN_NAME}" \ | ||
| base_output_directory="${BASE_OUTPUT_DIRECTORY}" \ | ||
| model_name="${MODEL_NAME}" \ | ||
| load_parameters_path="${MAXTEXT_CKPT_PATH}" \ |
docs/tutorials/posttraining/lora.md
Outdated
|
|
||
| ### Option 2: Converting a Hugging Face checkpoint | ||
|
|
||
| Refer the steps in [Hugging Face to MaxText](https://maxtext.readthedocs.io/en/maxtext-v0.2.1/guides/checkpointing_solutions/convert_checkpoint.html#hugging-face-to-maxtext) to convert a hugging face checkpoint to MaxText. Make sure you have correct checkpoint files converted and saved. Similar as Option 1, you can set the following environment and move on. |
Comment on lines
+100
to
+126
| ```sh | ||
| python3 -m maxtext.trainers.post_train.sft.train_sft \ | ||
| maxtext/configs/post_train/sft.yml \ | ||
| run_name="${RUN_NAME}" \ | ||
| base_output_directory="${BASE_OUTPUT_DIRECTORY}" \ | ||
| model_name="${MODEL_NAME}" \ | ||
| load_parameters_path="${MAXTEXT_CKPT_PATH}" \ | ||
| lora_restore_path="${LORA_RESTORE_PATH}" \ | ||
| hf_access_token="${HF_TOKEN}" \ | ||
| hf_path="${DATASET_NAME}" \ | ||
| train_split="${TRAIN_SPLIT}" \ | ||
| hf_data_dir="${HF_DATA_DIR}" \ | ||
| train_data_columns="${TRAIN_DATA_COLUMNS}" \ | ||
| steps="${STEPS}" \ | ||
| per_device_batch_size="${PER_DEVICE_BATCH_SIZE}" \ | ||
| max_target_length="${MAX_TARGET_LENGTH}" \ | ||
| learning_rate="${LEARNING_RATE}" \ | ||
| weight_dtype="${WEIGHT_DTYPE}" \ | ||
| dtype="${DTYPE}" \ | ||
| profiler=xplane \ | ||
| enable_nnx=True \ | ||
| pure_nnx_decoder=True \ | ||
| enable_lora=True \ | ||
| lora_rank="${LORA_RANK}" \ | ||
| lora_alpha="${LORA_ALPHA}" \ | ||
| scan_layers=True | ||
| ``` |
Collaborator
There was a problem hiding this comment.
Safety Syntax: Use the ${VAR?} syntax in the training command to ensure users don't run the script with missing configuration.
docs/tutorials/posttraining/lora.md
Outdated
|
|
||
| ```sh | ||
| python3 -m maxtext.trainers.post_train.sft.train_sft \ | ||
| maxtext/configs/post_train/sft.yml \ |
Collaborator
There was a problem hiding this comment.
please remove maxtext/configs/post_train/sft.yml, maxtext can detect the correct path
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Start with a short description of what the PR does and how this is a change from
the past.
The rest of the description includes relevant details and context, examples:
If the change fixes a bug or a Github issue, please include a link, e.g.,:
FIXES: b/123456
FIXES: #123456
Notice 1: Once all tests pass, the "pull ready" label will automatically be assigned.
This label is used for administrative purposes. Please do not add it manually.
Notice 2: For external contributions, our settings currently require an approval from a MaxText maintainer to trigger CI tests.
Tests
Please describe how you tested this change, and include any instructions and/or
commands to reproduce.
Checklist
Before submitting this PR, please make sure (put X in square brackets):
gemini-reviewlabel.