Skip to content

README_ko.md

Latest commit

 

History

History
466 lines (353 loc) · 21.1 KB

README_ko.md

File metadata and controls

466 lines (353 loc) · 21.1 KB

AITuberKit

AI 캐릭터 구축을 위한 올인원 툴킷

공지사항: 본 프로젝트는 버전 v2.0.0부터 커스텀 라이선스를 채택하고 있습니다. 상업적 목적으로 사용하시는 경우 이용약관 섹션을 확인해 주시기 바랍니다.

GitHub Last Commit GitHub Top Language GitHub Tag License: Custom

GitHub stars GitHub forks GitHub contributors GitHub issues CodeRabbit Pull Request Reviews

X (Twitter) Discord GitHub Sponsor DeepWiki

🌟 데모 사이트 🌟

📚 문서 사이트 📚

日本語｜ English｜ 简体中文｜ 繁體中文｜ Polski

개요

AITuberKit은 누구나 쉽게 AI 캐릭터와 채팅할 수 있는 웹 애플리케이션을 구축할 수 있는 오픈소스 툴킷입니다.
다양한 AI 서비스, 캐릭터 모델, 음성 합성 엔진을 지원하며, 높은 커스터마이징 기능을 갖춘 대화 기능과 AITuber 방송 기능을 중심으로 다양한 확장 모드를 제공합니다.

AITuberKit Architecture

자세한 사용 방법과 설정 방법은 문서 사이트를 참조해 주시기 바랍니다.

주요 기능

1. AI 캐릭터와의 대화

  • 각종 LLM의 API 키를 사용하여 AI 캐릭터와 쉽게 대화 가능
  • 멀티모달 지원으로 카메라 영상이나 업로드한 이미지를 인식하여 답변 생성
  • 최근 대화 내용을 기억으로 유지
  • RAG 기반 장기 기억으로 과거 대화를 컨텍스트에 활용

2. AITuber 방송

  • YouTube 방송 댓글을 가져와 AI 캐릭터가 자동으로 응답
  • 댓글 소스로 YouTube API / 완코메(OneComme) 선택 가능
  • 대화 지속 모드로 댓글이 없어도 자발적으로 발언 가능
  • 댓글 가져오기 간격 및 사용자 표시 이름 커스터마이징 지원

3. 데모 단말기 · 디지털 사이니지

  • 데모 단말기 모드: 디지털 사이니지용 풀스크린 표시. 패스코드 인증, NG 단어 필터, 입력 길이 제한 지원
  • 인감 검지: 카메라 얼굴 검출을 통한 방문자 자동 감지. 인사 · 작별 문구 자동 재생 지원
  • 아이들 모드: 대화가 끊겼을 때 캐릭터가 자동으로 발화. 정형 문구, 시간대별 인사, AI 자동 생성의 3가지 소스 지원

4. 고급 대화 모드

  • Realtime API: OpenAI의 Realtime API를 사용한 저지연 대화와 함수 실행
  • 오디오 모드: OpenAI의 Audio API 기능을 활용한 자연스러운 음성 대화
  • Reasoning 모드: AI의 사고 과정을 표시하고 추론 파라미터 설정 가능

5. 연동 · 확장

  • 외부 연동 모드: WebSocket으로 서버 앱과 연동하여 텍스트 및 이미지 교환을 포함한 더 고도한 기능 구현
  • 슬라이드 모드: AI 캐릭터가 슬라이드를 자동으로 발표하는 모드
  • 메시지 수신 기능: 전용 API를 통해 외부에서 텍스트와 이미지를 받아 AI 캐릭터가 발언하도록 하는 것이 가능

지원 모델 및 서비스

캐릭터 모델

  • 3D 모델: VRM 파일(모션 태그를 통한 포즈 및 제스처 제어 지원)
  • 2D 모델: Live2D 파일(Cubism 3 이상)
  • 모션 PNGTuber: 동영상 기반 캐릭터 표시(MotionPNGTuber)

지원 LLM

  • OpenAI
  • Anthropic
  • Google Gemini
  • Azure OpenAI
  • Groq
  • Cohere
  • Mistral AI
  • Perplexity
  • Fireworks
  • LM Studio
  • Ollama
  • Dify
  • xAI
  • DeepSeek
  • OpenRouter

