最近在玩 AI 桌宠的时候发现一个挺有意思的开源项目AIRI也就是大家常说的 AI 小镇my_ai_town。它把大模型对话、语音合成、桌面宠物交互都整合到了一起装好之后桌面上会多一个二次元角色能陪你聊天、陪你打游戏、还能通过角色设定扮演不同性格的虚拟伙伴。最吸引人的是这个项目完全开源、完全免费不需要订阅会员也不需要复杂的环境配置。本文就结合这个开源项目写一篇比较完整的 AIRI 桌宠保姆级教程覆盖从下载安装、首次启动、角色设定、模型接入到常见报错排查和二次开发思路。想直接上手的朋友可以跟着步骤走想做二次开发的也可以重点看后半部分。1. 背景与核心概念1.1 什么是 AI 桌宠桌面宠物其实不是新概念早年的电子宠物、瑞星小狮子、QQ 宠物都属于这类产品。它们的特点是桌面上常驻一个虚拟形象能够对用户的操作做出反应比如走路、说话、做表情。传统的桌宠是“脚本式”的能触发的内容有限无非是内置的几句对话循环播放。而 AI 桌宠与传统桌宠最大的区别在于它通过接入大语言模型LLM实现了真正意义上的自由对话。换句话说角色说的每句话不是提前写死的而是根据你输入的上下文实时生成的。一个标准的 AI 桌宠通常由下面几个模块组成模型渲染层负责把二次元角色显示在桌面上常见技术是 Live2D、Spine 或者骨骼动画。对话引擎层负责理解用户输入并生成回复常见技术是 OpenAI 兼容接口、本地大模型、各类国内大模型 API。语音合成层可选模块。负责把文本回复转成语音让角色真正“开口说话”。交互控制层负责处理鼠标拖拽、点击、悬浮窗、窗口置顶等桌面交互逻辑。AIRI 这类项目基本就是把这四层全部打通做成一个开箱即用的桌面小程序。1.2 AIRI 和 AI 小镇项目定位根据项目地址AIRI 对应的开源仓库是mewamew/my_ai_town项目简称为 AI 小镇。从名字和社区的讨论来看这个项目的定位是“带 AI 角色的桌面小镇”桌面上不只有一个角色而是可以存在多个 AI 角色它们有各自的设定、各自的对话模型并且可以和用户产生互动。相比传统桌宠AI 小镇更强调“陪伴感”。它并不只是弹窗精灵而是把角色当成一个常驻桌面、有性格、有记忆、会陪你玩游戏的小助手。很多用户在相关话题里把它描述成“二次元 AI 女友”这个说法在社区里比较流行。但我们从技术角度看它本质是一个情感陪伴型 AI 桌宠应用。之所以会给人“AI 女友”的感觉是因为项目支持高度自定义角色人设你可以通过修改角色设定文件让角色展现出温柔、活泼、御姐、萝莉等不同性格。1.3 为什么要选择开源 AI 桌宠现在市面上其实有一些收费的 AI 桌宠或虚拟角色产品为什么还要花时间折腾开源项目呢原因主要有几个。第一可控性强。开源项目所有代码都在本地角色设定、对话参数、模型地址都可以自己改不用担心厂商调整策略导致功能不可用。第二隐私相对安全。使用开源方案你可以把对话请求打到本地模型上也可以选择自己信任的 API 服务数据流向完全由你控制。第三免费。自建 AI 桌宠最大的成本可能就是调用大模型 API 的少量费用。如果完全使用本地模型比如通过 Ollama 部署量化版模型甚至能做到零成本运行。第四学习价值高。通过阅读这类项目的代码能学到 Live2D 如何嵌入桌面应用、大模型 API 如何封装、流式对话如何实现这些经验对做其他 AI 应用同样有参考价值。2. 准备工作与版本说明2.1 运行环境说明AIRI 项目的下载包分为 Windows 和 macOS 两个平台版本这也是社区里常见的分发方式。在开始之前建议先确认自己的操作系统满足基本要求。操作系统Windows 10/11 或 macOS 10.15 及以上版本。内存建议 8GB 以上。虽然桌宠本身占用资源不高但如果同时开多个 AI 角色内存占用会上升。显卡如果只使用云端 API核显就可以如果想跑本地模型建议至少 6GB 显存。网络使用云端大模型 API 时需要能正常访问对应接口。注意不要使用任何不安全的网络代理手段直接配置项目支持的 API 地址即可。注意具体版本号需要根据项目发布页的说明调整不同版本的依赖可能不同。本文以常见环境为例重点演示配置思路不锁定具体版本。2.2 下载项目与解压第一步打开项目开源地址https://github.com/mewamew/my_ai_town在页面中寻找 Releases 或者下载区域。根据项目说明可以直接下载ai小镇_macw压缩包里面会同时包含 macOS 和 Windows 版本的程序。下载完成后建议解压到没有中文和空格的路径下例如WindowsD:\AI_TownmacOS~/Applications/AI_Town避免中文路径的原因是某些桌面应用框架对中文路径支持不友好可能导致资源加载失败或动画无法播放。2.3 项目目录结构说明解压后建议先看一下目录结构不要急着双击运行。一个典型的 AI 桌宠项目目录里通常包含这些内容AI_Town/ ├── AIRI.exe # Windows 主程序 ├── AIRI.app # macOS 主程序 ├── resources/ # 资源文件目录 │ ├── models/ # Live2D 模型文件 │ ├── voices/ # 语音资源 │ └── config/ # 配置文件 ├── README.md # 说明文档 └── config.json # 用户配置文件如果你下载到的压缩包结构不同以实际文件为准。这里只需要重点关注配置文件的位置后面调整角色人设和模型参数时需要用到。3. 安装启动与首次运行3.1 Windows 平台启动步骤在 Windows 上启动流程比较简单。第一步找到AIRI.exe右键选择“以管理员身份运行”。虽然一般不需要管理员权限但首次运行时如果程序要写入配置到系统目录管理员权限能避免一些拦截问题。第二步如果杀毒软件弹出警告先不要急着添加信任。确认程序是从官方开源地址下载后再在杀毒软件中把解压目录加入白名单。这类桌宠程序常驻桌面、需要读取键盘鼠标事件容易被安全软件误判属于正常现象。第三步启动后程序会常驻系统托盘。如果桌面上没有立即出现角色检查一下托盘图标可能需要右键点击选择“显示角色”。3.2 macOS 平台启动步骤macOS 上的操作略有不同。解压后如果系统提示“无法打开因为无法验证开发者身份”需要进入“系统设置 - 隐私与安全性”在下方找到被拦截的 App选择“仍要打开”。macOS 首次运行桌面宠物类程序时还会询问“是否允许辅助功能访问”这一步需要点允许否则程序可能无法接收全局按键事件。如果后续角色对鼠标交互无响应多半是这个权限没有给。3.3 首次启动与配置文件生成第一次启动成功后程序会在配置目录下自动生成一份默认的config.json或类似格式的配置文件。以常见结构为例大概长这样{ role: { name: AIRI, personality: 温柔、活泼、喜欢二次元, greeting: 你好呀我是 AIRI今天想让我陪你做什么呢 }, model: { provider: openai-compatible, apiBase: https://your-api-endpoint.com/v1, apiKey: sk-xxxxxxxx, modelName: gpt-4o-mini }, tts: { enabled: true, voice: zh-CN-XiaoxiaoNeural }, window: { alwaysOnTop: true, opacity: 0.95, clickThrough: false } }这里的配置项分别控制三类功能role角色基础信息包括名字、性格描述和首次问候语。model大模型接口信息包括 API 地址、密钥和模型名称。tts语音合成开关和音色选择。window桌面窗口行为比如是否置顶、是否半透明、是否允许鼠标穿透。如果你打开配置文件后是空的说明程序走的是默认配置并不会影响运行。修改配置后记得重启程序大部分配置项不支持热加载。4. 角色设定与模型接入4.1 为什么角色设定很关键很多用户下载之后感叹“这个 AI 怎么不像宣传里那么可爱”其实问题不在模型而在角色设定。大语言模型本身是通用模型它不会天然扮演一个二次元角色。想让模型输出符合角色性格的话必须通过 System Prompt系统提示词把角色人设注入进去。AIRI 这类桌宠项目通常会在配置文件中预留角色设定字段我们要善用这个字段。举个例子如果你希望角色是温柔的陪伴型可以在配置文件里写成{ role: { name: 小樱, personality: 温柔体贴、有点小调皮、喜欢夸人、说话语气软萌, greeting: 欢迎回家今天过得怎么样要不要一起打一局游戏, systemPrompt: 你是小樱一个住在用户电脑桌面上的二次元虚拟伙伴。你性格温柔、活泼、爱笑。说话简短常用可爱的语气词。你喜欢陪用户打游戏会为用户的胜利欢呼也会在用户输了的时候安慰用户。你从不说教总是站在用户这一边。 } }System Prompt 写得越具体角色的表现就越稳定。重点不是“角色是谁”而是“角色怎么说话、怎么回应、有什么情绪反应”。建议包含以下信息名字身份背景性格关键词说话风格示例与用户的关系禁止出现的行为4.2 大模型接口配置AIRI 项目支持 OpenAI 兼容接口。也就是说任何提供 OpenAI 风格/v1/chat/completions接口的服务都可以接入。如果你没有可用的 API可以优先考虑国内大模型服务商。这类服务通常都提供 OpenAI 兼容模式只需要在配置里改一下apiBase和modelName即可。配置时注意三点第一apiBase只需要写到 API 版本路径之前程序会自动拼接完整的聊天接口路径。第二apiKey是密钥信息千万不要把写有真实密钥的配置文件截图发到公开平台也不要提交到公开的 Git 仓库。建议先在本地测试确认功能正常。第三模型名称要根据服务商提供的模型列表填写。不同服务商的模型命名差异很大填错了会直接报 404 或 Model Not Found。如果暂时不想申请 API也可以使用本地模型。不过 AIRI 默认对接的是 HTTP API本地部署需要先把模型封装成同一个接口格式。4.3 语音合成配置语音合成的作用是把角色回复的文本转成语音。常见音色信息如下{ tts: { enabled: true, provider: edge-tts, voice: zh-CN-XiaoyiNeural, rate: 10%, volume: 0% } }其中rate控制语速10%表示比默认语速快 10%volume控制音量。如果语音功能异常通常表现为“角色嘴巴在动但没声音”排查方向是系统音量是否静音语音合成服务是否正常网络权限是否被防火墙拦截。如果还是不行可以先关闭 TTS只使用文字气泡对话就不会影响整体体验。4.4 陪玩游戏功能设置AIRI 的一大特色是“陪你玩游戏”。这个功能的实现原理并不复杂主要是通过桌面悬浮窗和游戏窗口共存角色悬浮在游戏上方玩家可以通过语音或输入框和角色实时互动。从项目讨论来看AIRI 的陪玩场景包括单机游戏中角色在旁边加油鼓劲、讲解剧情联机游戏中角色作为语音伙伴陪你闲聊挂机游戏中角色定时提醒你补充体力、领取奖励。如果你希望角色在特定游戏窗口上方显示可以调整窗口配置{ window: { alwaysOnTop: true, clickThrough: true, position: bottom-right, offsetX: 20, offsetY: 20 } }这里clickThrough设置为true时角色窗口不会拦截鼠标点击适合在游戏中常驻避免挡操作。但设置为 true 后鼠标也无法通过常规方式拖拽角色需要通过托盘菜单调整位置。5. 从使用到动手二次开发5.1 理解桌面角色的渲染原理如果你想在 AIRI 基础上做二次开发第一个要理解的概念就是 Live2D。Live2D 是一种 2D 动画技术通过把一张插画拆分成多个零件再对这些零件做位移、旋转、变形产生“伪 3D”的动画效果。AIRI 的二次元角色就是用这种技术渲染的。如果你下载的是完整源码会发现模型文件通常是.moc3或.model3.json格式。这些是 Live2D Cubism 的标准格式想要替换角色皮肤就是替换这套模型文件。替换模型的大致流程准备一套 Live2D 模型文件放到resources/models/目录下修改配置文件中的模型路径重启程序。5.2 编写一个最简对话接入脚本如果你想验证某个大模型接口是否适合 AIRI可以先用一段 Python 脚本测试。下面是核心思路实际接口参数请以你的模型服务商文档为准。import requests API_BASE https://your-api-endpoint.com/v1 API_KEY sk-your-key MODEL your-model-name url f{API_BASE}/chat/completions headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { model: MODEL, messages: [ { role: system, content: 你是 AIRI一个住在用户桌面上的二次元虚拟伙伴。你温柔、可爱、说话简短。 }, { role: user, content: 今天陪我打游戏吗 } ], temperature: 0.8, max_tokens: 200 } resp requests.post(url, headersheaders, jsonpayload, timeout30) data resp.json() print(data[choices][0][message][content])这段脚本的作用是快速验证模型接口有没有通回复质量是否符合预期。如果接口正常resp.status_code应该是 200内容打印在终端里。如果报错重点看返回的error字段常见错误有invalid_api_key密钥错误。model_not_found模型名称不存在。insufficient_quota账户余额不足。rate_limit_exceeded请求频率过高。5.3 接入本地模型实现零成本运行想要完全不依赖云端 API可以考虑在本地部署一个小型对话模型。本地部署的核心思路是用一个本地推理服务把模型暴露成 HTTP 接口然后让 AIRI 的配置指向本地地址。常见的本地推理工具有 Ollama、LM Studio、llama.cpp 等。以 Ollama 为例启动一个支持 OpenAI 兼容接口的本地服务ollama pull qwen2.5:7b ollama serve服务启动后本地默认监听http://localhost:11434。接下来在 AIRI 的配置中填写{ model: { provider: openai-compatible, apiBase: http://localhost:11434/v1, apiKey: ollama, modelName: qwen2.5:7b } }这样对话请求只会发送到本机完全不需要联网也不产生任何接口费用。缺点是回复速度比云端模型慢一些尤其是显存不足时每句话可能要等很久。建议先用云端模型测试功能再切换本地模型节省成本。6. 常见问题与排查思路这里整理一下 AIRI 在使用过程中比较常见的问题方便读者按表排查。问题现象常见原因解决思路双击程序没反应解压目录存在中文字符 / 被杀毒软件拦截将目录改为英文路径在杀毒软件中加白名单角色出现在桌面但无法对话大模型接口配置错误 / API Key 无效检查 apiBase、apiKey、modelName 是否正确先用脚本测试接口连通性对话回复特别慢网络延迟高 / 模型参数量大 / 本地模型推理慢换更低延迟的 API 节点使用更小参数的模型开启流式对话角色有文字气泡但没有声音TTS 服务异常 / 系统音量问题检查系统音量确认 TTS 接口可用先关闭 TTS 再排查角色窗口挡住游戏操作窗口点击穿透未开启将 clickThrough 设为 true必要时关闭 alwaysOnTop角色突然消失程序崩溃 / 托盘退出 / 资源加载超时查看日志文件重启程序确认模型资源完整修改配置后不生效未重启程序 / 配置文件路径修改错误重启程序确认修改的是程序实际读取的配置文件角色表情和语音不同步动画资源与语音时长匹配不当更新模型资源降低语音语速更换匹配的音色无法显示中文字体系统缺少对应字体安装中文字体检查字体资源路径本地模型一直加载不出回复显存不足 / 模型未完全加载使用更小的量化模型关闭其他占用显存的应用经常有人说“配置改完但一点用都没有”九成情况是因为程序读取的配置路径和你修改的路径不一致。解决方法是先找到程序运行时自动生成的默认配置文件记录它的完整路径然后基于它做修改。7. 最佳实践与工程建议7.1 角色设定层面的建议角色设定的质量直接决定使用体验。建议重点优化 System Prompt而不是频繁更换模型。把好的角色设定当成一份“角色卡”每次调整只改一个维度。比如第一次只改性格关键词观察回复变化第二次加说话风格第三次加情绪反应规则。这样能精确定位哪些改动起了作用。另外建议把人设中加上“禁止行为”。比如不要说教。不要长篇大论单次回复控制在 50 字以内。不要主动询问用户隐私信息。负面约束往往比正面描述更有效。模型对“不要做什么”的理解更明确。7.2 配置管理层面的建议配置文件中包含 API Key属于敏感信息。建议把真实配置和示例配置分开管理。在项目目录下保留一份config.example.json只放占位符可以提交到代码仓库。真实的config.json加入.gitignore避免泄露。如果你做了二次开发想把自己的配置分享给其他人记得把所有密钥替换为示例值。7.3 性能与资源占用建议AI 桌宠属于常驻应用性能优化很重要。不要同时开启太多角色每个角色都会占用一定的模型调用资源和渲染资源。如果电脑配置一般优先选择云端 API把推理压力放在服务端。使用 Live2D 模型时尽量选择面数适中的资源避免动画掉帧。如果角色只是挂在桌面不需要频繁动画可以把帧率限制调低。7.4 生产环境与正式使用注意如果你打算把 AIRI 分享给同事、朋友或用于公开演示还需要注意几点。第一确认项目开源协议。分发前阅读项目的 LICENSE了解是否允许修改后重新分发是否允许商业使用。第二不要内置真实 API Key。正式分发给他人时应提供配置入口让用户自己填写 Key而不是把个人 Key 打包进应用。第三注意模型内容的合规性。开放给他人使用时需要在 System Prompt 中预设内容边界避免模型生成违规内容。第四涉及自动更新、远程加载资源的功能要谨慎。开源项目如果从远程拉取配置或模型存在供应链安全风险。建议固定版本离线使用。7.5 如何参与开源社区AIRI 目前是社区活跃度比较高的开源桌宠项目。如果你尝试后觉得不错可以参与贡献提交 Bug Issue附带系统版本、日志和复现步骤。贡献角色模型分享你自己调好的 Live2D 模型。编写教程文档帮新人降低上手门槛。提交代码修复比如增加模型平台适配、优化动画表现。开源项目最大的价值就是不只有一个人维护而是所有使用者都能参与改进。对个人开发者来说给这样的项目提 PR 也是积累实战经验的好机会。8. 总结与下一步学习方向到这里AIRI 桌宠的安装、配置、角色设定、模型接入、常见问题以及二次开发思路都梳理完了。整个上手过程可以概括为四步下载解压、修改配置、启动验证、调优人设。学习 AI 桌宠项目其实不只是为了好玩它会把你平时积累的 AI 知识串联起来。大模型接口调用、Prompt 工程、语音合成、桌面应用交互这些能力在任何 AI 产品开发中都用得上。接下来如果你想继续深入可以按这个顺序学习学会写 System Prompt把一个通用模型调教成有性格的角色。熟悉 OpenAI 兼容接口协议掌握 chat/completions 的核心参数。研究 Live2D 模型结构尝试自己制作或替换角色皮肤。接触本地模型部署工具了解显存、量化、推理速度之间的关系。阅读 AIRI 源码理解桌宠应用的整体架构。如果本文对你有帮助可以收藏备用。后续我也会继续分享 AI 桌宠、Prompt 工程和桌面应用相关的内容欢迎关注。