Docs: Improve TPU Runtime & Colab setup guide #2768
+157
−211
Conversation
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
RexBearIU
requested review from
A9isha,
RissyRan,
bvandermoon,
gagika,
gobbleturk,
jacoguzo,
jiangjy1982,
richjames0,
shralex and
vipannalla
as code owners
RexBearIU
force-pushed
the
jackyf/docs/fix-tpu-colab-setup
branch
from
002af5e to
1ffa78b
Compare
docs/tutorials/how_to_run_colabs.md
Outdated
|
|
||
| - **`rl_llama3_demo.ipynb`** → GRPO/GSPO training on math dataset (Colab/notebook) | ||
|
|
||
| #### GRPO/GSPO Colab Usage |
Collaborator
There was a problem hiding this comment.
This is not required, please remove this section.
RexBearIU
force-pushed
the
jackyf/docs/fix-tpu-colab-setup
branch
7 times, most recently
from
7635807 to
cc876b5
Compare
|
|
||
| - **`rl_llama3_demo.ipynb`** → GRPO/GSPO training on math dataset (Colab/notebook) | ||
|
|
||
| #### GRPO/GSPO Colab Usage |
Collaborator
Author
There was a problem hiding this comment.
Just to confirm, do you mean I should also remove the 'GRPO/GSPO Python Script Usage - local runs' and 'cluster runs' sections as well?
Collaborator
There was a problem hiding this comment.
Yes, because that is irrelevant to this documentation.
RexBearIU
force-pushed
the
jackyf/docs/fix-tpu-colab-setup
branch
3 times, most recently
from
1474f2e to
a78bf5c
Compare
…ng notebooks and connecting to local Jupyter Lab.
RexBearIU
force-pushed
the
jackyf/docs/fix-tpu-colab-setup
branch
from
a78bf5c to
f2cb1af
Compare
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
Updates the Jupyter/Colab documentation to resolve setup friction and connection errors identified during testing.
Key Changes:
Colab (Method 1): Clarified the workflow to open notebooks directly from GitHub to avoid file import confusion.
TPU VM (Method 2): Moved SSH tunneling to the initial connection step. This fixes the issue where users faced connection failures by attempting to access Jupyter before the tunnel was active.
GRPO/GSPO: Added specific open/setup instructions for running RL demos in both environments.
If the change fixes a bug or a Github issue, please include a link, e.g.,:
FIXES: b/463414427
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
I manually verified the updated instructions to ensure accuracy:
sft_qwen3_demo.ipynbinto a fresh Colab session.v5e-8TPU VM.-L 8888:localhost:8888).localhostlink worked immediately without needing a separate tunnel step.Checklist
Before submitting this PR, please make sure (put X in square brackets):
gemini-reviewlabel.