moeru-ai/airi 딥다이브
— 브라우저 안에서 "사는" 오픈소스 AI 버튜버·컴패니언

1프로젝트 한 줄 요약

airi는 "LLM으로 움직이는 가상 캐릭터를, 서버·구독 없이 내 컴퓨터에서 완전히 소유하며 키우는 오픈소스 프로젝트"다. 화면에는 2D(Live2D) 혹은 3D(VRM) 아바타가 떠 있고, 당신이 마이크로 말을 걸면 캐릭터가 귀로 듣고(음성 인식) → 머리로 생각하고(LLM) → 입으로 답하고(음성 합성) → 몸으로 반응한다(입 모양·표정·시선). 여기에 대화를 기억하는 장기 기억과, 디스코드·텔레그램에서 함께 떠들거나 마인크래프트를 직접 플레이하는 능력까지 붙는다.

핵심 지향점은 딱 한 문장이다. "Neuro-sama 같은 AI 버튜버를, 특정 회사의 클라우드에 묶이지 않고 누구나 자기 손으로 굴릴 수 있게 하자." 그래서 airi는 브라우저 웹앱(PWA), 데스크톱 앱(Electron), 모바일 앱(Capacitor), 그리고 네이티브 게임 엔진(Godot)까지 같은 두뇌를 여러 몸에 이식하는 형태로 만들어졌다.

2왜 지금 주목받는가

airi가 눈길을 끄는 이유는 "요즘 뜨는 기술 주제를 거의 다 한 저장소에서 실제로 동작하게 묶었다"는 데 있다. 브라우저 내 AI 추론, provider 무관 LLM 계층, 실시간 음성 대화, 3D 아바타, 임베디드 에이전트(게임 플레이), 로컬 벡터 메모리, 크로스플랫폼 배포 — 각각만 해도 인기 주제인데, airi는 이 전부를 하나의 완성도 높은 제품으로 합쳤다. "에이전트형 멀티모달 캐릭터 앱을 어떻게 짓는가"를 통째로 보여 주는 드문 레퍼런스다.

주목 포인트 1 — "완전 브라우저 내 AI"라는 도발

airi에서 가장 인상적인 건 음성 인식(Whisper)·음성 활동 감지(Silero VAD)·음성 합성(Kokoro), 그리고 원한다면 LLM까지 클라우드 없이 브라우저 탭 안에서 돌린다는 점이다. 이를 가능케 한 것이 @huggingface/transformers(transformers.js)와 onnxruntime-web, 그리고 WebGPU다. GPU가 없거나 브라우저가 WebGPU를 못 쓰면 자동으로 WASM으로 내려앉는(fallback) 안전장치까지 있다. "AI는 무조건 서버에서 돌린다"는 통념을 정면으로 흔드는, 요즘 가장 뜨거운 흐름의 실물 교보재다.

주목 포인트 2 — 하나의 두뇌, 여러 개의 몸

airi는 아바타 UI(무대, stage)와 실제 능력(음성·게임·기억)을 WebSocket "신경망 버스"로 느슨하게 분리했다. 덕분에 같은 두뇌가 브라우저에서는 말동무가 되고, 데스크톱에서는 화면 위를 떠다니는 오버레이가 되고, 마인크래프트 서버에 접속하면 게임 캐릭터가 된다. 이 "능력을 모듈로 꽂았다 뺐다" 하는 이벤트 기반 구조(§4)가 airi를 단순한 챗봇 UI가 아니라 확장 가능한 플랫폼으로 만든다.

3기술 스택 전체 지도

airi의 스택은 방대하지만, 캐릭터의 신체 은유로 묶으면 한눈에 들어온다 — 눈에 보이는 무대(Vue 프론트엔드), 듣고 말하는 감각(음성 파이프라인), 판단하는 두뇌(LLM 계층), 기억(로컬 벡터 DB), 그 모두를 잇는 신경(WebSocket 버스), 그리고 이 두뇌가 깃드는 여러 몸(데스크톱·모바일·게임)이다. 아래 버전은 클론한 소스의 실제 값 기준이다.

