VeloQ CLI
CLI VeloQ отдает агенту данные профилей Nsight Systems, Nsight Compute и PyTorch в версионном JSON и ставит скиллы анализа.
- 131 ★ репозитория
- Последний коммит
- MIT
Расширенный доступ
Почему такой уровень
- Установочный скрипт из `curl` выполняется в оболочке и пишет в `~/.local/bin` и `~/.agents/skills/`.
- Читает файлы профилей и создает кеш и рисунки в папке `<report>.veloq/` рядом с отчетом.
Установка
- Работает в
Ручная установка
curl -fsSL https://raw.githubusercontent.com/lucifer1004/veloq/main/scripts/install.sh | bashLinux и macOS. Ставит бинарник в `~/.local/bin` и скиллы в `~/.agents/skills/`. Флаги `--no-skills` и `--no-binary` разделяют установку.
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- Установочный скрипт из `curl` выполняется в оболочке и пишет в `~/.local/bin` и `~/.agents/skills/`.
- Читает файлы профилей и создает кеш и рисунки в папке `<report>.veloq/` рядом с отчетом.
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
VeloQ читает экспорт GPU-профилей и отвечает на один вопрос одной командой. Три источника: Nsight Systems (временная шкала), Nsight Compute (отчеты по ядрам) и экспериментальный PyTorch/Kineto в формате Chrome trace. В списке 17 команд для NSys, 11 для NCU и 10 для PyTorch, плюс служебные `info`, `sources`, `clean`, `recipes`, `agent` и `self-update`. Вывод идет в одном JSON-конверте версии v1 с устойчивым ключом строки, а там, где удобно, доступны CSV и таблица. Агенту не приходится читать длинные текстовые выдачи `nsys` и `ncu`: он получает уже ограниченные строки с признаками усечения. К бинарнику прилагаются скиллы `nsys-profile-analysis`, `ncu-profile-analysis` и `pytorch-profile-analysis`.
Для кого. Разработчикам CUDA-ядер и ML-инженерам, которые отдают разбор GPU-профилей агенту Claude Code или Codex.
Подходит, если
- Нужно найти самые долгие ядра в трассе Nsight Systems и сгруппировать их по пути NVTX.
- Надо сравнить два прогона: у каждой строки устойчивый ключ, и выдачи сопоставимы.
- Агенту нужны метрики одного запуска ядра из отчета Nsight Compute, включая дизассемблирование и причины простоев варпов.
- Профиль PyTorch снят в формате Chrome trace, и в нем ищут коллективные операции и корреляции.
Не подходит, если
- Нужно интерактивно ковыряться во временной шкале: для этого есть GUI Nsight.
- Профилей нет: VeloQ читает готовый экспорт, а `nsys` и `ncu` не заменяет.
- Версия `nsys` старше 2024.6: ей нужен тип экспорта `parquetdir`.
Пример запроса к агенту
Покажи десять самых долгих ядер в trace.nsys-rep и сгруппируй их по пути NVTX.Ограничения
VeloQ читает экспорт `nsys` и `ncu` и не заменяет сами профилировщики NVIDIA, поэтому они нужны. Для трасс NSys минимальная версия `nsys` равна 2024.6. Источник PyTorch/Kineto помечен как экспериментальный. Установка одной командой работает на Linux x86_64 и aarch64 и на macOS x86_64 и arm64, на Windows берут `cargo binstall veloq` или готовый exe из релизов. Скиллы ставят только инструкции, а извлечение данных все равно требует бинарника `veloq` в PATH. Плагины агентов Codex и Claude подключает команда `veloq agent install`.
Как отключить. Команда `veloq agent uninstall claude` или `veloq agent uninstall codex` снимает плагин. Бинарник лежит в `~/.local/bin`, скиллы в `~/.agents/skills/`, их можно удалить. Кеш и рисунки хранятся рядом с отчетом в папке `<report>.veloq/`, чистит их `veloq clean`.
Частые вопросы
Как установить VeloQ для Claude Code?
Выполните установочный скрипт из README: он ставит бинарник `veloq` в `~/.local/bin` и скиллы анализа в `~/.agents/skills/`. Плагин для Claude подключает `veloq agent install claude`.
Какие профили читает VeloQ?
Отчеты Nsight Systems, отчеты Nsight Compute и экспериментально трассы PyTorch/Kineto в формате Chrome trace. Для NSys нужен `nsys` не старше версии 2024.6, потому что данные берутся через `nsys export -t parquetdir`.
Чем VeloQ лучше сырого вывода nsys в контексте агента?
Выдача сжата в строки с признаками усечения и одним версионным JSON-конвертом, поэтому тратится меньше токенов. У строк устойчивый ключ, и запуски можно сравнивать между собой.
Работает ли VeloQ на Windows?
Да. Бинарник ставят командой `cargo binstall veloq` или берут `veloq-x86_64-windows.exe` со страницы релизов. Скрипт установки в README рассчитан на Linux и macOS.
Какой формат вывода у VeloQ?
По умолчанию JSON в одном конверте версии v1: списки лежат в `data.rows[]`, ошибки имеют ту же форму и ненулевой код выхода. Для ряда команд доступны `--format csv` и `--format table`.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
CLI-инструментыСкилл для Claude Code разбирает отчеты Nsight Compute на Blackwell и ведет от замера ядра CUDA к диагнозу и плану оптимизации.
Локальный MCP-сервер профилирования: агент запускает профайлеры и бенчмарки и получает ограниченные данные о горячих точках
Читает локальные журналы Claude Code, Codex, Cursor и других агентов и показывает расход токенов, время и сбои в TUI
TUI показывает, что делают в проекте Claude Code, Codex, Gemini CLI и opencode: открытый файл, правки и команды вживую
DevLens строит граф репозитория один раз, и агент по MCP получает ранжированные файлы, вызовы и радиус изменений
Аудитор-черный ящик запускает готовый CLI, ловит побочные записи на диск и отдает агентам индекс команд с оценкой готовности.
Коротко о README
Страница репозитория знакомит с семейством CLI для профилей GPU: состав команд по трем источникам, формат JSON-конверта, сравнение с GUI Nsight и ручными скриптами на SQLite. Затем идут способы установки, быстрый старт с примерами и таблицы команд NCU с форматами вывода.