Project AIRI 开发日志 2025.05.16 深度解读:角色卡片、浏览器语音管线与 Velin 模板引擎的落地实践

原创2026-10-16 10:23:091,687 阅读
文章标签:AI 应用大模型AI Agent数字人前端后端桌面应用移动开发音频

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 引入。

值得注意的实现细节有两点(从源码结构看,这是该包的设计亮点):

  1. 未知字段保留:所有 schema 均以 objectWithRest(..., unknown()) 结尾,parseCharacterCardV3 在解析失败时抛出 InvalidCharacterCardError,成功时返回 { card, compatibility }。compatibility 通过 resolveCompatibility 将 spec_version 与当前实现的 3.0 比较,得出 'older' | 'current' | 'newer' 三种分类,供上层决定是否向用户提示版本差异。
  2. 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-card story);该组件用纯 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 事件上阻止浏览器直接关闭页面,避免用户丢失未保存的角色配置。

Airi Card 菜单入口:设置页中「Airi Card」按钮所在位置

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 做颜色亮度过滤,实现明暗主题自适应。

角色卡片展示卡样式(以 ReLU 为例的卡片 UI 设计)

二、主任务「耳朵与嘴巴」:浏览器实时语音对话管线

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: 16000
  • speechThreshold: 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:

  1. VAD:仅语音活动检测;
  2. VAD + ASR:加上自动语音识别;
  3. VAD + ASR + LLM Chat:接入大模型对话;
  4. 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,流程非常完整:

  1. 通过 grammy 的 bot.api.getFile 拿到贴纸文件并下载到临时目录;
  2. 用 fluent-ffmpeg(二进制路径来自 @ffmpeg-installer/ffmpeg)以 -vf fps=15 抽帧为 frame-%03d.png;
  3. 帧数超过 8 帧时按采样率抽稀到约 5~8 帧;
  4. Stage 1:逐帧调用视觉 LLM(LLM_VISION_API_KEY / LLM_VISION_MODEL),给出每帧的详细描述;
  5. Stage 2:把所有帧描述交给纯文本 LLM 汇总成一段连贯的“动态贴纸理解”;
  6. 结果通过 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 允许提示词以“组件 + 数据”的方式组织,模型看到的其实是渲染后的确定性文本,而维护者可以在源码层面复用、参数化这段提示词。

Velin:基于 Vue 的 LLM 提示词编写工具界面

七、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 值得带走的三件事

  1. 事件驱动的流式管线是 AIRI 的骨架:从 llama-flow 的引入到 speech-pipeline.ts 的 Intent / priority / timeline 模型,语音链路已经是一套可独立复用、可测试的工程组件,而非散落的回调。
  2. 角色卡片不是一个 JSON,而是一套版本化规范:通过 packages/ccc 的 CCv3 Schema、兼容性分类与未知字段保留策略,AIRI 得以在社区生态(SillyTavern、RisuAI、chub.ai 等)与自身编辑器之间安全往返数据。
  3. 本地推理与提示词工程都在“组件化”:WebGPU 背景移除、Silero VAD、xsAI Transformers.js 把模型推理变成浏览器里的普通依赖;而 Velin 则把提示词从字符串升级为“可复用、可参数化、可渲染”的组件——这条思路对任何想构建 Agent 或角色扮演应用的开发者都有直接参考价值。

如需继续深入,建议按顺序阅读仓库中的 pipelines-audio 测试用例、ccc 包测试、stage-ui 的 inference 模块,再回到 角色卡片编辑页 串联完整调用链。

登录后查看全文
airi