#Fine-tune and Pretrain LLMs on Ascend NPU Using Workbench

#Общие сведения

В этом руководстве описаны решения на базе Workbench для запуска дообучения и предобучения больших моделей на узлах arm64 с Huawei Ascend NPU. Основной поток верификации использует образ Workbench PyTorch CANN, который собран для сред Ascend и включает Python 3.12, CANN 8.5.0, PyTorch 2.9.0 и torch_npu 2.9.0. На этой странице также приведён поток дообучения на базе MindSpore, использующий образ Workbench MindSpore CANN.

Рабочий процесс сосредоточен вокруг трёх проверочных notebooks:

• Download qwen3_finetune_verify.ipynb для полно-параметрического supervised fine-tuning Qwen3-8B в Jupyter-образе PyTorch CANN
• Download qwen25_pretrain_verify.ipynb для предобучения Qwen2.5-7B в Jupyter-образе PyTorch CANN
• Download qwen3_0.6b_finetune_verify.ipynb для полно-параметрического дообучения Qwen3-0.6B на базе MindSpore в Jupyter-образе MindSpore CANN

Все notebooks спроектированы как примеры с приоритетом проверки. Они начинаются с облегчённой конфигурации, чтобы вы могли подтвердить runtime, загрузку модели, предварительную обработку и путь запуска распределённого обучения, прежде чем масштабировать тот же workflow до реального тренировочного запуска. Notebooks на базе PyTorch работают поверх MindSpeed-LLM, а notebook на базе MindSpore проверяет включённые в образ исходные деревья MindSpeed-Core-MS и MindSpeed-LLM.

В отличие от потока на базе VolcanoJob, используемого в некоторых других примерах, это решение запускает обучение напрямую внутри одного контейнера Workbench с несколькими подключёнными Ascend NPU.

#Перед началом

Убедитесь, что кластер уже предоставляет рабочий Ascend runtime. На практике это означает, что драйвер Ascend, runtime CANN и Kubernetes device plugin уже установлены и работают, а ваш workbench можно запланировать на узел arm64 с ресурсами Ascend NPU.

Создайте workbench с образом, который соответствует notebook, который вы хотите запустить, как описано в Creating a Workbench:

• Используйте PyTorch CANN для qwen3_finetune_verify.ipynb и qwen25_pretrain_verify.ipynb.
• Используйте MindSpore CANN для qwen3_0.6b_finetune_verify.ipynb.

Для настроек notebook по умолчанию планируйте как минимум 4 NPU для примеров на базе PyTorch. Проверочный notebook MindSpore настроен на 2 Ascend 910B 32G NPU с TP=1, PP=1 и MBS=2. Все notebooks создают преобразованные веса модели, результаты предварительной обработки, логи и checkpoints, поэтому рабочее пространство должно использовать постоянное хранилище с достаточным свободным объёмом как для исходной модели HuggingFace, так и для преобразованных весов Megatron/MCore.

Notebooks на базе PyTorch во время выполнения клонируют MindSpeed-LLM из https://gitcode.com/ascend/MindSpeed-LLM.git. Если workbench не может получить доступ к этому репозиторию, разместите локальную копию в рабочем пространстве и обновите путь notebook в первой ячейке параметров. Notebook MindSpore не клонирует дополнительные репозитории во время выполнения. Вместо этого он использует включённое в образ исходное дерево в /opt/app-root/share/MindSpeed-Core-MS.

#Создание Workbench

Создайте JupyterLab workbench в пуле узлов Ascend и выберите образ, соответствующий notebook, который вы планируете запускать. Используйте PyTorch CANN для notebooks дообучения Qwen3-8B и предобучения Qwen2.5-7B, либо MindSpore CANN для notebook дообучения Qwen3-0.6B на базе MindSpore. Храните рабочее пространство на постоянном хранилище, чтобы notebooks, преобразованные веса и результаты обучения оставались доступны после перезапуска. Если вы следуете настройкам notebook по умолчанию, запросите достаточное количество ресурсов NPU, чтобы удовлетворить заданную tensor- и pipeline-parallelism.

Подробные шаги создания и выбора образа см. в Creating a Workbench.

#Импорт проверочных notebooks

