Metal · Candle · Qwen2
Как ускорить декодирование Qwen2 на Metal в Candle

Квантование уменьшает размер модели, но само по себе не гарантирует быстрое декодирование. В Qwen2 с grouped-query attention число query-heads больше числа KV-heads. Если backend перед вычислением внимания материализует расширенные копии ключей и значений, Metal получает лишнюю работу на каждом токене.
В этой статье показан безопасный путь диагностики и патчирования Candle: сохранить компактный KV-cache, передать повторение групп непосредственно в fused SDPA и сравнить baseline с изменённой реализацией на Apple M2. Численные результаты здесь не подменяются вымышленными измерениями: их нужно получить на вашей сборке и сохранить вместе с параметрами запуска.
Где появляется потеря производительности
В grouped-query attention запросы используют больше голов, чем cache ключей и
значений. Пусть n_q равно числу query-heads, а
n_kv равно числу KV-heads. Тогда размер группы равен:
group_size = n_q / n_kv
Наивный путь делает repeat_kv до формы
[batch, n_q, sequence, head_dim]. Это удобно для обычного
матричного умножения, но увеличивает объём чтения из памяти и создаёт
промежуточные tensor-операции. На коротком prompt проблема может быть
незаметной. При пошаговом декодировании она повторяется для каждого нового
токена.
На Metal стоимость таких операций особенно заметна, когда основной матричный продукт уже хорошо оптимизирован. В результате квантованный linear-слой ускоряется, а attention становится новым ограничением.
Проверяем baseline
Сначала зафиксируйте исходное состояние. Не меняйте одновременно модель, размер контекста и способ подсчёта токенов. Пример команд ниже не удаляет файлы и не изменяет глобальную конфигурацию Rust.
rustc --version
cargo --version
uname -m
system_profiler SPDisplaysDataType | sed -n '1,40p'
cargo run --release --features metal -- \
--model ./models/qwen2 \
--prompt "Explain grouped-query attention in one paragraph." \
--max-new-tokens 128 \
--measure decode
Если CLI проекта называется иначе, замените только имя бинарника и его аргументы. Для сравнения сохраните скорость декодирования, количество сгенерированных токенов, размер prompt, тип квантования и commit исходного Candle.
Что менять в Candle
Патч должен менять не математику attention, а место, где KV-heads
расширяются. Ищите вызов вроде repeat_kv,
repeat_interleave или reshape, который превращает
n_kv в n_q до вычисления attention.
Удобная граница для исправления выглядит так:
Q: [batch, n_q, q_len, head_dim]
K: [batch, n_kv, kv_len, head_dim]
V: [batch, n_kv, kv_len, head_dim]
Вместо materialize-расширения передайте эти tensor вместе с
group_size в fused SDPA. Внутри kernel каждая query-head
обращается к KV-head с индексом:
kv_head = query_head / group_size
Ниже приведён каркас патча. Названия функций зависят от версии Candle и вашего Metal backend, поэтому это пример места интеграции, а не готовый универсальный diff.
fn attention(
q: &Tensor,
k: &Tensor,
v: &Tensor,
scale: f64,
n_q: usize,
n_kv: usize,
) -> Result<Tensor> {
if n_q % n_kv != 0 {
bail!("n_q must be divisible by n_kv");
}
let group_size = n_q / n_kv;
// Не вызываем repeat_kv(k, group_size) и repeat_kv(v, group_size).
metal_fused_sdpa(
q,
k,
v,
scale,
group_size,
)
}
В kernel следует проверить границы индексов и поддержать causal mask.
Для decode обычно q_len == 1, поэтому путь для одного query
может быть отдельной специализацией. Важно не копировать K и V только ради
совместимости с формой Q.
Минимальная логика fused SDPA
Псевдокод вычисления для одной пары query-head и KV-head выглядит так:
for query_head in 0..n_q {
let kv_head = query_head / group_size;
for token in visible_tokens {
let score = dot(
q[query_head],
k[kv_head][token]
) * scale;
// causal mask применяется до softmax
scores[token] = score;
}
let weights = softmax(scores);
output[query_head] = weighted_sum(
weights,
v[kv_head]
);
}
Реальная реализация должна оставить вычисления на GPU, не создавать промежуточный tensor для повторенных голов и использовать тот же dtype, что и существующий Metal kernel. Для квантованных весов это не означает, что Q, K и V обязательно должны оставаться квантованными: проверьте текущую схему деквантизации и не переносите её в attention без необходимости.
Собираем и сравниваем
Соберите отдельную release-сборку после патча. Если проект использует lockfile, не обновляйте зависимости во время эксперимента.
cargo build --release --features metal
cargo run --release --features metal -- \
--model ./models/qwen2 \
--prompt "Explain grouped-query attention in one paragraph." \
--max-new-tokens 128 \
--measure decode
Повторите каждый вариант несколько раз после одинакового прогрева. Сравнивайте только декодирование, а не суммарное время загрузки модели и prompt-prefill. Для отчёта используйте одну таблицу:
| Вариант | Decode tokens/s | Память | Примечание |
|---|---|---|---|
| Baseline | заполнить | заполнить | KV-heads расширяются |
| Fused SDPA | заполнить | заполнить | расширение выполняется логически |
Ускорение считайте по формуле:
speedup = fused_decode_tokens_per_sec
/ baseline_decode_tokens_per_sec
Запишите также размер модели, commit патча, версию macOS, модель Mac, параметры Metal и точную команду запуска. Без этих данных число tokens/s трудно воспроизвести.
Типовые ошибки
-
Несовместимые формы. Проверьте, что
n_q % n_kv == 0, а head dimension совпадает для Q, K и V. - Неверная causal mask. Для decode позиция нового токена должна видеть весь доступный KV-cache, а не только последний элемент.
-
Скрытая материализация. Уберите не только явный
repeat_kv, но и операции, которые возвращают contiguous tensor размераn_q. - Сравнение разных режимов. Prefill и decode имеют разные профили. Не смешивайте их в одном показателе.
- Ошибки dtype. Если kernel ожидает float16, не передавайте float32 без явного решения. Это может увеличить память и изменить производительность.
Ограничения подхода
Fused SDPA не устраняет стоимость чтения KV-cache и не делает квантованные матричные операции бесплатными. Выигрыш зависит от размера группы, длины контекста, реализации Metal kernel и баланса между attention и остальными слоями.
Если текущий backend уже выполняет повторение голов внутри kernel, внешний патч может не дать ускорения. В этом случае измеряйте не только tokens/s, но и аллокации, объём переданных данных и время отдельного attention участка.
Итог
Чтобы ускорить декодирование Qwen2 на Metal в Candle, сначала найдите materialize-расширение KV-heads, затем перенесите отображение query-head → KV-head внутрь fused SDPA. После этого сравните baseline и патч на одинаковом prompt, контексте и числе новых токенов. Только измерение на конкретном Apple M2 покажет фактический выигрыш вашей сборки.
Для связанных практических материалов откройте раздел guides, а определения терминов проверьте в глоссарии.