airunner

环境要求

• Linux 桌面环境（README 的安装示例基于 Ubuntu/Debian），Docker GUI 模式需要 X11
• 已安装 Docker 与 docker compose
• 手动 Python 安装需 Python 3.13+，推荐 pyenv + venv
• 使用 CUDA 加速需安装 NVIDIA CUDA 工具链（nvidia-cuda-toolkit）
• 磁盘空间充足，用于存放本地模型与构建 sidecar

安装与启动步骤

1. 1获取项目代码

   Docker 与脚本安装都需要在仓库目录内执行，先把仓库克隆到本地并进入目录。

   git clone https://github.com/Capsize-Games/airunner.git
   cd airunner

   复制

2. 2Docker 启动图形界面

   README 推荐方式。先放开 X11 访问权限，再启动 GUI 容器，退出后容器自动删除。

   xhost +local:docker && docker compose run --rm airunner

   复制

3. 3Docker 启动无头服务

   以 headless 模式运行 HTTP API 服务；必须带 --service-ports，否则 8080 端口不会映射到宿主机。

   docker compose run --rm --service-ports airunner --headless

   复制

4. 4精简依赖重建镜像

   按部署需要指定安装 profile 列表重建镜像，可去掉用不到的运行时依赖。

   docker build --build-arg AIRUNNER_INSTALL_PROFILES=core,llm-native,stt-native -t airunner:headless .

   复制

5. 5开发者脚本安装

   适合基于仓库开发的场景，默认复用 ./venv，以可编辑模式安装并构建本地 sidecar。

   ./scripts/install.sh

   复制

6. 6分布式角色安装

   把守护进程与 GUI 客户端分开安装，可部署在不同机器上，分别指定 role。

   ./deployment/install_distributed.sh --role daemon
   ./deployment/install_distributed.sh --role gui-client

   复制

7. 7安装系统依赖

   手动安装路径的第一步，Ubuntu/Debian 下安装编译工具、音频、Qt 与语言包等系统库。

   sudo apt update && sudo apt install -y build-essential cmake git curl wget pkg-config nvidia-cuda-toolkit pipewire libportaudio2 libxcb-cursor0 espeak espeak-ng-espeak qt6-qpa-plugins qt6-wayland libsentencepiece-dev mecab libmecab-dev mecab-ipadic-utf8 libxslt-dev mkcert

   复制

8. 8PyPI 安装 GUI

   先装 CUDA 12.9 版 torch 系列，再安装桌面 GUI 包与含模型运行时的服务包。

   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu129
   pip install "airunner"
   pip install "airunner-services[headless]"

   复制

关键配置

如何确认成功

Docker 无头模式访问 http://localhost:8080/health 能返回健康状态；GUI 模式会弹出桌面窗口。

常见问题

注意事项

• README 明确标注 Docker 为推荐安装方式，GUI 模式依赖 X11，必须先执行 xhost +local:docker。
• Python 版本要求 3.13+，推荐使用 pyenv 与 venv 管理环境。
• base tts-python profile 有意排除了 MeCab 日语/韩语语音包，避免额外原生编译步骤。
• README 只给出了 Linux/Ubuntu 相关安装示例，Windows 与 macOS 步骤未提供。