무대 · 프론트엔드 (the Stage)

아바타 렌더링 (the Body — 2D/3D)

감각 · 음성 입출력 (Ears & Mouth — 브라우저 내 동작 가능)

두뇌 · LLM 계층 (the Brain)

airi의 LLM 추상화 핵심은 xsai ^0.5.0-beta.2 — OpenAI 스타일의 경량 SDK다. @xsai/stream-text·generate-text·generate-speech·stream-transcription·tool 등으로 잘게 쪼개져 있고, @xsai-ext/providers가 provider들을, @xsai-transformers가 브라우저 내 LLM(transformers.js)을 담당한다. 문서상 32개 provider(OpenAI·Anthropic Claude·Ollama·vLLM·SGLang·Gemini·DeepSeek·Qwen·Groq·Mistral·Cloudflare…)를 지원한다.

기억 · 로컬 데이터 (the Memory) / 신경 · 백엔드

여러 개의 몸 · 배포 타깃 (the Shells)

4아키텍처 심화 분석

4-1. 전체 그림 — 하나의 대화 한 바퀴

airi를 이해하는 가장 빠른 길은 "당신이 말 한마디를 걸었을 때, 그 신호가 어떤 순서로 캐릭터의 반응이 되는가"를 따라가는 것이다. 귀에서 시작해 몸으로 끝나는 이 루프가 airi의 심장이다.

핵심을 지탱하는 발상은 가운데 무대(아바타 UI)와 바깥의 능력들(게임·기억·챗 플랫폼)이 WebSocket 버스로 분리돼 있다는 것이다. 그래서 같은 두뇌가 게임을 하든, 채팅을 하든, 음성 통화를 하든 무대 코드는 그대로다.

4-2. 신경망 버스 — 모듈을 꽂으면 능력이 붙는다

airi에서 가장 구조적으로 영리한 부분은 server-runtime(서버) ↔ server-sdk(클라이언트)로 이뤄진 타입 있는 WebSocket 프로토콜이다. 어떤 모듈(마인크래프트 봇, 기억 저장소, 디스코드 브리지)이든 서버에 자신을 announce(등록)하고 이벤트를 주고받는다. 그 결과 능력을 코드 수정 없이 런타임에 붙였다 뗐다 할 수 있다.

// packages/memory-pgvector/src/index.ts:11 — 기억 모듈이 버스에 등록
const client = new Client<{ connectionString: string }>({ name: 'memory-pgvector' })
client.onEvent('module:configure', (_event) => {
  /* 서버로부터 DB 설정을 수신 */
})
runUntilSignal()   // 종료 신호가 올 때까지 이벤트 루프 유지

4-3. 두뇌의 도구 루프 — 여러 걸음(step) 걷는 에이전트

airi의 LLM은 단발 응답이 아니라 도구를 여러 번 호출하며 스스로 걸음을 이어가는 에이전트로 동작한다. 아래는 실제 런타임 코드다.

// packages/core-agent/src/runtime/llm-service.ts:231
const streamResult = streamText({
  ...chatConfig,
  abortSignal: options?.abortSignal,
  messages: sanitized,                      // ↓ 4-4에서 설명
  streamOptions: { includeUsage: true },
  stopWhen: stepCountAtLeast(10),        // 최대 10걸음까지 도구 호출 반복
  tools: streamTools,
  onEvent,
})

stopWhen: stepCountAtLeast(10)이 핵심이다. LLM이 "도구를 부르고 → 결과를 보고 → 또 도구를 부르고"를 최대 10번까지 반복하도록 허용한다. 예컨대 마인크래프트에서 "나무를 모아 집을 지어"라고 하면, 두뇌가 여러 걸음에 걸쳐 이동·채집·배치 도구를 순차 호출한다.

