piqc: находим утечки GPU-бюджета в Kubernetes

Что такое piqc?

piqc — это source-available коллектор фактов для AI-инференса на Kubernetes-кластерах. Он собирает факты с учётом модели: что запущено, на каком железе, с какими затратами и каким расходом впустую — и упаковывает их в стандартизированный пакет фактов (facts bundle), который передаётся на уровень оптимизации. Кроме того, piqc выводит читаемый отчёт о стоимости, позволяя сразу принять меры без какой-либо внешней платформы.

Это самый быстрый способ ответить на вопрос: сколько GPU-бюджета прямо сейчас тратит впустую мой Kubernetes-кластер?

piqc
  └── inference collector (vLLM-native)     ← собирает факты о модели, GPU, KV-кеше, пропускной способности
  └── hardware collector (plugin)           ← вендоры подключают собственную телеметрию
        ├── nvidia/   (DCGM, MIG state)
        ├── amd/      (ROCm metrics)
        └── your-hardware/

Факты поступают на уровень оптимизации Paralleliq, который соотносит расточительство с конкретными моделями и направляет устранение проблем через согласованные с человеком рабочие процессы. piqc работает и автономно — платформа не нужна, чтобы уже получить ценность из отчёта о стоимости.

piqc выявляет три типа неэффективности, которые стандартный мониторинг Kubernetes (kubectl top, kube-state-metrics, Prometheus node exporters) не обнаруживает самостоятельно:

Простаивающие аллокации (Idle allocation) — поды, удерживающие GPU-ресурсы при почти нулевой загрузке вычислений
Несоответствие уровня оборудования (Tier misplacement) — модели, запущенные на GPU-уровнях с избыточной памятью или производительностью
Тёмная ёмкость (Dark capacity) — GPU-узлы, на которых не запланировано ни одного пода

Инструмент работает с любым Kubernetes-кластером, на котором выполняются GPU-нагрузки для инференса — GKE, EKS, AKS, on-prem или bare metal. Основной поддерживаемый фреймворк инференса — vLLM; рабочие нагрузки Ray Serve также определяются (тип GPU, утилизация и стоимость — более глубокие метрики, такие как KV-кеш и пропускная способность по токенам, специфичны для vLLM). Сбор фактов об аппаратном обеспечении реализован через плагины — подробнее в разделе Разработка плагина для оборудования.

Как выглядит результат

Запустите piqc scan на своём кластере и получите мгновенный отчёт о стоимости:

                                              Discovered Inference Deployments
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Deployment                  ┃ Engine  ┃ GPU                ┃ Replicas ┃ Age ┃ GPU Util ┃  MFU ┃ $/1K tokens ┃   $/hr ┃   Idle $/day ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━┩
│ meta-llama/Llama-3-70B-Inst │ vllm    │ 8xH100-SXM4-80GB ⚠ │        2 │  6h │       4% │ 3.1% │     $0.0842 │ $68.00 │    $1,566.72 │
│ mistral-7b-instruct         │ vllm    │ 1xA100-SXM4-40GB ⚠ │        1 │  2d │      11% │ 8.4% │     $0.0073 │  $2.50 │       $53.40 │
│ codellama-34b-staging       │ vllm    │ 4xH100-SXM4-80GB ⚠ │        1 │ 19d │       0% │  N/A │         N/A │ $17.00 │      $408.00 │
│ embedding-bge-large         │ vllm    │ 1xT4 ✓             │        3 │ 14h │      82% │  N/A │     $0.0002 │  $1.35 │        $5.83 │
│ unknown-runtime-7f3a2       │ unknown │ 2xA100-SXM4-80GB ? │        1 │ 31d │      N/A │  N/A │         N/A │  $7.00 │ util unknown │
└─────────────────────────────┴─────────┴────────────────────┴──────────┴─────┴──────────┴──────┴─────────────┴────────┴──────────────┘

  ⚠ tier larger than this model requires   ·   ? model size unknown — fit not checked   ·   Age running 3+ days — confirm it's still needed

