快速摘要：AIRI 是一个拥有超过 2.2 万 GitHub Star 的开源 AI 虚拟角色项目，由 moeru-ai 团队开发，灵感来源于知名 AI 虚拟主播 Neuro-sama。 它不只是一个简单的聊天机器人——AIRI 能陪你玩 Minecraft、Factorio 等游戏，支持实时语音对话，还能通过 VRM 和 Live2D 模型展现栩栩如生的虚拟形象。整个项目基于现代 Web 技术栈构建，支持浏览器、桌面端和移动端多平台运行，并且接入了 30 多种大语言模型（LLM）服务商。更关键的是，AIRI 完全开源、支持自托管部署，你的数据完全由自己掌控。本文将由 莫潇羽@无忆研习社 为你从技术原理、系统架构到实际部署操作，做一次全面而深入的拆解。往下看有更详细的分析和手把手教程。
一、AI 虚拟角色赛道的现状与 AIRI 的定位
最近一段时间，AI 虚拟角色（或者叫"数字生命""赛博伴侣"）这个方向越来越热。从 Character.ai 到 SillyTavern，从各类角色扮演平台到本地化的聊天方案，AI 陪伴类产品已经遍地开花。但如果你仔细体验过这些产品，会发现它们大多停留在"文字聊天"或"视觉小说"的层面——你输入一段文字，AI 回复一段文字，交互模式相对单一。
那有没有一种 AI 虚拟角色，不仅能跟你聊天，还能陪你打游戏、跟你语音互动、拥有一个看得见的动态形象，甚至还能接入你常用的社交平台？
这正是 AIRI 这个项目想要回答的问题。
要理解 AIRI 的野心，我们需要先认识一下它的"精神原型"——Neuro-sama。
1.1 Neuro-sama：AI 虚拟主播的天花板
要理解 AIRI 的意义，我们得先聊聊 Neuro-sama 这个"前辈"。
Neuro-sama 是由一位化名 Vedal 的英国开发者创造的 AI 虚拟主播。她的故事可以追溯到 2019 年 5 月——那时候，Vedal 开发了一个能自动打 osu!（一款节奏游戏）的神经网络，并以 "Neuro-sama" 的名字在 Twitch 上直播它的游戏过程。当时的"Neuro-sama"还没有虚拟形象，也没有对话能力，只是一个静态图标加上 osu! 的游戏画面。
真正的转折发生在 2022 年 12 月 19 日。Vedal 把之前实验的 AI 对话系统（代号 Airis）和 Neuro-sama 的 osu! AI 合并在了一起，给她套上了 Live2D 的 Hiyori Momose 模型（Live2D 提供的免费样板模型），让她以 AI VTuber 的身份重新出道。这次出道引发了巨大的关注——她不仅能和观众实时对话，还能同时打游戏，这在当时的虚拟主播圈是前所未有的。
从技术层面来看，Neuro-sama 的核心架构包含几个关键模块。首先是语言模型部分，负责生成对话回复——这并不是简单套用 ChatGPT，而是 Vedal 自己训练和调优的定制模型，具有独特的"混沌"人格特征（她经常开玩笑甚至"吐槽"自己的创造者）。其次是一个独立的游戏操控 AI，专门负责在游戏中的操作决策——根据 Vedal 在采访中的说法，游戏 AI 使用了一个接收 80×60 像素灰度图的视觉输入系统。第三是语音合成系统，将文字回复转换为高音调的女性语音。最后是 Live2D 形象的实时驱动，让虚拟角色的表情和动作与对话内容同步。整套系统的前端展示部分使用 C# 和 Unity 构建，后端 AI 系统则由 Python 实现。
Neuro-sama 的成功是爆炸性的。2024 年 8 月，她在中国的哔哩哔哩平台开播，凭借此前国内粉丝长期搬运和翻译的积累，关注数迅速突破 70 万。到了 2025 年底至 2026 年初，Vedal 为 Neuro-sama 举办了一场长达 17 天的订阅马拉松活动，累计获得超过 4.1 万个订阅和 243 万小时的总观看时长，打破了多项 Twitch 平台记录。她还有一个"双胞胎姐妹" Evil Neuro，拥有不同的性格和声音，能够独立进行游戏（比如独自通关了 Slay the Spire）。
但问题在于，Neuro-sama 并不开源。Vedal 从未公开过她的核心代码、模型权重或训练细节。你无法在她下播之后继续和她互动，也无法基于她的技术搭建自己的虚拟角色。对于想要体验甚至创造类似 AI 虚拟角色的开发者和爱好者来说，这是一个巨大的遗憾。
而 AIRI，正是为了填补这个空缺而诞生的。它的目标很明确：让每个人都能拥有自己的 "Neuro-sama"，而且是完全开源、完全可控的。
1.2 AIRI 的核心定位
AIRI（日文读作"アイリ"）由 moeru-ai 团队开发，是一个完全开源、支持自托管的 AI 虚拟角色平台。项目采用 MIT 许可证发布，任何人都可以自由使用、修改和部署。moeru-ai 的名字来源于日文的"萌え"（Moe）与 AI 的结合，这个团队本身是一个由计算机科学家、多模态领域专家、设计师和开源贡献者组成的在线爱好者社区。
莫潇羽在研究这个项目时发现，AIRI 与市面上其他 AI VTuber 开源项目最大的不同在于两点：
第一，它不只是能聊天，而是能"做事"。 市面上大多数 AI 陪伴产品本质上都是"对话框"——你输入文字，AI 回复文字，交互模式相对单一。即使是加入了语音功能的产品，核心交互依然停留在"你说我答"的层面。而 AIRI 走得更远——它可以在 Minecraft 中帮你挖矿、建房子、跟随你移动，可以在 Factorio 中辅助你管理工厂生产线，未来还计划支持更多游戏。这种"能说还能做"的设计，才是 AIRI 试图还原的 Neuro-sama 式体验的核心。
第二，它是一个真正的"Web-first"项目。 很多开源的 AI VTuber 项目要么依赖于特定的桌面软件（如 Unity、VTube Studio），要么需要复杂的服务端部署，而 AIRI 从第一天起就基于 WebGPU、WebAudio、Web Workers、WebAssembly、WebSocket 等现代 Web 技术构建。这意味着它可以直接在浏览器中运行——打开网页就能用，不需要安装任何软件。同时，桌面版本通过 Rust + Tauri 插件提供原生 GPU 加速，做到了"Web 的便捷性 + 原生的高性能"两全其美。
截至本文发布时（2026 年 3 月），AIRI 在 GitHub 上已经累积超过 2.2 万个 Star，Fork 数超过 2000，社区活跃度持续走高，几乎每天都有新的代码提交。项目最新的稳定版本为 v0.8.4，当前正在向 v0.9 迈进。
在开源社区中，2 万级别的 Star 数已经代表了相当高的关注度和认可度。作为一个 AI 虚拟角色领域的项目，能在短时间内获得如此多的关注，说明这个方向确实击中了很多人的需求——人们不只是想要一个能聊天的 AI，更想要一个能"陪伴"、能"互动"的数字伙伴。
项目地址：https://github.com/moeru-ai/airi
二、AIRI 的系统架构深度拆解
要真正理解 AIRI 是怎么工作的，我们需要深入它的架构设计。莫潇羽@无忆研习社（www.wuyi.wiki）在这里为大家做一次比较详细的技术拆解，力求让即使是非开发背景的读者也能理解其中的核心逻辑。
2.1 "灵魂容器"架构：拟人化的模块设计
AIRI 的整体架构非常有意思，它把一个 AI 虚拟角色的各种能力拆分成了类似人体器官的模块，项目内部称之为"灵魂容器"（Soul Container）。这种设计思路让每个模块可以独立开发、独立替换，也让整个系统的可维护性和可扩展性大大提升。
大脑（Brain） 是 AIRI 的核心决策引擎，负责处理用户输入、生成回复、决定行为策略。大脑模块通过 xsAI 抽象层接入各种大语言模型服务商，支持的服务商数量超过 30 家，包括 OpenAI、Gemini、DeepSeek、Qwen、Ollama、vLLM 等。这个抽象层的设计非常关键——它让开发者可以随时切换底层模型，而无需修改上层业务逻辑。
记忆（Memory） 是大脑的辅助系统，负责存储和检索对话历史、用户偏好等信息。目前 AIRI 的记忆系统已经实现了基于浏览器内数据库的存储方案，使用 DuckDB WASM 或 pglite 作为存储引擎。正在开发中的 Memory Alaya 系统将提供更加精细化的记忆管理能力，融合了认知科学的设计理念。
耳朵（Ears） 负责音频输入处理。AIRI 支持从浏览器麦克风或 Discord 语音频道接收音频流。音频处理在 Web Worker 中运行，不会阻塞主线程，保证了界面的流畅性。语音识别（STT）在桌面端通过 ONNX Runtime 加速的 Whisper 模型实现，在浏览器端则通过 Transformers.js 的 WASM 版本完成。此外，AIRI 还内置了语音活动检测（VAD）功能，能够自动判断用户是否在说话。
嘴巴（Mouth） 负责语音合成（TTS）输出。目前主要支持 ElevenLabs 的语音合成服务，通过 unspeech 代理服务器统一管理。生成的音频还会驱动唇形同步（Lipsync）系统，让虚拟角色的嘴型动作与语音内容相匹配。
身体（Body） 负责虚拟角色的视觉呈现。AIRI 同时支持 VRM 和 Live2D 两种主流的虚拟形象格式，并提供了丰富的自动动画效果——自动眨眼、自动视线追踪、待机时的眼球微动等。这些细节看似简单，却是让虚拟角色"看起来像活着"的关键。
2.2 数据流：从你说话到角色回应的完整链路
为了让大家更直观地理解 AIRI 的工作流程，莫潇羽在这里梳理一下一次完整交互的数据流向：
用户说话 → 麦克风采集音频
→ VAD 检测语音活动（Web Worker）
→ Whisper 语音识别，转换为文字（Web Worker / ONNX Runtime）
→ 文字传入 LLM（通过 xsAI 抽象层调用选定的模型服务商）
→ LLM 生成回复文本（支持流式输出）
→ 回复文本传入 TTS（ElevenLabs / 其他服务商）
→ 生成语音音频
→ 音频驱动唇形同步（Lipsync → Live2D / VRM 模型）
→ 虚拟角色开口说话，嘴型与语音匹配这条链路中最考验工程能力的地方在于"实时性"。从用户开口说话到角色开始回应，中间经历了语音识别、模型推理、语音合成三个可能产生延迟的环节。AIRI 的解决方案是全面采用流式处理——STT 在用户说话时就开始逐步转写，LLM 的回复采用流式输出，TTS 也是边生成边播放。这种管线式的并行处理大大降低了整体延迟。
2.3 Monorepo 架构与技术栈
AIRI 的代码采用 Monorepo（单一仓库）组织方式，使用 pnpm 作为包管理器。整个仓库包含多个子包和子应用，每个子包负责一个特定的功能领域。
以下是 AIRI 的主要技术栈：
前端框架：Vue 3 + TypeScript
构建工具：Rolldown-Vite（新一代高性能构建器）
样式方案：UnoCSS
状态管理：Pinia
桌面端框架：Electron（搭配 Tauri 插件提供原生能力）
移动端方案：Capacitor（PWA）
3D 渲染：Three.js + WebGPU
2D 虚拟形象：Live2D SDK
3D 虚拟形象：VRM（通过 Three.js 渲染）
数据库：DuckDB WASM / pglite（浏览器内嵌数据库）
ORM：Drizzle ORM
LLM 接入层：xsAI（自研的超轻量 AI SDK）
语音识别：Whisper（ONNX Runtime / Transformers.js WASM）
语音合成：ElevenLabs / unspeech 代理
事件系统：@moeru/eventa（自研的类型安全事件驱动工具库）
依赖注入：injeca
原生加速：Rust（通过 Tauri 插件，支持 CUDA / Metal / DirectML）这个技术栈有几个值得关注的设计决策：
首先是"Web 优先，原生增强"的策略。核心功能完全在浏览器中实现，而桌面端通过 Tauri 插件（Rust 编写）提供原生 GPU 加速能力。这意味着浏览器版本就能完成大部分功能，而桌面版本在此基础上获得更好的性能。
其次是 xsAI 这个自研的 AI SDK。这个库的设计理念是"极致轻量"，它为 30 多种 LLM 服务商提供了统一的接口抽象，开发者只需修改一个配置项就能切换底层模型，不需要改动任何业务代码。这种设计在实际使用中非常灵活——你可以根据不同场景选择不同的模型，比如日常聊天用一个便宜的模型，游戏决策用一个推理能力更强的模型。
再者是 DuckDB WASM 的引入。DuckDB 是一个高性能的嵌入式分析数据库，通过 WASM 版本直接运行在浏览器中，无需任何服务端支持。AIRI 用它来存储对话记录、记忆数据等结构化信息，配合 Drizzle ORM 提供类型安全的数据访问。这个选择非常聪明——传统的 Web 应用通常使用 IndexedDB 或 localStorage 进行客户端存储，但这些方案不支持复杂的 SQL 查询，对于需要检索和分析对话历史的记忆系统来说捉襟见肘。DuckDB WASM 则提供了完整的 SQL 能力，让 AIRI 可以对记忆数据进行高效的检索、过滤和聚合操作。
最后值得一提的是事件系统的设计。AIRI 自研了一个叫做 @moeru/eventa 的事件驱动工具库，它提供了类型安全的事件定义和触发机制，特别适合在 Web Worker、WebSocket、Electron IPC 等多种通信场景中使用。这个库让 AIRI 内部的各个模块能够通过事件进行松耦合的通信——比如"耳朵"模块检测到用户说话时会触发一个事件，"大脑"模块监听到这个事件后开始处理输入，处理完成后再触发一个新的事件通知"嘴巴"模块开始语音合成。这种基于事件的架构让各模块可以独立开发和测试，也方便后续通过插件系统进行扩展。
2.4 多平台部署架构
AIRI 的多平台支持不是简单的代码复制，而是通过精心设计的分层架构实现的：
┌─────────────────┐
│ @proj-airi/ui │ ← 基础 UI 组件
└────────┬────────┘
│
┌────────┴────────┐
│ @proj-airi/ │ ← 共享舞台 UI
│ stage-ui │ (角色渲染、交互逻辑)
└────────┬────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌────────┴───┐ ┌──────┴──────┐ ┌───┴────────┐
│ stage-web │ │stage-tamago │ │stage-pocket│
│ (浏览器版) │ │ chi(桌面版)│ │ (移动版) │
└────────────┘ └─────────────┘ └────────────┘三个平台版本共享同一套核心业务逻辑（通过 stage-ui 包），但各自有不同的"壳"：
- Stage Web（浏览器版） 是一个标准的 Vue PWA 应用，直接部署在 Web 服务器上，用户通过浏览器访问即可使用。官方提供了在线演示站点
airi.moeru.ai。 - Stage Tamagotchi（桌面版） 基于 Electron 构建，通过 Rust 编写的 Tauri 插件提供原生能力加持。这个版本可以调用 NVIDIA CUDA、Apple Metal 或 DirectML 进行本地模型推理，性能远超浏览器版本。模型文件通过 HuggingFace 的 hf-hub 库自动下载管理。
- Stage Pocket（移动版） 基于 Capacitor 框架，目前主要面向 iOS 平台（通过 Xcode 编译运行），Android 版本也在规划中。
三、核心功能详解
了解了架构之后，我们来看看 AIRI 具体能做哪些事情。本节由 莫潇羽@无忆研习社 根据实际项目文档和社区反馈整理，力求给大家一个真实准确的功能图景。
3.1 游戏互动：不只是聊天的 AI 伙伴
这是 AIRI 最让人眼前一亮的功能。
Minecraft 游戏互动 是目前最成熟的游戏集成模块。AIRI 内置了一个基于 mineflayer 库的 Minecraft 机器人，它能够：
- 理解自然语言指令（比如"帮我挖 10 块石头""跟着我走""在这里建一个 3×3 的小木屋"）
- 自动进行路径规划和移动
- 管理背包物品
- 执行采集、建造、战斗等操作
- 跟随玩家或前往指定位置
整个指令系统的工作原理是：用户在 Minecraft 聊天框中输入自然语言指令（以 # 开头的是快捷命令，其他则由 LLM 理解并执行），AIRI 通过 LLM 解析用户意图，然后调用 mineflayer 提供的 API 执行对应的游戏操作。
项目源码中的 Minecraft 模块结构如下：
src/
├── agents/ # AI 智能体实现（负责决策逻辑）
├── composables/ # 可复用的组合式函数
├── libs/ # 核心库代码
├── mineflayer/ # mineflayer 插件实现（底层游戏操作）
├── prompts/ # AI 提示词模板（定义 LLM 的行为规范）
├── skills/ # 机器人技能和动作定义
└── utils/ # 工具函数配置 Minecraft 机器人需要在 .env.local 文件中填写以下信息：
BOT_USERNAME=your_bot_username
BOT_HOSTNAME=localhost
BOT_PORT=25565
BOT_VERSION=1.20Factorio 游戏互动 目前处于概念验证（PoC）阶段，但已经有了可用的演示。AIRI 的 Factorio 集成思路与 Minecraft 类似，但额外引入了计算机视觉模块——使用 YOLO 目标检测模型来"看"游戏画面，然后由 LLM 做出决策。这是一个非常前沿的尝试，将视觉感知和语言推理结合起来，让 AI 能够理解和操控复杂的工厂管理游戏。
项目团队还在 proj-airi 组织下维护了一个通用的 2D 游戏 AI 试验场（game-playing-ai-playground-2d），探索将类似的视觉+LLM 方案推广到更多游戏中。
3.2 实时语音对话
AIRI 的语音交互系统是一个完整的"听说"管线：
语音输入端（"耳朵"）：
音频信号首先经过 VAD（语音活动检测）模块处理。VAD 的作用是判断当前是否有人在说话，只有检测到语音活动时，才会触发后续的语音识别流程，这样可以避免将背景噪音误认为用户输入。
通过 VAD 筛选后的音频流会被送入 STT（语音转文字）引擎。AIRI 在不同平台上使用不同的 STT 方案：桌面端通过 Rust 编写的 Tauri 插件调用 ONNX Runtime 加速的 Whisper 模型，能够获得接近实时的转写速度；浏览器端则使用 Transformers.js 的 WASM 版本，虽然速度稍慢但不需要任何服务端支持。
一个很重要的细节是，AIRI 的 STT 采用的是流式转写模式——用户说话的同时就开始转写，不需要等用户说完整句话才开始处理。这大大降低了响应延迟。
语音输出端（"嘴巴"）：
LLM 生成的回复文本会通过 unspeech 代理服务器转发给 TTS 服务商（目前主要是 ElevenLabs）。unspeech 的设计类似于 LiteLLM，但专门针对语音识别和语音合成场景，为各种 STT/TTS 服务商提供统一的 API 接口。
语音合成同样采用流式输出——不需要等整段文字全部合成完毕再播放，而是边合成边播放，进一步降低了用户感知到的延迟。
社区中也有开发者在探索本地化的 TTS 方案，比如使用 Kokoro 模型或 IndexTTS 来替代 ElevenLabs。随着本地 TTS 技术的不断成熟，未来 AIRI 有望实现完全本地化的语音交互，彻底摆脱对云端服务的依赖。
3.3 虚拟形象系统
AIRI 同时支持两种主流的虚拟角色格式：
VRM 格式 是一种基于 glTF 的 3D 人形角色数据格式，在日本的虚拟形象领域被广泛使用。AIRI 通过 Three.js 进行 VRM 模型的渲染，支持加载自定义的 VRM 模型文件。
Live2D 格式 是一种通过 2D 纹理变形来模拟 3D 效果的技术，被大量虚拟主播和游戏角色使用。AIRI 通过专门的 Live2D SDK 插件进行集成。
两种格式都支持以下自动动画效果：
- 自动眨眼（Auto Blink）：模拟真实的眨眼频率和节奏，让角色看起来不那么"死鱼眼"
- 自动视线追踪（Auto Look At）：角色的视线会自动看向镜头或用户鼠标的位置
- 待机眼球运动（Idle Eye Movement）：在没有交互时，眼球会做出自然的微动效果
这些自动动画效果的参数由 @proj-airi/model-driver-lipsync 模块统一驱动。当 TTS 音频播放时，这个模块会将音频信号转换为 viseme（视素，即嘴型参数），实时驱动虚拟角色的口型变化，实现与语音同步的说话效果。
如果你是一个 Live2D 或 VRM 建模师，完全可以制作自己的专属角色形象导入 AIRI 使用，打造一个独一无二的 AI 伙伴。
3.4 LLM 服务商的灵活选择
AIRI 通过 xsAI 抽象层实现了对大量 LLM 服务商的支持，这里有必要展开讲一下，因为选择合适的 LLM 直接影响到 AI 角色的对话质量和使用体验。
目前 AIRI 支持的主要 LLM 服务商包括但不限于：
国际服务商方面：OpenAI（GPT-4o、GPT-4o-mini 等）、Google Gemini、Anthropic Claude、Mistral 等都在支持之列。这些模型在英文对话方面表现出色，如果你的 AI 角色主要使用英文交流，它们是很好的选择。
国内服务商方面：DeepSeek、Qwen（通义千问）、智谱 GLM 等也都可以接入。对于中文场景的 AIRI 用户来说，这些模型在中文理解和生成方面有天然的优势，而且通常价格更加亲民。莫潇羽个人比较推荐 DeepSeek 的 deepseek-chat 模型，它在中文对话的自然度和性价比方面表现都不错。
本地推理方案方面：Ollama 是最容易上手的本地方案——在本地安装 Ollama 后，只需要一行命令就能下载并运行各种开源模型（如 LLaMA、Qwen、Mistral 等），然后在 AIRI 中将 API 地址指向 Ollama 的本地端点即可。vLLM 则适合有独立 GPU 服务器的高级用户，能够提供更高的推理吞吐量。
xsAI 抽象层的一个重要设计是"服务商无关性"——开发者只需要指定 API 地址和模型名称，xsAI 会自动处理不同服务商之间的协议差异。这意味着你可以随时切换模型，甚至可以为不同的功能场景配置不同的模型。比如，日常聊天使用一个响应快、成本低的小模型，游戏决策使用一个推理能力更强的大模型，TTS 使用一个专门的语音模型——这种灵活性在实际使用中非常有价值。
3.5 多平台社交集成
除了直接在应用界面中交互，AIRI 还支持通过社交平台与你的 AI 角色沟通：
- Discord 集成：AIRI 可以作为 Discord 机器人加入你的服务器，在文字频道中与用户聊天，甚至可以加入语音频道接收和播放音频。这在技术上通过 Discord Bot API 和 Discord.js 库实现，语音频道的音频流通过 WebSocket 传输到 AIRI 的音频处理管线中
- Telegram 集成：通过 Telegram Bot API，AIRI 可以在 Telegram 上与用户进行文字对话。由于 Telegram 的 Bot API 相对简单，这个集成模块也比较轻量
这种多平台集成意味着你可以在不同场景下与同一个 AI 角色保持连续的互动——在电脑前用桌面版一起玩游戏，外出时通过 Telegram 继续聊天，在社群中让它作为 Discord 机器人与大家互动。理论上，如果记忆系统足够完善，AI 角色应该能够在不同平台之间保持对你的"记忆"和对话上下文的延续，就像一个真正的朋友无论在哪里见面都认识你一样。
3.6 浏览器内本地推理
这是 AIRI 技术架构中最有前瞻性的一个功能点。通过 WebGPU 技术，AIRI 可以直接在浏览器中运行 LLM 推理，完全不需要任何云端服务或本地服务器。
WebGPU 是新一代的 Web 图形和计算 API，相比传统的 WebGL，它提供了更底层的 GPU 访问能力和更好的计算性能。AIRI 利用 WebGPU 在浏览器中运行量化后的语言模型，配合 Web Workers 实现后台推理，不影响页面的交互流畅度。
proj-airi 组织下还维护了一系列 WebAI 示例项目（webai-examples），展示如何在浏览器中运行 Whisper 语音识别、LLM 推理等任务。此外，candle-examples 项目使用 Rust + HuggingFace candle 库实现了高效的 WASM 推理引擎，可以在浏览器中运行 LLM、Whisper、Embedding 等模型。
当然，浏览器内推理的性能受限于设备的 GPU 能力。如果你需要更好的推理性能，桌面版本的 AIRI 可以直接调用 NVIDIA CUDA（Windows/Linux）或 Apple Metal（macOS）进行原生加速，无需手动安装 CUDA toolkit 等复杂依赖——Tauri 插件已经帮你处理好了一切。
四、从零开始：AIRI 的完整部署教程
接下来是大家最关心的实操部分。莫潇羽@无忆研习社（www.wuyi.wiki）尽量把每一步写得足够细致，让没有太多开发经验的朋友也能跟着操作。
4.1 环境准备
在开始之前，你需要确保系统中安装了以下工具：
Node.js（版本 18 或更高）
AIRI 是一个 TypeScript 项目，需要 Node.js 运行时。推荐使用 LTS（长期支持）版本。
# 检查 Node.js 版本
node --version
# 应该显示 v18.x.x 或更高如果你还没有安装 Node.js，可以从官方网站 https://nodejs.org/ 下载安装包，或者使用 nvm（Node Version Manager）来管理多个版本：
# 安装 nvm（macOS/Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 安装 Node.js 20 LTS
nvm install 20
nvm use 20pnpm（包管理器）
AIRI 使用 pnpm 作为包管理器，它比 npm 和 yarn 更快、更节省磁盘空间。
# 启用 corepack（Node.js 16.10+ 内置）
corepack enable
# 或者直接安装 pnpm
npm install -g pnpm
# 验证安装
pnpm --versionGit
用于克隆项目代码。
git --version可选：Rust 工具链
如果你需要开发桌面版本（Stage Tamagotchi），则需要安装 Rust 工具链：
# 安装 Rust
curl --proto '=https' --tlv1.2 -sSf https://sh.rustup.rs | sh
# 验证安装
rustc --version
cargo --version4.2 获取源代码
# 克隆仓库
git clone https://github.com/moeru-ai/airi.git
# 进入项目目录
cd airi
# 安装所有依赖
pnpm install第一次安装依赖可能需要一些时间，因为项目包含大量子包。安装完成后，你应该会看到类似 Packages: +XXXX 的输出。
如果你计划参与桌面版本的开发，还需要额外获取 Rust 依赖：
cargo fetch4.3 启动浏览器版本（Stage Web）
这是最简单的启动方式，适合大多数用户快速体验：
pnpm dev等待编译完成后，你会看到类似如下的输出：
ROLLDOWN-VITE v7.3.0 ready in 1073 ms
➜ Local: https://localhost:5273/
➜ Network: https://<你的IP地址>:5273/在浏览器中打开 https://localhost:5273/ 即可访问 AIRI 的 Web 界面。
注意这里使用的是 HTTPS 协议（而不是 HTTP），这是因为部分浏览器 API（如麦克风权限、WebGPU 等）要求在安全上下文中运行。首次访问时浏览器可能会提示证书不受信任，这是正常的，选择"继续访问"即可。
如果你不想自己搭建，也可以直接访问官方提供的在线演示：airi.moeru.ai
4.4 启动桌面版本（Stage Tamagotchi）
桌面版本提供了更好的性能和更多的原生功能：
pnpm dev:tamagotchi首次启动时，Electron 会自动下载所需的二进制文件。启动后，一个独立的桌面窗口会弹出，显示 AIRI 的界面。
如果你使用的是 Nix 包管理器，还可以用一行命令直接运行：
nix run github:moeru-ai/airi另外，你也可以直接从 GitHub Releases 页面下载预编译的安装包：
https://github.com/moeru-ai/airi/releases目前提供以下平台的安装包：
- macOS：.dmg 格式（支持 Intel 和 Apple Silicon）
- Windows：标准安装程序
- Linux：.deb（Debian/Ubuntu）、.rpm（Fedora/CentOS）、.flatpak（通用）
macOS 用户首次打开时可能会遇到"无法验证开发者"的提示，可以通过以下命令解决：
sudo xattr -cr /Applications/AIRI.app4.5 启动移动版本（Stage Pocket）
移动版本目前主要面向 iOS：
# 启动开发服务器
pnpm dev:pocket然后在输出信息中找到你的网络 IP 地址，运行：
CAPACITOR_DEV_SERVER_URL=https://<你的IP地址>:5273 pnpm open:ios这会自动打开 Xcode，你可以在模拟器或真机上运行 AIRI。
4.6 配置 LLM 服务商
启动 AIRI 之后，最重要的一步是配置大语言模型服务商。AIRI 通过 xsAI 抽象层支持超过 30 种 LLM 服务商，以下是一些常见的选择和配置方法：
使用云端模型服务商
在 AIRI 的设置界面中，你可以选择服务商并填入 API Key。以下是几个常见服务商的配置要点：
- OpenAI：填入 API Key，选择模型（如 GPT-4o、GPT-4o-mini 等）
- Gemini：填入 Google AI Studio 的 API Key
- DeepSeek：填入 DeepSeek 的 API Key，选择 deepseek-chat 或 deepseek-reasoner 模型
- Qwen（通义千问）：填入阿里云的 API Key
- 硅基流动（SiliconFlow）：填入 SiliconFlow 的 API Key
使用本地模型
如果你更注重隐私或想要完全离线使用，AIRI 也支持本地模型推理：
- Ollama：先在本地安装并运行 Ollama，然后在 AIRI 中将 API 地址指向 Ollama 的本地端点（默认
http://localhost:11434） - vLLM：适合有独立 GPU 服务器的用户，可以部署高性能的本地推理服务
- 浏览器内 WebGPU 推理：直接在浏览器中加载模型运行推理，无需任何额外服务
对于国内用户，莫潇羽建议优先考虑 DeepSeek 或 Qwen 作为模型服务商，它们在中文理解和生成方面表现出色，而且接入流程相对简单。
4.7 配置 Minecraft 游戏互动
如果你想体验 AIRI 最精彩的 Minecraft 游戏互动功能，需要进行以下配置：
首先，确保你有一个运行中的 Minecraft 服务器（版本 1.20 或更高），可以是本地单人世界开放的局域网联机，也可以是独立的服务器。
然后，在项目根目录创建（或编辑） .env.local 文件，添加以下配置：
# Minecraft 机器人配置
BOT_USERNAME=AIRI_Bot
BOT_HOSTNAME=localhost
BOT_PORT=25565
BOT_VERSION=1.20
# LLM 配置（用于理解自然语言指令）
OPENAI_API_KEY=your_api_key_here
OPENAI_API_BASEURL=https://api.openai.com/v1这里的 OPENAI_API_BASEURL 可以替换为任何兼容 OpenAI API 格式的服务商地址。
配置完成后，启动 AIRI 并连接到 Minecraft 服务器。你可以在游戏中通过聊天框与 AIRI 机器人互动：
# 快捷命令
#help - 显示帮助信息
#follow - 让机器人跟随你
#stop - 停止当前动作
#come - 让机器人来到你的位置
# 自然语言指令（LLM 理解并执行）
帮我砍几棵树
去前面那个山洞看看
在这里建一个火把围栏4.8 配置语音功能
要启用语音交互，需要配置 TTS（文字转语音）服务：
ElevenLabs 是目前 AIRI 的主要 TTS 方案。注册 ElevenLabs 账号后，在 AIRI 设置中填入 API Key 即可。ElevenLabs 提供了多种语音风格和语言支持，你可以根据喜好选择合适的声音。
对于语音输入，AIRI 使用浏览器的麦克风 API 采集音频，语音识别由内置的 Whisper 模型自动完成，无需额外配置。首次使用时，浏览器会请求麦克风权限，允许即可。
五、AIRI 的进阶玩法与定制
5.1 自定义角色形象
AIRI 支持导入自定义的 VRM 和 Live2D 模型文件。如果你有自己制作的虚拟形象文件，可以在 AIRI 的设置页面上传。
对于 VRM 模型，推荐使用 VRoid Studio（一款来自 Pixiv 的虚拟形象制作工具）进行创建。VRoid Studio 提供了直观的可视化编辑界面，即使没有 3D 建模经验也能轻松上手。制作完成后导出 .vrm 文件，直接在 AIRI 中加载即可。
对于 Live2D 模型，你需要使用 Live2D Cubism Editor 进行制作。Live2D 模型的制作门槛相对较高，需要一定的美术功底和对 Live2D 参数系统的理解。如果你不会制作，也可以在网络上找到一些免费的 Live2D 模型资源。
5.2 Prompt 工程与角色人设
AIRI 的"灵魂"很大程度上取决于 Prompt（提示词）的设计。项目中使用了一个叫做 Velin 的工具，它允许你使用 Vue SFC（单文件组件）和 Markdown 语法来编写有状态的 Prompt 模板。这个设计在开源 AI 项目中相当独特——传统的做法是把 Prompt 写成纯文本文件，而 Velin 将其变成了一种可以包含逻辑判断和状态管理的"活文档"。
简单来说，你可以通过修改 Prompt 来定义 AI 角色的性格、说话风格、背景故事等。这些 Prompt 模板存放在项目的 prompts/ 目录下，你可以参考现有模板来创建自己的角色人设。
举个具体的例子来说明 Prompt 设计对角色行为的影响：如果你在 Prompt 中设定角色是一个"热情开朗、喜欢用感叹号和颜文字的元气少女"，那么 LLM 生成的回复就会带有大量的感叹号和俏皮的表达。反过来，如果你设定的是一个"沉稳冷静、言简意赅的学者型角色"，回复风格就会完全不同。这就是所谓的"灵魂容器"概念的实际体现——通过不同的 Prompt 配置，同一个 AIRI 系统可以表现出截然不同的"人格"。
在实际操作中，一个好的角色 Prompt 通常需