지원 음성 합성 엔진

  • VOICEVOX
  • Koeiromap
  • Google Text-to-Speech
  • Style-Bert-VITS2
  • AivisSpeech
  • Aivis Cloud API
  • Cartesia
  • GSVI TTS
  • ElevenLabs
  • OpenAI
  • Azure OpenAI

퀵 스타트

개발 환경

  • Node.js: 24.x
  • npm: ^11.6.2

설치 순서

  1. 리포지토리를 로컬에 클론합니다.
git clone https://github.com/tegnike/aituber-kit.git
  1. 폴더를 엽니다.
cd aituber-kit
  1. 패키지를 설치합니다.
npm install
  1. 필요에 따라 .env 파일을 생성합니다.
cp .env.example .env
  1. 개발 모드로 애플리케이션을 실행합니다.
npm run dev
  1. URL을 엽니다. http://localhost:3000

간편 실행

초기 설정 완료 후에는 실행 스크립트를 더블 클릭하는 것만으로 실행할 수 있습니다.

  • Windows: LAUNCH.bat를 더블 클릭
  • macOS: LAUNCH.command를 더블 클릭(실행 권한이 없는 경우 chmod +x LAUNCH.command를 실행하세요)

자세한 설정 방법과 사용 방법은 문서 사이트를 참조해 주시기 바랍니다.

Docker로 실행하는 경우

  1. .env 파일을 생성합니다.
cp .env.example .env
  1. Docker Compose로 실행합니다.
docker compose up -d
  1. URL을 엽니다. http://localhost:3000

중지하는 경우:

docker compose down

배포

Vercel

  1. Vercel 계정을 생성하고 GitHub 리포지토리를 가져옵니다.

  2. Vercel 대시보드에서 환경 변수를 설정합니다. 필요한 API 키(OPENAI_API_KEY 등)를 추가하세요. 설정 가능한 환경 변수는 .env.example을 참조하세요.

  3. 배포는 프로젝트 설정의 Production Branch에 푸시할 때 자동으로 실행됩니다(기본값은 main 브랜치).

Cloudflare Workers

Cloudflare Workers로의 배포를 지원합니다. OpenNext를 사용하여 Cloudflare Workers에서 Next.js 애플리케이션을 실행합니다.

  1. Wrangler CLI를 설치하고 Cloudflare 계정에 로그인합니다.

  2. 필요에 따라 wrangler.jsonc의 프로젝트 이름을 변경합니다.

  3. 환경 변수를 설정합니다.

    • 프론트엔드 설정(NEXT_PUBLIC_*): .env 파일에 작성합니다. 빌드 시 클라이언트 코드에 포함됩니다.
    • 서버 사이드 API 키(OPENAI_API_KEY 등): Wrangler 시크릿으로 설정합니다.
cp .env.example .env
# .env를 편집하여 NEXT_PUBLIC_*의 값을 설정

# 서버 사이드 API 키를 Wrangler 시크릿으로 설정
npx wrangler secret put OPENAI_API_KEY

필요한 API 키마다 wrangler secret put를 반복합니다.

  1. 로컬 프리뷰로 동작을 확인합니다.
npm run preview:cloudflare
  1. 프로덕션 환경에 배포합니다.
npm run deploy:cloudflare

주의사항:

  • 빌드 시 NEXT_PUBLIC_RESTRICTED_MODE=true가 자동 설정되어 파일 시스템 API가 비활성화됩니다. 에셋 목록은 빌드 시 생성되는 매니페스트에서 제공됩니다.
  • public/ 하위의 25MB 초과 파일이나 비ASCII 파일명의 파일은 배포 대상에서 자동 제외됩니다.

⚠️ 보안에 관한 중요 주의사항

이 리포지토리는 개인 사용과 로컬 환경에서의 개발은 물론, 적절한 보안 대책을 마련한 상업적 사용도 고려하고 있습니다. 단, 웹 환경에 배포할 때는 다음 사항에 주의해 주시기 바랍니다:

  • API 키 취급: 백엔드 서버를 통해 AI 서비스(OpenAI, Anthropic 등)와 TTS 서비스의 API를 호출하는 사양이므로, API 키의 적절한 관리가 필요합니다.

