Project AIRI 全解析：自托管 Neuro-sama 式 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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi
导读
Project AIRI 是一个以「AI 虚拟伴侣 / 赛博生命体」为核心目标的自我托管开源项目，致力于把 Neuro-sama 这类「能玩游戏、能实时语音对话、拥有 Live2D/VRM 数字形象」的数字存在带进普通用户的日常设备。本文基于仓库中的日文版项目文档 README.ja-JP.md 整理而成，结合 apps、packages、integrations 等目录下的真实源码进行佐证与扩展。读完本文，你将掌握 AIRI 的项目定位、三大运行形态（Web / 桌面 / 移动）、完整安装与开发命令、支持的 LLM 与语音供应商矩阵，以及它从「大脑、耳朵、口、身体」四个层面构建数字生命体的整体架构思路。
一、项目定位：为什么要再造一个 Neuro-sama
1.1 出发点：开源可控的「数字伴侣」
Neuro-sama 是目前公认最优秀的 AI 数字主播之一，能够一边打游戏一边与观众实时聊天。但她的实现并非开源，直播结束后用户便无法与她互动。AIRI 项目的核心差异在于：任何人都可以自托管属于自己的数字生命体，随时、随地、随时可用，并完全拥有自己的「数字生活」。
1.2 现有方案的边界
ChatGPT、Claude 等大模型已经让「与 AI 角色扮演、聊天」变得足够简单，Character.ai、JanitorAI 等平台以及 SillyTavern 这类本地方案也提供了出色的聊天与视觉冒险游戏体验。但 AIRI 的文档进一步追问：游戏能力呢？看到用户编码的画面、一边打游戏一边聊天、看视频，以及更多其他能力呢？这正是 AIRI 与传统聊天机器人方案拉开距离的地方——它不仅是一个聊天框，还是一个能够「看到」和「行动」的智能体。
二、三大运行形态与技术栈
2.1 Web 技术驱动的核心设计
与多数 AI VTuber 开源项目不同，AIRI 从开发第一天起就全面拥抱 Web 技术栈：WebGPU、WebAudio、Web Workers、WebAssembly 与 WebSocket 均作为一等公民被支持（见文档「このプロジェクトの特別な点は？」一节）。
这意味着 AIRI 可以在现代浏览器与移动设备（PWA）上直接运行。依赖 apps/stage-web/package.json 可以看到浏览器版实际引入的技术组件：
@huggingface/transformers与onnxruntime-web：浏览器端模型推理vite-plugin-pwa：PWA 支持，实现移动端安装@tresjs/core与three：Three.js 3D 渲染（VRM 模型）@proj-airi/stage-ui-live2d、@proj-airi/stage-ui-three等渲染器包@proj-airi/pipelines-audio：音频处理流水线
同时，AIRI 并未把全部能力押注在 Web 上。桌面版默认支持 NVIDIA CUDA 与 Apple Metal（借助 HuggingFace 的 candle 推理框架），并且保留让用户启用「TCP 连接或非 Web 技术」的灵活性——例如接入 Discord 语音频道、与朋友联机玩 Minecraft 或 Factorio。
2.2 三种运行形态：Stage Web / Stage Tamagotchi / Stage Pocket
项目把客户端应用统称为「Stage（舞台）」，目前有三个形态：
| 应用 | 目录 | 形态 | 说明 |
|---|---|---|---|
| Stage Web | apps/stage-web | 浏览器版（含 PWA） | pnpm dev默认启动 |
| Stage Tamagotchi | apps/stage-tamagotchi | Electron 桌面应用 | macOS / Windows / Linux，附带 Nix 包 |
| Stage Pocket | apps/stage-pocket | Capacitor 移动应用 | iOS / Android（实验性） |
桌面版是功能最完整的形态：apps/stage-tamagotchi/package.json 显示它基于 Electron 构建，同时引入了@proj-airi/server-runtime（本地服务通道）、@proj-airi/plugin-sdk（插件系统）、@proj-airi/electron-screen-capture（屏幕捕获，用于让 AI「看到」你的屏幕）、uiohook-napi（全局键鼠钩子）等能力，并支持通过electron-builder产出 Win/macOS/Linux 安装包。
三、快速安装与获取
3.1 桌面版包管理器安装
Windows 用户可通过 winget 一键安装：
winget install MoeruAI.AIRI或使用 Scoop：
scoop bucket add airi https://github.com/moeru-ai/airi scoop install airi/airimacOS 用户无需自定义 tap，直接用 Homebrew Cask：
brew install --cask airi注：上述外部命令与链接来自原文档的安装指引部分；当前仓库为源码形态，实际版本安装以对应发布渠道为准。
3.2 离线二进制与移动端体验
- 仓库文档提供了 Windows（
v0.12.0-beta.5对应AIRI-0.12.0-beta.5-windows-x64-setup.exe）、macOS（darwin-arm64.dmg）及 Linux 的发布二进制下载入口； - Web 端可通过在线地址直接试用，移动端则支持 PWA 安装。
3.3 安全提示
原文档特别给出了官方警告：AIRI 从未发行任何官方加密货币或代币，请用户警惕相关误导信息。这一点在阅读第三方推广内容时务必留意。
四、从源码搭建开发环境
4.1 环境准备与依赖安装
AIRI 是一个 pnpm monorepo 工作区，工作区声明于根 package.json 的workspaces字段，覆盖packages/**、apps/**、integrations/**、services/**、engines/**、docs/**、server/**等目录。安装依赖并启动开发服务器：
pnpm i pnpm dev其中pnpm dev默认启动 Stage Web（浏览器版）的开发服务器。根 package.json 中该命令展开为pnpm -r -F @proj-airi/stage-web dev。
详细贡献流程请参阅 .github/CONTRIBUTING.md。
4.2 各形态开发命令速查
| 形态 | 命令 | 说明 |
|---|---|---|
| Stage Web（浏览器版） | pnpm dev | 根脚本默认行为 |
| Stage Tamagotchi（桌面） | pnpm dev:tamagotchi | 启动 Electron 开发环境 |
| Stage Pocket（移动） | pnpm dev:pocket | 启动 Capacitor Web 版开发服务器 |
| 文档站点 | pnpm dev:docs | 本地渲染 docs 站点 |
| iOS 真机运行 | CAPACITOR_DEV_SERVER_URL=https://<ip>:5273 pnpm open:ios | 打开 Xcode 后点击 Run |
对应脚本均可在根 package.json 的scripts段核对：dev:tamagotchi指向@proj-airi/stage-tamagotchi run dev，open:ios指向@proj-airi/stage-pocket run open:ios等。
4.3 Stage Pocket 的 iOS 联调细节
执行pnpm dev:pocket后，终端会输出形如：
ROLLDOWN-VITE v7.3.0 ready in 1073 ms ➜ Local: https://localhost:5273/ ➜ Network: https://<ip-will-be-here>:5273/ ➜ Vue DevTools: Open https://localhost:5273/__devtools__/ as a separate window ➜ Vue DevTools: Press Option(⌥)+Shift(⇧)+D in App to toggle the Vue DevTools ➜ UnoCSS Inspector: https://localhost:5273/__unocss/使用 Network 地址，在另一个终端设置开发服务器 URL 并打开 Xcode：
CAPACITOR_DEV_SERVER_URL=https://<your-ip-address>:5273 pnpm open:ios若需要在无线模式下连接 Pocket 到 Tamagotchi 的服务器通道，文档建议以 root 权限启动桌面端：
sudo pnpm dev:tamagotchi然后在 Tamagotchi 的settings/connections中启用 secure websocket。
4.4 Nix 运行方式
桌面版提供 Nix 包，启用 flakes 后可直接运行：
nix run github:moeru-ai/airi4.5 版本发布流程
发布时使用bumpp更新 monorepo 版本（不自动提交与打 tag）：
npx bumpp --no-commit --no-tag当前仓库版本为v0.12.0-beta.5（见根 package.json 的version字段）。
五、「大脑」：能力与功能路线图
原文档以「脑 / 耳 / 口 / 体」四个比喻组织功能状态，下面完整还原并补充源码佐证。
5.1 脑（思考与行动）
- ✅ 游玩 Minecraft —— 集成代码见 integrations/minecraft，其中
src/minecraft-bot-runtime.ts与src/airi子目录承载机器人运行时 - ✅ 游玩 Factorio（进行中，已有 PoC 与 demo）—— 相关自动化库见
autorio子项目 - ⏳ 一起玩 Helldivers 2（进行中）
- ✅ Telegram 聊天 —— integrations/telegram-bot
- ✅ Discord 聊天 —— integrations/discord-bot
- 记忆能力：
- ✅ 浏览器内数据库支持（DuckDB WASM /
pglite）—— 对应包 packages/drizzle-duckdb-wasm 与 packages/duckdb-wasm - ⏳ 记忆阵列（进行中）
- ✅ 浏览器内数据库支持（DuckDB WASM /
- ⏳ 浏览器内本地（WebGPU）推理
从源码看，「脑」的核心由 packages/core-agent 承担，其中包含agents/、runtime/、session/、messages/、contracts/等子模块与配套测试，实现会话编排、上下文管理与工具调用等 Agent 运行时能力。
5.2 耳（听觉输入）
- ✅ 浏览器语音输入
- ✅ Discord 语音输入
- ✅ 客户端侧语音识别（STT）
- ✅ 客户端侧说话人检测（VAD）
音频能力对应 packages/pipelines-audio（26 个源文件），同时 packages/audio 提供底层音频工具。测试与演示方面，仓库还维护了 packages/testing-audio 用于语音流水线的验证。
5.3 口（语音合成）
✅ 已支持多供应商 TTS，包括：
- ElevenLabs
- Microsoft / Azure Speech
- OpenAI 兼容 TTS
- 阿里云 Model Studio（百炼）
- 本地 Kokoro TTS
5.4 体（数字形象）
- ✅ VRM 支持（模型控制）—— 渲染实现见 packages/stage-ui-three，桌面端还集成 MMD（packages/stage-ui-mmd）与 Spine（packages/stage-ui-spine）
- ✅ VRM 动画：自动眨眼、自动视线追踪、待机眼部微动
- ✅ Live2D 支持（模型控制）—— packages/stage-ui-live2d
- ✅ Live2D 动画：自动眨眼、自动视线追踪、待机眼部微动
5.5 近期 DevLog 时间线
原文档列出的一系列 DevLog 展示了项目演进脉络（2025.06 ～ 2026.03）：
- 2026.03.23：移动端性能与游戏引擎选型
- 2026.03.14：VRM 舞台的生命周期、缓存与可观测性
- 2026.02.16：Dome Keeper 数据采集与学习流水线
- 2026.01.01：AIRI Pocket 与 FlowChat 的存储实验
- 2025.10.20：Electron 迁移、新模型与 Moeru AI 更新
- 2025.08.26：airi-factorio 纯视觉方向进展
- 2025.08.05：AIRI v0.7 发布亮点
- 2025.08.01：流式文本动画与字素簇（grapheme cluster）
- 2025.07.18：从 Factorio Learning Environment 反思 airi-factorio
- 2025.06.16：DreamLog 0x1 项目背景故事
六、支持的 LLM 与语音供应商矩阵
6.1 LLM 提供商（基于 xsai）
AIRI 的 LLM 接入基于自研的 xsai 库（类似 Vercel AI SDK 的精简实现）。原文档列出的已支持提供商如下：
已支持 ✅：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、腾讯云、小米 MiMo。
期待 PR ⏳：Azure OpenAI、AWS Claude（Amazon Bedrock）、Spark（讯飞星火）、火山引擎。
这一供应商矩阵在仓库中也有实现层面的印证：packages/provider-inference 的src/providers/cloud/目录下可见openai/、anthropic/、deepseek/、groq/、mistral-ai/、moonshot-ai/、minimax/、modelscope/、cloudflare-workers-ai/、together-ai/、fireworks-ai/、openrouter-ai/、xai/、zai/（智谱）等独立目录；src/providers/local/下则有ollama/、lm-studio/、browser-web-speech-api/、voicevox/等本地运行时实现。
6.2 推理层的设计意图
从 packages/provider-inference 的目录结构可以推断，AIRI 通过「cloud / local」两层抽象把云端 API 与本地模型统一收敛到同一套推理接口上：云端侧覆盖各大厂商的 OpenAI 兼容与非兼容端点，本地侧则覆盖 Ollama、LM Studio、浏览器 Web Speech API、VOICEVOX、vLLM TTS 等场景，再配合registry.ts的运行时矩阵注册机制（runtime-matrix.test.ts与runtime-matrix.browser.test.ts分别验证 Node 与浏览器运行时的注册一致性）。
七、整体架构：Stage + 共享包 + 服务通道 + 托管后端
原文档用一张 Mermaid 流程图描述了项目整体架构，下面转述为可读的分层说明（对应 apps、packages、integrations、server 目录）。
- Stage 应用层：Web（stage-web）、Desktop（stage-tamagotchi）、Pocket（stage-pocket，实验性）
- 共享产品包层：stage-ui（UI 组件库，packages/stage-ui，包含 200+ 个 Vue 组件与 490+ 个 TS 模块）、core-agent / core-character（领域逻辑，packages/core-agent、packages/core-character）、pipelines-audio（packages/pipelines-audio）、渲染器（stage-ui-live2d、stage-ui-three 等）、server-sdk / server-shared（packages/server-sdk、packages/server-shared）
- 桌面服务通道层：server-runtime（packages/server-runtime），与 SDK 通过
server channel双向通信 - 集成层：discord-bot（integrations/discord-bot）、minecraft-bot（integrations/minecraft）、Telegram、Factorio、MCP 等可选接入 SDK
- 托管后端层：Caddy 网关（server/dev/caddy）、api-server（server/apps/api）、auth-server（server/apps/auth）、PostgreSQL 与 Redis 存储
值得注意的还有桌面端插件体系：@proj-airi/plugin-sdk（packages/plugin-sdk）与@proj-airi/plugin-sdk-tamagotchi（packages/plugin-sdk-tamagotchi）为 Tamagotchi 提供了插件化扩展能力，而 plugins 目录下的实际插件（如 homeassistant、claude-code、game-chess、web-extension 等）则展示了生态的雏形。
八、衍生子项目生态
AIRI 仓库衍生出一批可独立使用的子项目，覆盖工具链与周边生态：
- Awesome AI VTuber：AI VTuber 相关项目精选列表
unspeech：/audio/transcriptions与/audio/speech通用端点代理，类似 LiteLLM 之于任意 ASR/TTShfup：HuggingFace Spaces 部署与打包工具xsai-transformers：为 xsAI 提供的 Transformers.js 实验性 Provider- WebAI: Realtime Voice Chat：VAD + STT + LLM + TTS 的实时语音聊天完整示例
@proj-airi/drizzle-duckdb-wasm/@proj-airi/duckdb-wasm：DuckDB WASM 的 Drizzle 驱动与易用封装（仓库内目录见 packages/drizzle-duckdb-wasm、packages/duckdb-wasm）- AIRI Factorio /
autorio/tstl-plugin-reload-factorio-mod：让 AIRI 玩 Factorio 的系列组件 - Factorio RCON API：Factorio 无头服务器控制台的 RESTful API 封装
- Velin：用 Vue SFC 与 Markdown 管理提示词（Prompt）的机制
demodel：多运行时/下载器的模型与数据集加速获取inventory：模型目录与默认 Provider 配置的后端服务- MCP Launcher：统一管理 MCP 服务器的构建与启动器
- SAD：自托管与浏览器运行 LLM 的文档与笔记
九、社区、翻译与贡献
- 官方组织 @proj-airi 承载了 AIRI 衍生的所有子项目（RAG、记忆系统、嵌入式数据库、图标、Live2D 工具等）
- 翻译项目托管在 Crowdin，读者若发现译文不自然或不准确，可在 Crowdin 上直接参与翻译与修正
- 项目仍在早期开发阶段，欢迎各类贡献者：即使不熟悉 Vue.js / TypeScript，也可以作为艺术家、设计师或直播主参与；使用 React / Svelte / Solid 的开发者同样被欢迎——可以开启子目录添加自己想看到的功能。文档点名需要以下领域人才：Live2D 建模、VRM 建模、VRChat 头像设计、计算机视觉、强化学习、语音识别、语音合成、ONNX Runtime、Transformers.js、vLLM、WebGPU、Three.js、WebXR
结语
Project AIRI 用「大脑、耳朵、口、身体」四个维度重新定义了开源 AI 数字伴侣的可能性：既能通过 Web 技术在浏览器与移动端即开即用，又能通过 Electron 桌面形态调用 CUDA / Metal 本地算力并接入 Discord、Minecraft、Factorio 等真实世界场景。配合 packages/provider-inference 的云 + 本地双层推理抽象、packages/core-agent 的 Agent 运行时以及 integrations 下的各类通道集成，AIRI 展示了一条从「聊天机器人」走向「看得见、听得懂、说得出、动起来」的完整数字生命体实现路径。对于想要研究或自托管 AI VTuber 的开发者而言，这是一个可直接上手、可深度定制的优秀蓝本。
说明：本文内容以 docs/README.ja-JP.md 为骨架，仓库源码与目录结构仅作为补充佐证；文中对源码目录结构的描述均为对当前仓库的如实引用，涉及版本与命令以当前仓库实际内容为准。
【免费下载链接】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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
