Документация Qwen, часть 1: путеводитель, ключевые понятия и быстрый старт

На чём основана страница

Сайт qwen.readthedocs.io из нашей сети не открывается, но его исходники лежат в открытом репозитории QwenLM/Qwen3 (папка docs/source, английский текст; китайская версия сайта собирается из него через файлы перевода docs/locales/zh_CN). Мы читали коммит 7a2f61f от 9 января 2026 года.

Лицензии на текст документации нет, поэтому здесь не дословный перевод, а путеводитель и пересказ своими словами с короткими цитатами. Код на этой странице — наш, но делает то же, что примеры документации (вызовы библиотек и номера токенов сверены с оригиналом).

Документация описывает поколение Qwen3 и Qwen3-2507 (2025 год). Для моделей 2026 года (Qwen3.5 и новее) сверяйтесь с README их репозиториев и карточками на Hugging Face / ModelScope: общие принципы те же, но имена, рекомендованные параметры и версии библиотек отличаются.

Что это и кому нужно

Документация Qwen — официальное руководство команды Qwen (Alibaba) по использованию открытых моделей: как скачать, запустить, развернуть как сервис, квантовать, дообучить и подключить к агентным фреймворкам. Как устроены модели внутри, здесь почти нет — это в техотчётах и блоге (см. наши конспекты поста о Qwen3 и поста о GSPO).

Для нашего курса документация полезна на ступенях 6–8: это самый короткий путь от «я понимаю, что такое шаблон чатаchat-шаблонEN chat templateПравило (обычно Jinja в tokenizer_config.json), которое превращает список сообщений с ролями в одну строку со спецтокенами.» до «у меня на четырёх видеокартах работает OpenAI-совместимый сервер с Qwen, а мой агент вызывает в нём функции». Почти все команды переносятся на любую другую открытую модель.

Мы разбили путеводитель на четыре страницы:

1. Эта страница — карта документации, ключевые понятия, быстрый старт на transformers.
2. Запуск: vLLM, SGLang, Ollama — сервер с OpenAI-совместимым API и локальный запуск.
3. Вызов функций — как модель «вызывает» инструменты и как это разбирать.
4. Дообучение — LLaMA-Factory, ms-swift, verl, Unsloth, Axolotl.

Карта документации

Раздел оригинала	Страницы	О чём	Урок курса	Важность
Getting Started	Quickstart, Key Concepts	первый запуск; имена моделей, токены, шаблон чата, режим размышления	7.2.2, 6.1.2	обязательно
Getting Started	Speed Benchmark, Quantization Benchmark	таблицы скорости и качества квантованных версий	7.2.1	справочно
Inference	Transformers	pipeline() и generate(), переключение режима размышления, разбор ответа	7.2.2	обязательно
Run Locally	llama.cpp, Ollama, MLX-LM, LM Studio	запуск на одном компьютере, GGUF	7.2.2	важно (Ollama)
Deployment	vLLM, SGLang, TGI, dstack, SkyPilot, OpenLLM	сервер для многих пользователей	7.1.2	важно (vLLM, SGLang)
Quantization	AWQ, GPTQ, llama.cpp	как квантовать самому	7.2.1	полезно
Training	LLaMA-Factory, ms-swift, verl, Unsloth, Axolotl	SFT, LoRA, RL	6.2.2, 6.4.5	важно
Framework	Function Calling, Qwen-Agent, LangChain, LlamaIndex	вызов инструментов, агенты, RAG	8.3.2, 8.2.1	важно (Function Calling)

В каком порядке читать

Новичку: Key Concepts → Quickstart → Ollama (запустить хоть что-то) → vLLM → Function Calling. Остальное — по мере надобности, когда дойдёте до соответствующего урока.

Ключевые понятия (пересказ раздела Key Concepts)

Что такое Qwen и какие бывают версии

Qwen по-китайски — «Тунъи Цяньвэнь» (примерно «понимающий смысл, отвечающий на тысячу вопросов»). Так называется семейство языковых и мультимодальных моделей команды Qwen из Alibaba. Есть закрытые версии (доступны только через облако Alibaba Cloud Model Studio) и открытые веса. Документация — про открытые языковые модели.