프로덕션 환경에서의 사용에 대하여

프로덕션 환경에서 사용할 경우 다음 중 하나의 대응을 권장합니다:

  1. 백엔드 서버 구현: API 키 관리를 서버 사이드에서 수행하여 클라이언트로부터의 직접적인 API 액세스를 피함
  2. 사용자에 대한 적절한 설명: 각 사용자가 자신의 API 키를 사용하는 경우 보안상의 주의점에 대해 설명
  3. 액세스 제한 구현: 필요에 따라 적절한 인증・인가 메커니즘을 구현

스폰서 모집

개발을 지속하기 위해 스폰서를 모집하고 있습니다.
여러분의 지원은 AITuberKit의 개발과 개선에 크게 기여합니다.

GitHub Sponsor

"Buy Me A Coffee"

협력자 여러분(지원해 주신 순서)

morioki3 hodachi-axcxept coderabbitai wmoto-ai JunzoKamahara darkgaldragon usagi917 ochisamu mo0013 tsubouchi bunkaich seiki-aliveland rossy8417 gijigae takm-reason haoling FoundD-oka terisuke konpeita MojaX2 micchi99 nekomeowww yfuku 8484ff_42 sher1ock-jp uwaguchi M1RA_A_Project teruPP aituber-akari harumeri spring-hh dotneet schroneko ParachutePenguin eruma _cityside nyapan-mohy hattoritatsuya sa1p

기타 프라이빗 스폰서 다수

Star History

Star History Chart

감사의 말

본 프로젝트는 pixiv 주식회사가 공개한 ChatVRM을 포크하여 개발되었습니다. 훌륭한 오픈소스 프로젝트를 공개해 주신 pixiv 주식회사에 깊이 감사드립니다.

기여

AITuberKit의 개발에 관심을 가져주셔서 감사합니다. 커뮤니티의 기여를 환영합니다.

이슈 신고

버그를 발견했거나 새로운 기능에 대한 아이디어가 있으시면 GitHub의 Issues 페이지를 통해 알려주세요.

이슈를 작성할 때 다음 정보를 포함하면 원활한 대응이 가능합니다:

  • 문제나 새로운 기능에 대한 자세한 설명
  • 재현 단계 (버그의 경우)
  • 예상 동작과 실제 동작
  • 사용 환경 (브라우저, OS, Node.js 버전 등)
  • 스크린샷이나 동영상 (가능하다면)

풀 리퀘스트

코드 개선이나 새로운 기능을 추가하고 싶으시면 포크한 저장소에서 변경사항을 만들고 풀 리퀘스트를 생성해 주세요.

  • 하나의 풀 리퀘스트에서는 하나의 기능이나 수정사항에 집중해 주세요.
  • 풀 리퀘스트 설명에 변경 내용과 이유를 작성해 주세요.
  • 머지 대상 브랜치는 반드시 develop로 설정해 주세요.
  • 충돌이 발생해도 무리하게 해결하지 않으셔도 됩니다. 개발팀이 처리합니다.

이용약관

라이선스

본 프로젝트는 버전 v2.0.0부터 커스텀 라이선스를 채택하고 있습니다.

  • 무상 이용

    • 영리 목적 이외의 개인 사용, 교육 목적, 비영리 목적의 사용은 무상으로 이용 가능합니다.

  • 상업용 라이선스

    • 상업적 목적의 사용에 관해서는 별도의 상업용 라이선스 취득이 필요합니다.
    • 자세한 내용은 라이선스에 대하여를 확인해 주시기 바랍니다.

기타

우선 구현에 대하여

본 프로젝트에서는 유상으로 기능 우선 구현을 받고 있습니다.

  • 기업이나 개인으로부터 요청받은 기능을 우선적으로 구현할 수 있습니다.
  • 구현된 기능은 본 OSS 프로젝트의 일부로 공개됩니다.
  • 요금은 기능의 복잡도와 구현에 소요되는 시간에 따라 개별 견적이 됩니다.
  • 이 우선 구현은 상업용 라이선스와는 별개의 시도입니다. 구현된 기능을 상업적으로 사용하는 경우에는 별도로 상업용 라이선스 취득이 필요합니다.

자세한 내용은 [email protected]으로 문의해 주시기 바랍니다.