4-4. 실전의 진짜 어려움 — 32개 provider가 서로 다르게 군다

"32개 provider 지원"은 말은 쉽지만, OpenAI 호환을 자처하는 게이트웨이들이 실제로는 미묘하게 다른 스펙을 요구한다. airi의 sanitizeMessages()는 그 상처를 꿰맨 흔적이다.

4-5. 브라우저 내 추론의 현실 — 장치를 잃으면 물러선다

WebGPU는 강력하지만 불안정하다 — 탭이 백그라운드로 가거나 드라이버가 GPU 컨텍스트를 회수(device loss)하면 추론이 실패한다. airi는 이를 감지해 자동으로 WASM으로 강등한다.

// packages/stage-ui/src/libs/inference/adapters/whisper.ts:279
// device-loss가 임계값 넘게 반복되면 선제적으로 WASM으로 승격(강등)
const requestedDevice =
  deviceLossCount >= DEVICE_LOSS_WASM_THRESHOLD ? 'wasm' : 'webgpu'
w.postMessage({ type: 'load-model', requestId, modelId: MODEL_NAMES.WHISPER, device: requestedDevice })

5디렉토리 · 모노레포 구조 해부

airi는 크다. 그래서 오히려 대형 모노레포가 어떻게 관심사를 나누는지를 통째로 볼 수 있는 교보재다. 크게 다섯 갈래다 — 실제 실행되는 앱(apps), 앱들이 공유하는 부품(packages), 외부 세계에 붙는 서비스(services), 네이티브 엔진(engines), 그리고 플러그인(plugins).

6학습 포인트

배울 것 1 — provider 무관 LLM 설계와 상호운용의 현실

xsai를 얇은 OpenAI 호환 계층으로 두고, 그 위에서 32개 백엔드의 미묘한 차이를 런타임에 흡수하는 법(§4-4의 sanitizeMessages). "추상화는 예외 처리로 완성된다"는 실무 감각을, 실제 이슈 번호가 달린 코드로 배운다. LLM 앱을 특정 벤더에 묶지 않으려는 모든 개발자에게 직접적인 교보재다.

배울 것 2 — 브라우저 내(in-browser) AI 파이프라인 엔드투엔드

Whisper(STT)·Silero(VAD)·Kokoro(TTS), 그리고 옵션 LLM까지 transformers.js + onnxruntime-web + WebGPU로 브라우저에서 돌리고, device-loss 시 WASM으로 우아하게 폴백하는 실물. "AI = 서버"라는 고정관념을 깨는, 지금 가장 앞선 프론트엔드 AI 패턴을 코드로 익힐 수 있다.

배울 것 3 — Vue로 선언적 3D (@tresjs + three-vrm)

Three.js 명령형 코드 대신 @tresjs/core로 VRM 아바타를 Vue 컴포넌트처럼 마운트·애니메이션하는 법. 자동 눈 깜빡임·시선 추적·idle 모션, 그리고 소리→음소→blendshape(wlipsync) 립싱크까지 — 웹 3D 캐릭터를 다루는 실전 레시피다.

// packages/stage-ui-three/src/composables/vrm/lip-sync.ts:7
import { createWLipSyncNode } from 'wlipsync'
// 음소 → VRM ARKit 비짐(viseme) 블렌드셰이프 이름 매핑
const BLENDSHAPE_MAP: Record<LipKey, string> = {
  A: 'aa', E: 'ee', I: 'ih', O: 'oh', U: 'ou',
}

배울 것 4 — 이벤트 기반 모듈 아키텍처(WebSocket "신경망")

능력(게임·기억·챗 봇)을 코어에 하드코딩하지 않고, 타입 있는 WebSocket 프로토콜로 announce·이벤트 교환하며 붙였다 뗐다 하는 설계(§4-2). 마이크로서비스의 서비스 디스커버리를 앱 내부 규모로 축소한 좋은 예로, 확장 가능한 클라이언트 앱을 짜려는 사람에게 유용하다.