Загрузите notebook или notebooks, которые вы планируете использовать, в рабочее пространство JupyterLab и откройте их там. Если дистрибутив вашего образа уже предоставляет notebooks в рабочем пространстве, вы можете использовать их напрямую. В противном случае скачайте их по ссылкам выше и загрузите через файловый браузер JupyterLab. Процесс загрузки в JupyterLab описан в Creating a Workbench.

#Подготовка базовой модели

Все три notebook ожидают базовую модель в формате HuggingFace в рабочем пространстве. Пути по умолчанию:

Вы можете поместить файлы модели в эти каталоги или изменить HF_MODEL_DIR в первой ячейке параметров. Перед запуском notebook убедитесь, что целевой каталог содержит ожидаемые файлы конфигурации модели, tokenizer и файлы весов.

Если вы хотите, чтобы модель была версионируемой и повторно используемой между workbench, сначала загрузите её в репозиторий моделей платформы, а затем клонируйте или скопируйте в рабочее пространство. Процесс загрузки через репозиторий описан в Upload Models Using Notebook.

Примечание: Все три notebook преобразуют веса HuggingFace в формат Megatron/MCore перед началом обучения. Это преобразование создаёт ещё один большой набор файлов, поэтому планирование хранилища имеет значение.

#Подготовка датасета

В notebooks дообучения и предобучения ожидаются разные типы входных данных.

#Данные для fine-tuning

Notebook fine-tuning использует instruction-tuning данные. Его путь верификации основан на образцах в стиле Alpaca, а также может работать с реальным датасетом, если вы поместите файлы в рабочее пространство и обновите переменные пути в ячейке параметров.

По умолчанию notebook ищет:

• ALPACA_PARQUET = /opt/app-root/src/datasets/alpaca/train-00000-of-00001-a09b74b3ef9c3b56.parquet
• RAW_DATA_FILE = /opt/app-root/src/Qwen3-8B-work-dir/finetune_dataset/alpaca_sample.jsonl

Notebook fine-tuning на базе MindSpore использует ту же схему в стиле Alpaca, но записывает преобразованный JSONL в другой рабочий каталог:

• ALPACA_PARQUET = /opt/app-root/src/datasets/alpaca/train-00000-of-00001-a09b74b3ef9c3b56.parquet
• RAW_DATA_FILE = /opt/app-root/src/Qwen3-0.6B-work-dir/finetune_dataset/alpaca_sample.jsonl

Если parquet-файл существует, notebook автоматически преобразует его в JSONL. Если у вас уже есть instruction-данные в JSONL, поместите их в RAW_DATA_FILE или обновите переменную на фактический путь.

Ожидаемая запись JSONL в стиле Alpaca:

{"instruction": "...", "input": "...", "output": "..."}

Notebook также можно адаптировать под другие instruction-форматы, такие как ShareGPT или Pairwise datasets, изменив обработчик в разделе параметров.

#Данные для pretraining

Notebook pretraining использует неструктурированный текст. Предварительная обработка MindSpeed-LLM поддерживает .parquet, .json, .jsonl и .txt. Для структурированных форматов, таких как parquet, json или jsonl, данные должны содержать поле text. Для обычного текстового ввода предоставляйте один текстовый сегмент на строку.

Notebook верификации использует следующий путь входных данных по умолчанию:

• ALPACA_PARQUET = /opt/app-root/src/datasets/alpaca/train-00000-of-00001-a09b74b3ef9c3b56.parquet

Если этот файл отсутствует, notebook переключается на небольшой встроенный пример, чтобы можно было проверить и предварительную обработку, и поток обучения.

#Как загрузить данные в рабочее пространство

Для небольших тестовых файлов обычно достаточно прямой загрузки в JupyterLab. Для более крупных датасетов практичнее смонтировать PVC или загрузить данные из репозитория наборов данных платформы в рабочее пространство. Если вам нужен workflow с датасетом на базе репозитория, см. Fine-tuning LLMs using Workbench.

#Запуск notebook fine-tuning

Откройте qwen3_finetune_verify.ipynb в workbench, который использует Jupyter-образ PyTorch CANN, и начните с первой ячейки параметров. Эта ячейка управляет путём к модели, путём к датасету, расположением выходных данных, длиной последовательности, числом итераций обучения, а также tensor- и pipeline-parallelism, используемыми и при преобразовании весов, и при обучении.