Про Qwen3 документация выделяет четыре новшества:

• вернулись модели-смесь экспертовсмесь экспертов (MoE)EN mixture of experts (MoE) — Qwen3-30B-A3B и Qwen3-235B-A22B; самая большая плотная модель — Qwen3-32B;
• гибридное мышлениегибридный режим мышленияEN hybrid thinking modeОдна модель умеет отвечать и с длинным рассуждением, и сразу. В Qwen3 режим переключается флагами /think и /no_think.: одна и та же модель умеет и «думать» (длинная цепочка рассуждений), и отвечать сразу — без смены весов;
• поддержка 119 языков и диалектов;
• модели специально усилены для программирования и агентов, включая MCP.

Как читать имя модели

Начиная с Qwen3, имя строится по схеме Qwen3[-размер][-тип][-дата].

• Размер. У плотной модели — число параметров: 4B, 32B. У MoE — общее число параметров и через A число активных параметровактивные параметрыEN activated (active) parametersСколько параметров MoE-модели реально участвует в обработке одного токена. «A22B» в названии Qwen3-235B-A22B — 22 млрд активных из 235 млрд. на токен: 30B-A3B значит «всего 30 млрд, на каждый токен работают 3 млрд».
• Тип. -Instruct — обычная чат-модель (без рассуждений); -Thinking — рассуждающая модель, всегда думает перед ответом; -Base — предобученная модель, которая не знает шаблона чата (её берут для дообучения и обучения в контексте); без типа — гибридная модель, где режим переключается.
• Дата в формате «год-месяц»: 2507 — июль 2025 года.

Пример: Qwen3-30B-A3B-Instruct-2507 — MoE на 30 млрд параметров (3 млрд активных), чат-модель без рассуждений, выпуск июля 2025 года. А Qwen3-8B — плотная гибридная модель на 8 млрд.

Токены и токенизация

Модель работает не с буквами, а с токенамитокенEN tokenВ разговорной речи и статьях китайцы чаще всего пишут просто «token».. Qwen использует байтовый BPEбайтовый BPE (byte-level BPE)EN byte-level BPE (BBPE)BPE, у которого базовый словарь — 256 байтов UTF-8. Любой текст кодируется без <unk>. Используется в GPT-2, GPT-4o, Llama 3, Qwen, DeepSeek.: текст сначала превращается в байты UTF-8, а затем частые последовательности байтов склеиваются в токены. Отсюда главное свойство: неизвестных слов не бывает — любой текст, даже на редком языке или с эмодзи, разбивается на токены.

Числа из документации:

• в словаре 151 643 обычных токена (результат BPE) и всего 151 646 токенов вместе с управляющими;
• на глаз: 1 токен ≈ 3–4 символа английского текста и ≈ 1,5–1,8 символа китайского.

Пример: строка из 1000 китайских иероглифов займёт примерно $1000 / 1{,}65 \approx 600$ токенов, а 1000 символов английского текста — примерно $1000 / 3{,}5 \approx 290$. Русский текст в документации не оценивается — проверьте сами (см. «Что сделать руками» ниже).

Управляющие токены

Управляющие (специальные) токеныспециальный токен (спецтокен)EN special tokenУправляющий токен, а не кусок текста — начало/конец текста (BOS/EOS), заполнитель для батча (PAD), разметка ролей в чате (например, <|im_start|> у Qwen). несут служебный смысл, а не текст. У Qwen их три главных:

• <|endoftext|> — конец документа. При предобучении несколько документов склеивают в одну длинную последовательность, и между ними ставят этот токен.
• <|im_start|> — начало реплики в диалоге.
• <|im_end|> — конец реплики.

А вот чего у Qwen нет, и это частый источник ошибок при дообучении:

• нет токена «неизвестное слово» (unk) — байтовый BPE в нём не нуждается;
• нет токена-заполнителя (pad) — Qwen не обучали на дополненных последовательностях. Для батчей можно взять любой служебный токен вместе с маской внимания; обычно ставят тот же <|endoftext|>;
• нет фиксированного токена начала (bos) последовательности. Документация прямо предупреждает: не назначайте bos равным <|im_start|>, иначе при дообучении первая реплика получит двойной <|im_start|>;
• нет отдельного токена конца (eos), но многие фреймворки останавливают генерацию именно по eos, поэтому eos выставлен равным <|im_end|>. Двойной <|im_end|> в конце, по словам документации, «менее вреден».

Шаблон чата

Диалог превращается в одну строку по шаблону ChatML: каждая реплика — <|im_start|>роль, перенос строки, текст, <|im_end|>. Роли — system, user, assistant. Начиная с Qwen3, системного сообщения по умолчанию нет (у Qwen2.5 было «You are Qwen, created by Alibaba Cloud…»).

Вот как выглядит короткий диалог после применения шаблона (наш пример):

<|im_start|>system
Ты — вежливый помощник. Отвечай по-русски.<|im_end|>
<|im_start|>user
Привет! Что такое токен?<|im_end|>
<|im_start|>assistant
Токен — это кусочек текста, с которым работает модель…<|im_end|>

Генерация ответа — это продолжение строки после <|im_start|>assistant и переноса строки. Модель пишет текст и сама ставит <|im_end|>, когда считает ответ законченным. Подробно о шаблонах и о том, почему при дообучении потери считают только по ответу ассистента, — в уроке 6.1.2.

Вызов инструментов в шаблоне

Для вызова инструментоввызов инструментовEN tool calling / function calling Qwen3 использует формат, похожий на формат модели Hermes (NousResearch). Суть:

1. В системное сообщение добавляется раздел # Tools с JSON-схемами функций внутри тегов <tools></tools> и инструкцией: для каждого вызова верни JSON с полями name и arguments внутри тегов <tool_call></tool_call>.
2. Модель отвечает одним или несколькими блоками <tool_call>{"name": …, "arguments": {…}}</tool_call>. Вызовов может быть несколько сразу (параллельный вызов) и в несколько шагов подряд.
3. Результаты функций возвращаются как особое сообщение пользователя: каждый результат в тегах <tool_response></tool_response>.
4. Модель пишет итоговый ответ.

Две детали из документации: в сообщении с вызовами может быть и обычный текст; поле arguments — это JSON-объект, а не строка (у OpenAI в API — строка; конвертацию делают фреймворки). Собирать такой шаблон руками документация не советует: пусть это делает токенизатор (apply_chat_template(..., tools=...)) или Qwen-Agent. Подробности — на странице о вызове функций.

Режим размышления в шаблоне

В режиме размышления ответ ассистента начинается с блока <think>…</think>, после него — пустая строка и обычный ответ. Важное правило: рассуждения хранят только в последнем ходе диалога. Когда диалог продолжается, старые блоки <think> из истории выбрасывают (шаблон чата Qwen3 делает это сам). Исключение — многошаговый вызов инструментов внутри одного хода. Зачем так сделано и как это связано с обучением — в уроке 6.4.4.

Длина контекста

Документация разделяет два числа: сколько токенов модель видела в одной упакованной последовательности при предобучении, и какой длины ответы ассистента были при дообучении.

Поколение	Длина при предобучении	Расширение	Макс. ответ (думающий режим)	Макс. ответ (без размышления)
Qwen3	32 768	до 131 072, если сказано в карточке	38 912	16 384
Qwen3-2507	262 144	до 1 млн	81 920	16 384

Практический вывод документации: модели нередко пишут связный текст и длиннее, чем видели при обучении (например, 32 тыс. токенов вместо 16 тыс. — особенно код), но качество длинных ответов нужно проверять самим, прежде чем ставить большой max_tokens.

Быстрый старт (пересказ разделов Quickstart и Transformers)

Что установить

Документация требует transformers>=4.51.0 (более старые версии не знают архитектуру Qwen3), рекомендует Python 3.10+ и PyTorch 2.6+.