╭──────────────────────────────────── Cost Summary ──────────────────────────────────────╮
│   Total GPU spend rate      : $95.85/hr                                                │
│                                                                                        │
│   Leased & idle (util <60%) : $2,033.95/day  (low utilization — may reflect traffic    │
│ patterns; worth investigating)                                                         │
│   Unallocated nodes         : $1,152.00/day  (12 GPU(s) with no pods scheduled)        │
│   Tier misplacement         :   $721.20/day  (3 model(s) on oversized GPU tier)        │
│                                                                                        │
│   Total estimated leak      : $3,907.15/day  ($1,426,110/yr at current rate)           │
│                                                                                        │
│   Confirmed waste   : unallocated nodes, tier misplacement                             │
│   Signals to investigate: low GPU utilization (verify against traffic data)            │
│                                                                                        │
│   Avg MFU (active deployments) : 15.7%  (healthy range: 30–60%)                        │
╰────────────────────────────────────────────────────────────────────────────────────────╯
  ─────────────────────────────────────────────────────────────
  → Want to know what this waste is actually costing you?
  Paralleliq turns these signals into confirmed findings with dollar impact,
  continuous monitoring, and automated remediation — so you act on facts, not guesses.
  Running proprietary models or on-prem hardware? We'll configure it for your exact costs.
  Free to get started: paralleliq.ai  ·  Questions? sam@paralleliq.ai

piqc бесплатен и доступен в исходных кодах (лицензия Business Source License 1.1, с переходом на Apache 2.0 в 2028 году). Сканирование даёт полную картину — что запущено, на каком железе, во сколько это обходится и где утечка бюджета. Для непрерывного мониторинга, алертинга по всему парку и автоматизированных рабочих процессов устранения проблем см. paralleliq.ai.

🚀 Быстрый старт

Вариант 1: Запуск как Kubernetes Job (рекомендуется)

Выполняется внутри кластера — не нужно возиться с Docker-аутентификацией или kubeconfig:

# Шаг 1 — Применить права RBAC (однократная настройка)
kubectl apply -f https://raw.githubusercontent.com/paralleliq/piqc/main/deploy/rbac.yaml

# Шаг 2 — Запустить сканирование
kubectl apply -f https://raw.githubusercontent.com/paralleliq/piqc/main/deploy/scan-job.yaml

# Шаг 3 — Просмотреть вывод
kubectl logs -f job/piqc-scan -n kube-system

# Очистить после завершения
kubectl delete job piqc-scan -n kube-system

Job удаляется автоматически через 10 минут (ttlSecondsAfterFinished: 600).

Хотите видеть динамику, а не только снимок? Одно сканирование показывает расточительство на сегодня. Чтобы наблюдать изменения со временем — рост тёмной ёмкости, повторяющееся несоответствие уровней — запускайте сканирование по расписанию и отправляйте результаты на платформу. Два способа сделать это:

Одна команда: чарт helm/piqc — устанавливает RBAC и повторяющийся скан вместе. Перед установкой выполните helm template, чтобы увидеть, что именно будет применено; подробнее в helm/piqc/README.md.
Чистый YAML без Helm: deploy/scan-cronjob.yaml — тот же скан, те же права RBAC, только с повторением по расписанию и аутентификацией через API-ключ кластера вместо однократного локального запуска.

Вариант 2: Установка из PyPI и запуск локально

# Рекомендуется — pipx устанавливает piqc в изолированное окружение
pipx install piqc

# Или через pip (см. предупреждение ниже)
pip install piqc

piqc scan --format table

Используйте pipx, а не обычный pip install, если у вас уже есть другие Python CLI-инструменты. piqc требует pydantic v2. Такие инструменты, как dstack, фиксируют версию pydantic v1, поэтому обычный pip install piqc в общее окружение (например, conda base) может молча обновить или понизить версию pydantic и сломать их. pipx полностью изолирует зависимости piqc, исключая подобные конфликты.

Вариант 3: Запуск через Docker с вашего ноутбука

# Экспортировать статический kubeconfig со встроенными учётными данными
kubectl config view --raw --flatten > /tmp/piqc-kubeconfig.yaml

