[examples] docs: add sarvam-30b conversion and inference examples (#2963)

Signed-off-by: yaoyu-33 <yaoyu.094@gmail.com>
Signed-off-by: Yu Yao <yaoyu.094@gmail.com>

Author: yaoyu-33

examples/models/sarvam/README.md

@@ -0,0 +1,69 @@
+# Sarvam Examples
+
+This directory contains example scripts for Sarvam language models.
+
+Sarvam models use a Mixture of Experts (MoE) architecture with QKV layernorm and Grouped Query Attention (GQA).
+
+| Model | HF ID | Architecture | Params |
+|---|---|---|---|
+| Sarvam 30B | `sarvamai/sarvam-30b` | MoE (128 experts, top-6) | 30B total, 3B active |
+| Sarvam 105B | `sarvamai/sarvam-105b` | MoE (128 experts, top-8) | 105B total, 10.3B active |
+
+## Workspace Configuration
+
+All scripts use a `WORKSPACE` environment variable for the base directory. Default: `/workspace`.
+
+```bash
+export WORKSPACE=/your/custom/path
+```
+
+Directory structure:
+- `${WORKSPACE}/models/` - Converted checkpoints
+- `${WORKSPACE}/results/` - Training outputs
+
+## Checkpoint Conversion
+
+See [conversion.sh](conversion.sh) for checkpoint conversion examples.
+
+### Import HF → Megatron
+
+```bash
+python examples/conversion/convert_checkpoints.py import \
+    --hf-model sarvamai/sarvam-30b \
+    --megatron-path ${WORKSPACE}/models/sarvam-30b \
+    --trust-remote-code
+```
+
+### Export Megatron → HF
+
+```bash
+python examples/conversion/convert_checkpoints.py export \
+    --hf-model sarvamai/sarvam-30b \
+    --megatron-path ${WORKSPACE}/models/sarvam-30b/iter_0000000 \
+    --hf-path ${WORKSPACE}/models/sarvam-30b-hf-export
+```
+
+### Round-trip Validation
+
+```bash
+python -m torch.distributed.run --nproc_per_node=8 \
+    examples/conversion/hf_megatron_roundtrip_multi_gpu.py \
+    --hf-model-id sarvamai/sarvam-30b \
+    --megatron-load-path ${WORKSPACE}/models/sarvam-30b/iter_0000000 \
+    --tp 2 --pp 2 --ep 2 \
+    --trust-remote-code
+```
+
+## Inference
+
+See [inference.sh](inference.sh) for text generation with:
+- Hugging Face checkpoint (`sarvamai/sarvam-30b`)
+- Imported Megatron checkpoint (after [conversion.sh](conversion.sh) import)
+- Exported HF checkpoint (after conversion export)
+
+The default parallelism for 8 GPUs is `--tp 2 --pp 1 --ep 4 --etp 1`.
+TP×PP×EP must equal `--nproc_per_node`.
+
+> **Note**: `sarvamai/sarvam-30b` is a base pretrained model published in float32.
+> The Bridge conversion is correct (verified by matching outputs between HF and Megatron checkpoints).
+> For coherent text generation, use an instruction-tuned variant if available.

examples/models/sarvam/conversion.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Copyright (c) 2025, NVIDIA CORPORATION.  All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -xeuo pipefail
+
+# Workspace directory for checkpoints and results
+WORKSPACE=${WORKSPACE:-/workspace}
+
+MODEL_NAME=sarvam-30b
+HF_MODEL_ID=sarvamai/sarvam-30b
+
+# Import HF → Megatron
+uv run python examples/conversion/convert_checkpoints.py import \
+    --hf-model "$HF_MODEL_ID" \
+    --megatron-path "${WORKSPACE}/models/${MODEL_NAME}" \
+    --trust-remote-code
+
+# Export Megatron → HF
+uv run python examples/conversion/convert_checkpoints.py export \
+    --hf-model "$HF_MODEL_ID" \
+    --megatron-path "${WORKSPACE}/models/${MODEL_NAME}/iter_0000000" \
+    --hf-path "${WORKSPACE}/models/${MODEL_NAME}-hf-export"
+
+# Round-trip validation
+uv run python -m torch.distributed.run --nproc_per_node=8 \
+    examples/conversion/hf_megatron_roundtrip_multi_gpu.py \
+    --hf-model-id "$HF_MODEL_ID" \
+    --megatron-load-path "${WORKSPACE}/models/${MODEL_NAME}/iter_0000000" \
+    --tp 2 --pp 2 --ep 2 \
+    --trust-remote-code

examples/models/sarvam/inference.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Copyright (c) 2025, NVIDIA CORPORATION.  All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Workspace directory for checkpoints and results
+WORKSPACE=${WORKSPACE:-/workspace}
+
+# Inference with Hugging Face checkpoints
+uv run python -m torch.distributed.run --nproc_per_node=8 examples/conversion/hf_to_megatron_generate_text.py \
+    --hf_model_path sarvamai/sarvam-30b \
+    --prompt "Hello, how are you?" \
+    --max_new_tokens 64 \
+    --tp 2 --pp 1 --ep 4 --etp 1 \
+    --trust-remote-code
+
+# Inference with imported Megatron checkpoints
+uv run python -m torch.distributed.run --nproc_per_node=8 examples/conversion/hf_to_megatron_generate_text.py \
+    --hf_model_path sarvamai/sarvam-30b \
+    --megatron_model_path ${WORKSPACE}/models/sarvam-30b/iter_0000000 \
+    --prompt "Hello, how are you?" \
+    --max_new_tokens 64 \
+    --tp 2 --pp 1 --ep 4 --etp 1 \
+    --trust-remote-code
+
+# Inference with exported HF checkpoints
+uv run python -m torch.distributed.run --nproc_per_node=8 examples/conversion/hf_to_megatron_generate_text.py \
+    --hf_model_path ${WORKSPACE}/models/sarvam-30b-hf-export \
+    --prompt "Hello, how are you?" \
+    --max_new_tokens 64 \
+    --tp 2 --pp 1 --ep 4 --etp 1 \
+    --trust-remote-code