llamadart 기반 온디바이스 LLM 채팅 앱입니다. Cloudflare R2 모델 허브 서버는 로컬/비공개 구성으로 사용할 수 있습니다.

공개 Git 업로드에서는 server/ 디렉터리를 제외합니다. R2 키, 운영 환경변수, 업로드 API는 별도 비공개 저장소나 로컬 환경에서 관리하세요.

• 앱에서 원격(R2) 모델 목록 확인
• 원하는 GGUF 모델 다운로드/로컬 삭제
• 로컬 모델을 llamadart로 로드해서 온디바이스 채팅
• 서버에서 R2 다운로드 URL(Presigned URL) 발급

ondevicehub/
├─ lib/ # Flutter 앱
├─ android/ ios/ # 플랫폼 설정
├─ server/ # 로컬 전용, 공개 Git 업로드 제외
└─ README.md

• Flutter SDK (Dart 3.11+)
• Node.js 20+ (비공개 서버 연동 시)
• Cloudflare R2 버킷 및 API 토큰(비공개 서버 연동 시)

cd server
cp .env.example .env
npm install
npm start

server/.env 필수 값:

• R2_ACCOUNT_ID
• R2_ACCESS_KEY_ID
• R2_SECRET_ACCESS_KEY
• R2_BUCKET

선택 값:

• PORT (기본 8787)
• R2_MODEL_PREFIX (기본 models/)
• ADMIN_API_KEY (관리 API 보호용)
• ALLOWED_ORIGINS (CORS)

cd server
npm run upload:model -- /absolute/path/to/model.gguf

원격 키 직접 지정:

npm run upload:model -- /absolute/path/to/model.gguf models/custom/my-model.gguf

프로젝트 루트에서:

flutter pub get
flutter run --dart-define=ODH_API_BASE_URL=http://10.0.2.2:8787

서버 URL 규칙:

• Android 에뮬레이터: http://10.0.2.2:<PORT>
• 실기기: http://<서버PC-LAN-IP>:<PORT>

1. 앱 실행 후 모델 허브 탭에서 파일 가져오기
2. GGUF 파일 절대경로 입력 (예: /path/to/model.gguf)
3. 로컬 목록에서 모델 선택 후 선택 모델 로드
4. 채팅 탭에서 메시지 전송

1. 앱 상단에 Hub API URL 입력 후 서버 적용
2. 모델 허브 탭에서 원격 모델 목록 확인
3. 모델 다운로드
4. 로컬 목록에서 모델 선택 후 선택 모델 로드
5. 채팅 탭에서 메시지 전송

안전하게 받으려면 다음 순서를 권장합니다.

• 1순위: 공식 조직이 직접 배포한 GGUF (예: Qwen/*-GGUF)
• 2순위: Hugging Face의 검증된 GGUF 변환자 (예: bartowski/*-GGUF)
• 공통 체크: 모델 카드의 License, Original model, 파일 확장자(.gguf) 확인

양자화 기본값은 Q4_K_M부터 시작하는 것을 권장합니다(속도/품질/메모리 균형).

• Qwen2.5-1.5B-Instruct-GGUF
  • https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF
• Qwen2.5-3B-Instruct-GGUF
  • https://huggingface.co/Qwen/Qwen2.5-3B-Instruct-GGUF
• Qwen2.5-7B-Instruct-GGUF
  • https://huggingface.co/Qwen/Qwen2.5-7B-Instruct-GGUF
• Qwen3-4B-GGUF
  • https://huggingface.co/Qwen/Qwen3-4B-GGUF
• Qwen3-8B-GGUF
  • https://huggingface.co/Qwen/Qwen3-8B-GGUF

• Llama-3.2-1B-Instruct-GGUF (Meta Llama 계열, 경량)
  • https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF
• Llama-3.2-3B-Instruct-GGUF (Meta Llama 계열, 균형)
  • https://huggingface.co/bartowski/Llama-3.2-3B-Instruct-GGUF
• gemma-2-2b-it-GGUF (Google Gemma 계열)
  • https://huggingface.co/bartowski/gemma-2-2b-it-GGUF
• Mistral-7B-Instruct-v0.3-GGUF (Mistral 계열)
  • https://huggingface.co/bartowski/Mistral-7B-Instruct-v0.3-GGUF
• Phi-3.5-mini-instruct-GGUF (Microsoft Phi 계열)
  • https://huggingface.co/bartowski/Phi-3.5-mini-instruct-GGUF
• DeepSeek-R1-Distill-Llama-8B-GGUF (추론/리즌닝 성향)
  • https://huggingface.co/bartowski/DeepSeek-R1-Distill-Llama-8B-GGUF
• aya-expanse-8b-GGUF (다국어 강점)
  • https://huggingface.co/bartowski/aya-expanse-8b-GGUF

아래 3개를 기본 프리셋으로 두고 시작하는 것을 권장합니다.

1. 저사양/가벼운 테스트: Llama-3.2-1B-Instruct-GGUF (Q4_K_M)
   • https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF
2. 균형형(속도/품질): Qwen2.5-3B-Instruct-GGUF (Q4_K_M)
   • https://huggingface.co/Qwen/Qwen2.5-3B-Instruct-GGUF
3. 고품질(메모리 여유 필요): Mistral-7B-Instruct-v0.3-GGUF (Q4_K_M)
   • https://huggingface.co/bartowski/Mistral-7B-Instruct-v0.3-GGUF

• GET /health
• GET /models
• GET /models/download-url?key=<r2-key>&expiresInSeconds=3600
• POST /models/upload-url (선택: ADMIN_API_KEY 필요)
• DELETE /models?key=<r2-key> (선택: ADMIN_API_KEY 필요)

상세 서버 문서는 공개 업로드에서 제외되는 로컬 server/README.md를 참고하세요.

flutter analyze
flutter test

• 대형 GGUF는 저장공간/메모리를 많이 사용합니다.
• 추론 속도는 모델 크기와 기기 NPU/CPU/GPU 성능에 직접 영향받습니다.
• 모바일에서 HTTP(비TLS) 서버를 쓰는 경우 Android cleartext 설정이 필요합니다(프로젝트에 반영됨).