# Запустить сканирование
docker run --rm \
  -v /tmp/piqc-kubeconfig.yaml:/root/.kube/config \
  ghcr.io/paralleliq/piqc:latest \
  scan --format table

Поддерживаются платформы linux/amd64 и linux/arm64.

Вариант 4: Установка из исходников

git clone https://github.com/paralleliq/piqc.git
cd piqc
poetry install
poetry run piqc scan --format table

✨ Возможности

🔍 Интеллектуальное обнаружение

Автоопределение: автоматически находит развёртывания инференса на базе vLLM и Ray Serve во всех пространствах имён
Взвешенная оценка достоверности: использует несколько сигналов (образы, переменные окружения, аргументы CLI, метки) с взвешенной оценкой
Определение фреймворка: с высокой точностью идентифицирует vLLM и Ray Serve с помощью сопоставления шаблонов и эвристик

📊 Комплексный сбор метрик

Метрики GPU: утилизация GPU в реальном времени, память, температура и потребляемая мощность через nvidia-smi
Метрики среды выполнения: сбор метрик vLLM API, включая:
- задержку запросов (P50, P95, P99)
- пропускную способность по токенам (prefill и decode)
- утилизацию KV-кеша
- глубину очереди и активные запросы
- состояние работоспособности

💰 Обнаружение неэффективности

Низкая утилизация GPU — развёртывания ниже порога 60% утилизации с указанием суточных и годовых потерь в деньгах
Тёмная ёмкость — GPU-узлы без запланированных подов (оплачиваемые, но простаивающие)
Несоответствие уровня — модели на завышенном GPU-уровне с оценкой разницы стоимости в день
Фрагментация — узлы со свободными GPU-слотами, слишком маленькими для любой из работающих моделей
Ожидающие GPU-поды — нагрузки, заблокированные в очереди планировщика, с указанием времени ожидания
Панель сводки затрат — общая скорость расходов, все категории расточительства, суммарная оценочная утечка в день и в год
MFU (Model FLOPS Utilization) — наблюдаемые вычисления по сравнению с теоретическим пиком GPU для каждого развёртывания
Стоимость за 1K токенов — расходы на GPU, переведённые в бизнес-метрику, сопоставимую с ценообразованием API

🔭 Отчёт о покрытии (`--coverage`)

Слой аппаратного обеспечения GPU — DCGM exporter, NVIDIA device plugin, обнаружение функций GPU/узла: что реально инструментировано, а что нет
Слой фреймворка обслуживания — достоверность обнаружения vLLM и GPU-поды, не соответствующие ни одной известной сигнатуре обслуживания
Стек наблюдаемости — наличие Prometheus Operator, факт сбора метрик vLLM, наличие OpenTelemetry Collector
Трёхуровневая отчётность (обнаружено / частично подключено / не видно отсюда) — без жёсткого «прошёл/не прошёл», поскольку «не видно» может означать как реальное отсутствие, так и нахождение вне текущей области RBAC для piqc
Только чтение, как и весь piqc — несколько дополнительных вызовов Kubernetes API для обнаружения, никаких новых прав на запись

📄 Несколько форматов вывода

Формат	Описание
Table	Отчёт о стоимости с MFU, $/1K токенов, суточными потерями от простоя (по умолчанию)
YAML	Файлы развёртываний инференса в стиле Kubernetes
JSON	Машиночитаемый вывод в формате JSON
PIQC Facts	Стандартизированный пакет фактов для интеграции с управляющим уровнем

Формат

Описание

Table

Отчёт о стоимости с MFU, $/1K токенов, суточными потерями от простоя (по умолчанию)

YAML

Файлы развёртываний инференса в стиле Kubernetes

JSON

Машиночитаемый вывод в формате JSON

PIQC Facts

Стандартизированный пакет фактов для интеграции с управляющим уровнем

🚀 Готовность к производственной среде

Параллельная обработка: многопоточное сканирование с настраиваемым числом воркеров
Поддержка RBAC: преднастроенные манифесты ClusterRole и ServiceAccount
Гибкие режимы: автоопределение, удалённый (kubeconfig) или внутрикластерный режим выполнения
Управление таймаутами: настраиваемые таймауты операций
Docker-образ: готовый мультиплатформенный образ (linux/amd64 + linux/arm64) в GitHub Container Registry

