# 웹의 로컬 AI 연결

웹 버전에서만 사용합니다. Anna 설정과 배포는 바뀌지 않습니다. 게임 서버나 AI 프록시는 필요하지 않습니다.

## 1. Ollama: 대화와 가구 배치

같은 PC에 Ollama를 설치하고 텍스트 모델을 준비하세요. 실행 중인 Ollama를 종료한 뒤 다음 환경변수로 서버를 실행합니다. macOS 앱 등으로 실행하면 해당 실행 환경에 변수를 적용해야 합니다.

```sh
OLLAMA_ORIGINS=https://kdkrkwhr.github.io OLLAMA_NO_CLOUD=1 ollama serve
```

이 프로젝트에서 우선 사용할 모델은 `qwen3.5:4b-q4_K_M`입니다. 같은 이름의 기본 `qwen3.5:4b`는 Apple Silicon에서 MLX 모델이 선택될 수 있으며, 이번에 확인한 Ollama 0.40.5의 MLX 실행은 JSON 강제 출력을 501로 거부했습니다. 가구 배치에는 GGUF 모델을 명시하세요. 기존 `qwen3:8b`도 대화·배치 실검증을 통과했습니다. `vision` 표시는 이미지 이해 기능이며 이미지 생성 기능이 아닙니다.

```sh
ollama pull qwen3.5:4b-q4_K_M
```

개발 주소로 접속한다면 `OLLAMA_ORIGINS`에 해당 출처(예: `http://localhost:8080`)를 허용하세요. 출처에는 `/notebook-pets/` 경로를 넣지 않습니다.

웹의 **설정 → 대화·가구 배치 → Ollama**에서 `http://localhost:11434`를 입력하고 **연결하고 설치된 모델 보기**를 누른 뒤 모델을 선택합니다. 연결 확인은 목록만 읽으며 추론하지 않습니다. 실제 요청 전 모델 정보를 확인해 클라우드 모델을 거부합니다. 작은 모델은 JSON 후보 선택에 실패할 수 있으며, 검증되지 않은 배치는 적용하지 않습니다. 모델 다운로드는 앱이 자동 실행하지 않습니다.

## 2. ComfyUI: 참고 그림으로 방향별 동작 생성

Ollama의 텍스트 API는 동작 시트 이미지 생성에 사용하지 않습니다. 같은 PC의 ComfyUI와 별도로 설치한 로컬 이미지 모델을 사용합니다.

```sh
python main.py --enable-cors-header https://kdkrkwhr.github.io --disable-api-nodes
```

ComfyUI 버전에 따라 지원되는 옵션을 확인하세요. `--disable-api-nodes`로 외부 API 노드를 끄고, 로컬 모델과 노드만 사용하는 신뢰할 수 있는 워크플로를 준비합니다. 앱은 임의의 커스텀 노드 내부 동작까지 검사할 수 없습니다. 서버를 외부에 공개하거나 `--listen 0.0.0.0`으로 실행할 필요는 없습니다.

ComfyUI에서 먼저 **참고 이미지 기반** 워크플로를 완성하고 **API 형식 JSON**으로 내보냅니다. 일반 UI 편집용 JSON은 사용할 수 없습니다. 워크플로의 다음 번호를 웹 설정에 입력합니다.

- 프롬프트 노드와 문자열 입력 필드(일반적으로 CLIPTextEncode의 `text`). 앱의 동작 시트 프롬프트로 교체합니다.
- 참고 그림 `LoadImage` 노드. 앱이 현재 친구 그림을 업로드하고 `image` 입력을 교체합니다.
- 출력 `SaveImage` 또는 `PreviewImage` 노드. 이 노드가 프롬프트와 참고 그림에 모두 연결돼 있어야 합니다.