Notebook проходит через простую последовательность шагов. Сначала он проверяет Ascend runtime и подтверждает, что доступны torch_npu, MindSpeed и MindSpeed-LLM. Затем он подготавливает небольшой датасет в стиле Alpaca или загружает ваш реальный датасет, клонирует репозиторий MindSpeed-LLM, преобразует checkpoint HuggingFace в формат Megatron/MCore, предварительно обрабатывает данные в формат, требуемый MindSpeed-LLM, запускает full-parameter SFT с posttrain_gpt.py и, наконец, выполняет проверку inference на сгенерированном checkpoint.

Конфигурация по умолчанию намеренно консервативна. Она использует короткую длину последовательности и небольшое число итераций, чтобы notebook мог служить инструментом проверки среды, а не длительным production-запуском. После того как этот путь будет работать, переходите к реальному датасету и настраивайте параметры под фактическую нагрузку.

Наиболее важные параметры для проверки:

• HF_MODEL_DIR
• ALPACA_PARQUET или RAW_DATA_FILE
• OUTPUT_DIR
• TP и PP
• SEQ_LENGTH
• TRAIN_ITERS
• ENABLE_THINKING

Для реального fine-tuning в рекомендациях notebook указано увеличить SEQ_LENGTH в соответствии с контекстным окном модели, увеличить TRAIN_ITERS до production-значения и настроить parallelism и размер batch в зависимости от доступных NPUs и размера обучающего набора. Если вам нужны периодические checkpoints, также обновите интервал сохранения в ячейке обучения.

#Запуск notebook MindSpore fine-tuning

Откройте qwen3_0.6b_finetune_verify.ipynb в workbench, который использует Jupyter-образ MindSpore CANN. Этот notebook проверяет официальный путь полно-параметрического fine-tuning Qwen3 на MindSpore и повторяет upstream workflow, реализованный следующими скриптами в MindSpeed-LLM:

• examples/mindspore/qwen3/ckpt_convert_qwen3_hf2mcore.sh
• examples/mindspore/qwen3/data_convert_qwen3_instruction.sh
• examples/mindspore/qwen3/tune_qwen3_0point6b_4K_full_ms.sh

В отличие от notebook на базе PyTorch, этот поток использует встроенное в образ исходное дерево в /opt/app-root/share/MindSpeed-Core-MS. Он проверяет включённые каталоги MindSpeed-LLM, MindSpeed, MSAdapter и Megatron-LM, а также подтверждает, что образ предоставляет скрипты окружения Ascend и ожидаемые записи PYTHONPATH до начала обучения.

Конфигурация валидации по умолчанию в первой ячейке параметров:

• HF_MODEL_DIR=/opt/app-root/src/models/Qwen3-0.6B
• WORK_DIR=/opt/app-root/src/Qwen3-0.6B-work-dir
• RAW_DATA_FILE=/opt/app-root/src/Qwen3-0.6B-work-dir/finetune_dataset/alpaca_sample.jsonl
• OUTPUT_DIR=/opt/app-root/src/Qwen3-0.6B-work-dir/output/qwen3_0.6b_finetuned
• TP=1, PP=1, MBS=2
• SEQ_LENGTH=2048
• TRAIN_ITERS=100
• ENABLE_THINKING=true

Notebook выполняет следующую последовательность:

1. Проверяет runtime-среду. Он проверяет mindspore, msadapter, mindspeed и mindspeed_llm, подтверждает, что каталог модели содержит config.json, файлы tokenizer и веса .safetensors, и проверяет, что доступное количество NPU совместимо с заданными TP и PP.
2. Подготавливает instruction dataset. Если существует ALPACA_PARQUET, notebook преобразует его в JSONL в стиле Alpaca. В противном случае он создаёт небольшой встроенный sample dataset, чтобы полный pipeline всё равно можно было проверить.
3. Преобразует веса HuggingFace в формат MindSpeed/MCore. Notebook вызывает mindspeed_llm/mindspore/convert_ckpt.py с --load-model-type hf, --save-model-type mg и --ai-framework mindspore, и записывает преобразованные веса в каталог вывода, специфичный для TP и PP.
4. Предварительно обрабатывает датасет для fine-tuning. Notebook запускает preprocess_data.py с AlpacaStyleInstructionHandler, PretrainedFromHF, prompt-type qwen3 и enable-thinking true, а затем проверяет, что требуемые файлы .bin и .idx были сгенерированы.
5. Запускает full-parameter SFT training. Ячейка обучения использует msrun вместе с posttrain_gpt.py, задаёт --finetune, --stage sft, --is-instruction-dataset, --ai-framework mindspore и --ckpt-format msadapter, а также записывает логи в /opt/app-root/src/Qwen3-0.6B-work-dir/logs.
6. Проверяет сгенерированный checkpoint. Финальная ячейка проверяет latest_checkpointed_iteration.txt, выводит каталоги checkpoint iter_* и подтверждает наличие файла training log.