🔌 Аппаратные плагины

Сбор фактов об оборудовании в piqc спроектирован как подключаемый. Коллектор инференса (vLLM) поддерживается в этом репозитории. Производители оборудования вносят собственные коллекторы, используя ту же схему фактов — так поддержка телеметрии AMD, Intel и нестандартного железа добавляется без изменения ядра системы.

🔴 Плагин AMD GPU

Аппаратный плагин для GPU AMD Instinct через rocm-smi:

Обнаружение AMD Instinct MI250X/MI300X
Утилизация GPU, метрики памяти и температуры
Интеграция с экосистемой ROCm
Разработан сообществом / AMD

🌐 LLM-D (LLM-Distributed)

Обнаружение и документирование распределённого инференса LLM:

Картирование топологии распределённого инференса
Метрики координации GPU на нескольких узлах
Агрегация производительности между узлами
Анализ распределённого KV-кеша

Хотите разработать аппаратный плагин? См. раздел Разработка плагина для оборудования.

🔌 Интеграции с оркестраторами

dstack

paralleliq-dstack-plugin (PyPI) подключается к системе плагинов dstack. Когда парк GPU или задача применяется к dstack-проекту на Kubernetes-бэкенде, плагин выводит команды сканирования piqc — так вы сразу знаете, стоит ли проверить кластер, на который dstack только что выполнил подготовку, на предмет расточительства.

pip install paralleliq-dstack-plugin

dstack обнаруживает плагин автоматически через точки входа Python — дополнительная настройка не требуется. Подробнее о том, что плагин делает сегодня и о его текущих ограничениях, см. в репозитории плагина.

vLLM Production Stack

Предложено, ожидает рассмотрения. vLLM Production Stack — это эталонное развёртывание vLLM на Kubernetes на основе Helm, с собственным стеком наблюдаемости Prometheus/Grafana и руководством по выгрузке KV-кеша на основе LMCache. piqc дополняет этот стек, а не конкурирует с ним — он находится над этой телеметрией и превращает её в приоритизированные, оценённые в деньгах выводы (неиспользуемая GPU-ёмкость, простаивающие развёртывания, низкий процент попаданий в prefix-кеш), а не в ещё один дашборд. Черновик руководства, написанного в стиле их документации — docs/integrations/26-detect-gpu-waste.md, — подготовлен для предложения в качестве PR в их папку tutorials/.

📋 Команды

`piqc scan`

Сканирует Kubernetes-кластер на наличие нагрузок инференса и выявляет расточительство GPU.

piqc scan [OPTIONS]

Параметры сканирования

Параметр По умолчанию Описание

Параметр	По умолчанию	Описание
`--kubeconfig PATH`	`~/.kube/config`	Путь к файлу kubeconfig
`--context TEXT`	текущий	Используемый контекст Kubernetes
`-n, --namespace TEXT`	все	Конкретное пространство имён для сканирования
`--format [yaml\|json\|table]`	`yaml`	Формат вывода
`-o, --output PATH`	`./output`	Директория вывода для сгенерированных файлов

--kubeconfig PATH

~/.kube/config

Путь к файлу kubeconfig

--context TEXT

текущий

Используемый контекст Kubernetes

-n, --namespace TEXT

все

Конкретное пространство имён для сканирования

--format [yaml|json|table]

yaml

Формат вывода

-o, --output PATH

./output

Директория вывода для сгенерированных файлов

Параметры сбора данных

Параметр По умолчанию Описание

Параметр	По умолчанию	Описание
`--collect-runtime`	`false`	Собирать метрики среды выполнения через vLLM API
`--no-exec`	`false`	Отключить exec в подах (пропустить метрики GPU)
`--no-logs`	`false`	Отключить чтение логов
`--aggregate/--no-aggregate`	`aggregate`	Агрегировать метрики по репликам подов
`--contribute-benchmarks`	`false`	Передавать анонимизированные данные о производительности GPU/модели в датасет бенчмарков Paralleliq
`--coverage`	`false`	Также сообщать о том, какую инфраструктуру GPU, фреймворк обслуживания и стек наблюдаемости видит скан в вашем кластере (только для табличного вывода)

