Project AIRI 完全指南：自托管 AI 虚拟伙伴的架构、功能与开发实战
Project AIRI 完全指南自托管 AI 虚拟伙伴的架构、功能与开发实战【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本文以 Project AIRI仓库 docs/README.ko-KR.md 等本地化 README为骨架系统梳理这个以复现 Neuro-sama 为目标的自托管 AI 虚拟伙伴项目从项目定位、多平台安装方式到 Web 优先的技术选型、脑/耳/嘴/身四层功能路线图再到 pnpm 工作区下的 Web、桌面Electron、移动Capacitor三端开发实战最后结合仓库源码剖析其 LLM Provider 体系与 Server Channel 通信架构。读完本文你将掌握如何安装、运行、开发并扩展属于自己的数字生命。项目定位把 AI 虚拟伙伴的灵魂装进自托管的容器借助 ChatGPT、Claude 等大语言模型向虚拟角色索取角色扮演与对话早已不是难事Character.ai、JanitorAI 等平台与 SillyTavern 等本地方案也能提供聊天或视觉冒险类体验。但 Project AIRI 提出了一个不同的追问AI 能否真正玩起来——能否看到你编码、边玩游戏边聊天、看视频并持续与你互动这正是 AIRI 从 Neuro-sama 获得灵感的地方Neuro-sama 是目前能玩游戏、聊天并与观众实时互动的顶尖 AI VTuber但它是闭源的直播结束便无法再与其互动。AIRI 的目标因此非常直白——让你随时随地在自己的设备上拥有一个可复现的数字生命AI 妻子、数字宠物、能够一起玩耍交谈的数字伴侣。项目自述将其定位为赛博生命的灵魂容器a container of souls并明确声明是受 Neuro-sama 启发的开源再创作而非商业闭源方案。仓库根 package.json 将项目描述为 LLM powered virtual character版本号与桌面端发行包一致当前0.12.0-beta.5。整个仓库采用 pnpm 工作区monorepo组织工作区覆盖apps/**、packages/**、integrations/**、server/**、docs/**、engines/**等这决定了后续所有开发命令都建立在 pnpm workspace 之上。快速上手四种安装与获取方式官方 README 为不同平台的用户提供了开箱即用的安装路径以下命令均完整保留自文档在线体验浏览器 / 移动端可直接访问官方演示站点 airi.moeru.ai 试用浏览器版本由于浏览器版本是完整 PWA手机等移动设备同样可以直接运行无需安装原生应用。WindowswingetWindows 用户可用 winget 一键安装winget install MoeruAI.AIRIWindowsScoop也可以借助 Scoop bucket 安装scoop bucket add airi https://github.com/moeru-ai/airi scoop install airi/airimacOSHomebrew CaskmacOS 无需添加自定义 tap直接用 Homebrew Cask 安装brew install --cask airi桌面端发行物仓库 README 提供了 Windowsx64 setup 安装包与 macOSApple Silicon dmg的官方 release 下载入口Linux 用户则指向 latest release 页面获取对应包桌面应用 ID 为ai.moeru.airi可在 apps/stage-tamagotchi/package.json 中确认。重要安全提醒官方 README 明确警告——项目从未发行任何官方加密货币或代币遇到相关宣传务必警惕并自行甄别。这一声明同时说明该项目的开源性质一切能力来自自托管与自带模型/API 配置而非任何代币经济。技术选型Web 优先的设计哲学与原生性能的取舍与其他 AI VTuber 开源项目不同AIRI 从开发第一天起就围绕现代 Web 技术栈设计README 列出的核心技术包括WebGPU浏览器内的 GPU 计算与渲染接口为本地推理与 3D 渲染铺路WebAudio音频捕获、分析与合成支撑语音输入与实时说话检测Web Workers将音频处理、推理等重任务移出主线程保证 UI 流畅WebAssembly承载 ONNX Runtime、Transformers.js 等推理运行时WebSocket实现浏览器端与本地/远端服务通道Server Channel的实时双向通信。针对Web 技术会不会性能不佳的疑虑README 给出了明确回应浏览器版本意在展示浏览器与 WebView 的能力上限但项目并不完全依赖它——桌面版本默认可调用 NVIDIA CUDA 与 Apple Metal得益于 HuggingFace 的 candle 项目无需繁琐的依赖管理而图形、布局、动画以及进行中的插件系统则部分复用 Web 技术以换取跨端一致性与开发效率。这一设计带来的直接结果是AIRI 能在现代浏览器与设备上运行移动端PWA同样可用同时为开发者保留了启用非 Web 能力的灵活性——例如连接 Discord 语音频道或与朋友一起玩 Minecraft、Factorio。在 apps/stage-web/package.json 的依赖中可以印证这一技术栈onnxruntime-web、huggingface/transformers、three、tresjs/core、vite-plugin-pwa等一应俱全。功能全景与路线图脑、耳、嘴、身四层架构README 以脑 / 耳 / 嘴 / 身四个维度划分当前实现进度这一结构直观地对应了虚拟生命体的感知—决策—表达链路大脑Two Brains玩游戏已支持 Minecraft、FactorioPoC 与 demo 已提供、Kerbal Space Program公告待发Helldivers 2 合作游玩进行中聊天渠道Telegram、Discord 已支持记忆已支持纯浏览器内数据库DuckDB WASM 与 pgliteMemory Alaya 进行中纯浏览器本地WebGPU推理规划中。耳朵Ears浏览器语音输入、Discord 语音输入客户端语音识别客户端 ASR与客户端说话检测VAD均已实现。嘴Mouth多提供商语音合成ElevenLabs、Microsoft/Azure Speech、OpenAI 兼容 TTS、阿里云 Model Studio、本地 Kokoro TTS 等。身体BodyVRM 支持模型控制以及自动眨眼、自动视线追踪、待机视线移动等动画能力Live2D 支持模型控制同样具备自动眨眼、自动视线追踪、待机视线移动。从源码层面看大脑的载体是 packages/core-agent含 agents、runtime、session、contracts、messages 等模块耳朵/嘴的音频管线集中在 packages/pipelines-audio而 VRM/Live2D 渲染器分别对应 packages/stage-ui-three 与 packages/stage-ui-live2d 等包均可在仓库中按需深入。开发指南从源码构建三端应用README 明确指出默认pnpm dev启动的是 Stage Web浏览器版开发服务器如需开发桌面版须阅读 CONTRIBUTING 指南并正确配置环境。仓库根 package.json 的 scripts 与 README 的说明一一对应。通用准备在仓库根目录安装依赖并启动pnpm i pnpm devStage Web浏览器版对应 airi.moeru.aipnpm devStage Tamagotchi桌面版Electronpnpm dev:tamagotchiTamagotchi 还附带 Nix 包启用 flakes 后可直接运行nix run github:moeru-ai/airi从 apps/stage-tamagotchi/package.json 可以看到该应用基于electron-vite构建electron-vite dev/electron-vite build并内置了 electron-builder 的 Windows/macOS/Linux 打包脚本build:win、build:mac、build:linux以及 Flatpak 支持目录结构上分为mainElectron 主进程、preload、renderer、shared四个部分。Stage Pocket移动版Capacitor启动 Capacitor 开发服务器pnpm dev:pocket:ios --target DEVICE_ID_OR_SIMULATOR_NAME # 或通过环境变量指定 CAPACITOR_DEVICE_ID_IOSDEVICE_ID_OR_SIMULATOR_NAME pnpm dev:pocket:ios需要注意两点README 特别强调模拟器名称含空格如iPhone 16 Pro目标名必须用引号包裹查看可用设备/模拟器列表的命令是pnpm -F proj-airi/stage-pocket exec cap run ios --list——capacitor/cli仅声明在apps/stage-pocket中因此在仓库根目录下直接执行cap是解析不到的。Pocket 无线连接模式若需要 Pocket 以无线模式连接 Tamagotchi 的服务器通道须以 root 权限启动 Tamagotchisudo pnpm dev:tamagotchi然后在 Tamagotchi 的settings/connections中启用安全 WebSocket。文档站点pnpm dev:docs版本发布运行 bumpp 更新 monorepo 版本号npx bumpp --no-commit --no-tag另外根 package.json 还提供了dev:backenddocker compose -f server/docker-compose.yaml up --build用于拉起托管后端、dev:serverserver-runtime 开发、dev:uistage-ui 的 Story 开发等脚本按需使用。LLM API 提供商支持矩阵基于 xsai 的统一抽象README 用一个长长的清单展示了 AIRI 的 LLM Provider 支持情况并注明其建立在 xsaiVercel AI SDK 的轻量替代仓库内以xsai/*系列包引入之上。已支持[x]的提供商包括AIHubMix推荐、OpenRouter、vLLM、SGLang、Ollama、302.AI、OpenAI、Anthropic Claude、DeepSeek、Qwen通义千问、Google Gemini、xAI、Groq、Mistral、Cloudflare Workers AI、Together.ai、Fireworks.ai、Novita、Zhipu智谱、SiliconFlow硅基流动、Stepfun阶跃星辰、Baichuan百川、Minimax、Moonshot AI月之暗面、ModelScope魔搭、Player2、Tencent Cloud腾讯云、Xiaomi Mimo小米 MiMo尚未支持[ ]且欢迎 PR 的有Azure OpenAI API、AWS ClaudeBedrock、Sparks讯飞星火、Volcano Engine火山引擎。这一矩阵在源码中有扎实的实现支撑packages/provider-inference 维护了一个可移植的 Provider 注册表入口 packages/provider-inference/src/index.ts 通过createProviderRegistry(portableProviderDefinitions)构建注册表对外暴露getDefinedProvider(id)与listProviders()两个核心 API并在providers/cloud/下为每家厂商提供了独立实现可看到 anthropic、openai、ollama、cloudflare-workers-ai、deepseek 等目录。这意味着在 UI 中新增/配置一家模型厂商本质上就是在注册表中登记一个新的 Provider 定义——理解这一点对自部署时排查某个模型接不通或想换一家 API非常有帮助。整体架构Stage 应用、共享包与 Server ChannelREADME 用一张 mermaid 流程图给出了项目全景本文完整继承并保留如下这张图清晰揭示了四个层次Stage 应用层stage-web浏览器版、stage-tamagotchi桌面版、stage-pocket移动版标记为 experimental三个前端壳共享产品包层stage-uiUI 组件库仓库中规模最大的包之一、core-agent/core-character领域逻辑、pipelines-audio音频管线、stage-ui-live2d/stage-ui-three等渲染器、server-sdk/server-sharedSDK 契约桌面服务器通道Server Channelserver-runtime运行在桌面端与 SDK 通过 WebSocket 双向通信——这是 AIRI 把浏览器/移动端与桌面端能力打通的关键。从源码看packages/server-runtime/src/index.ts 基于crossws与proj-airi/better-ws构建 WebSocket 服务实现了事件编解码server-ws/airi/codec、路由与鉴权timingSafeEqual做安全比较、心跳帧MessageHeartbeat保活等并对 JSON 消息有严格的错误处理集成与托管后端层discord-bot、minecraft-bot等通过 SDK 接入Telegram、Factorio、MCP 等为可选api-server/auth-server经由 Caddy 暴露后端使用 PostgreSQL Redis。值得一提的是stage-tamagotchi的 main 进程服务目录 apps/stage-tamagotchi/src/main/services 同时存在airi/与electron/两类服务与桌面端承载 server channel 原生能力的定位相符而 integrations/discord-bot 采用 adapters/bots/pipelines 的结构接入同一套 SDK 契约印证了集成即插件的架构意图。子项目生态围绕 AIRI 生长出来的工具链README 记录了从 Project AIRI 中孵化出的多个子项目体现了造 AI VTuber 顺便造轮子的务实路线awesome-ai-vtuberAI VTuber 及相关项目的精选列表unspeech面向/audio/transcriptions与/audio/speech的通用端点代理服务器类似 LiteLLM 但覆盖所有 ASR/TTShfup支持部署与打包到 HuggingFace Spaces 的工具xsai-transformers为 xsAI 提供的实验性 Transformers.js ProviderWebAI Realtime Voice Chat从零实现 ChatGPT 实时语音VAD STT LLM TTS的完整示例drizzle-duckdb-wasm / duckdb-wasmDuckDB WASM 的 Drizzle ORM 驱动与易用封装对应仓库 packages/drizzle-duckdb-wasm 与 packages/duckdb-wasmAIRI Factorio让 AIRI 玩 Factorio 的项目含autorio自动化库与开发期 mod 热重载插件tstl-plugin-reload-factorio-mod等配套Velin用 Vue SFC 与 Markdown 管理状态化 LLM 提示词demodel加速多推理运行时下模型与数据集下载inventory集中式模型目录与默认 Provider 配置的后端服务MCP Launcher一键构建并运行 MCP 服务器的启动器模型世界的 OllamaSAD自托管并在浏览器中运行 LLM 的文档与笔记。此外 README 也坦诚地列出了若干同类开源项目如 7 天复现 Neuro-sama 的 Neuro、擅长 VRM/WebXR 的 amica、聚焦 Agent 集成的 eliza 等作为对比参考便于读者横向评估定位差异。社区、翻译与贡献项目设有面向所有子项目的专门组织 proj-airi涵盖 RAG、记忆系统、嵌入式数据库、图标、Live2D 工具等多个领域翻译工作依托 Crowdin 上的 proj-airi 翻译项目进行若你觉得某处翻译不准确可以自由参与贡献——本文所依据的 docs/README.ko-KR.md 即属于该多语言体系英文主版在 docs/README.md另有 zh-CN、ja-JP、ru-RU、vi、fr 等版本项目仍处于开发早期README 明确欢迎各类贡献者不仅限于 Vue.js / TypeScript 开发者也欢迎艺术家、设计师甚至愿意帮项目迈出第一场直播的人即便你习惯 React、Svelte 或 Solid也可以为 AIRI 创建子目录来实验自己想加的功能。官方文档列出的求贤领域包括 Live2D/VRM 建模、VRChat 头像设计、计算机视觉、强化学习、语音识别与合成、ONNX Runtime、Transformers.js、vLLM、WebGPU、Three.js、WebXR 等。小结Project AIRI 的价值在于把闭源限时直播的 Neuro-sama转化为随时可自托管的开源数字生命框架Web 优先但保留 CUDA/Metal 原生算力的双轨技术路线脑/耳/嘴/身四层功能规划基于 xsai 与 provider-inference 的开放模型接入体系以及通过 server-runtime WebSocket 通道把 Web、桌面、移动、聊天集成Discord/Minecraft/Telegram串成一体的架构。对于想打造个人 AI 伙伴、研究 AI Agent 游戏能力或复刻 AI VTuber 管线的开发者而言这份 README 与仓库源码本身就是一份高完整度的参考实现。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考