本页目录

AI Runner 离线 AI 推理引擎(无头服务端 / HTTP+WebSocket API)

airunner · Capsize-Games/airunner

AI Runner 是一个采用 GPL-3.0 的离线 AI 推理项目,官方简介涵盖图像生成、实时语音对话、LLM 聊天机器人与自动化工作流。据 README,本仓库现为无头服务端,提供模型 worker、运行时编排、持久化以及 HTTP/WebSocket API;Qt 桌面应用...

其他 Pygame Python 网络联机 音频系统 高级
★ Stars 1,317 Forks 104 License GPL-3.0 更新 2026-11-19

国内开发环境适配

Windows
未知
Linux
官方声明支持
macOS
未知
引擎 / 框架:Pygame 暂无中文教程标记 未标记站长实测
README 说明 airunner-common、facehuggershield、airunner-tts-vendor 的 PyPI 发布处于暂停或未解决状态,相关 extras 无法从公共索引解析,国内访问 GitHub Release 与 Actions 制品可能更困难,建议提前准备可访问的代理或内部镜像,并核验包来源。Linux CUDA 配置档固定 CUDA 12.9 PyTorch 栈与哈希锁 wheel,下载体积大。Docker 开发路径需 GH_TOKEN 拉取 Actions 制品。国内镜像源可用性与实际解析结果待核验。

中文项目介绍

AI Runner 是一个以 GPL-3.0-only 许可发布的离线推理项目,由 Capsize LLC 的一名工程师构建与发布,并通过 GitHub Sponsors 接受赞助以维持维护。仓库的 README 明确说明:本仓库当前提供的是无头服务端——为其他应用提供模型 worker、运行时编排、持久化以及 HTTP/WebSocket API;早期的 Qt 桌面应用与付费桌面商店已经退役,不再随本仓库维护。

因此,阅读这个仓库时应当把它当作一套「推理后端 / 本地模型服务」来理解,而不是一个带图形界面的桌面软件。项目主页指向 airunner.art,仓库内同时提供 Issue 模板(缺陷报告、功能请求)与安全公告入口,便于外部贡献者与使用者反馈问题。

需要注意的是,仓库的 GitHub 简介与 Topics 仍包含图像生成、实时语音对话、LLM 聊天机器人、自动化工作流等关键词;但 README 的正式叙述已收窄为服务端能力,图像与语音相关功能在代码中的实际成熟度需要读者自行核验,文档本身并不给出功能矩阵。

补充说明

仓库组成与包结构

README 用一张表列出了仓库内外的关键组成部分:

  • services/:守护进程、FastAPI 路由、运行时编排、下载与持久化,是服务的核心。
  • native/:Python 启动器与运行时布局辅助工具。
  • airunner-common(独立仓库):服务包所依赖的共享契约与配置定义。
  • airunner-native(独立仓库):负责构建并发布 llama.cpp 与 whisper.cpp 的 sidecar 组件。

这种拆分意味着服务本体与本地推理后端(llama.cpp / whisper.cpp)是解耦的:主仓库通过 sidecar 方式调用原生推理程序,而公共契约被抽到独立包中以便多包复用。

安装与依赖状态

README 对依赖状态的描述相当克制,并且反复强调「不要以此绕过可用性问题」:

  • 包元数据要求 Python 3.13.3 或更新版本;Linux CUDA 配置档固定使用 CUDA 12.9 的 PyTorch 栈。
  • 仓库没有定义经过验证的通用硬件或语言支持矩阵,模型与运行时需求随负载类型变化。
  • 服务 extras 包括 core、llm-native、stt-native、art-python、tts-python、tts-python-core;headless 聚合 LLM、STT、图像与 TTS 运行时;desktop 只是更宽服务配置的遗留名称,不会安装任何 GUI;linux-release 是当前的 Linux 候选聚合,排除 TTS vendor;development 面向贡献者与打包工具。
  • 部分 extras 仍无法从配置的公共索引解析:airunner-common 与 facehuggershield 的 PyPI 发布处于暂停状态,airunner-common==6.1.8 需从评审过的 GitHub Release 获取,FacehuggerShield 通过可选的 legacy-shield extra 提供且被 linux-release 排除。
  • TTS 相关 extras 依赖 airunner-tts-vendor,其 PyPI 可用性问题记录在 issue #2413;tts-python、headless、desktop、all 等继承该依赖,因此无法从公共索引安装。Linux linux-release 排除该依赖,OpenVoice 与 Melo 支持在该发布配置中被推迟。

