🛠️ 나만의 봇 만들기 자습서

📖 이 자습서가 제공하는 것

나만의 AI 아바타 봇을 학생이 코드 수정 없이 만들 수 있도록 안내합니다.

1사전 준비 — Git 설치

1-0. CMD (명령 프롬프트) 열기

윈도우에서 CMD 여는 방법 (셋 중 아무거나):

• Win + R 키 동시 누름 → cmd 입력 → Enter
• 시작 메뉴 → cmd 또는 명령 프롬프트 검색 → 클릭
• 탐색기 주소창에 cmd 입력 → Enter (현재 폴더에서 열림)

검은색 창 (또는 흰색) 이 뜨면 OK. 여기에 명령어를 입력합니다.

1-1. Git 확인

git --version

git version 2.49.0

'git'은(는) 내부 또는 외부 명령... 명령으로 인식되지 않습니다.

📥 Git 설치

winget install --id Git.Git -e --source winget

brew install git

1-2. (선택) 코드 에디터

이 자습서는 코드 거의 안 만짐 — 설치 불필요. 나중에 코드 보고 싶을 때만 VS Code 또는 메모장 사용.

git --version     → git version 2.x.x   (필수)

2GitHub 가입 + Git 설정

2-1. GitHub 가입 (이미 있으면 건너뛰기)

1. https://github.com/signup 접속
2. 이메일 → 비밀번호 → 사용자명 입력
3. 이메일 인증 완료

2-2. Git에 GitHub 계정 등록 (최초 1회)

git config --global user.name "본인_GitHub_사용자명"
git config --global user.email "본인_이메일@example.com"

3템플릿 클론 + 로컬 실행

3-1. 작업 폴더로 이동

cd C:\projects
mkdir my-bot
cd my-bot

cd ~/projects
mkdir my-bot
cd my-bot

3-2. 템플릿 클론

git clone https://github.com/sdkparkforbi/my-vrm-bot.git .

3-3. 기존 .git 폴더 삭제 (내 레포로 새로 시작)

rmdir /s /q .git
git init -b main

rm -rf .git
git init -b main

원본 템플릿의 git 히스토리를 끊고, 본인 레포로 다시 시작합니다.

my-bot/                       ← 본인 작업 폴더 (계속 여기서 작업)
  ├─ public/
  │   └─ avatar.vrm           ← Step 8에서 본인 VRM 여기에 넣음
  ├─ src/                     ← 코드 (수정 안 해도 됨!)
  ├─ api/                     ← Vercel 서버리스 함수
  ├─ index.html
  └─ package.json

4환경 변수 설정 (.env)

4-1. 본인 닉네임(BOT_ID) 정하기

이 봇의 지식·페르소나는 닉네임(BOT_ID) 으로 구분됩니다. 본인만의 닉네임을 하나 정하세요.

5본인 GitHub 레포 만들기 + 푸시

5-1. GitHub 에서 빈 레포 만들기 (브라우저)

1. https://github.com/new 접속
2. Repository name: 본인 봇 이름 (예: my-bot)
3. Public 선택
4. 체크박스 모두 OFF — README, .gitignore, license 다 끄기 (켜면 push 시 충돌)
5. Create repository 클릭
6. 생성된 페이지 URL 복사: https://github.com/본인_사용자명/my-bot.git

5-2. (선택) README 수정

메모장으로 README.md 열기 → 본인 봇 이름과 설명으로 수정. 안 해도 됨.

5-3. Git에 커밋

git add .
git commit -m "Initial commit: 내 봇 시작"

5-4. 본인 GitHub 레포와 연결 + 푸시

git remote add origin https://github.com/본인_사용자명/my-bot.git
git push -u origin main

처음 푸시할 때 GitHub 로그인 창이 뜹니다. 브라우저에서 본인 계정으로 인증하면 자동 푸시됩니다.

git add .
git commit -m "수정 내용"
git push

6Vercel 배포

6-1. Vercel 가입

1. https://vercel.com/signup 접속
2. "Continue with GitHub" 선택 → GitHub 권한 승인
3. (첫 가입 시) SMS 인증 화면 — 본인 휴대폰 번호 입력 → 4자리 코드 받아 입력
4. 가입 완료 → Vercel 대시보드 진입