--collect-runtime

false

Собирать метрики среды выполнения через vLLM API

--no-exec

false

Отключить exec в подах (пропустить метрики GPU)

--no-logs

false

Отключить чтение логов

--aggregate/--no-aggregate

aggregate

Агрегировать метрики по репликам подов

--contribute-benchmarks

false

Передавать анонимизированные данные о производительности GPU/модели в датасет бенчмарков Paralleliq

--coverage

false

Также сообщать о том, какую инфраструктуру GPU, фреймворк обслуживания и стек наблюдаемости видит скан в вашем кластере (только для табличного вывода)

Когда сканирование завершается в интерактивном терминале (табличный вывод, найдены результаты), piqc один раз задаёт пропускаемый вопрос: отправить ли имя/компанию/email вместе с кратким резюме скана в Paralleliq для последующей связи. Отказ — чистый выход, ничего не отправляется. При запуске в скриптах, через пайп или с флагами --format json/yaml этот запрос никогда не появляется.

Параметры вывода

Параметр По умолчанию Описание

Параметр	По умолчанию	Описание
`--combined`	`false`	Создать единый объединённый файл вывода
`--output-piqc`	`false`	Создать `piqc-facts.json` (схема PIQC v0.1)

--combined

false

Создать единый объединённый файл вывода

--output-piqc

false

Создать piqc-facts.json (схема PIQC v0.1)

Параметры выполнения

Параметр По умолчанию Описание

Параметр	По умолчанию	Описание
`--timeout INT`	`30`	Таймаут операции в секундах
`--workers INT`	`10`	Количество параллельных воркеров
`--mode [auto\|remote\|incluster\|dry-run]`	`auto`	Режим выполнения
`-v, --verbose`	`false`	Включить подробный вывод
`--debug`	`false`	Включить режим отладки с детальной трассировкой

--timeout INT

30

Таймаут операции в секундах

--workers INT

10

Количество параллельных воркеров

--mode [auto|remote|incluster|dry-run]

auto

Режим выполнения

-v, --verbose

false

Включить подробный вывод

--debug

false

Включить режим отладки с детальной трассировкой

Примеры

# Базовое сканирование — обнаружить все развёртывания vLLM и выявить расточительство
piqc scan

# Сканирование конкретного пространства имён с выводом в JSON
piqc scan -n production --format json

# Быстрое сканирование без метрик GPU (быстрее)
piqc scan --no-exec

# Сбор метрик среды выполнения из vLLM API
piqc scan --collect-runtime

# Также сообщить о покрытии инфраструктуры GPU / фреймворка обслуживания / наблюдаемости
piqc scan --format table --coverage

# Создать пакет фактов PIQC для интеграции с управляющим уровнем
piqc scan --output-piqc -o ./facts

# Табличный вывод в консоль (для человека)
piqc scan --format table

# Пользовательский kubeconfig и контекст
piqc scan --kubeconfig /path/to/config --context my-cluster

# Передать анонимизированные бенчмарки GPU/модели в датасет Paralleliq
piqc scan --contribute-benchmarks

`piqc test-connection`

Проверяет подключение к Kubernetes-кластеру и необходимые права.

piqc test-connection [OPTIONS]

Параметр По умолчанию Описание

Параметр	По умолчанию	Описание
`--kubeconfig PATH`	`~/.kube/config`	Путь к файлу kubeconfig
`--context TEXT`	текущий	Используемый контекст Kubernetes

--kubeconfig PATH

~/.kube/config

Путь к файлу kubeconfig

--context TEXT

текущий

Используемый контекст Kubernetes

`piqc version`

piqc version

📁 Форматы вывода

Табличный формат (по умолчанию)

Запустите piqc scan --format table — никаких дополнительных флагов не нужно. Пример вывода см. в разделе Как выглядит результат выше.

Маркеры столбца GPU (соответствие уровня, отображаются рядом с типом GPU):

Символ Значение

