Project AIRI 开发日志 2025.05.16 深度解读:角色卡片、浏览器语音管线与 Velin 模板引擎的落地实践
Project AIRI 开发日志 2025.05.16 深度解读:角色卡片、浏览器语音管线与 Velin 模板引擎的落地实践
本文以 Project AIRI(moeru-ai/airi)2025-05-16 开发日志为骨架,系统梳理 v0.5.0 前后社区贡献的核心能力:Character Card V3 角色卡片的解析与编辑、基于 VAD/ASR/TTS 的浏览器实时语音对话管线、xsAI Transformers.js 本地推理切换、Telegram 机器人增强、WebGPU 背景移除,以及用 Vue 编写 LLM 提示词的 Velin 项目。文中所有实现细节均可在当前仓库源码中找到对应佐证。
写在前面:这篇 DevLog 在讲什么
2025 年 5 月 16 日的这篇开发日志(原文,另有 英文版、中文版、日文版)发布于 v0.5.0 里程碑前后。它既是月度进展汇报,也是一份难得的“架构决策实录”:作者 Neko 在经历了 2025 年 3 月以来大规模 UI 重构与连续发布后出现轻度倦怠,主要开发工作由社区维护者完成。日志按「主任务 / 支线任务」两层结构组织,覆盖了角色卡片、语音管线、本地模型推理、Telegram 机器人、背景移除、UI 组件、Velin 提示词模板引擎等多项技术主题。
对开发者而言,这篇日志最具价值的地方在于:它揭示了 AIRI 如何把「LLM 角色扮演」「实时语音对话」「本地 WebGPU 推理」这三件相互独立又彼此咬合的事情,以事件驱动流式管线的方式串联起来。下文将逐主题展开,并把每个主题映射到当前仓库的具体实现路径上,方便读者按图索骥深入阅读。
一、社区贡献主线:角色卡片(Character Card)支持
1.1 角色卡片是什么
日志中用「提示框(tip)」介绍了角色卡片的行业背景:SillyTavern、RisuAI 等本地优先聊天应用,以及 JanitorAI 等在线服务,都使用一种文件来承载角色的背景、性格、示例对话等角色扮演上下文。它是 LLM 角色扮演社区里保存与分享角色事实标准之一;日志同时点名了 Lorebook(世界书)这类相邻概念,推荐阅读 Void's Lorebook Types 与 AI Dynamic Storytelling Wiki 作为入门。
1.2 仓库里的角色卡片落地:ccc 包
日志提到角色卡片支持主要由 @LemonNekoGH,其名称正是 "Character Card Codec" 的缩写。
在 characterCardV3.ts 中可以看到完整的 Character Card V3(CCv3)Schema 实现,它基于 valibot 构建:
- 外层信封
characterCardV3Schema:要求spec: 'chara_card_v3',spec_version需匹配\d+(?:\.\d+)*的正则; - 内层数据对象
characterCardDataSchema:包含name、description、personality、scenario、first_mes、mes_example、alternate_greetings、character_book、character_version、creator、creator_notes、extensions、post_history_instructions、system_prompt、tags,以及 V3 新增的assets、creation_date、creator_notes_multilingual、group_only_greetings、modification_date、nickname、source等字段; - 类型上通过
DataV1/DataV2/DataV3三个 Pick 类型清晰标注了字段的版本沿革:description、first_mes、mes_example、name、personality、scenario继承自 V1;alternate_greetings、character_book等继承自 V2;assets、nickname等为 V3 引入。
值得注意的实现细节有两点(从源码结构看,这是该包的设计亮点):
- 未知字段保留:所有 schema 均以
objectWithRest(..., unknown())结尾,parseCharacterCardV3在解析失败时抛出InvalidCharacterCardError,成功时返回{ card, compatibility }。compatibility通过resolveCompatibility将spec_version与当前实现的 3.0 比较,得出'older' | 'current' | 'newer'三种分类,供上层决定是否向用户提示版本差异。 - Lorebook 内嵌:
character_book条目(characterBookEntrySchema)完整支持keys、content、enabled、insertion_order、use_regex、case_sensitive、selective、secondary_keys、position等字段——这正是日志中提及的 Lorebook 概念在数据层的落点。
该包的测试位于 characterCardV3.test.ts,覆盖了合法卡片解析、非法输入抛错等边界场景,可以作为二次开发的参考基准。
1.3 AIRI Card 编辑页:从菜单到编辑器
日志给出了完整的使用路径:进入设置页(桌面端悬停右上角齿轮图标)→ 点击 Airi Card 按钮 → 进入「Airi Card 编辑画面」,上传并编辑角色卡片以定制人格。对应到仓库:
- 菜单入口组件为 character-card.vue,其 Story 页面可直接在组件库中体验(
airi.moeru.ai/ui的character-cardstory);该组件用纯 CSS 与 JavaScript 控制布局与条码装饰,正如日志所说“无需操心画布计算”; - 编辑页面位于 packages/stage-pages/src/pages/settings/airi-card,包含列表页
index.vue、新建页new.vue、编辑页[cardId]/edit.vue,以及CardEditor.vue、CardDetailDialog.vue、CardListItem.vue等子组件; - 编辑页的组合式函数 use-airi-card-editor-page.ts 实现了典型的“脏数据守卫”:维护
isDirty状态,通过onBeforeRouteLeave拦截路由跳转并弹出未保存确认框,同时在beforeunload事件上阻止浏览器直接关闭页面,避免用户丢失未保存的角色配置。
1.4 角色卡片展示卡(Showcase)
日志还展示了为蓝发角色「ReLU」设计的卡片式 UI 展示方案,并提到该设计已上架到组件库 Story(src-components-menu-charactercard-story-vue)。在仓库中对应 character-card.story.vue 与 character-card.vue——后者通过 props 暴露 title、subtitle、primaryColor、secondaryColor、textColor、barcodeCount、barWidth 等十余个样式参数,并用 culori 做颜色亮度过滤,实现明暗主题自适应。
二、主任务「耳朵与嘴巴」:浏览器实时语音对话管线
2.1 从队列到 llama-flow:管线思想的转变
日志记录了 AIRI 语音链路的一次重要架构演进:自 2025 年 4 月 15 日起,作者意识到 VAD(语音活动检测)、ASR(自动语音识别)、TTS(文本转语音)三者组合起来“非常复杂、难以书写和理解”。在此之前,AIRI 需要自己用队列结构 + Vue 响应式手搓一个工作流系统来串接多个异步任务;之后作者与 @himself65 合作改进并测试了 Llama Index 的新项目 llama-flow——一个帮助处理 LLM 流式 token 与音频字节事件流的类型安全库。
这一思想直接沉淀为仓库中的 packages/pipelines-audio 包。其中 speech-pipeline.ts 用 createSpeechPipeline<TAudio>() 提供了完整的流式语音合成调度能力:
- 意图(Intent)模型:每次说话请求作为一个
IntentState,携带turnId、streamId、priority、behavior('queue' | 'interrupt' | 'replace')等元数据; - 并发控制:
ttsMaxConcurrent(默认 4)限制同时进行的 TTS 生成任务数,inFlightTasks集合配合Promise.race实现背压等待; - 抢占策略:
priorityResolver解析优先级,behavior === 'replace'直接取消当前意图,'interrupt'则在新意图优先级不低于当前时打断; - 时间线调度:通过
createTimeline()保证“同一语音轨道上的播放严格按序”,而不同轨道可并行,最终由waitForPlayback串起播放事件。
2.2 语音输入端的工程化:AudioInput
与流水线配套的是 audio-input.ts 中的 AudioInput 类,它把麦克风这类实时音频源共享给多个订阅者:
- 第一个订阅者打开音频源,最后一个离开时关闭;
- 支持
historyMs历史窗口(默认 0,可通过retain()租赁延长),让“语音已经在说话、检测器才刚触发”的场景也能重放已发生音频; - 每个订阅流通过
maxBufferedMs(默认 60_000ms)限制积压缓冲,慢消费订阅者单独报错而不是拖垮整条链路——这是实时音频处理里非常实用的背压设计。
2.3 VAD 的本地化实现:Silero 模型 + Transformers.js
日志提到 VAD/ASR/TTS 三个环节都被重新审视。在仓库中,VAD 的实现位于 apps/stage-web/src/workers/vad/vad.ts,它基于 @huggingface/transformers 加载 onnx-community/silero-vad 模型,并给出了一组可直接参考的默认参数:
sampleRate: 16000speechThreshold: 0.3(说话判定阈值)exitThreshold: 0.1(静音退出阈值)minSilenceDurationMs: 400(最小静音时长)speechPadMs: 80(语音前后填充)minSpeechDurationMs: 250(最小语音时长)maxBufferDuration: 30(最大缓冲秒数)newBufferSize: 512(新缓冲区大小)
VAD 被封装在 Web Worker 中,并通过 BaseVAD / BaseVADConfig 接口与 stage-ui 的音频层解耦,保证模型推理不阻塞主线程。
2.4 TTS 文本切分器:把流式 token 变成可合成片段
tts-chunker.ts 是语音管线中最“咬文嚼字”的模块,负责把 LLM 流式输出的 token 切成适合 TTS 请求的文本块。其关键设计包括:
- 标点分类:硬标点(
.。??!!…⋯~~\n\t\r)、软标点(,,、–—::;;《》「」)、保留标点(??!!)分别触发不同的切分策略; - 三档字数控制:
boost(默认 2,开头的块可提前在软标点处结束以降低“首音频延迟”)、minimumWords(默认 4)、maximumWords(默认 12); - 特殊控制字符:
TTS_FLUSH_INSTRUCTION(零宽空格\u200B)强制刷新当前块,TTS_SPECIAL_TOKEN(\u2063)标记动作/表情类特殊事件,二者与writeSpecial()/writeFlush()意图 API 对应; - 叙述剥离:
stripNarrative选项配合processNarrative()与isProbablyAngleTag(),可识别并剥离*动作*、[括号注释]、<动作标签>等叙事文本,避免 TTS 把场景描写读出来。
2.5 WebAI Realtime Voice Chat Examples:300~500 行复刻 ChatGPT 式语音对话
日志以一个小目标证明了这套管线的可行性:用单个 TypeScript 文件、300~500 行代码在浏览器里实现类 ChatGPT 的实时语音对话系统。示例仓库按依赖关系拆成了四个可独立学习的 Stage:
VAD:仅语音活动检测;VAD + ASR:加上自动语音识别;VAD + ASR + LLM Chat:接入大模型对话;VAD + ASR + LLM Chat + TTS:完整闭环。
此外还有基于 k2-fsa/sherpa-onnx 的变体 demo(sherpa-onnx-demo)。日志强调 sherpa-onnx 支持 12 种以上语言、18 类语音处理任务,覆盖 macOS / Windows / Linux / Android / iOS。对想从零搭建浏览器语音对话的读者,这组示例是极好的阶梯式教程。
三、xsAI 🤗 Transformers.js:本地 WebGPU 推理与云端的“一键切换”
3.1 项目的诞生背景
日志记录了 xsai-transformers(moeru-ai/xsai-transformers)作为新旁支项目的诞生:在制作 VAD/ASR/Chat/TTS 示例的过程中,作者希望有一个库能做到——既能在浏览器里通过 WebGPU 模型推理 + Worker 服务 简单调用本地模型,又能与之前成功的 xsAI 保持 API 兼容。它自发布当天起即可通过 npm 安装:
npm install xsai-transformers
3.2 它能带来什么:从云端到本地的一键切换
日志用一个「提示框」点明了它的价值:把云端 LLM / 语音提供商与本地 WebGPU 模型用“一个开关”互相切换。这意味着:
- 不需要后端服务器、不需要任何服务端代码,就能在浏览器里实验甚至实现简单的 RAG 与重排系统;
- 支持 Node.js 运行环境;
- 官方提供了可在线体验的 playground(
xsai-transformers.netlify.app)。
3.3 仓库中的印证:本地推理与 GPU 资源协调
这一「本地推理优先」的设计哲学在当前仓库的 packages/stage-ui/src/libs/inference 系列模块中得到印证:本地推理通过 gpu-resource-coordinator、load-queue、protocol 等模块进行 GPU 内存预算分配、模型加载排队与统一消息协议管理。以下文要讲的背景移除为例,background-removal.ts 中能看到:
- 模型加载走
getLoadQueue().enqueue(...),并申请MODEL_VRAM_ESTIMATES.modnet的 GPU 显存配额; - 推理状态通过
updateInferenceStatus上报给 UI,用户可以实时看到「下载中 / 就绪 / 推理中」; - 所有请求带
AbortSignal,支持取消与超时(LOAD_TIMEOUT/PROCESS_TIMEOUT)。
这说明 AIRI 的本地推理基础设施并非玩具,而是已经具备资源预算、排队、取消、状态上报等生产级要素。
四、Telegram 机器人增强:动图贴纸理解与 Token 瘦身
4.1 用 ffmpeg 理解动画贴纸
日志提到,Telegram 机器人新增了对动态(动画)贴纸与视频的读取理解能力,实现方式是(毫不意外地)使用 ffmpeg。仓库中的对应实现位于 integrations/telegram-bot/src/llm/animated-sticker.ts,流程非常完整:
- 通过 grammy 的
bot.api.getFile拿到贴纸文件并下载到临时目录; - 用
fluent-ffmpeg(二进制路径来自@ffmpeg-installer/ffmpeg)以-vf fps=15抽帧为frame-%03d.png; - 帧数超过 8 帧时按采样率抽稀到约 5~8 帧;
- Stage 1:逐帧调用视觉 LLM(
LLM_VISION_API_KEY/LLM_VISION_MODEL),给出每帧的详细描述; - Stage 2:把所有帧描述交给纯文本 LLM 汇总成一段连贯的“动态贴纸理解”;
- 结果通过
recordSticker存入数据库,并用首帧作为缩略图;命中缓存的贴纸直接跳过重复推理。
这个“先逐帧描述、再整体归纳”的两段式方法,把「动画内容理解」拆解成了视觉模型擅长、文本模型也擅长的两步,是很值得借鉴的工程模式。
4.2 系统提示词瘦身:Token 用量直降 80%
日志强调系统提示词被“大幅削减”,token 用量节省了 80% 以上。仓库中的佐证是 system-ticking-v1.velin.md——注意这个文件名的 .velin.md 后缀:它本身就是下文要讲的 Velin 格式的应用实例。该提示词把机器可读的「动作列表」(list_chats、send_message、send_sticker、read_unread_messages、continue、break、sleep、come_up_ideas、come_up_goals 等)以结构化的方式组织起来,让模型以 JSON 消息数组回应,从而大幅压缩冗余表述。
五、支线任务:背景移除工具与 UI 组件
5.1 WebGPU 背景移除器
日志提到,由于角色卡片涉及大量图片素材,作者不想每次都去外部找在线抠图工具,于是基于 Xenova 的工作自制了一个 WebGPU 背景移除器,体验地址为 airi.moeru.ai/devtools/background-remove。仓库实现位于 apps/stage-web/src/pages/devtools/background-removal.vue:
- 页面通过
createBackgroundRemovalAdapter()创建适配器,挂载时adapter.load()加载模型,卸载时adapter.terminate()释放资源; - 支持多图队列处理:
pending→processing→done/error状态机,并带「自动处理」开关与逐图进度展示; - 推理本身在 Worker 中进行(见 packages/stage-ui/src/libs/inference/adapters/background-removal.ts 中
new Worker(...)的创建逻辑),主线程只负责把ImageData像素拷贝(Transferable 转移)发给 Worker,再把返回的 mask 数据写回 alpha 通道:output.data[4 * i + 3] = maskData[i]——简洁而典型的“抠图 = 用 mask 改 alpha”实现。
5.2 UI 组件库进展
日志列出了 v0.5.0 周期内新增/改进的 UI 组件,均可在 packages/stage-ui 的 Story 库中找到对应 Story 文件:
- 新的教程 Stepper 组件:
components/misc/steppers/steppers.story.vue; - 新的文件上传组件:
components/form/input/input-file.story.vue(含卡片形态input-file-card.story.vue与字段形态field-input-file.story.vue); - Textarea 组件:
components/form/textarea/textarea.story.vue; - 另修复了颜色问题、改进了排版(Typography)。
六、支线任务:Velin——用前端框架写 LLM 提示词
6.1 动机:模板变量与组件复用之痛
日志用一段“如果……会怎样”的假设展开了 Velin 的动机:在支持角色卡片之后,作者发现「模板变量渲染 + 组件复用」这两件事的体验并不顺滑。如果:
- 能维护一个组件化提示词库,供其他 Agent、角色扮演应用甚至角色卡片复用(比如:先定一个“魔法与龙的中世纪奇幻世界观”,然后只专注写新角色;或者只在“入夜”时用
if/if-else控制流注入特殊提示词); - 能用 Vue SFC 或 React JSX 解析模板、识别 props,在写提示词的同时渲染一个表单面板用于调试与测试;
- 能把 Lorebook 与角色卡片整体可视化成一个可交互页面;
那么是否可以用 Vue 或 React 这类前端框架来“写 LLM 提示词”,并进一步扩展到其他框架与平台?——Velin(github.com/luoling8192/velin)正是这个设想的产物。
6.2 形态与生态
- 提供编辑器内即时渲染的 playground(
velin-dev.netlify.app),并且完全复用 npm 生态——“是的,什么都能 import”; - 支持编程 API 与 Markdown 语法(MDX 仍在开发中,MDC 已支持);
- 发布当日即可安装:
npm install @velin-dev/core
6.3 仓库内的实战证据
Velin 并非停留在概念层。前文提到的 system-ticking-v1.velin.md 就是它的真实使用案例:提示词文件开头直接是一个 <script setup> 块(Vue 语法),内部用 defineProps 声明 responseLanguage,并用 v-for 循环渲染 actions 数组,把结构化动作列表注入提示词。这说明 Velin 允许提示词以“组件 + 数据”的方式组织,模型看到的其实是渲染后的确定性文本,而维护者可以在源码层面复用、参数化这段提示词。
七、Demo Day @ Hangzhou 与 v0.5.0 里程碑
日志以作者参加杭州 Demo Day @ Hangzhou 活动的照片收尾:作者向现场的开发者、产品设计师与创业者介绍了 AIRI 项目,并分享了 Neuro-sama 等 AI VTuber 相关内容;演讲幻灯片也完全开源(talks.ayaka.io/nekoayaka/2025-05-10-airi-how-we-recreated-it)。
最后,日志列出了 v0.5.0 里程碑的成果清单,可作为理解该项目演进节奏的参考:
- 社区与规模:达成 700 星;新增 4 名以上贡献者;Discord 新增 72 名以上成员;开始与多家公司洽谈赞助与合作;
- 角色资产:ReLU 角色设计与建模完成;
- 路线图执行:Roadmap v0.5 中 92 个任务完成,覆盖:
- UI:加载画面、教程模块、Firefox 兼容性等多处 bug 修复;
- Body:基于语义的 motion embedding 与 RAG(在私有仓库
moeru-ai/motion-gen中开发),以及用 embedding provider + DuckDB WASM 做向量存储与检索; - Inputs:修复 Discord 语音频道的语音识别;
- Outputs:实验性的歌声功能;
- Engineering:全项目共享 UnoCSS 配置、
moeru-ai/inventory模型目录、组织级包重组; - Assets:贴纸、UI 元素、VTuber logo 等新角色素材,语音线选择功能,角色「Me」与「ReLU」的 Live2D 建模;
- 社区支持与营销:日文 README 与更完善的文档。
结语:这篇 DevLog 值得带走的三件事
- 事件驱动的流式管线是 AIRI 的骨架:从
llama-flow的引入到 speech-pipeline.ts 的 Intent / priority / timeline 模型,语音链路已经是一套可独立复用、可测试的工程组件,而非散落的回调。 - 角色卡片不是一个 JSON,而是一套版本化规范:通过 packages/ccc 的 CCv3 Schema、兼容性分类与未知字段保留策略,AIRI 得以在社区生态(SillyTavern、RisuAI、chub.ai 等)与自身编辑器之间安全往返数据。
- 本地推理与提示词工程都在“组件化”:WebGPU 背景移除、Silero VAD、xsAI Transformers.js 把模型推理变成浏览器里的普通依赖;而 Velin 则把提示词从字符串升级为“可复用、可参数化、可渲染”的组件——这条思路对任何想构建 Agent 或角色扮演应用的开发者都有直接参考价值。
如需继续深入,建议按顺序阅读仓库中的 pipelines-audio 测试用例、ccc 包测试、stage-ui 的 inference 模块,再回到 角色卡片编辑页 串联完整调用链。