# создайте окружение курса, если ещё нет (урок 0.1), затем:
pip install "transformers>=4.51.0" accelerate
# если Hugging Face недоступен — скачивайте через ModelScope:
pip install modelscope
modelscope download --local_dir ./Qwen3-0.6B Qwen/Qwen3-0.6B

Первый запуск: гибридная модель

Ниже — тот же порядок действий, что в Quickstart, на самой маленькой модели Qwen3-0.6B (≈1,2 ГБ в bf16, запускается даже на CPU, хоть и медленно). Для Qwen3-8B поменяйте одно имя.

from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "Qwen/Qwen3-0.6B"        # или локальная папка ./Qwen3-0.6B

tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",   # возьмёт bf16 из чекпойнта; без этого будет float32 — вдвое больше памяти
    device_map="auto",    # разложит слои по доступным GPU (нужен пакет accelerate)
)

messages = [{"role": "user", "content": "Объясни в двух предложениях, что такое языковая модель."}]

# Шаблон чата превращает список сообщений в одну строку с <|im_start|> и <|im_end|>
text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,   # добавить "<|im_start|>assistant\n" — приглашение отвечать
    enable_thinking=True,         # True — думать перед ответом (по умолчанию), False — отвечать сразу
)
inputs = tokenizer([text], return_tensors="pt").to(model.device)

out = model.generate(**inputs, max_new_tokens=2048)
new_ids = out[0][len(inputs.input_ids[0]):].tolist()   # отрезаем промпт, оставляем только ответ

# Ищем с конца токен </think> (его id = 151668), чтобы отделить рассуждение от ответа
try:
    split = len(new_ids) - new_ids[::-1].index(151668)
except ValueError:      # блока размышления нет
    split = 0

thinking = tokenizer.decode(new_ids[:split], skip_special_tokens=True).strip("\n")
answer = tokenizer.decode(new_ids[split:], skip_special_tokens=True).strip("\n")
print("РАССУЖДЕНИЕ:", thinking[:300], "...")
print("ОТВЕТ:", answer)

Что вы увидите: сначала рассуждение (обычно по-английски, даже на русский вопрос — модель так обучена), затем ответ по-русски. Точный текст будет другим — генерация случайна.

Типичные ошибки новичка

• KeyError: 'qwen3' или «model type qwen3 not recognized» — старый transformers; обновите до 4.51+.
• Память кончилась на CPU — проверьте, что передали torch_dtype="auto", иначе модель загрузится в float32.
• Нельзя одновременно передавать device_map и device — выберите что-то одно.

Как выключить размышление

Документация описывает два способа.

• Жёсткий переключатель: enable_thinking=False в apply_chat_template. Технически шаблон просто дописывает пустой блок <think>\n\n</think>\n\n в начало ответа ассистента, и модели «уже нечего» думать. Тот же эффект в pipeline() даёт последнее сообщение ассистента с содержимым "<think>\n\n</think>\n\n". Действует только на один ход.
• Мягкий переключатель: дописать /no_think (или /think) в сообщение пользователя или системы. Модель следует последней такой команде в диалоге, то есть настройка «запоминается» на следующие ходы.

У моделей -Instruct-2507 размышления нет вовсе (и enable_thinking не нужен), у -Thinking-2507 оно есть всегда; причём шаблон сам открывает <think>, поэтому в выводе бывает только закрывающий </think> — это нормально.

Рекомендованные параметры генерации

Режим	temperature	top_p	top_k	min_p
с размышлением (Qwen3, Thinking-2507)	0,6	0,95	20	0
без размышления (Qwen3 с enable_thinking=False, Instruct-2507)	0,7	0,8	20	0

Главное предупреждение документации: не используйте жадное декодирование в режиме размышления — модель начинает бесконечно повторяться. Против повторов можно поднять presence_penalty (от 0 до 2), но большие значения иногда приводят к смешению языков. Что значат эти параметры — в уроке о декодировании.

Бюджет размышления

