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-sama's 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，手机等移动设备同样可以直接运行，无需安装原生应用。

Windows（winget）：Windows 用户可用 winget 一键安装：

winget install MoeruAI.AIRI

Windows（Scoop）：也可以借助 Scoop bucket 安装：

scoop bucket add airi https://github.com/moeru-ai/airi scoop install airi/airi

macOS（Homebrew Cask）：macOS 无需添加自定义 tap，直接用 Homebrew Cask 安装：

brew install --cask airi

桌面端发行物：仓库 README 提供了 Windows（x64 setup 安装包）与 macOS（Apple 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、Factorio（PoC 与 demo 已提供）、Kerbal Space Program（公告待发）；Helldivers 2 合作游玩进行中；
聊天渠道：Telegram、Discord 已支持；
记忆：已支持纯浏览器内数据库（DuckDB WASM 与 pglite），Memory Alaya 进行中；
纯浏览器本地（WebGPU）推理：规划中。

耳朵（Ears）

浏览器语音输入、Discord 语音输入；
客户端语音识别（客户端 ASR）与客户端说话检测（VAD）均已实现。

嘴（Mouth）

多提供商语音合成：ElevenLabs、Microsoft/Azure Speech、OpenAI 兼容 TTS、阿里云 Model Studio、本地 Kokoro TTS 等。

身体（Body）

VRM 支持：模型控制，以及自动眨眼、自动视线追踪、待机视线移动等动画能力；
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 dev

Stage Web（浏览器版，对应 airi.moeru.ai）：

pnpm dev

Stage Tamagotchi（桌面版，Electron）：

pnpm dev:tamagotchi

Tamagotchi 还附带 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 支持；目录结构上分为main（Electron 主进程）、preload、renderer、shared四个部分。

Stage Pocket（移动版，Capacitor）：启动 Capacitor 开发服务器：

pnpm dev:pocket:ios --target "<DEVICE_ID_OR_SIMULATOR_NAME>" # 或通过环境变量指定 CAPACITOR_DEVICE_ID_IOS="<DEVICE_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 权限启动 Tamagotchi：

sudo pnpm dev:tamagotchi

然后在 Tamagotchi 的settings/connections中启用安全 WebSocket。

文档站点：

pnpm dev:docs

版本发布：运行 bumpp 更新 monorepo 版本号：

npx bumpp --no-commit --no-tag

另外，根 package.json 还提供了dev:backend（docker compose -f server/docker-compose.yaml up --build，用于拉起托管后端）、dev:server（server-runtime 开发）、dev:ui（stage-ui 的 Story 开发）等脚本，按需使用。

LLM API 提供商支持矩阵：基于 xsai 的统一抽象

README 用一个长长的清单展示了 AIRI 的 LLM Provider 支持情况，并注明其建立在 xsai（Vercel 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 Claude（Bedrock）、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 Channel

README 用一张 mermaid 流程图给出了项目全景，本文完整继承并保留如下：

这张图清晰揭示了四个层次：

Stage 应用层：stage-web（浏览器版）、stage-tamagotchi（桌面版）、stage-pocket（移动版，标记为 experimental）三个前端壳；
共享产品包层：stage-ui（UI 组件库，仓库中规模最大的包之一）、core-agent/core-character（领域逻辑）、pipelines-audio（音频管线）、stage-ui-live2d/stage-ui-three等渲染器、server-sdk/server-shared（SDK 契约）；
桌面服务器通道（Server Channel）：server-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-vtuber：AI VTuber 及相关项目的精选列表；
unspeech：面向/audio/transcriptions与/audio/speech的通用端点代理服务器，类似 LiteLLM 但覆盖所有 ASR/TTS；
hfup：支持部署与打包到 HuggingFace Spaces 的工具；
xsai-transformers：为 xsAI 提供的实验性 Transformers.js Provider；
WebAI Realtime Voice Chat：从零实现 ChatGPT 实时语音（VAD + STT + LLM + TTS）的完整示例；
drizzle-duckdb-wasm / duckdb-wasm：DuckDB WASM 的 Drizzle ORM 驱动与易用封装（对应仓库 packages/drizzle-duckdb-wasm 与 packages/duckdb-wasm）；
AIRI Factorio：让 AIRI 玩 Factorio 的项目，含autorio自动化库与开发期 mod 热重载插件（tstl-plugin-reload-factorio-mod）等配套；
Velin：用 Vue SFC 与 Markdown 管理状态化 LLM 提示词；
demodel：加速多推理运行时下模型与数据集下载；
inventory：集中式模型目录与默认 Provider 配置的后端服务；
MCP Launcher：一键构建并运行 MCP 服务器的启动器（"模型世界的 Ollama"）；
SAD：自托管并在浏览器中运行 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 与仓库源码本身就是一份高完整度的参考实现。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析