ExperionCrawler/plans/local-llm-chat-webpage-plan.md

폐쇄 네트워크 로컬 LLM 채팅 웹페이지 제작 계획

1. 분석 요약

Ollama (로컬 LLM 런타임)

• 기본 API 엔드포인트: http://localhost:11434/api
• OpenAI 호환 API: http://localhost:11434/v1/
• 주요 API:
  • POST /api/chat - 채팅 (메시지 배열 기반)
  • POST /api/generate - 텍스트 생성 (프롬프트 기반)
  • GET /api/tags - 로컬 모델 목록 조회
  • POST /api/pull - 모델 다운로드 (폐쇄 네트워크에서는 사전 다운로드 필요)
• 스트리밍 응답: NDJSON 형식 (application/x-ndjson), "stream": false로 비활성화 가능
• 모델: 폐쇄 네트워크에서는 ollama pull로 사전 다운로드 필요 (예: llama3, gemma3, qwen3 등)

Open WebUI (참용 웹 UI)

• 기술 스택: Svelte (프론트엔드) + FastAPI (백엔드)
• 설치: Docker 또는 pip (pip install open-webui)
• Ollama 연결: OLLAMA_BASE_URL 환경변수
• 참고: 폐쇄 네트워크에서 바로 사용 가능한 완성된 솔루션이지만, 커스텀 웹페이지 제작을 위한 참고용으로 활용

---

2. 필요한 정보 요약

필수 조건

1. Ollama 설치 및 실행 (폐쇄 네트워크에 사전 설치)
2. 로컬 모델 다운로드 (사전 ollama pull <model_name> 실행)
3. 웹 서버 (정적 파일 서빙 + API 프록시, 또는 프론트엔드에서 직접 Ollama API 호출)

API 요청/응답 형식

// 채팅 요청 (POST /api/chat)
{
  "model": "llama3",
  "messages": [
    {"role": "user", "content": "안녕하세요"}
  ],
  "stream": false
}

// 채팅 응답
{
  "model": "llama3",
  "message": {"role": "assistant", "content": "안녕하세요! 어떻게 도와드릴까요?"}
}

스트리밍 응답 처리 (선택사항)

• NDJSON 형식으로 각 줄이独立的 JSON 객체
• done: true로 응답 종료 신호
• ReadableStream + TextDecoder로 처리 가능

---

3. Todo List

Phase 1: 환경 준비

• 1.1 폐쇄 네트워크 서버에 Ollama 설치
• 1.2 필요한 LLM 모델 사전 다운로드 (ollama pull)
• 1.3 Ollama 서비스 실행 및 localhost:11434 접근 확인

Phase 2: 프론트엔드 기본 구조

• 2.1 HTML/CSS/JavaScript 기반 채팅 UI 스키레션 작성
• 2.2 채팅 메시지 표시 영역 (사용자/보조 구분)
• 2.3 입력 필드 및 전송 버튼 구현
• 2.4 반응형 디자인 (모바일/데스크톱)

Phase 3: Ollama API 연동

• 3.1 fetch()로 Ollama /api/chat 엔드포인트 호출 구현
• 3.2 메시지 히스토리 관리 (배열 유지)
• 3.3 모델 선택 기능 (/api/tags로 모델 목록 조회)
• 3.4 로딩 상태 및 에러 처리

Phase 4: 스트리밍 응답 (선택사항)

• 4.1 NDJSON 스트리밍 파싱 구현
• 4.2 실시간 텍스트 표시 (타이핑 효과)
• 4.3 스트리밍 중단 기능

Phase 5: 추가 기능

• 5.1 채팅 기록 저장 (localStorage)
• 5.2 새 채팅 시작 / 채팅 초기화
• 5.3 Markdown 렌더링 (코드 블록, 수식 등)
• 5.4 시스템 프롬프트 설정 기능

Phase 6: 배포

• 6.1 정적 파일 빌드
• 6.2 폐쇄 네트워크 서버에 배포
• 6.3 CORS 설정 (Ollama OLLAMA_HOST 환경변수)
• 6.4 최종 테스트

---

4. 기술 선택 가이드

옵션	설명	추천도
순수 HTML/JS	의존성 없음, 폐쇄 네트워크에 적합	⭐⭐⭐
Vue/React SPA	빌드 필요, 하지만 풍부한 생태계	⭐⭐
Open WebUI 그대로 사용	별도 개발 불필요, Docker로 배포	⭐⭐⭐

폐쇄 네트워크 권장: 순수 HTML/CSS/JavaScript 또는 Open WebUI Docker 배포