Символ	Значение
`✓`	Модель находится на подходящем GPU-уровне для своего размера
`⚠`	Модель избыточно обеспечена — GPU-уровень завышен
`?`	Число параметров не удалось извлечь из имени модели — соответствие не проверяется

✓

Модель находится на подходящем GPU-уровне для своего размера

⚠

Модель избыточно обеспечена — GPU-уровень завышен

?

Число параметров не удалось извлечь из имени модели — соответствие не проверяется

Столбец Age: отображается как 5m / 2h / 19d — время с момента создания подов развёртывания. Развёртывания, работающие 3+ дня, выделяются — о долгоработающих GPU-аллокациях легко забыть, а оплата продолжается незаметно.

Формат YAML

Создаёт отдельные YAML-файлы в стиле Kubernetes для каждого развёртывания:

apiVersion: piqc/v1
kind: InferenceDeployment
metadata:
  name: vllm-llama-7b
  namespace: inference
  collectionTimestamp: "2024-01-07T12:00:00Z"
  collectorVersion: "1.0.0"
model:
  name: meta-llama/Llama-2-7b-hf
  architecture: llama
  parameters: "7B"
  identificationConfidence: 0.95
engine:
  name: vllm
  version: "0.4.0"
  detectionConfidence: 0.95
inference:
  precision: float16
  tensorParallelSize: 4
  maxModelLen: 4096
  gpuMemoryUtilization: 0.90
resources:
  replicas: 2
  gpuCount: 4
  gpus:
    - type: A100-SXM4-80GB
      memoryTotal: "80GB"
      utilization: 87
      memoryUsed: 72000
runtimeState:
  vllm:
    healthStatus: healthy
    kvCacheUsagePercent: 45.2
    avgPromptThroughput: 1250.5
    avgGenerationThroughput: 85.3

Пакет фактов PIQC

С флагом --output-piqc создаётся стандартизированный пакет фактов для интеграции с уровнем оптимизации Paralleliq:

{
  "schemaVersion": "piqc-scan.v0.1",
  "generatedAt": "2026-06-20T12:00:00Z",
  "tool": {
    "name": "piqc",
    "version": "1.1.0"
  },
  "cluster": {
    "context": "my-context",
    "name": "my-cluster"
  },
  "objects": [
    {
      "workloadId": "ns/inference/deployment/vllm-llama-7b",
      "kind": "Deployment",
      "name": "vllm-llama-7b",
      "namespace": "inference",
      "facts": {
        "runtime.engineType": {"value": "vllm", "dataConfidence": "high"},
        "hardware.gpuType": {"value": "A100-SXM4-80GB", "dataConfidence": "high"},
        "hardware.gpuCount": {"value": 4, "dataConfidence": "high"},
        "obs.gpu.memUtilAvgPct": {"value": 87, "dataConfidence": "high"},
        "obs.vllm.kvCacheUsagePct": {"value": 45.2, "dataConfidence": "high", "units": "%"},
        "obs.vllm.requestsRunning": {"value": 3, "dataConfidence": "high"},
        "obs.vllm.requestsWaiting": {"value": 0, "dataConfidence": "high"},
        "k8s.ageHours": {"value": 18.5, "dataConfidence": "high", "units": "hours"}
      }
    },
    {
      "workloadId": "ns/gpu-pool/node/h100-node-07",
      "kind": "Node",
      "name": "h100-node-07",
      "namespace": "gpu-pool",
      "facts": {
        "hardware.gpuType": {"value": "nvidia-h100-80gb", "dataConfidence": "high"},
        "hardware.gpuCount": {"value": 4, "dataConfidence": "high"},
        "node.allocatedGpuCount": {"value": 2, "dataConfidence": "high"},
        "node.unallocatedGpuCount": {"value": 2, "dataConfidence": "high"}
      }
    }
  ]
}

Первый объект — обычная просканированная рабочая нагрузка. Второй — объект уровня узла, создаваемый, когда узел имеет GPU-ёмкость, которую ни один под не запросил (случай «тёмной ёмкости» из раздела об обнаружении расточительства); он не содержит фактов runtime./model., поскольку не описывает работающую нагрузку инференса.