배울 것 5 — 계층형 임베디드 에이전트(마인크래프트)

services/minecraft/src/cognitive/가 지각(perception)·의식(conscious)·행동(action)·반사(reflex)로 나뉜 교과서적 구조라는 점, 그리고 isolated-vm으로 LLM이 생성한 코드를 격리 실행하고 @modelcontextprotocol/sdk(MCP)로 도구를 노출하는 방식. "게임하는 AI"를 만들려는 사람에게 직접적인 청사진이다.

// packages/stage-ui/src/workers/vad/vad.ts — Silero VAD 상태 텐서(발췌)
import { AutoModel, Tensor } from '@huggingface/transformers'
// 기본값: sampleRate 16000, speechThreshold 0.3, minSilenceDurationMs 400
this.sampleRateTensor = new Tensor('int64', [this.config.sampleRate], [])
this.state = new Tensor('float32', new Float32Array(2 * 1 * 128), [2, 1, 128]) // LSTM 상태

배울 것 6 — 대형 모노레포 엔지니어링(pnpm 카탈로그 + Turborepo)

웹·데스크톱·모바일·네이티브까지 한 저장소에서 버전을 한 곳(catalog)에 몰고 Turborepo로 태스크를 조율하는 법. 47개 패키지가 어떻게 관심사별로 쪼개지고 서로를 참조하는지 — 규모 있는 프론트엔드 프로젝트를 지속 가능하게 유지하는 실전 구조를 통째로 관찰할 수 있다.

7시스템 · 하드웨어 요구사항

airi의 요구사항은 두 축으로 정리된다 — 어떤 실행체(브라우저·데스크톱·모바일·Godot)를 쓰느냐, 그리고 LLM·음성 추론을 로컬(내 GPU)에서 하느냐 클라우드에서 하느냐다. 클라우드 LLM을 쓰면 GPU 없이도 충분히 돌아간다.

8직접 해볼 수 있는 실습 과제

먼저 클론 후 웹 무대부터. 모노레포라 루트에서 한 번 설치하면 된다.

# 클론 & 웹 무대 실행 (Node 24 · pnpm 10 권장)
git clone --depth 1 https://github.com/moeru-ai/airi.git
cd airi && pnpm i
pnpm dev            # stage-web (브라우저 PWA) 개발 서버
# 데스크톱 오버레이를 원하면:
pnpm dev:tamagotchi # Electron 무대

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

공식
· GitHub 저장소: github.com/moeru-ai/airi (모노레포 · MIT · © 2024-PRESENT Neko Ayaka)
· TrendShift 카드: trendshift.io/repositories/14636 (Daily #15 · #AI agent #Digital human)
· 한국어 README: 저장소 내 README.ko-KR.md · 데스크톱 바이너리 릴리스 v0.10.2(Win/macOS/Linux)

저장소 안에서 꼭 읽을 것
· packages/core-agent/src/runtime/llm-service.ts — 도구 루프(stepCountAtLeast)와 sanitizeMessages(두뇌)
· packages/stage-ui/src/workers/vad/ · libs/inference/adapters/whisper.ts — 브라우저 내 음성·폴백(감각)
· packages/stage-ui-three/src/composables/vrm/ — VRM 렌더·립싱크(몸)
· packages/server-runtime · server-sdk — WebSocket 모듈 버스(신경)
· services/minecraft/src/cognitive/ — 계층형 임베디드 에이전트(능력)

곁들여 학습
· transformers.js · onnxruntime-web · WebGPU 기초(MDN·HuggingFace 문서)
· Three.js → @tresjs/core → @pixiv/three-vrm · VRM/Live2D 아바타
· xsai · OpenAI 호환 API 상호운용 · Model Context Protocol(MCP)
· pnpm workspace/catalog · Turborepo 모노레포 관리
· mineflayer · isolated-vm 샌드박싱 · 임베디드 게임 에이전트