Capsize-Games/airunner

Offline inference engine for art, real-time voice conversations, LLM powered chatbots and automated workflows

AI Runner

제품 개요

AI Runner는 셀프 호스팅 데스크톱 애플리케이션으로, 두 가지 주요 경험을 결합합니다.

AI 컴패니언 – 이름을 지정하고, 음성을 할당하고, 시간이 지남에 따라 사용자를 기억하는 챗봇입니다. 말하고, 듣고(음성 인식), 말할 수 있으며(음성 합성), 현재 시간, 날짜, 날씨를 인식합니다.
아트 캔버스 – 레이어 기반 드로잉 표면으로, 스케치, 페인팅, 로컬 확산 모델로 스케치를 이미지로 변환, 편집(인페인팅, 배경 제거, 스타일 필터), 레이어 합성을 할 수 있습니다.

모든 처리(LLM 채팅, 이미지 생성, TTS/STT)는 사용자의 하드웨어에서 실행되며, API 키, 클라우드 구독이 필요하지 않으며, 선택적 클라우드 기능을 켜지 않는 한 데이터가 외부로 전송되지 않습니다.

주요 기능(README에 설명된 대로)

기능	설명
🤖 AI 컴패니언	이름과 음성을 가진 영구 메모리와 자연스럽게 변하는 기분을 가진 페르소나.
🎨 레이어 캔버스	여러 레이어에서 '스케치 → 생성 → 필터 → 합성'을 실행합니다.
🖼️ 이미지 생성	Z-Image Turbo, Stable Diffusion 1.5, 이미지 간 변환, 인페인팅, 배경 제거, 후처리 필터를 지원합니다.
🗣️ 음성 대화	선택 가능한 음성으로 전이중 TTS(텍스트 음성 변환) 및 STT(음성 인식).
🧠 메모리 및 RAG	장기 대화 메모리와 과거 대화를 회상하기 위한 검색 증강 생성(RAG).
🌤️ 환경 인식	로컬 시간, 날짜, 날씨를 인식하고 응답에 반영할 수 있습니다.
🔒 프라이버시 우선	모든 데이터는 로컬에 저장되며, 선택적 클라우드 기능은 옵트인만 가능합니다.
🛡️ 안전 필터	내장 NSFW 필터 및 불법 콘텐츠 분류기.
📦 모델 관리	HuggingFace 또는 CivitAI에서 원클릭 다운로드. 여러 로컬 LLM 및 이미지 모델을 지원합니다.
🌍 다국어 지원	영어(풀 스택), 일본어(TTS/LLM), 기타 언어에 대한 제한적 STT.

사용 방법

모드	일반적인 사용 사례
데스크톱 GUI(Itch.io 다운로드, Docker 또는 `pip install airunner`로 설치)	같은 화면에서 그림을 그리고 아트를 생성하면서 음성 지원 컴패니언과 대화형 채팅.
헤드리스 서버(`airunner-headless`)	LLM, 이미지, TTS, STT 엔드포인트를 노출하는 REST API 실행. 원격 서버, VS Code 확장, 자동화 파이프라인에 유용.
Docker 컨테이너	샌드박스 환경에서 빠른 배포. 전체 GUI(`docker compose run …`) 또는 헤드리스 API(`--headless`)를 실행할 수 있습니다.
Python 라이브러리	자체 스크립트에서 `airunner` 패키지를 가져와 동일한 추론 백엔드를 호출할 수 있습니다.

설치 옵션(요약)

방법	내용	비고
데스크톱 다운로드	사전 빌드된 바이너리(Python 불필요).
Docker	선택적 프로필(`core,llm-native,stt-native` 등)이 포함된 컨테이너 이미지.
PyPI(`pip install airunner`)	GUI와 `airunner-services` 런타임을 포함하는 Python 패키지.
APT(Ubuntu 22.04+)	데몬 서비스만 설치. Qt GUI는 포함되지 않습니다.
소스에서	저장소를 클론하고 `./scripts/install.sh`(개발 모드) 또는 `./deployment/install_distributed.sh`(데몬/GUI 분할 설치)를 실행.

모든 경로는 궁극적으로 동일한 사이드카 바이너리(LLM용 llama.cpp, STT용 whisper.cpp)를 설치하며, 자동으로 빌드 또는 다운로드됩니다.

아키텍처 개요

flowchart LR
  User --> Native[Native launcher & side‑cars]
  Native --> GUI[Desktop client (src)]
  Native --> Daemon[Headless daemon (services)]
  GUI --> Daemon
  Native --> Sidecars[llama.cpp & whisper.cpp]
  Daemon --> Sidecars
  GUI --> Scripts[dev tools]
  Daemon --> Scripts
  GUI --> Data[(AIRUNNER_BASE_PATH)]
  Daemon --> Data

src – Qt 기반 GUI, 위젯, 진입점.
services – FastAPI 서버, 모델 다운로드 관리자, 지속성, 안전 필터.
native – 컴파일된 사이드카를 번들하고 적절한 진입점을 실행하는 작은 헬퍼.
scripts – UI 빌드, 테스트 실행, 인증서 생성 등을 위한 헬퍼 명령.

모델 지원(기본 모델)

유형	기본 모델(크기)
LLM	Qwen3.5‑9B GGUF(`Q8_0`, 약 12GB VRAM)
이미지	Stable Diffusion 1.5(약 2GB) 및 Z-Image Turbo(약 12GB)
TTS	OpenVoice(약 654MB)
STT	`Systran/faster-distil-whisper-large-v3`

호환되는 파일을 ~/.local/share/airunner/...에 배치하거나 CLI/GUI 다운로드 관리자에 경로를 전달하여 이러한 모델을 교체할 수 있습니다.

유지 관리자

이 프로젝트는 GPL-3.0 라이선스로 배포되며, 주로 Capsize LLC(https://capsize.online)의 단일 엔지니어가 개발합니다. 커뮤니티 지원은 Discord(배지의 링크) 및 GitHub 이슈 트래커를 통해 이루어집니다.

빠른 시작(대부분의 사용자를 위한 한 줄 명령)

# Linux/macOS – Python 패키지 설치 및 GUI 실행
pip install "airunner" "airunner-services[headless]"
airunner   # 데스크톱 앱 열기

헤드리스 API 서버의 경우:

airunner-headless   # http://127.0.0.1:8080에서 수신

결론

AI Runner는 진정한 셀프 호스팅 AI 어시스턴트 + 생성형 아트 플랫폼입니다. 로컬 LLM 추론(llama.cpp 경유), 확산 이미지 생성, 음성 파이프라인을 번들로 제공하며, 모든 것을 프라이버시 우선 데스크톱 UI로 감싸고 REST 서비스로도 노출할 수 있습니다.