6-2. 프로젝트 배포

1. 대시보드에서 Add New → Project
2. 본인 GitHub 레포 안 보이면 → Adjust GitHub App Permissions 클릭:
   • "Install Vercel" GitHub 앱 권한 설정 화면 열림
   • Only select repositories 선택 → 본인 레포 (예: my-bot) 체크
   • 또는 All repositories 선택 (간단, 모든 본인 레포 접근 허용)
   • Install 또는 Save 클릭 → 자동으로 Vercel Import 화면 복귀
3. 본인 레포 (my-bot) → Import
4. Framework Preset: Vite 자동 인식
5. Environment Variables 펼치기 → 다음을 추가:

   Name	Value
   BOT_ID	본인 닉네임 (예: bungae)
   VITE_BOT_ID	BOT_ID 와 같은 값 (브라우저용)
   VITE_KAKAO_JS_KEY	Step 7에서 발급할 키 (지금은 임시값 가능)

   선택: VITE_BOT_NAME(봇 이름)·VITE_BOT_INTRO(첫 인사)도 넣으면 인사말이 바뀝니다.
6. Deploy 클릭

6-3. 완료!

1~3분 후 https://my-bot.vercel.app 같은 URL이 생성됩니다.

7카카오 SDK 설정 (로그인 + 공유)

한 번의 셋업으로 두 가지가 활성화됩니다:

• 카카오 로그인 — 사용자가 봇 첫 방문 시 자동으로 로그인 모달 (AuthModal) 이 뜸. 카카오 계정 또는 이메일로 가입/로그인 가능.
• 카카오 공유 — 봇을 카카오톡으로 친구에게 공유 가능.

7-1. Kakao Developers 가입 및 앱 생성

1. https://developers.kakao.com/ 접속
2. 카카오 계정으로 로그인
3. 내 애플리케이션 → 애플리케이션 추가하기
4. 앱 이름 입력 (본인 봇 이름, 예: "내 봇") + 사업자명 (본인 이름) → 생성

7-2. JavaScript 키 복사

앱 선택 → 요약 정보 → JavaScript 키 복사 (32자리 영숫자)

7-3. 사이트 도메인 등록 (필수)

1. 좌측 플랫폼 → Web 플랫폼 등록
2. 사이트 도메인에 본인 Vercel URL 입력:

   https://my-bot.vercel.app

3. 저장 클릭 — 등록 안 하면 카카오 SDK 작동 안 함

7-4. 카카오 로그인 활성화 (필수)

1. 좌측 제품 설정 → 카카오 로그인
2. 활성화 설정: ON
3. Redirect URI 등록: https://my-bot.vercel.app/oauth (사용 안 해도 등록 필요)
4. 동의 항목 설정: 닉네임 필수, 이메일 선택 (사용자가 거부 가능)

7-5. Vercel 환경변수 업데이트 + Redeploy

1. Vercel 대시보드 → 본인 프로젝트 → Settings → Environment Variables
2. VITE_KAKAO_JS_KEY 항목 우측 ⋯ → Edit
3. 값을 7-2에서 복사한 JavaScript 키 (32자리)로 교체 → Save
4. Deployments 탭 → 최상단 배포 → ⋯ → Redeploy 클릭
5. 2~3분 후 배포 완료

7-6. 동작 확인

1. 본인 Vercel URL 접속
2. 자동으로 로그인 모달이 뜸
3. 카카오로 로그인 클릭 → 카카오 인증 팝업
4. 권한 동의 → 모달 자동 닫힘 → 봇과 대화 시작 가능

8VRoid 아바타 적용 🎨

봇의 3D 캐릭터를 본인 봇 컨셉에 맞게 만듭니다. 두 가지 경로:

🚀 빠른 경로: VRoid Hub에서 다운로드

1. https://hub.vroid.com/ 접속
2. 우측 필터 → License → Allow Redistribution 체크 (재배포 허용된 모델만)
3. 마음에 드는 캐릭터 클릭 → Download → .vrm 파일 받기
4. 다운로드된 파일을 본인 프로젝트로 옮기는 건 8-5 진행

🎨 정공법 8-1. VRoid Studio 다운로드 + 설치