Наиболее важные параметры для проверки:

• HF_MODEL_DIR
• ALPACA_PARQUET или RAW_DATA_FILE
• OUTPUT_DIR
• TP, PP и MBS
• SEQ_LENGTH
• TRAIN_ITERS
• ENABLE_THINKING
• MASTER_ADDR, MASTER_PORT, NNODES и NODE_RANK

При переходе от верификации к реальному тренировочному запуску постепенно увеличивайте SEQ_LENGTH, TRAIN_ITERS и размер датасета в зависимости от доступной памяти NPU и целевой длины контекста. Если вы изменяете TP или PP, повторно выполните преобразование весов, чтобы layout преобразованного checkpoint соответствовал layout обучения. Для многоузлового обучения обновите MASTER_ADDR, MASTER_PORT, NNODES и NODE_RANK перед повторным запуском ячейки обучения.

Текущий notebook проверяет только генерацию checkpoint. Он не включает стабильный шаг inference на MindSpore.

#Запуск notebook pretraining

Откройте qwen25_pretrain_verify.ipynb в workbench, который использует Jupyter-образ PyTorch CANN, и так же проверьте первую ячейку параметров. Этот notebook использует не instruction-response записи, а сырой текстовый корпус, однако общая структура похожа.

Он начинается с проверки окружения, подготавливает sample text dataset или загружает ваш реальный, клонирует репозиторий MindSpeed-LLM, преобразует checkpoint HuggingFace в формат Megatron/MCore, предварительно обрабатывает raw text в файлы .bin и .idx и запускает pretraining с pretrain_gpt.py.

Конфигурация валидации снова намеренно минимальна. Она полезна для проверки того, что предварительная обработка, преобразование checkpoint, распределённый запуск и запись выходных данных корректно работают в Ascend runtime, прежде чем вы перейдёте к гораздо более длительному запуску.

Основные параметры для проверки:

• HF_MODEL_DIR
• переменные пути к датасету, такие как ALPACA_PARQUET
• OUTPUT_DIR
• TP и PP
• SEQ_LENGTH
• TRAIN_ITERS

При переходе от верификации к реальному pretraining-заданию увеличьте длину последовательности и число итераций, задайте global batch size в соответствии с доступными NPUs и размером корпуса, а также пересмотрите интервал сохранения. Если вы меняете TP или PP, повторно выполните шаг преобразования весов, чтобы преобразованный checkpoint соответствовал layout обучения.

#Выходные данные и постоянное хранение

По умолчанию notebooks записывают выходные данные в следующие расположения:

Храните эти каталоги на постоянном хранилище. Выходные данные могут быть большими, и в большинстве реальных workflow вам потребуется сохранить их после перезапуска workbench или опубликовать для последующего использования. Если вы хотите отправить полученную модель обратно в репозиторий моделей, следуйте workflow Git LFS в Upload Models Using Notebook.

#Эксплуатационные замечания

• Эти notebooks в первую очередь являются примерами проверки. Не оставляйте значение количества итераций и длины последовательности по умолчанию неизменёнными для реального обучения.
• Notebooks fine-tuning выполняют full-parameter SFT, а не LoRA.
• qwen3_0.6b_finetune_verify.ipynb требует Jupyter-образ MindSpore CANN и включённое исходное дерево MindSpeed-Core-MS.
• Выбранная конфигурация parallelism влияет на использование памяти, преобразование весов и layout runtime. Если вы изменяете TP или PP, повторно преобразуйте веса перед обучением.
• В автономных или ограниченных средах подготовьте репозиторий MindSpeed-LLM для notebooks на базе PyTorch и поместите необходимые файлы модели и датасета напрямую в рабочее пространство. Notebook MindSpore использует включённое в образ исходное дерево.