워크플로는 **정사각형 4열 × 4행 시트 한 장**을 출력해야 합니다. 행은 정면/왼쪽/오른쪽/뒷면, 열은 걷기 A/중립/걷기 B/눈 감기입니다. 배경은 투명 또는 흰색, 프레임 사이 여백을 충분히 두고 16개의 캐릭터가 분리돼야 합니다. 앱은 시트 크기·16개 프레임·잘림 등을 검사하지만 캐릭터 유사도와 자세의 정확성은 보장하지 않습니다. 일반 이미지 모델에 프롬프트만 넣는 것으로 만족스러운 시트가 나오지 않을 수 있습니다. 적절한 모델·참고 이미지 처리·워크플로는 사용자가 준비해야 합니다.

**방향별 동작 이미지 → ComfyUI**에서 주소(기본 `http://127.0.0.1:8188`), API JSON, 노드 번호를 설정합니다. **서버 연결 확인**은 서버 정보만 확인하며, 모델/노드 설치 또는 생성 품질 검증은 아닙니다.

워크플로에는 경로 등 개인 설정이 있을 수 있어 이 탭에만 보관하고 새로고침·초기화·백업 교체 때 비웁니다. API 키와 워크플로는 게임 백업에 포함하지 않습니다. 제공자 선택·주소·모델명·노드 번호는 브라우저에 기억합니다.

## 3. 브라우저 허용과 사용 시점

진화 방향 제안은 현재 그림을 읽으므로 Ollama의 비전·JSON 출력 지원이 필요합니다. 현재 모습의 특징과 키운 기록을 한 번의 요청으로 읽습니다. 분석 실패 시 기본 진화 방향을 사용하며 자동 재요청하지 않습니다.

**진화 초상화**는 참고 이미지를 보내지 않는 텍스트 생성입니다. ComfyUI에서는 `LoadImage`가 출력에 연결되지 않은 텍스트 기반 워크플로를 준비하고, 참고 그림 노드 번호를 비우세요. 한 명의 캐릭터 그림 한 장을 출력해야 합니다. 마이홈 동작 시트를 만들 때는 위의 참고 이미지 워크플로로 다시 설정합니다. 설정이 맞지 않으면 작업을 큐에 보내기 전에 멈추며, 진화 진행도와 이전 그림은 남습니다.

브라우저가 로컬 네트워크 접속을 요청하면 허용하세요. 사이트 권한을 차단했거나 CORS 설정이 빠졌거나 서버가 꺼졌다면 연결할 수 없습니다. 브라우저/OS에 따라 HTTPS 사이트에서 HTTP 로컬 연결을 제한할 수 있으므로 로컬 네트워크 접근을 지원하는 최신 브라우저를 사용하세요. 이 기능은 `localhost`, `127.0.0.1`, `[::1]`의 루트 서버 주소만 받으며 다른 PC나 LAN 서버 연결은 지원하지 않습니다.

텍스트를 Ollama, 이미지를 ComfyUI로 선택하면 Gemini 키가 필요 없습니다. Gemini는 선택한 기능에서만 사용하고 로컬 실패 시 자동 대체하지 않습니다. 두 제공자를 섞어 쓸 수도 있습니다.

새 친구를 만나거나 새 그림을 저장한 뒤 **마이홈 첫 방문에서 AI 픽셀 캐릭터 생성을 선택할 때** 이미지 생성을 한 번 요청합니다. 무료 기본 모습을 선택하면 AI 없이 저장합니다. 친구·그림 저장, 홈 재입장·가구 구매·이동·되돌리기·동작 저장 재시도는 AI를 호출하지 않습니다. 실패한 생성도 자동 재요청하지 않습니다. ComfyUI의 제출은 한 번만 하며 대기는 최대 4분입니다. 브라우저 대기를 취소해도 ComfyUI 큐의 작업은 계속될 수 있으므로 서버에서 확인하세요. 앱이 다른 작업까지 중단하는 서버 전체 interrupt를 보내지는 않습니다.

[Ollama CORS 안내](https://docs.ollama.com/faq) · [Ollama Chat API](https://docs.ollama.com/api/chat) · [ComfyUI 서버 경로](https://docs.comfy.org/development/comfyui-server/comms_routes) · [Chrome 로컬 네트워크 권한](https://developer.chrome.com/blog/local-network-access)