[26.06] verl release: documentation updates

amd-docs/conf.py

@@ -12,15 +12,15 @@
 flavor options: rocm, rocm-docs-home, rocm-blogs, rocm-ds, instinct, ai-developer-hub, local, generic
 '''
 html_theme = "rocm_docs_theme"
-html_theme_options = {"flavor": "rocm-llmext", "repository_url": "https://github.com/ROCm/verl/"}
+html_theme_options = {"flavor": "rocm-llmext", "repository_url": "https://github.com/AMD-Ecosystem/verl/"}
 
 '''
 docs_header_version is used to manually configure the version in the header. If
 there exists a non-null value mapped to docs_header_version, then the header in
 the documentation page will contain the given version string.
 '''
 html_context = {
-    "docs_header_version": "26.02"
+    "docs_header_version": "26.06"
 }
 
 

amd-docs/examples/verl-async-examples.rst

@@ -0,0 +1,102 @@
+.. meta::
+  :description: verl fully asynchronous examples
+  :keywords: verl, programming, ROCm, example, DAPO, GRPO, Megatron, FSDP2
+
+.. _run-a-fully-async-verl-example:
+
+********************************************************************
+Run fully asynchronous verl examples
+********************************************************************
+
+This guide shows how to run fully asynchronous verl examples on AMD GPUs with ROCm.
+It covers preparing data and models, launching fully asynchronous GRPO training on a
+vision-language model with Megatron, and running fully asynchronous DAPO math
+reasoning training with FSDP2.
+
+Megatron example
+--------------------------------------------------------------------
+
+The `geo3k_qwen25vl_7b_megatron_4_4.sh <https://github.com/AMD-Ecosystem/verl/blob/main/verl/experimental/fully_async_policy/shell/geo3k_qwen25vl_7b_megatron_4_4.sh>`_ example launches fully asynchronous GRPO training for ``Qwen2.5-VL-7B-Instruct`` on the Geometry3k vision-math dataset using verl's fully asynchronous policy with the Megatron trainer configuration.
+
+1. Download `prepare_geo3k_qwen25vl_7b_megatron_4_4.sh <https://github.com/AMD-Ecosystem/verl/tree/amd-integration/verl/experimental/fully_async_policy/shell/data_model_preparation/prepare_geo3k_qwen25vl_7b_megatron_4_4.sh>`_ and run:
+
+   .. code-block:: bash
+
+      export HF_TOKEN=your_token
+      # or: hf auth login
+      cd /workspace/verl
+      bash verl/experimental/fully_async_policy/shell/data_model_preparation/prepare_geo3k_qwen25vl_7b_megatron_4_4.sh
+
+2. Run the example:
+
+   .. code-block:: bash
+
+      export HF_MODEL_PATH=${HOME}/models/Qwen2.5-VL-7B-Instruct
+      cd /workspace/verl
+      bash verl/experimental/fully_async_policy/shell/geo3k_qwen25vl_7b_megatron_4_4.sh
+
+   This example will take several hours to run. Once the example completes, the output should resemble the following:
+
+   .. image:: ../data/geo3k_qwen25vl_7b_megatron_4_4_complete.png
+      :alt: Expected terminal output after geo3k_qwen25vl_7b_megatron_4_4.sh completes
+
+DAPO example
+--------------------------------------------------------------------
+
+The `dapo_7b_math_fsdp2_4_4.sh <https://github.com/AMD-Ecosystem/verl/blob/main/verl/experimental/fully_async_policy/shell/dapo_7b_math_fsdp2_4_4.sh>`__
+example launches fully asynchronous DAPO reinforcement learning training using ``Qwen2.5-Math-7B`` on math reasoning tasks.
+
+1. Download `prepare_dapo_7b_math_fsdp2_4_4.sh <https://github.com/AMD-Ecosystem/verl/tree/amd-integration/verl/experimental/fully_async_policy/shell/data_model_preparation/prepare_dapo_7b_math_fsdp2_4_4.sh>`_ and run:
+
+   .. code-block:: bash
+
+      export HF_TOKEN=your_token
+      # or: hf auth login
+      cd /workspace/verl
+      bash verl/experimental/fully_async_policy/shell/data_model_preparation/prepare_dapo_7b_math_fsdp2_4_4.sh
+
+2. Run the example:
+
+   .. code-block:: bash
+
+      cd /workspace/verl
+      bash verl/experimental/fully_async_policy/shell/dapo_7b_math_fsdp2_4_4.sh
+
+   This example will take several hours to run. Once the example completes, the output should resemble the following:
+
+   .. image:: ../data/dapo_7b_math_fsdp2_4_4_complete.png
+      :alt: Expected terminal output after dapo_7b_math_fsdp2_4_4.sh completes
+
+3. If you encounter out of memory issues, reduce ``max_position_embeddings`` in the ``config.json`` to 4096:
+
+   .. code-block:: bash
+
+      python -c "
+      import json, pathlib
+      config_path = pathlib.Path.home() / 'verl/models/Qwen2.5-Math-7B/config.json'
+      with open(config_path) as f:
+          config = json.load(f)
+      config['max_position_embeddings'] = 4096
+      with open(config_path, 'w') as f:
+          json.dump(config, f, indent=2)
+      "
+
+4. Apply these changes as overrides in ``dapo_7b_math_fsdp2_4_4.sh``:
+
+   .. code-block:: bash
+
+      # line 55: default uses * 2
+      actor_ppo_max_token_len=$((max_prompt_length + max_response_length))
+
+      # line 56: default uses * 3
+      infer_ppo_max_token_len=$(((max_prompt_length + max_response_length) * 2))
+
+      # line 61: default is fsdp_size=2
+      fsdp_size=4
+
+      # line 74: default is total_rollout_steps=$(((512*100)))
+      total_rollout_steps=$((100))
+
+      # line 105: default is max_position_embeddings=32768
+      +actor_rollout_ref.model.override_config.max_position_embeddings=4096 \
+

amd-docs/examples/verl-examples.rst

@@ -13,7 +13,7 @@ It covers data preparation, model loading checks, configuration,
 environment variables, running PPO and GRPO, and launching multi-node
 training with Slurm.
 
-1. Prepare the GSM8K dataset using the provided preprocessing script from the examples directory at `https://github.com/ROCm/verl/tree/main/examples/data_preprocess <https://github.com/ROCm/verl/tree/main/examples/data_preprocess>`__.
+1. Prepare the GSM8K dataset using the provided preprocessing script from the examples directory at `https://github.com/AMD-Ecosystem/verl/tree/main/examples/data_preprocess <https://github.com/AMD-Ecosystem/verl/tree/main/examples/data_preprocess>`__.
 
    .. code-block:: bash
 

amd-docs/index.rst

@@ -22,10 +22,10 @@ verl achieves high training and generation throughput by building on existing LL
 Its 3D-HybridEngine reduces memory use and communication overhead when switching between training 
 and inference, improving overall performance.
 
-verl is part of the `ROCm-LLMExt toolkit
+verl is part of the `AMD LLM Extension toolkit
 <https://rocm.docs.amd.com/projects/rocm-llmext/en/docs-26.02/>`__.
 
-The verl public repository is located at `https://github.com/ROCm/verl <https://github.com/ROCm/verl>`__.
+The verl public repository is located at `https://github.com/AMD-Ecosystem/verl <https://github.com/AMD-Ecosystem/verl>`__.
 
 .. grid:: 2
   :gutter: 3
@@ -37,13 +37,14 @@ The verl public repository is located at `https://github.com/ROCm/verl <https://
   .. grid-item-card:: Examples
 
     * :doc:`Run a verl example <examples/verl-examples>`
+    * :doc:`Run fully asynchronous verl examples <examples/verl-async-examples>`    
 
   .. grid-item-card:: Reference
 
       * `Quickstart PPO training on GSM8K dataset (upstream) <https://verl.readthedocs.io/en/latest/start/quickstart.html>`__
       * `HybridFlow programming guide (upstream) <https://verl.readthedocs.io/en/latest/hybrid_flow.html>`__
 
 To contribute to the documentation, refer to
-`Contributing to verl <https://github.com/ROCm/verl/blob/main/CONTRIBUTING.md>`__.
+`Contributing to verl <https://github.com/AMD-Ecosystem/verl/blob/main/CONTRIBUTING.md>`__.
 
 You can find licensing information on the :doc:`Licensing <about/license>` page.

amd-docs/install/verl-install.rst

@@ -15,7 +15,7 @@ To use verl `0.7.1 <https://github.com/volcengine/verl/releases/tag/v0.7.1>`__,
 
 - **ROCm version:** `7.0.2 <https://rocm.docs.amd.com/en/docs-7.0.2/>`__
 - **Operating system:** Ubuntu 22.04
-- **GPU platform:** AMD Instinct™ MI300X, MI308, MI325X, MI350X, or MI355X
+- **GPU platform:** AMD Instinct™ MI300X, MI325X, MI355X
 - **PyTorch:** `2.9.1 <https://github.com/ROCm/pytorch/tree/release/2.9-rocm7.x-gfx115x>`__
 - **Python:** `3.12 <https://www.python.org/downloads/release/python-31211/>`__
 - **vLLM:** `0.20.2 <https://github.com/vllm-project/vllm/releases/tag/v0.20.2>`__
@@ -42,68 +42,56 @@ Prebuilt Docker images with verl configured for ROCm are available on `Docker Hu
 
    .. code-block:: bash
 
-      docker pull rocm/verl:verl-release-v0.7.1amd0
+      docker pull rocm/verl:verl-0.7.1.amd0_rocm7.0.2_ubuntu22.04_py3.12_vllm0.20.2
 
 2. Launch and connect to the Docker container
 
    .. code-block:: bash
 
-      docker run --rm -it \
-         --name rocm_verl \
-         --device /dev/dri \
+      docker run -it \
+         --name verl-release \
          --device /dev/kfd \
+         --device /dev/dri \
+         --privileged \
+         --network=host \
          --group-add video \
          --cap-add SYS_PTRACE \
          --security-opt seccomp=unconfined \
-         --privileged \
-         -p 8265:8265 \
-         -v "$HOME/.ssh:/root/.ssh" \
-         -v "$HOME:$HOME" \
-         --shm-size 128G \
-         -w "$PWD" \
-         rocm/verl:verl-release-v0.7.1amd0 \
+         --shm-size 2048g \
+         --ulimit memlock=-1 \
+         --ulimit stack=67108864 \
+         -w /workspace \
+         rocm/verl:verl-0.7.1.amd0_rocm7.0.2_ubuntu22.04_py3.12_vllm0.20.2 \
          /bin/bash
 
 .. _build-your-verl-rocm-docker-image:
 
 Build your own Docker image
 --------------------------------------------------------------------------------
 
-1. Clone the `https://github.com/ROCm/verl <https://github.com/ROCm/verl>`_ repository
+1. Download the Dockerfile from the ``release/0.7.1.amd0`` branch:
 
    .. code-block:: bash
 
-      git clone https://github.com/ROCm/verl.git
+      curl -O https://raw.githubusercontent.com/AMD-Ecosystem/verl/release/0.7.1.amd0/docker/rocm/verl0.7.1-amd0/Dockerfile
 
-2. Build the Docker container using the Dockerfile in the ``verl/docker`` directory
+2. Build the Docker image:
 
    .. code-block:: bash
 
-      cd verl
-      docker build --build-arg VLLM_REPO=https://github.com/vllm-project/vllm.git \
-         --build-arg VLLM_BRANCH=4ca5cd5740c0cd7788cdfa8b7ec6a27335607a48 \
-         --build-arg VERL_REPO=https://github.com/ROCm/verl.git \
-         --build-arg VERL_BRANCH=0eb50ec4a33cda97e05ed8caab9c7f17a30c05a9 \
-         -f docker/Dockerfile.rocm7 -t my-rocm-verl .
+      docker build -t verl-release-v0.7.1amd0 .
 
-3. Launch and connect to the container
+3. Run the Docker container:
 
    .. code-block:: bash
 
-      docker run --rm -it \
-         --device /dev/dri \
-         --device /dev/kfd \
-         -p 8265:8265 \
-         --group-add video \
-         --cap-add SYS_PTRACE \
-         --security-opt seccomp=unconfined \
-         --privileged \
-         -v $HOME/.ssh:/root/.ssh \
-         -v $HOME:$HOME \
-         --shm-size 128G \
-         -w $PWD \
-         --name rocm_verl \
-         my-rocm-verl \
+      docker run -it --name verl-release --device /dev/kfd --device /dev/dri \
+         --privileged --network=host \
+         --group-add video --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
+         --shm-size=2048g \
+         --ulimit memlock=-1 --ulimit stack=67108864 \
+         -w /workspace \
+         verl-release-v0.7.1amd0 \
          /bin/bash
 
    .. note::

amd-docs/sphinx/_toc.yml.in

@@ -16,6 +16,8 @@ subtrees:
   entries:
   - file: examples/verl-examples.rst
     title: Run a verl example
+  - file: examples/verl-async-examples.rst
+    title: Run fully asynchronous verl examples
 
 - caption: Reference
   entries:
@@ -28,7 +30,7 @@ subtrees:
   entries:
   - url: https://rocm.blogs.amd.com/artificial-intelligence/verl-large-scale-rocm7/README.html
     title: ROCm verl blog
-  - url: https://github.com/ROCm/verl/blob/main/CONTRIBUTING.md
+  - url: https://github.com/AMD-Ecosystem/verl/blob/main/CONTRIBUTING.md
     title: Contribute to verl
   - file: about/license.rst
     title: License

amd-docs/sphinx/requirements.in

@@ -1 +1 @@
-rocm-docs-core==1.32.0
+rocm-docs-core==1.37.0