Harmonia — ML Dependency Harmony
Harmonia detects GPU, CUDA, driver, OS, Python, and installed ML packages — then reports exactly what's compatible with what. Zero dependencies, works offline.
When To Use This Skill
- - User asks to set up a PyTorch or ML environment
- User hits a dependency error with torch, transformers, torchaudio, torchvision, accelerate, or CUDA
- User asks "what version of X works with Y" for ML packages
- User asks to check their GPU, CUDA, or driver setup
- User says something like "my torch is broken", "CUDA error", "version mismatch", "which torch for my Python"
- User is installing local models via Ollama or setting up training
Instructions
Step 1: Install harmonia (if not already installed)
CODEBLOCK0
Step 2: Choose the right command based on the user's need
Full environment scan — use when diagnosing issues:
harmonia check
This scans OS, Python, GPU, CUDA driver chain, torch, transformers, and known conflicts all at once.
Deep system diagnostics — use when the user asks specifically about GPU, CUDA, or driver:
harmonia doctor
Shows GPU model, VRAM, driver version, CUDA (nvidia-smi vs nvcc vs torch), glibc, virtualenv status.
Suggest compatible versions — use when the user wants to know what works together:
CODEBLOCK3
Show compatibility matrix — use when the user wants to see all options:
CODEBLOCK4
List known conflicts — use when the user hit a specific error:
harmonia conflicts
Shows known bug patterns with exact error messages and fixes.
JSON output — use for programmatic processing:
CODEBLOCK6
Step 3: Interpret the output for the user
- - Lines starting with
❌ are errors that must be fixed - Lines starting with
⚠️ are warnings worth noting - Lines starting with
✅ mean everything is fine - The
📦 Recommended compatible set section gives the exact versions to install - The
Install command at the bottom can be copied and run directly
Step 4: Help the user fix issues
When harmonia reports errors, help the user fix them by running the suggested commands. Common fixes:
- - Wrong companion version:
pip install torchaudio==2.5.1 (use the version harmonia suggests) - CUDA mismatch: Install torch with the correct CUDA index URL from the recommendation
- torch too old for transformers: INLINECODE6
- No virtualenv: INLINECODE7
Rules
- - Always run
harmonia check FIRST when a user reports any ML dependency issue — do not guess - Always show the full output to the user — do not summarize away important details
- If harmonia is not installed, install it with
pip install harmonia-ml before running commands - Do NOT try to manually diagnose version compatibility — let harmonia do it
- When harmonia suggests a fix, offer to run the fix command for the user
- If the user asks about versions not in harmonia's database, say so and suggest checking the official docs
Constraints
- - This skill only checks compatibility — it does not install or modify packages unless the user asks
- harmonia works offline with a local database — it does not make API calls
- The database covers PyTorch 2.0–2.5 and Transformers 4.24–5.x — very old versions may not be covered
Harmonia — ML依赖和谐工具
Harmonia能够检测GPU、CUDA、驱动、操作系统、Python版本以及已安装的ML包，然后准确报告哪些组件相互兼容。零依赖，可离线运行。
何时使用此技能
- - 用户要求搭建PyTorch或ML环境
- 用户遇到torch、transformers、torchaudio、torchvision、accelerate或CUDA相关的依赖错误
- 用户询问ML包的X版本与Y版本是否兼容
- 用户要求检查GPU、CUDA或驱动配置
- 用户反馈类似我的torch坏了、CUDA错误、版本不匹配、我的Python该用哪个torch
- 用户正在通过Ollama安装本地模型或配置训练环境
操作步骤
步骤1：安装harmonia（如未安装）
bash
pip install harmonia-ml
步骤2：根据用户需求选择正确的命令
完整环境扫描 — 用于诊断问题：
bash
harmonia check
此命令一次性扫描操作系统、Python、GPU、CUDA驱动链、torch、transformers及已知冲突。
深度系统诊断 — 当用户专门询问GPU、CUDA或驱动时使用：
bash
harmonia doctor
显示GPU型号、显存、驱动版本、CUDA（nvidia-smi vs nvcc vs torch）、glibc、虚拟环境状态。
推荐兼容版本 — 当用户想知道哪些组件可以一起使用时：
bash
与特定torch版本兼容的组件
harmonia suggest torch==2.5.1
与特定transformers版本兼容的组件
harmonia suggest transformers==4.44.2
针对特定Python + CUDA的最佳组合
harmonia suggest transformers --python 3.11 --cuda 12.1
显示兼容性矩阵 — 当用户想查看所有选项时：
bash
harmonia matrix pytorch
harmonia matrix transformers
列出已知冲突 — 当用户遇到特定错误时：
bash
harmonia conflicts
显示已知的错误模式，包含精确的错误信息和修复方法。
JSON输出 — 用于程序化处理：
bash
harmonia check --json
步骤3：为用户解读输出结果
- - 以❌开头的行是必须修复的错误
- 以⚠️开头的行是值得注意的警告
- 以✅开头的行表示一切正常
- 📦 推荐的兼容组件集部分给出需要安装的确切版本
- 底部的安装命令可以直接复制运行
步骤4：帮助用户修复问题
当harmonia报告错误时，通过运行建议的命令帮助用户修复。常见修复方法：
- - 错误的配套版本：pip install torchaudio==2.5.1（使用harmonia建议的版本）
- CUDA不匹配：根据推荐，使用正确的CUDA索引URL安装torch
- torch版本过旧，不支持transformers：pip install torch>=2.4.0
- 没有虚拟环境：python -m venv .venv && source .venv/bin/activate
规则
- - 当用户报告任何ML依赖问题时，始终先运行harmonia check — 不要猜测
- 始终向用户显示完整输出 — 不要省略重要细节
- 如果harmonia未安装，在运行命令前先使用pip install harmonia-ml安装
- 不要手动诊断版本兼容性 — 让harmonia来完成
- 当harmonia建议修复方案时，主动为用户运行修复命令
- 如果用户询问的版本不在harmonia的数据库中，如实告知并建议查看官方文档
约束条件
- - 此技能仅检查兼容性 — 除非用户要求，否则不会安装或修改包
- harmonia使用本地数据库离线运行 — 不进行API调用
- 数据库涵盖PyTorch 2.0–2.5和Transformers 4.24–5.x — 可能不包含非常旧的版本
