온프레미스 환경에서 운영하는 오픈소스 기반 AI 플랫폼. LibreChat + LiteLLM 위에 Ollama / vLLM 과 OpenRouter 를 묶어 채팅, RAG, 이미지 생성, 코드 실행을 한 곳에서 제공한다. Commercial 모델 (OpenAI/Anthropic/Google) 은 OpenRouter 경유. Super Agent (qwen2.5:7b-instruct 라우터 + qwen3.6:35b 합성) 가 기본 에이전트.
본인 환경에 맞는 시나리오 하나를 골라 따라가면 된다:
- A — 로컬 GPU 만 (Ollama / vLLM): 자체 GPU 클러스터가 있을 때. 무료이며 데이터가 외부로 나가지 않는다. 4090/5090 노드는 Ollama, Pro 5000/6000 · GB10 같은 5000+ 노드는 vLLM 을 권장한다 (동시성 8+ 에서 3-89배 우위). 모델 다운로드 시간과 100 GB 이상의 디스크가 필요하다.
- B — OpenRouter 만: 자체 GPU 클러스터가 없을 때. OpenRouter API 키 1개로 GPT/Claude/Gemini 다 쓸 수 있음. 5분 안에 띄움. 단, 사용량당 과금 + 데이터는 OpenRouter 경유.
- C — 로컬 GPU + OR: 가장 흔한 셋업. GPU 로 로컬 모델 + OR 키 하나로 frontier 모델 같이. 민감 대화는 로컬로, 고난이도 작업만 OR 경유.
git clone https://github.com/boanlab/KloudChat.git && cd KloudChat
./scripts/gen-env.sh # .env 생성 (시크릿 자동 채움)GPU 가 compose 호스트와 같은 머신이면:
# 1. (선택) FLUX.1-dev 받을 거면 .env 에 HF_TOKEN 먼저 채우기
$EDITOR .env # HF_TOKEN=hf_... (없으면 flux-dev 만 빠지고 나머지 이미지 모델은 그대로)
# 2. GPU 호스트에 Ollama + (선택) vLLM + ComfyUI + Whisper 설치 + 모델 다운로드
./scripts/install-ollama.sh
./scripts/download-ollama-models.sh # GPU 자동 감지 추천 셋
# (선택) Pro 5000 / Pro 6000 / GB10 — 5000+ 노드만 vLLM 권장. 4090/5090 은 ollama 만.
./scripts/install-vllm.sh # docker 이미지 pull + GPU 런타임 검증
./scripts/download-vllm-models.sh # GPU class 자동 감지 권장 셋
./scripts/manage-vllm.sh up # vllm-qwen7b + qwen35b + bge-m3 컨테이너 띄우기
# .env 에 VLLM_QWEN7B_URL=http://host.docker.internal:8001 등 채워두면 LiteLLM 이 해당 model_name 의 ollama deployment 대신 vLLM 으로 단일 라우팅 (35B 는 8002, bge-m3 는 8003).
./scripts/install-comfyui.sh # 이미지 생성 — Pro 6000 / GB10 노드만 (4090/5090/Pro 5000 은 hard fail)
./scripts/download-image-models.sh # 기본 셋 + (HF_TOKEN 있으면 flux-dev)
./scripts/install-whisper.sh # 자막 없는 YouTube 영상 전사 쓸 거면
./scripts/download-whisper-models.sh # (선택) prewarm — 첫 호출 lazy-load 회피
# 3. setup + admin (OPENROUTER_API_KEY 빈 칸 두면 commercial 모델 미등록, OLLAMA_URLS/COMFYUI_URLS는 기본값 그대로)
./scripts/setup.sh all
./scripts/manage.sh user create --id admin@example.com --name '관리자' --username admin --password '비번8자이상'→ LibreChat http://localhost:8080 로 로그인 → 모델 dropdown 에 Super Agent (vLLM 띄웠다면) 또는 local/qwen3.6:35b (Ollama) 가 보이면 정상. 안 보이면 장애 대응 참고.
GPU 가 별도 노드면:
# 1. 각 GPU 노드에서 — flux-dev 쓸 거면 HF_TOKEN 환경변수로 전달
# (또는 조정 노드의 .env 에 NODES_OLLAMA/COMFYUI/WHISPER/VLLM 채우고
# ./scripts/setup.sh all 한 번에 — 아래 "멀티 노드를 한번에" 참고)
./scripts/install-ollama.sh
./scripts/download-ollama-models.sh
# (선택) 5000+ 노드만 — vLLM 컨테이너 띄우기
./scripts/install-vllm.sh
./scripts/download-vllm-models.sh
./scripts/manage-vllm.sh up
./scripts/install-comfyui.sh
HF_TOKEN=hf_... ./scripts/download-image-models.sh # HF_TOKEN 생략 시 flux-dev만 빠짐
./scripts/install-whisper.sh # YouTube 음성 인식 폴백 쓸 거면
./scripts/download-whisper-models.sh # (선택) prewarm — 첫 호출 lazy-load 회피
# 2. compose 호스트의 .env 에서 노드 가리키기
$EDITOR .env
# OLLAMA_URLS=http://gpu-node-1:11434,http://gpu-node-2:11434
# COMFYUI_URLS=http://gpu-node-1:8188,http://gpu-node-2:8188
# WHISPER_URLS=http://gpu-node-1:9000,http://gpu-node-2:9000 # whisper 멀티노드 쓸 거면
# # vLLM 띄운 노드만 — csv 로 여러 노드 동시 가능 (router 가 LB).
# VLLM_QWEN7B_URL=http://gpu-node-1:8001,http://gpu-node-2:8001
# VLLM_QWEN35B_URL=http://gpu-node-1:8002,http://gpu-node-2:8002
# VLLM_BGE_M3_URL=http://gpu-node-1:8003,http://gpu-node-2:8003
# 3. setup
./scripts/setup.sh all멀티 노드일 때 LibreChat 메뉴에 등장하는 모델 = 어느 노드에라도 pull/적재된 모델(union). 같은 모델을 여러 노드에 받으면 LiteLLM router 가 노드 간 LB.
VLLM_*_URL이 채워진 모델은 같은 model_name 의 ollama deployment 가 카탈로그에서 빠지고 vLLM 으로 단일 라우팅 (vLLM 우선 정책).
# 1. .env 의 OPENROUTER_API_KEY 채우기 + 나머지는 그대로
$EDITOR .env
# OPENROUTER_API_KEY=sk-or-v1-...
# 2. setup (Ollama 노드는 unreachable warn 만 뜨고 진행됨)
./scripts/setup.sh all
# 3. admin 생성
./scripts/manage.sh user create \
--id admin@example.com --name '관리자' --username admin --password '비번8자이상'→ LibreChat http://localhost:8080. gpt-5.5, claude-opus-4.7, gemini-3.1-pro-preview 등 OR 라우팅 모델이 메뉴에 나옴.
이미지 생성·RAG 임베딩은 로컬 모델이 필요해 이 시나리오에선 비활성. 활성하려면 A 또는 C.
A의 로컬 GPU 위에 B의 OR 단일 키를 얹어 frontier 모델까지 함께 운영.
# 1. (선택) FLUX.1-dev 받을 거면 .env 에 HF_TOKEN 먼저 채우기
$EDITOR .env
# OPENROUTER_API_KEY=sk-or-v1-...
# OLLAMA_URLS=http://host.docker.internal:11434 (또는 원격 노드 csv)
# COMFYUI_URLS=http://host.docker.internal:8188 (이미지 생성 쓸 거면)
# # vLLM 띄울 거면 (5000+ 노드)
# VLLM_QWEN7B_URL=http://host.docker.internal:8001
# VLLM_QWEN35B_URL=http://host.docker.internal:8002
# VLLM_BGE_M3_URL=http://host.docker.internal:8003
# HF_TOKEN=hf_...
# 2. GPU 호스트에서 Ollama + (선택) vLLM + ComfyUI + Whisper
./scripts/install-ollama.sh
./scripts/download-ollama-models.sh
./scripts/install-vllm.sh && ./scripts/download-vllm-models.sh && ./scripts/manage-vllm.sh up # 5000+ 노드만
./scripts/install-comfyui.sh # Pro 6000 / GB10 만 (4090/5090/Pro 5000 은 hard fail)
./scripts/download-image-models.sh
./scripts/install-whisper.sh
./scripts/download-whisper-models.sh # (선택) prewarm — 첫 호출 lazy-load 회피
# 3. setup + admin
./scripts/setup.sh all
./scripts/manage.sh user create --id admin@example.com --name '관리자' --username admin --password '비번8자이상'→ LibreChat http://localhost:8080 → dropdown 에 OR commercial 모델 + 로컬 Super Agent / qwen3.6:35b 가 같이 보이면 정상.
LibreChat 메뉴에는 OR 라우팅 commercial 모델 (gpt-5.5, claude-opus-4.7, gemini-3.1-pro-preview 등) + 로컬 모델 (qwen3.6:35b — Ollama 또는 vLLM, qwen3.5:9b 는 4090 dev 한정) + Super Agent (local/super-agent — 7b router + 35b chat 합성) 가 노출. qwen2.5:7b-instruct 는 router 전용, qwen3-coder-next:q8_0 는 외부 코딩 클라이언트 (Claude Code / Codex CLI) 전용이라 둘 다 hidden. .env 의 VLLM_*_URL 이 채워진 모델은 같은 model_name 의 ollama deployment 대신 vLLM 으로 단일 라우팅 (5000+ 노드 = vLLM, 4090/5090 = ollama).
자세한 매트릭스는 docs/models.md 참고.
1. ./scripts/gen-env.sh → .env 생성 (시크릿 자동, 외부 키는 사용자가 채움)
2. (선택) GPU 노드에서 install-ollama + download-ollama-models
install-vllm + download-vllm-models + manage-vllm up (5000+ 노드만)
install-comfyui + download-image-models
install-whisper + download-whisper-models
3. ./scripts/setup.sh all → .env + 노드 discovery로 모델 매트릭스 결정 → docker compose up
(분리 노드면 litellm 노드 setup.sh litellm → librechat 노드 setup.sh librechat)
4. ./scripts/manage.sh user create → admin 생성, 끝
여러 호스트로 분산 운영할 때 각 노드에 ssh 해서 똑같은 명령을 치는 대신, .env 에 노드 ssh 타겟을 박아두고 한 줄로 푼다. setup.sh 가 .env 의 NODE_* / NODES_* 를 SoT 로 보고 로컬이면 직접 실행, 원격이면 rsync + ssh 로 디스패치한다. 사전 조건: 각 노드에 ssh-copy-id + NOPASSWD sudo (자세한 절차는 prerequisites.md::멀티 노드). 단일노드면 모든 NODE_* 를 비워두거나 같은 호스트로 — 자기 자신 ssh 불필요.
# .env (조정 노드 — 보통 LibreChat 노드 또는 워크스테이션)
NODES_OLLAMA=ops@gpu-1.lan,ops@gpu-2.lan
NODES_COMFYUI=ops@gpu-1.lan # Pro 6000 / GB10 만
NODES_WHISPER=ops@gpu-1.lan,ops@gpu-2.lan
NODES_VLLM=ops@gpu-2.lan # 5000+ 노드만
NODE_LITELLM=ops@10.0.0.10
NODE_LIBRECHAT=ops@10.0.0.11
LITELLM_URL=http://10.0.0.10:8000 # LibreChat 노드 입장에서 본 LiteLLM 주소./scripts/setup.sh all
# 1) NODES_* 의 각 GPU 노드에 rsync + setup.sh {ollama|vllm|comfyui|whisper}
# 2) NODES_VLLM 채워졌으면 python3 -m scheduler apply -y → 노드별 .env 오버라이드 (자세히는 docs/scheduler.md)
# 3) NODE_LITELLM 에 rsync + setup.sh litellm → 끝나면 .env (LITELLM_SERVICE_KEY) 로컬로 pull
# 4) NODE_LIBRECHAT 에 갱신된 .env (LITELLM_SERVICE_KEY 포함) 까지 rsync + setup.sh librechatsetup.sh all 한 줄로 위 4 단계 자동 진행 — LITELLM_SERVICE_KEY 발급/회수/재배포까지 자동. 분리 노드를 setup.sh litellm + setup.sh librechat 으로 따로 실행할 때는 LiteLLM 노드에서 발급된 LITELLM_SERVICE_KEY 를 LibreChat 노드의 .env 에 수동 복사해야 librechat 단계의 사전 검증을 통과 (env-reference.md::LITELLM_SERVICE_KEY).
# 개별 role 만 :
./scripts/setup.sh ollama --coder
./scripts/setup.sh comfyui --force
./scripts/setup.sh litellm
./scripts/setup.sh scheduler apply --priorities chat,rag,image # 자세히는 docs/scheduler.md
./scripts/setup.sh scheduler inventory # 노드별 GPU / VRAM / 실행 컨테이너 진단scheduler 는 멀티노드 vLLM 운영의 placement 자동화 도구. 단일노드 / Ollama-only 운영에선 알 필요 없음 (KLOUDCHAT_SKIP_SCHEDULER=1 로 끄거나 그냥 안 호출). 자세히는 scheduler 문서.
| 기능 | 컴포넌트 |
|---|---|
| 멀티 LLM 채팅 | LibreChat + LiteLLM |
| 로컬 LLM 런타임 | Ollama (host-native, 4090/5090) / vLLM (docker, 5000+ 노드) |
| 라우터 + 합성 에이전트 | Super Agent (super-agent-shim — 7B 라우터 + 35B 합성) |
| RAG | pgvector + MeiliSearch + bge-m3 |
| 웹 검색 | SearXNG (engines: Google/DDG + 학술 science 탭) + valkey rate-limiter |
| 웹 페이지 스크레이핑 | Crawl4AI shim (firecrawl-호환 API, 외부 의존성 없음) |
| 코드 실행 | LibreCodeInterpreter |
| 파일 업로드 | LibreChat RAG API |
| 이미지 생성 | ComfyUI + A1111 shim |
| MCP 도구 | stdio (fetch_url / time / usage / youtube) + HTTP (deep_research 사이드카) |
| 운영 관리 | LiteLLM + scripts/manage.sh |
이미지 생성은 FLUX.1 (dev, schnell — Q8 GGUF) — tools.md#이미지-백엔드. RAG API 는 HWP / PDF / DOCX 등 업로드 처리. MCP 서버 전체 목록은 tools.md. 운영 관리는 팀·사용자·예산 (LiteLLM 가상 키).
| 환경 | 시나리오 |
|---|---|
| Linux x86_64, GPU 없음 | B (OR-only) |
| Linux x86_64 + NVIDIA GPU | A / B / C |
| Linux aarch64 — DGX Spark (GB10) | A / B / C |
GPU 없으면 채팅만 가능 — 이미지 / RAG 임베딩은 로컬 모델 필요해서 비활성. ComfyUI · Ollama · Whisper 는 모두 GPU 호스트에 systemd native 로 설치 (컨테이너 아님) — DGX Spark (GB10 arm64) 도 동일, install-comfyui.sh 가 GPU class 감지해 Blackwell 노드만 torch 2.9.1 (NVFP4 dtype 노출) 로 설치.
[사용자] → LibreChat (:8080)
↓
LiteLLM (:8000) ──→ Ollama (OLLAMA_URLS, 4090/5090 노드의 model_name LB)
├─→ vLLM (VLLM_*_URL, 5000+ 노드 — 채워지면 ollama deployment 대체)
├─→ super-agent-shim → 7B router → tool_call 즉시 반환
│ → 없으면 35B 합성 (stream)
└─→ OpenRouter (gpt-*/claude-*/gemini-*)
RAG API → LiteLLM → bge-m3 → pgvector + MeiliSearch (Hybrid)
crawl4ai-shim → Playwright Chromium (firecrawl-호환)
comfyui-shim → ComfyUI (COMFYUI_URLS)
whisper-shim → Whisper (WHISPER_URLS, inflight 카운터 + 페어 ollama VRAM 기준 라우팅)
youtube MCP → whisper-shim
SearXNG (+ valkey limiter) / code-interpreter
더 자세한 다이어그램과 컴포넌트 설명은 docs/overview.md.
처음 띄울 때는 위 빠른 시작만 따라하면 된다. 막힐 때 / 더 깊이 보고 싶을 때:
- 사전 요구사항 — 하드웨어/소프트웨어 체크리스트
- 장애 대응 — 첫 실행 점검, 컨테이너 죽음, vLLM cold-start fail, swap thrash, 로그 위치
- 환경변수 레퍼런스 —
.env변수 전체 - 모델 설정 — 카탈로그 + 라우팅 매트릭스 + 모델 추가법
- 도구 — Built-in / MCP / image 백엔드 + 모델별 부착 매트릭스
- 코딩 에이전트 연동 — Claude Code / Codex를 로컬
qwen3-coder-next로 구동 - 브랜딩 커스터마이징 — 로고 / 파비콘 / PWA / 엔드포인트 아이콘 교체
- 아키텍처 상세 — 컴포넌트별 동작
- GPU 메모리 가이드 — 시나리오별 VRAM 점유 + 노드 클래스별 정책
- Ollama 튜닝 — systemd 환경변수 / GPU 클래스별 결정값 /
KEEP_ALIVE - vLLM 튜닝 — 모델 매트릭스 / gpu_memory_utilization / hybrid 정책
- scheduler — 멀티노드 vLLM placement 자동화 (단일노드는 안 읽어도 됨)
CLI:
./scripts/manage.sh— 팀 / 사용자 / 가상키 / 에이전트 관리 (인자 없이 실행 시 도움말)./scripts/manage-vllm.sh— vLLM 컨테이너 라이프사이클 (up/down/restart/logs/status).--coder로 코더 전용 노드 격리../scripts/clean.sh [litellm|librechat|local|all]—docker compose down후 bind-mount 데이터 (librechat/litellm/mongodb/meilisearch/rag/code-interpreter/scripts/.data) 삭제.⚠️ 대화/사용자/RAG 임베딩/사용량 로그까지 모두 지워지는 복구 불가 작업 — 백업 필요하면 따로 받고 실행.YES=1로 확인 프롬프트 스킵 가능..env의NODE_LITELLM/NODE_LIBRECHAT보고 다중노드면 ssh 로 dispatch (setup.sh 와 동일 패턴). 기본all./scripts/tune-host.sh [--check]— LLM 서빙 호스트의 sysctl 튜닝 (vm.swappiness=10등). 모델 weight mmap 의 file cache 가 swap 되는 idle cold-start 회피. GB10 unified memory 노드에 특히 유용
MIT — 자세한 내용은 LICENSE 참고.