jhqxxx
11 KiB
11 KiB
安装指南
本指南介绍如何在您的系统上安装和设置 AHA。
目录
前置要求
必需
-
Rust 工具链：Rust 1.85 或更高版本（edition 2024）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -
Git：用于克隆仓库
# Ubuntu/Debian sudo apt-get install git # macOS brew install git # Windows # 从 https://git-scm.com/download/win 下载
可选（用于 FFmpeg 功能）
- FFmpeg 开发库：音频/视频处理所需
安装方法
方法 1：从源码构建
克隆仓库并构建：
git clone https://github.com/jhqxxx/aha.git
cd aha
# 构建发布版本
cargo build --release
# 二进制文件位于 target/release/aha
方法 2：从 Crates.io 安装（当可用时）
cargo install aha
方法 3：启用特定功能构建
使用特定功能构建：
# 启用 CUDA 支持（NVIDIA GPU）
cargo build --release --features cuda
# 启用 Metal 支持（Apple Silicon）
cargo build --release --features metal
# 启用 Flash Attention
cargo build --release --features cuda,flash-attn
# 启用 FFmpeg 支持
cargo build --release --features ffmpeg
平台特定说明
Linux
Ubuntu/Debian
# 安装构建依赖
sudo apt-get update
sudo apt-get install -y build-essential pkg-config git clang cmake
# FFmpeg 功能所需
sudo apt-get install -y ffmpeg libavutil-dev libavcodec-dev \
libavformat-dev libavfilter-dev libavdevice-dev \
libswresample-dev libswscale-dev
# CUDA 支持，从 https://developer.nvidia.com/cuda-downloads 安装 CUDA toolkit
Fedora/RHEL
# 安装构建依赖
sudo dnf install gcc gcc-c++ make git clang pkg-config
# FFmpeg 功能所需
sudo dnf install ffmpeg-devel
# CUDA 支持
sudo dnf install cuda-devel
macOS
Apple Silicon (M1/M2/M3/M4)
# 安装 Rust（如果尚未安装）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# 安装命令行工具
xcode-select --install
# FFmpeg 功能所需
brew install ffmpeg
# 启用 Metal 支持以进行 GPU 加速
cargo build --release --features metal
Intel Mac
# 安装 Rust（如果尚未安装）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# 安装命令行工具
xcode-select --install
# FFmpeg 功能所需
brew install ffmpeg
# CUDA 支持（如果您有 NVIDIA GPU）
# 从 https://developer.nvidia.com/cuda-downloads 安装 CUDA
cargo build --release --features cuda
Windows
使用 MSVC
# 从 https://rustup.rs/ 安装 Rust
# 从 https://visualstudio.microsoft.com/downloads/ 安装 Visual Studio Build Tools
# FFmpeg 功能
# 从 https://ffmpeg.org/download.html 下载 FFmpeg
# 设置 FFMPEG_DIR 环境变量指向您的 FFmpeg 安装目录
# 构建
cargo build --release
使用 WSL2（推荐）
# 在 WSL2 中按照 Linux 说明操作
wsl
sudo apt-get update
sudo apt-get install -y build-essential pkg-config git clang cmake
功能特性
AHA 支持多个可选功能：
cuda
启用 NVIDIA GPU 加速的 CUDA 支持。
cargo build --release --features cuda
要求：
- NVIDIA GPU
- CUDA Toolkit 11.0 或更高版本
- cuDNN 库
优势：
- 推理速度提升 10-50 倍
- 支持更大的模型
- 降低 CPU 使用率
metal
启用 Apple Silicon GPU 加速的 Metal 支持。
cargo build --release --features metal
要求：
- Apple Silicon (M1/M2/M3/M4)
- macOS 11.0 或更高版本
优势：
- 推理速度提升 5-20 倍
- 更低的功耗
- 支持更大的模型
flash-attn
启用 Flash Attention 以优化长序列处理。
cargo build --release --features cuda,flash-attn
要求：
- 启用 CUDA 功能
- 支持的 GPU 架构（计算能力 7.0+）
优势：
- 减少内存使用
- 长序列推理更快
- 对视觉模型特别有益
注意：必须与 cuda 功能一起使用。
ffmpeg
启用 FFmpeg 支持以进行音频/视频处理。
cargo build --release --features ffmpeg
要求：
- FFmpeg 开发库
- 特定平台（见上文）
优势：
- 扩展的音频格式支持（MP3、AAC 等）
- 视频处理能力
- 更好的音频重采样
组合功能
您可以组合多个功能：
# NVIDIA GPU 上的最佳性能
cargo build --release --features cuda,flash-attn
# 带音频支持的 Apple Silicon
cargo build --release --features metal,ffmpeg
# 启用所有功能
cargo build --release --features cuda,flash-attn,ffmpeg
验证安装
安装后，验证 AHA 是否正常工作：
# 检查版本
./target/release/aha --version
# 列出支持的模型
./target/release/aha list
# （如果已安装到 PATH）
aha --version
aha list
aha list 的预期输出：
#Supported models:
Available models:
Model ID Owner type Download
--------------------------------------------------------------------------------
LiquidAI/LFM2-1.2B LiquidAI llm ✔
LiquidAI/LFM2.5-1.2B-Instruct LiquidAI llm ✔
LiquidAI/LFM2.5-VL-1.6B LiquidAI vlm ✔
LiquidAI/LFM2-VL-1.6B LiquidAI vlm ✔
OpenBMB/MiniCPM4-0.5B OpenBMB llm ✔
Qwen/Qwen2.5-VL-3B-Instruct Qwen vlm ✔
Qwen/Qwen2.5-VL-7B-Instruct Qwen vlm
Qwen/Qwen3-0.6B Qwen llm ✔
Qwen/Qwen3-1.7B Qwen llm
Qwen/Qwen3-4B Qwen llm
Qwen/Qwen3.5-0.8B Qwen vlm ✔
Qwen/Qwen3.5-2B Qwen vlm
Qwen/Qwen3.5-4B Qwen vlm
Qwen/Qwen3.5-9B Qwen vlm
qwen3.5-gguf none vlm
Qwen/Qwen3-ASR-0.6B Qwen asr ✔
Qwen/Qwen3-ASR-1.7B Qwen asr
Qwen/Qwen3-VL-2B-Instruct Qwen vlm ✔
Qwen/Qwen3-VL-4B-Instruct Qwen vlm
Qwen/Qwen3-VL-8B-Instruct Qwen vlm
Qwen/Qwen3-VL-32B-Instruct Qwen vlm
deepseek-ai/DeepSeek-OCR deepseek-ai ocr ✔
deepseek-ai/DeepSeek-OCR-2 deepseek-ai ocr
Tencent-Hunyuan/HunyuanOCR Tencent-Hunyuan ocr ✔
PaddlePaddle/PaddleOCR-VL PaddlePaddle ocr ✔
PaddlePaddle/PaddleOCR-VL-1.5 PaddlePaddle ocr
AI-ModelScope/RMBG-2.0 AI-ModelScope image ✔
OpenBMB/VoxCPM-0.5B OpenBMB tts ✔
OpenBMB/VoxCPM1.5 OpenBMB tts ✔
ZhipuAI/GLM-ASR-Nano-2512 ZhipuAI asr ✔
FunAudioLLM/Fun-ASR-Nano-2512 FunAudioLLM asr ✔
ZhipuAI/GLM-OCR ZhipuAI ocr ✔
故障排除
构建错误
"error: linking with cc failed"
通常表示缺少系统依赖。
解决方案：为您的平台安装所需的构建工具（见平台特定说明）。
"error: CUDA not found"
启用了 CUDA 功能但未安装 CUDA toolkit。
解决方案：
- 从 https://developer.nvidia.com/cuda-downloads 安装 CUDA toolkit
- 或不使用 CUDA 构建：
cargo build --release
"error: Metal not available"
启用了 Metal 功能但硬件不支持。
解决方案：
- 确保您在 Apple Silicon 上
- 或不使用 Metal 构建：
cargo build --release
运行时错误
"error while loading shared libraries"
缺少运行时库。
解决方案：安装所需的库（见平台特定说明）。
"Out of memory"
模型对于可用 RAM/VRAM 太大。
解决方案：
- 使用更小的模型
- 关闭其他应用程序
- 启用 GPU 加速以获得更好的内存效率
"Model download failed"
网络问题或磁盘空间不足。
解决方案：
- 检查互联网连接
- 确保
~/.aha/中有足够的磁盘空间 - 重试：如果中断，下载将恢复
性能问题
推理速度慢
解决方案：
- 启用 GPU 加速：
--features cuda或--features metal - 启用 Flash Attention：
--features "cuda,flash-attn" - 使用更小的模型
- 检查是否正在使用 GPU（应在监控工具中看到 GPU 使用率）
CPU 使用率高
解决方案：
- 启用 GPU 加速
- 减少批处理大小
- 使用低精度模型
系统要求
注：模型不同需求不同的硬件和软件，供参考
最低要求
- CPU：x86_64 或 ARM64
- RAM：8 GB（推荐 16 GB）
- 磁盘：10 GB 用于模型（因模型而异）
- OS：Linux、macOS 或 Windows
推荐要求
- CPU：现代多核处理器
- RAM：24 GB 或更多
- GPU：NVIDIA GPU（带 CUDA）或 Apple Silicon
- 磁盘：具有 50+ GB 可用空间的 SSD
- OS：Linux (Ubuntu 22.04+) 或 macOS (Monterey+)
模型大小
流行模型的大致下载大小：
| 模型 | 大小 | RAM 使用 |
|---|---|---|
| Qwen/Qwen3-0.6B | ~1.2 GB | ~2 GB |
| Qwen/Qwen3-VL-2B-Instruct | ~4 GB | ~6 GB |
| Qwen/Qwen3-VL-8B-Instruct | ~16 GB | ~20 GB |
| Qwen/Qwen3-VL-32B-Instruct | ~64 GB | ~70 GB |
后续步骤
成功安装后：