📥 Установка

Требования

Python: 3.11 или выше
Доступ к Kubernetes: действительный kubeconfig с доступом к кластеру
Poetry: для установки из исходников

Установка из PyPI (рекомендуется)

# Изолированная установка — не конфликтует с другими Python-инструментами
pipx install piqc

piqc --version

pip install piqc тоже работает, но устанавливает в текущее активное окружение. piqc требует pydantic v2; такие инструменты, как dstack, фиксируют pydantic v1, поэтому установка piqc через обычный pip в окружение, где уже есть dstack (или что-либо другое, привязанное к pydantic v1), может его сломать. Если pipx не установлен, сначала установите его: python3 -m pip install --user pipx.

Установка из исходников

git clone https://github.com/paralleliq/piqc.git
cd piqc
poetry install
poetry run piqc --version

Установка для разработки

git clone https://github.com/paralleliq/piqc.git
cd piqc
poetry install --with dev
poetry run pytest tests/unit -v

🔐 Требования к RBAC в Kubernetes

piqc работает только на чтение. Он никогда не создаёт, не изменяет и не удаляет ресурсы в кластере. Единственное право на запись — pods/exec (для запуска nvidia-smi внутри подов с целью получения метрик GPU) — и его можно отключить флагом --no-exec.

kubectl apply -f https://raw.githubusercontent.com/paralleliq/piqc/main/deploy/rbac.yaml

Ресурс Действия Назначение

Ресурс	Действия	Назначение
`pods`	get, list	Обнаружение нагрузок инференса
`pods/exec`	create	Запуск nvidia-smi для метрик GPU
`pods/log`	get	Расширенное определение фреймворка
`namespaces`	get, list	Сканирование нескольких пространств имён
`deployments`	get, list	Получение метаданных развёртываний
`statefulsets`	get, list	Определение нагрузок StatefulSet
`services`	get, list	Обнаружение эндпоинтов, обнаружение OTel Collector (`--coverage`)
`nodes`	get, list	Анализ GPU-ёмкости / тёмной ёмкости
`servicemonitors.monitoring.coreos.com`	get, list	Необязательно — используется только с `--coverage` для проверки покрытия vLLM сбором метрик. Безвредно предоставлять даже без установленного Prometheus Operator.

pods

get, list

Обнаружение нагрузок инференса

pods/exec

create

Запуск nvidia-smi для метрик GPU

pods/log

get

Расширенное определение фреймворка

namespaces

get, list

Сканирование нескольких пространств имён

deployments

get, list

Получение метаданных развёртываний

statefulsets

get, list

Определение нагрузок StatefulSet

services

get, list

Обнаружение эндпоинтов, обнаружение OTel Collector (--coverage)

nodes

get, list

Анализ GPU-ёмкости / тёмной ёмкости

servicemonitors.monitoring.coreos.com

get, list

Необязательно — используется только с --coverage для проверки покрытия vLLM сбором метрик. Безвредно предоставлять даже без установленного Prometheus Operator.

🔧 Режимы выполнения

Режим Описание

Режим	Описание
`auto`	Автоматически определяет, выполняется ли piqc внутри кластера или удалённо
`remote`	Принудительный удалённый режим (использует kubeconfig)
`incluster`	Принудительный внутрикластерный режим (использует ServiceAccount)
`dry-run`	Имитация сканирования без доступа к кластеру

auto

Автоматически определяет, выполняется ли piqc внутри кластера или удалённо

remote

Принудительный удалённый режим (использует kubeconfig)

incluster

Принудительный внутрикластерный режим (использует ServiceAccount)

dry-run

Имитация сканирования без доступа к кластеру

🐛 Решение проблем

Ошибки плагина аутентификации Docker (GKE / EKS / AKS)

Используйте подход с Job внутри кластера (Вариант 1 в разделе Быстрый старт) — он выполняется внутри кластера и не требует плагинов аутентификации. Или экспортируйте статический kubeconfig:

kubectl config view --raw --flatten > /tmp/piqc-kubeconfig.yaml
docker run --rm -v /tmp/piqc-kubeconfig.yaml:/root/.kube/config ghcr.io/paralleliq/piqc:latest scan