在依赖可从受认可来源获取时,贡献者可用 uv 建立隔离环境(uv venv --python 3.13 .venv 后以 -e 方式安装 services[development] 与 native)。README 特别提示该命令并非上述依赖问题的绕行方案。

Docker Compose 运行方式

仓库为「检出源码开发」与「已发布镜像」分别准备了两套 compose 文件:

  • 开发路径:先用 scripts/stage_docker_release_inputs.py 把哈希锁定的运行时、构建器与 pip 引导 wheel 暂存到检出目录之外的临时目录,再通过 AIRUNNER_DOCKER_REVIEWED_INPUTS 环境变量指向该目录,执行 docker compose -f docker-compose.dev.yml run --rm --service-ports airunner。
  • 发布路径:直接使用 docker-compose.release.yml,引用 ghcr.io/capsize-games/airunner/airunner:linux-headless 镜像。README 同时声明该镜像的仓库可用性与实际运行行为在本次文档更新中尚未验证。

开发镜像的构建过程使用评审过的 pip wheel 引导系统 Python(因为暂存输入不包含受评审的 uv 可执行文件),随后在无索引模式下使用暂存的哈希锁安装依赖。暂存前需要在环境中设置对有 Actions 制品读权限的 GH_TOKEN,命令本身不会打印或持久化该 token;未设置 AIRUNNER_DOCKER_REVIEWED_INPUTS 时,compose 会直接失败并指向该说明。

两套 compose 都会绑定宿主 127.0.0.1:8080,并挂载本地的 AI Runner 数据目录与 Hugging Face 缓存目录;--service-ports 用于在 docker compose run 时发布配置端口。

无头服务与安全注意

无头 CLI 默认只监听回环地址。若要绑定到非回环地址,必须提供 AIRUNNER_API_KEY;--insecure-no-auth 选项会跳过该校验,README 明确建议不要在面向网络的服务中使用它。健康检查端点为 /health,适合与容器编排或探活脚本配合。

开发校验与延伸文档

README 给出的最小校验方式是在依赖解析完成后、于仓库根目录运行聚焦的服务测试:.venv/bin/python -m pytest services/tests/test_service_bootstrap.py -q。同时提醒:运行时冒烟与功能测试可能需要 sidecar、模型文件或 GPU 资源,测试被跳过或缺少资源并不等同于「已支持该运行时」。

项目信息区列出了继续深入的入口:服务包指南、原生包指南、systemd 部署指南、Agent 评测测试文档、分层产品架构文档、许可证与安全策略。对想了解「服务端 + sidecar + 契约包」如何分层的读者,架构文档是首选。

学习建议

  • 若你关注本地离线推理服务的工程化组织方式,可重点阅读 services/ 的 FastAPI 路由与运行时编排层,理解 worker 与持久化如何解耦。
  • 若关注端侧原生推理集成,airunner-native 的 llama.cpp / whisper.cpp 构建与发布流程值得对照阅读。
  • 若只想快速跑起来,优先走 release compose 路径;若需要改代码,再走 dev compose 的暂存输入流程,并预期较长的依赖准备时间。
  • 部署前务必确认依赖来源可用性与镜像是否可达,README 已明确说明这些内容不在已验证范围内。

开源许可证与版权说明

许可证标识:GPL-3.0。源码、资源与依赖许可可能不同,请以官方仓库为准。本站仅做索引,不托管源码。

相似项目