Бюджет размышлениябюджет мышленияEN thinking budgetЛимит токенов на рассуждение; при его исчерпании рассуждение обрывают и просят модель ответить. Ручка «точность ↔ задержка». — ограничение на длину рассуждения. В облачном API Alibaba он встроен, а в открытых фреймворках документация предлагает сделать его в два вызова:

1. Сгенерировать не больше thinking_budget токенов.
2. Если модель за это время не закрыла </think>, дописать к выводу фразу-«стоп-кран» (в оригинале по-английски: «Considering the limited time by the user, I have to give the solution based on the thinking directly now.») и закрывающий </think>.
3. Продолжить генерацию: модель напишет ответ по тому, что успела надумать.

Документация советует бюджет не меньше 1024 токенов — меньшие значения заметно портят ответы. Если рассуждение не нужно вообще, используйте не бюджет, а жёсткий переключатель.

ModelScope и OpenAI-совместимый API

Если загрузка с Hugging Face не работает, ModelScope предлагает почти тот же интерфейс: достаточно заменить from transformers import … на from modelscope import ….

Для настоящих приложений модель запускают как сервер (vLLM или SGLang) и обращаются к нему через OpenAI-совместимый APIOpenAI-совместимый APIEN OpenAI-compatible APIHTTP-интерфейс в формате OpenAI Chat Completions (/v1/chat/completions). Его отдают Ollama, llama-server, vLLM, SGLang, а также DeepSeek и Qwen в облаке — код клиента не меняется.. Как это сделать и какие флаги нужны для разбора рассуждений и вызовов функций — на второй странице путеводителя.

🖥 На вашей машине (4× RTX 4080, 32 ГБ каждая)

Оценка памяти под веса в bf16: число параметров × 2 байта (плюс место под KV-кэшKV-кэшEN KV cache).

Модель	Веса в bf16	Где запускать
Qwen3-0.6B, 1.7B, 4B	1,2 / 3,4 / 8 ГБ	одна GPU или даже CPU
Qwen3-8B	≈16 ГБ	одна GPU, остаётся место под длинный контекст
Qwen3-14B	≈30 ГБ	впритык на одной GPU — лучше две (тензорный параллелизм)
Qwen3-30B-A3B	≈61 ГБ	две–четыре GPU; работает быстро, потому что активны только 3 млрд параметров
Qwen3-32B	≈66 ГБ	четыре GPU или AWQ/FP8-версия на двух
Qwen3-235B-A22B	≈470 ГБ	не помещается; только сильно квантованная GGUF с выгрузкой в RAM — медленно

Для transformers с device_map="auto" модель просто раскладывается по картам слоями (работает, но медленно); для скорости берите vLLM — см. часть 2.

Что сделать руками

1. Запустите пример выше на Qwen3-0.6B с enable_thinking=True и False. Сравните длину ответа и время.
2. Посчитайте токены: возьмите абзац этой страницы и его английский перевод, прогоните через tokenizer(text).input_ids и сравните «символов на токен» для русского, английского и китайского.
3. Напечатайте tokenizer.apply_chat_template(messages, tokenize=False) для диалога из трёх ходов, где ассистент думал. Убедитесь, что блоки <think> из старых ходов исчезли.
4. Проверьте tokenizer.eos_token, tokenizer.pad_token и tokenizer.bos_token — совпадает ли с описанием выше?

Что читать дальше

• Часть 2: vLLM, SGLang, Ollama.
• Урок 7.2.2 «Запускаем Qwen/DeepSeek локально» и китайский трек 8 о ключевых идеях Qwen.
• Оригинал: Quickstart, Key Concepts, Transformers (китайская версия — замените /en/ на /zh-cn/).

Словарик

English	Русский
chat template	шаблон чата
control token / special token	управляющий (специальный) токен
thinking mode / non-thinking mode	режим размышления / без размышления
hybrid thinking	гибридное мышление
thinking budget	бюджет размышления
activated parameters	активные параметры
tool calling / function calling	вызов инструментов / функций
greedy decoding	жадное декодирование