1. https://vroid.com/en/studio 접속
2. Windows / Mac 버전 다운로드 (무료, 약 1GB)
3. 설치 후 실행 — 처음 켜면 튜토리얼 영상 자동 재생 (스킵 가능)

🎨 정공법 8-2. 첫 화면 + 기본 캐릭터 선택

1. 왼쪽 위 + New 버튼 클릭
2. 샘플 캐릭터 중 하나 선택:
   • AvatarSample_A (여성, 단정한 학생) → 학습·상담 도우미 봇에 잘 어울림
   • AvatarSample_B (남성, 활동적) → 나달/장보고 같은 봇에 추천
   • AvatarSample_F (귀여운 캐릭터) → 식구/숨돌이/하루 같은 봇에 추천
3. 편집 화면 진입 — 좌측에 메뉴 카테고리들 표시됨

🎨 정공법 8-3. 캐릭터 커스터마이즈

좌측 메뉴 카테고리별로 수정:

🎨 정공법 8-4. VRM으로 Export

1. 좌측 상단 ☰ (햄버거 메뉴) 클릭 → Export → Export as VRM
2. VRM 1.0 선택 (VRM 0.x 는 일부 기능 호환 안 됨)
3. 라이선스 화면에서 다음 4가지 반드시 설정:
   • Avatar Permission: Everyone (모두 사용 가능)
   • Commercial Usage: Allow (시연/배포 위해 필수)
   • Modification: Allow
   • Redistribution: Allow
4. 파일명: 본인이 원하는 이름 OK — 다음 단계에서 어차피 avatar.vrm 으로 바꿉니다
5. 저장 위치 기억! 보통 Desktop 또는 Documents\VRoid\avatars

8-5. 프로젝트에 적용 (두 경로 공통) ⚠️ 파일명 정확히 avatar.vrm

탐색기에서 VRM 파일을 public/ 폴더에 복사하고 이름을 avatar.vrm 으로 변경. 그 다음 CMD에서:

cd C:\projects\my-bot
git add .
git commit -m "avatar.vrm 추가"
git push origin main

1~3분 후 Vercel 자동 재배포 → 새 아바타 등장.

9RAG 페이지: 페르소나 + 지식 ⭐

9-1. 내 봇의 RAG 관리 페이지 접속

지식·페르소나는 내 봇 사이트 안의 /rag 페이지에서 직접 관리합니다. (외부 서버 페이지 아님)

https://[본인-vercel-url].vercel.app/rag

또는 봇 화면 오른쪽 위 🧠 아이콘을 누르면 바로 이동합니다. 처음 들어가면 로그인(카카오 또는 이메일) 후, 본인 닉네임(BOT_ID) 으로 지식을 관리합니다.

9-2. 🎭 PERSONA 설정 (봇의 성격 · 말투 · 정체성)

1. 최상단 보라색 PERSONA 박스의 textarea
2. 본인 봇 정체성을 자유 서술 (최대 2000자)
3. COMMIT 버튼 클릭 → 다음 채팅부터 즉시 반영
4. 비우고 RESET 누르면 기본값 (봇 이름 + 친절한 어시스턴트) 으로 복귀

예시 페르소나 (참고용 — 본인 봇 컨셉으로 작성)

학습 친구형 (반말, 친근):

당신은 [본인 봇 이름] 봇입니다.
[학생/사용자]가 [주제]를 어려워하면 차근차근 단계별로 풀어주세요.
반말로 친근하게, 이모티콘은 가끔만 사용해요.
모르는 것은 솔직히 모른다고 답합니다.

위로 친구형 (존댓말, 따뜻함):

당신은 [본인 봇 이름] 봇입니다.
사용자가 힘든 이야기를 하면 판단하지 않고 공감해주세요.
"그랬군요", "많이 힘드셨겠어요" 같은 공감 표현을 자주 사용해요.
조언보다 들어주는 것을 우선하고, 부드러운 존댓말로 대화합니다.
가끔 따뜻한 이모지 (🌸 💛 ☁️) 사용.

전문가형 (존댓말, 정확성 우선):

당신은 [본인 봇 이름] — [전문 분야] 전문 안내 봇입니다.
사용자 질문에 정확하고 간결하게 답하세요.
답변 형식: 핵심 결론 먼저, 그 다음 1~2문장 설명, 필요 시 예시.
출처가 불명확한 정보는 추측하지 말고 "확인이 필요합니다" 라고 답합니다.

