huggingface/chat-ui

📣 huggingface/chat-ui 란?

가볍고 오픈 소스인 웹 프론트엔드로, OpenAI 호환 언어 모델 엔드포인트와 채팅할 수 있습니다. SvelteKit으로 구축되었으며 공개 HuggingChat 서비스(hf.co/chat)를 지원합니다. UI는 사용자 계정, 채팅 기록, 모델 선택, 테마, 선택적 도구 호출(MCP) 또는 멀티모달 입력을 처리하며, 모든 추론은 OpenAI /v1 프로토콜을 지원하는 외부 API(예: Hugging Face Inference Router, llama.cpp 서버, Ollama, OpenRouter 등)에 위임합니다.

🎯 핵심 기능

기능	작동 방식	중요성
모델 비종속 백엔드	`OPENAI_BASE_URL` 및 `OPENAI_API_KEY`를 통해 OpenAI `/v1` API를 노출하는 모든 서비스에 연결합니다.	코드 변경 없이 호스팅 HF 모델, 로컬 `llama.cpp`, Ollama 또는 상용 공급자 간에 전환할 수 있습니다.
채팅 영속성	사용자, 대화, 설정, 파일 업로드를 MongoDB에 저장합니다. 기본적으로 `./db`에 쓰는 임베디드 MongoDB로 대체됩니다.	세션 간 기록을 유지하고 로컬 개발에 즉시 사용할 수 있습니다.
Omni 라우터(선택 사항)	내장된 휴리스틱으로 각 요청에 대해 라우트(기본, 멀티모달, 도구 지원)를 선택한 다음 구체적인 모델을 선택합니다. JSON 정책 파일 및 환경 변수로 구성할 수 있습니다.	단일 "Omni" 모델 항목을 제공하여 이미지, 함수 호출 또는 일반 텍스트에 가장 적합한 백엔드를 자동으로 선택합니다.
MCP 도구 통합	Model Context Protocol 서버를 지원합니다. UI는 외부 도구(검색, 데이터베이스 조회 등)를 호출하고 OpenAI 함수 호출을 사용하여 결과를 모델에 피드백할 수 있습니다.	사용자 정의 백엔드 코드를 작성하지 않고도 더 풍부하고 에이전트적 대화가 가능합니다.
테마 및 브랜딩	간단한 환경 변수(`PUBLIC_APP_NAME`, `PUBLIC_APP_ASSETS` 등)로 앱 이름 변경, 로고 교체, 데이터 공유 옵트인 전환 등을 할 수 있습니다.	제품이나 커뮤니티 사이트에 UI를 쉽게 포함할 수 있습니다.
Docker 지원	공식 `ghcr.io/huggingface/chat-ui-db` 이미지에는 UI와 임베디드 MongoDB가 번들로 포함되어 있으며 동일한 환경 변수 인터페이스를 노출합니다.	모든 컨테이너 호스트나 클라우드 서비스에 한 번의 명령으로 배포할 수 있습니다.
ML Intern 모드	실험적인 "어시스턴트"로, 대화 내에서 Hugging Face Hub 작업(논문 재현, 미세 조정, 데이터 세트 생성)을 생성하고 실행할 수 있으며, 사용자별 컴퓨팅 예산을 존중합니다.	채팅 UI를 로우코드 ML 워크플로 오케스트레이터로 전환합니다.

🛠️ 시작하기(빠른 시작)

.env.local을 생성하고 최소한 다음을 설정합니다:

OPENAI_BASE_URL=https://router.huggingface.co/v1   # 또는 모든 OpenAI 호환 URL
OPENAI_API_KEY=hf_XXXXXXXXXXXXXXXXXXXXXXXXX      # 토큰 또는 로컬 서버용 더미 키

클론 및 설치

git clone https://github.com/huggingface/chat-ui
cd chat-ui
npm install
npm run dev -- --open   # http://localhost:5173 시작

(선택 사항) MongoDB 추가 – MONGODB_URL을 원격 Atlas 클러스터로 설정하거나 로컬 컨테이너를 실행합니다:
```
docker run -d -p 27017:27017 --name mongo-chatui mongo:latest
```
MONGODB_URL을 생략하면 임베디드 DB가 자동으로 사용됩니다.

배포 – 프로덕션의 경우 npm run build && npm run preview를 실행하거나 제공된 Docker 이미지를 사용합니다:

docker run -p 3000:3000 \
  -e OPENAI_BASE_URL=… -e OPENAI_API_KEY=… \
  -v chat-ui-data:/data \
  ghcr.io/huggingface/chat-ui-db:latest

📚 일반적인 사용 사례

자체 호스팅 ChatGPT 스타일 UI: 프런트엔드를 처음부터 구축하지 않고 개인 모델(예: 회사 내부 LLM)용으로 사용.
연구 모델용 데모 플랫폼: llama.cpp 서버 또는 Ollama 모델을 연결하고 사용자가 세련된 웹 UI를 통해 상호 작용할 수 있도록 합니다.
도구 강화 에이전트: MCP를 통해 검색이나 코드 실행 서비스를 노출하고 모델이 자동으로 호출하도록 합니다.
멀티모달 실험: Omni 라우터를 통해 이미지 입력을 비전 지원 모델로 라우팅합니다.
ML Intern 플레이그라운드: 비기술 사용자가 채팅에서 직접 미세 조정 작업이나 데이터 세트 생성을 트리거할 수 있도록 합니다.

⚠️ 제한 사항 및 주의 사항

OpenAI 스타일 API만 지원 – 다른 프로토콜을 사용하는 공급자(예: 기본 Hugging Face pipeline 엔드포인트)는 지원되지 않습니다.
/models 이상의 모델 검색 기능 없음 – 백엔드에서 /models 목록을 노출하거나 MODELS 환경 변수를 수동으로 구성해야 합니다.
사용자 지정 라우팅에는 라우터 정책 파일이 필요 – 기본 분기에는 샘플 JSON이 포함되어 있지 않습니다. 내장 휴리스틱 이상을 원하면 직접 만들어야 합니다.
MCP 지원은 모델의 함수 호출 기능에 따라 다름 – 선택한 모델이 도구를 지원하지 않으면 UI에서 해당 기능을 숨깁니다.
프로덕션 배포에는 SvelteKit 어댑터가 필요(예: Vercel, Netlify, Cloudflare) – README에 언급되어 있지만 바로 사용할 수 있는 구성은 제공되지 않습니다.

📦 TL;DR

huggingface/chat-ui는 OpenAI 호환 LLM 엔드포인트와 작동하는 즉시 실행 가능한 SvelteKit 기반 웹 채팅 프런트엔드입니다. MongoDB를 통한 영구 기록, 선택적 스마트 라우팅(Omni), MCP를 통한 도구 통합, 테마, 손쉬운 배포를 위한 Docker 이미지를 제공합니다. UI 코드를 작성하지 않으면서도 로컬 또는 클라우드 LLM, 멀티모달 모델, 에이전트형 도구 호출을 연결할 수 있는 세련된 채팅 인터페이스를 원하는 모든 사람에게 적합합니다.

huggingface/chat-ui