Ошибки прав RBAC

kubectl auth can-i list pods --all-namespaces
kubectl auth can-i create pods/exec -n <namespace>
kubectl apply -f https://raw.githubusercontent.com/paralleliq/piqc/main/deploy/rbac.yaml

Метрики GPU недоступны

piqc scan --no-exec

📚 Структура проекта

piqc/
├── src/piqc/
│   ├── cli/                  # CLI-команды (scan, test-connection, version)
│   ├── collectors/           # Сборщики данных (конфигурация vLLM, метрики GPU)
│   ├── core/                 # Основная логика (оркестратор, обнаружение, k8s-клиент)
│   ├── generators/           # Генераторы вывода (YAML, JSON, Table, PIQC)
│   ├── models/               # Pydantic-модели данных (развёртывание инференса, схема PIQC)
│   ├── parsers/              # Парсеры конфигурации (vLLM)
│   └── utils/                # Утилиты (логирование, исключения)
├── tests/
│   ├── unit/                 # Модульные тесты
│   └── integration/          # Интеграционные тесты
├── rbac/                     # Манифесты Kubernetes RBAC
├── docs/                     # Документация
└── examples/                 # Примеры результатов сканирования и пакетов фактов

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

piqc сообщает, что не так. Уровень оптимизации Paralleliq замыкает цикл — принимает пакет фактов piqc, соотносит расточительство с конкретными моделями и направляет устранение проблем через согласованные с человеком рабочие процессы с полным журналом аудита.

→ paralleliq.ai · info@paralleliq.ai

Разработка плагина для оборудования

Сбор фактов об оборудовании в piqc спроектирован так, чтобы производители оборудования и участники сообщества могли добавлять поддержку собственных GPU или ускорителей без изменения основного коллектора инференса.

Аппаратный плагин — это коллектор, который:

Считывает телеметрию с целевого оборудования (через nvidia-smi, rocm-smi, вендорский BMC API или аналог)
Выдаёт факты по схеме фактов piqc (hardware.gpuType, hardware.gpuCount, observed.gpuUtilization и т. д.)
Располагается в директории src/piqc/collectors/hardware/<vendor>/

Коллектор инференса vLLM является эталонной реализацией. Если вы представляете производителя оборудования или хотите добавить поддержку AMD, Intel Gaudi или другого ускорителя, откройте issue или напишите на info@paralleliq.ai.

📄 Лицензия

Apache License 2.0 — подробнее в файле LICENSE.

piqc: находим утечки GPU-бюджета в Kubernetes

Что такое piqc?

Как выглядит результат

🚀 Быстрый старт

Вариант 1: Запуск как Kubernetes Job (рекомендуется)

Вариант 2: Установка из PyPI и запуск локально

Вариант 3: Запуск через Docker с вашего ноутбука

Вариант 4: Установка из исходников

✨ Возможности

🔍 Интеллектуальное обнаружение

📊 Комплексный сбор метрик

💰 Обнаружение неэффективности

🔭 Отчёт о покрытии (--coverage)

📄 Несколько форматов вывода

🚀 Готовность к производственной среде

🔌 Аппаратные плагины

🔌 Интеграции с оркестраторами

dstack

vLLM Production Stack

📋 Команды

piqc scan

Параметры сканирования

Параметры сбора данных

Параметры вывода

Параметры выполнения

Примеры

piqc test-connection

piqc version

📁 Форматы вывода

Табличный формат (по умолчанию)

Формат YAML

Пакет фактов PIQC

📥 Установка

Требования

Установка из PyPI (рекомендуется)

Установка из исходников

Установка для разработки

🔐 Требования к RBAC в Kubernetes

🔧 Режимы выполнения

🐛 Решение проблем

Ошибки плагина аутентификации Docker (GKE / EKS / AKS)

Ошибки прав RBAC

Метрики GPU недоступны

📚 Структура проекта

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

Разработка плагина для оборудования

📄 Лицензия

Похожее

🔭 Отчёт о покрытии (`--coverage`)

`piqc scan`

`piqc test-connection`

`piqc version`