좋은 페르소나 4가지 요소

"[본인 봇 주제] 봇의 페르소나를
시스템 프롬프트로 작성해줘. 300자 이내, 반말 톤."

9-3. ✨ AUTO_CHUNKER 로 지식 추가 (가장 핵심) ⭐

학생 입장에서 가장 쉬운 방법. JSONL 형식 몰라도 됨. 평범한 텍스트만 던지면 AI가 알아서 Q&A 청크로 변환.

1. 본인 봇 주제 텍스트 준비 (뉴스 기사, 강의 노트, 위키, 책 한 챕터 등)
2. 시안색 AUTO_CHUNKER 박스에서:
   • 방법 A: ▸ upload .txt or .md 클릭 → 파일 선택
   • 방법 B: textarea에 텍스트 직접 붙여넣기
3. GENERATE CHUNKS 버튼 클릭
4. 30초~1분 대기 (Gemma4가 분석)
5. ✨ 생성된 청크 5~25개 미리보기 (PREVIEW)
6. COMMIT TO RAG 클릭 → 봇에 즉시 반영. 마음에 안 들면 RETRY.

9-4. 봇에서 확인

본인 봇 사이트 (https://[본인-vercel-url].vercel.app) 새로고침 → 채팅 → 청크 활용 답변 확인.

예시 — 내가 넣은 지식과 관련된 질문을 던져 확인:

• 지식에 넣은 내용에 대한 질문 (예: "○○가 뭐야?", "△△는 어떻게 해?")
• 봇이 내 청크를 활용해 답하면 성공 ✅
• 엉뚱하게 답하면 → /rag 에서 청크를 더 추가하거나 페르소나를 다듬기

10완성! 봇 공유하기 🎉

10-1. 최종 체크리스트

10-2. 친구에게 공유

Vercel URL을 카카오톡으로:

• URL: https://my-bot.vercel.app
• QR 생성: qr-code-generator.com

10-3. 개선 사이클

1. 친구 피드백 수집 ("이런 질문에 답 못해" / "톤이 좀..." 등)
2. RAG 페이지에서:
   • 지식 부족 → AUTO_CHUNKER로 청크 추가 (1분)
   • 톤 부족 → PERSONA 수정 (10초)
3. 봇 사이트 새로고침 → 즉시 반영
4. 반복!

📚 추가 자료

• 스타터킷 GitHub 레포
• React 공식 문서
• VRoid Studio
• Vercel 문서

🆘 자주 겪는 문제

Q1: 봇 채팅이 작동하지 않습니다

• Vercel 환경변수 BOT_ID 와 VITE_BOT_ID 가 본인 닉네임으로 (같은 값) 설정됐는지 확인
• Vercel Deployments → 최근 배포 로그에서 에러 확인
• 브라우저 콘솔(F12) 에서 빨간 메시지 확인

Q2: 내 지식이 다른 사람 봇에 섞이지 않나요?

• 안 섞입니다 — 지식·페르소나는 로그인한 본인 닉네임(BOT_ID) 에만 저장됩니다.
• 지식을 수정하려면 /rag 에서 로그인해야 합니다 (남이 못 바꿈).
• 읽기(봇이 답하는 것)는 누구나 가능 — 봇의 지식은 방문자 모두에게 쓰입니다.

Q3: 봇이 RAG 청크를 무시하고 일반 답변만 합니다

• 청크 추가 후 "총 N개" 메시지 확인 (실제 저장됐는지)
• 질문이 청크 question 과 의미적으로 비슷한지 (코사인 유사도 임계값)
• 청크 수가 너무 적으면 (5개 이하) 매칭이 안 잡힐 수 있음 — 30개 이상 권장

Q4: 카카오 공유 버튼이 작동하지 않음

• Vercel 환경변수 VITE_KAKAO_JS_KEY 확인
• Kakao Developers 의 Web 플랫폼에 Vercel URL 등록 확인

Q5: VRM 아바타가 안 보입니다 ("아바타가 비어있어요")

• public/avatar.vrm 파일 존재 + git 에 푸시됐는지 확인
• Vercel Deployments → Source → public/avatar.vrm 있는지