Desktop AI Pet

로컬 LLM · 대화 기능

펫과 자유롭게 대화하려면 PC에서 돌아가는 로컬 LLM 서버가 필요합니다. 클라우드 API 키는 쓰지 않으며, 요청은 http://127.0.0.1 (또는 [::1]) 으로만 나갑니다. 에이전트는 기본 꺼짐이라, 설정하지 않아도 책상 위 펫·규칙 기반 행동은 동작합니다.

무엇이 필요하고, 무엇이 아닌가

기능	로컬 LLM	비고
책상 위 펫 · 걷기 · 상호작용	불필요	규칙 기반 동작
팩에 작성된 대사 · 말풍선	불필요	캐릭터 팩 데이터
사용자 대화 (채팅)	필요	설정 → 로컬 에이전트 켜기
LLM 기반 자발 대사 · 행동 제안	필요	에이전트 + 플래너 간격
음성 읽기 (TTS)	불필요	OS 내장 TTS
마이크 → 글자 (STT)	불필요*	Whisper 서버 별도 (*대화 전송은 LLM 필요)

마이크만 켜도 인식 결과 글자는 입력창에 들어가지만, 답변을 생성하려면 로컬 에이전트(LLM)가 켜져 있어야 합니다.

앱 설정 값 (공통 · Win/Mac)

endpoint: http://127.0.0.1:11434/api/generate
model:    exaone3.5:7.8b   (또는 ollama list 에 있는 이름)
플래너 간격: 45초 이상 (기본 45)

PC에서 LLM 서버를 먼저 실행 (아래 Ollama 권장)
Desktop AI Pet 설정 → 로컬 에이전트
endpoint · model 입력
로컬 에이전트 사용 체크 후 저장
(선택) 에이전트 대화 테스트로 연결 확인
우클릭 → 대화 → 메시지 전송

보안: endpoint는 loopback만 허용됩니다. 외부 IP · HTTPS · localhost 문자열 · 쿼리/인증 정보는 거부됩니다. 대화 원문 영구 저장은 기본 꺼짐이며, 메모리 탭에서 따로 켤 수 있습니다.

macOS — Ollama 설치

설치 (둘 중 하나)

# 공식 설치 스크립트
curl -fsSL https://ollama.com/install.sh | sh

# 또는 DMG: https://ollama.com/download/mac
# (macOS 14 Sonoma 이상 권장)

서버 확인 (설치 후 보통 백그라운드에서 동작)
```
ollama serve
# 다른 터미널에서:
curl http://127.0.0.1:11434/
```
응답이 오면 준비된 상태입니다.

모델 받기

# 앱 기본 예시 (용량 큼 — 한국어 품질 양호)
ollama pull exaone3.5:7.8b

# 더 가벼운 대안 예 (이름 그대로 앱 model 칸에 입력)
ollama pull llama3.2
# 또는
ollama pull qwen2.5:7b

동작 확인

ollama list
ollama run exaone3.5:7.8b "안녕, 짧게 인사해줘"

앱 설정에 endpoint / model 을 맞추고 에이전트를 켭니다.

RAM·디스크: 7B급은 대략 수 GB~십수 GB 여유를 권장합니다. 느리면 더 작은 모델로 바꾸세요.

Windows — Ollama 설치

설치 (둘 중 하나)

# PowerShell
irm https://ollama.com/install.ps1 | iex

# 또는 설치 파일: https://ollama.com/download/windows
# (Windows 10 이상)

설치 후 트레이에 Ollama가 떠 있는지 확인. 필요하면 시작 메뉴에서 Ollama 실행.

PowerShell / 명령 프롬프트에서 모델 받기

ollama pull exaone3.5:7.8b

# 가벼운 대안 예
ollama pull llama3.2
ollama pull qwen2.5:7b

연결 확인

curl http://127.0.0.1:11434/
ollama list

앱 설정

endpoint: http://127.0.0.1:11434/api/generate
model:    ollama list 에 표시된 이름 그대로

로컬 에이전트 사용 켠 뒤 저장 → 대화 테스트.

Windows 방화벽 팝업이 뜨면 개인 네트워크에서 Ollama 허용. 앱은 127.0.0.1 만 쓰므로 외부 공개는 필요 없습니다.

대화 사용 흐름

Ollama(또는 호환 서버) 실행 + 모델 pull 완료
앱에서 로컬 에이전트 ON
펫 우클릭 → 대화
텍스트 입력 후 보내기 (또는 STT로 입력 후 보내기)
전송 중 → 답변 대기 → 말풍선·대화 기록에 공개 reply 표시

thinking / reasoning / JSON 내부 힌트는 사용자에게 노출되지 않도록 걸러집니다. 서버가 꺼져 있거나 타임아웃이면 안전한 fallback 메시지가 나가고, 펫 애니메이션은 계속됩니다.

Ollama 외 서버

앱이 기대하는 형태는 loopback HTTP POST 로 텍스트 생성을 하는 로컬 엔드포인트입니다.
권장·검증 경로는 Ollama /api/generate 입니다.
다른 로컬 서버를 쓸 경우, 앱이 보내는 요청 형식과 맞는 어댑터가 있어야 하며 endpoint는 반드시 http://127.0.0.1:… 또는 http://[::1]:… 이어야 합니다.

자주 하는 확인

증상	확인할 것
대화가 실패 / 타임아웃	`ollama list`, 서버 실행 여부, model 이름 오타, RAM 부족
설정 저장 거부	endpoint가 127.0.0.1 인지, 플래너 간격 ≥ 45초
에이전트 껐는데 펫이 안 움직임?	정상 — 에이전트 없이도 규칙 기반 동작은 유지
자발 대사만 막고 싶을 때	설정 조용한 모드 (직접 대화 응답은 유지)