비공개 오픈소스 모델이나 파인튜닝된 자체 가중치를 HuggingChat 대화 인터페이스에서 구동하려면, 먼저 플랫폼의 구조적 특징을 이해해야 합니다. 많은 개발자가 공개 버전의 HuggingChat(hf.co/chat)에 접속하여 사용자 설정이나 어시스턴트 설정 창에 엔드포인트 URL과 개인 API 토큰을 입력하는 옵션을 찾곤 합니다. 하지만 공개 HuggingChat은 Hugging Face가 직접 관리하는 라우팅 인프라 위에서 구동되는 멀티테넌트 쇼케이스 서비스입니다. 따라서 보안 격리와 컴퓨팅 리소스 보호 정책상, 사용자가 임의의 전용 추론 엔드포인트를 공개 웹 화면에 직접 연결할 수 없도록 설계되어 있습니다.
HuggingChat 특유의 직관적인 사용자 경험을 유지하면서 프라이빗 모델을 연동하는 정석적인 방법은 HuggingChat의 기반 오픈소스 소프트웨어인 Chat UI를 자체 인프라에 배포하는 것입니다. SvelteKit 기반의 Chat UI는 OpenAI 호환 API 규격을 기본 지원하므로, 환경 변수인 OPENAI_BASE_URL과 OPENAI_API_KEY에 Hugging Face 추론 엔드포인트(Inference Endpoints) 주소와 계정 토큰을 지정하기만 하면 즉시 전용 모델로 트래픽을 라우팅할 수 있습니다. 이는 비공개 Hugging Face Space 또는 로컬 Docker 환경을 통해 몇 분 안에 구축할 수 있습니다.
아키텍처 및 연동 흐름
프라이빗 모델 연동은 다음 세 가지 핵심 구성 요소로 이루어집니다.
- Hugging Face Inference Endpoints: Text Generation Inference(TGI) 또는 vLLM 고성능 엔진 기반으로 비공개 리포지토리 모델(Llama 3.3, Mistral, Qwen 또는 자체 LoRA 모델)을 구동하며, OpenAI 규격의
/v1/chat/completionsREST API를 제공합니다. - User Access Token (
HF_TOKEN): 엔드포인트에 전송되는 모든 추론 요청에 대한 보안 인증을 처리합니다. - Chat UI (자체 HuggingChat 인스턴스): 전용 엔드포인트를 호출하여 대화 기록 관리, 멀티모달 입력 및 툴 호출 등 HuggingChat 고유의 기능을 제공하는 프론트엔드 웹 애플리케이션입니다.
+-------------------------------------------------------------+
| Chat UI 프라이빗 인스턴스 |
| (Hugging Face Space / 로컬 Docker) |
+-------------------------------------------------------------+
|
OPENAI_BASE_URL | OPENAI_API_KEY (hf_xxx)
v
+-------------------------------------------------------------+
| Hugging Face Inference Endpoint |
| https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1 |
| (TGI / vLLM 컨테이너 구동) |
+-------------------------------------------------------------+
|
v
+-------------------------------------------------------------+
| 비공개 리포지토리 / 미세조정 가중치 |
+-------------------------------------------------------------+
1단계: 전용 추론 엔드포인트(Inference Endpoint) 배포
Hugging Face 관리형 클라우드에서 전용 GPU 인스턴스를 프로비저닝합니다.
- **Inference Endpoints 관리 콘솔**에 접속합니다.
- Create New Endpoint를 클릭합니다.
- Model Repository: 배포할 비공개 리포지토리 ID(예:
your-org/private-llama-3-8b-instruct) 또는 오픈소스 모델 경로를 입력합니다. - Cloud Provider & Region: 클라우드 제공업체(AWS 또는 Azure)와 사용자와 지연 시간이 낮은 리전을 선택합니다.
- Instance Type: 모델 파라미터 크기에 적합한 가속기 하드웨어를 지정합니다(8B 모델의 경우 NVIDIA A10G 1장, 70B 모델의 경우 A100/H100 멀티 GPU).
- Framework & Engine: 컨테이너 런타임으로 Text Generation Inference (TGI) 또는 vLLM을 선택합니다. 두 엔진 모두 OpenAI 호환 엔드포인트를 기본 노출합니다.
- Create Endpoint를 누르고 생성을 완료합니다.
상태가 Building에서 Running으로 변경될 때까지 대기한 후, 콘솔 대시보드에 부여된 전용 엔드포인트 URL을 복사합니다.
https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud
2단계: 계정 접근 토큰(Access Token) 발급
전용 엔드포인트 호출에 필요한 인증 자격 증명을 생성합니다.
- 계정 설정의 Settings > Access Tokens(
hf.co/settings/tokens) 메뉴로 이동합니다. - Create new token을 클릭합니다.
- 토큰 권한 유형을 설정합니다.
- Fine-grained token(세분화된 권한 토큰, 권장): Inference 항목에서 "Make calls to your Inference Endpoints" 옵션을 활성화합니다.
- Read token: 개인 계정 소유의 엔드포인트 호출 시 표준 Read 토큰으로도 인증이 가능합니다.
- 발급된 토큰 문자열(
hf_...)을 복사하여 안전한 키 저장소에 보관합니다.
3단계: Chat UI(HuggingChat) 설정 및 구동
Chat UI는 베이스 URL 뒤에 자동으로 /v1을 연결하여 모델 탐색과 대화 라우팅을 수행합니다.
옵션 A: Hugging Face Spaces 원클릭 배포 (권장)
팀 차원에서 물리 서버 관리 없이 간편하게 사용할 수 있는 가장 최적화된 방법입니다.
- Chat UI 공식 Space 템플릿을 엽니다.
- 비인가 사용자의 외부 접근을 차단하기 위해 공개 범위를 Private으로 설정합니다.
- Space의 Settings > Variables and Secrets에서 환경 변수를 등록합니다.
OPENAI_BASE_URL:https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1OPENAI_API_KEY:hf_************************(2단계에서 발급받은 접근 토큰)
- (선택 사항) Space 재시작 후에도 대화 내역을 유지하려면
MONGODB_URL을 설정합니다. 개인 테스트 환경의 경우 내장 데이터베이스가 자동으로 동작하므로 추가 설정이 필요 없습니다. - Space를 재시작하면 Chat UI가 엔드포인트를 감지하여 대화 준비를 완료합니다.
옵션 B: 로컬 또는 사내 인프라 자가 호스팅 (Node.js / Docker)
사내 폐쇄망이나 개인 워크스테이션에서 구동하는 절차입니다.
-
Chat UI 오픈소스 저장소를 클론합니다.
git clone https://github.com/huggingface/chat-ui.git cd chat-ui -
.env.local설정 파일을 생성합니다.# 추론 엔드포인트 설정 OPENAI_BASE_URL=https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1 OPENAI_API_KEY=hf_your_token_here # 데이터베이스 설정 (로컬 개발 시 생략하면 ./db 내장 DB 사용) # MONGODB_URL=mongodb://localhost:27017 -
엔드포인트에서
/v1/models경로 조회를 지원하지 않거나 모델 표시명과 생성 하이퍼파라미터를 커스텀하려면,.env.local내에MODELSJSON5 환경 변수를 선언합니다.MODELS=`[ { "id": "tgi", "name": "사내 전용 프라이빗 모델", "multimodal": false, "supportsTools": false, "parameters": { "temperature": 0.7, "max_tokens": 4096 } } ]` -
의존 패키지를 설치하고 개발 서버를 실행합니다.
npm install npm run dev -- --open
브라우저에서 http://localhost:5173 주소로 접속하면 프라이빗 가중치와 연결된 HuggingChat 환경이 실행됩니다.
연결 상태 검증
웹 인터페이스에서 테스트하기 전, 터미널에서 curl을 통해 엔드포인트 가동 상태와 권한을 사전 검증하는 것을 권장합니다.
curl -X POST "https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1/chat/completions" \
-H "Authorization: Bearer hf_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"model": "tgi",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello! Confirm endpoint readiness."}
],
"max_tokens": 50
}'
정상적인 텍스트 응답이 포함된 JSON이 반환되면 엔드포인트와 토큰이 정상적으로 결합된 것입니다.
운영 고려 사항 및 유의점
- 공개 버전 어시스턴트(Assistants)와의 기능적 차이:
hf.co/chat에서 생성하는 어시스턴트는 시스템 프롬프트 지정 및 RAG 지식 문서 업로드를 지원하지만, 실행 모델은 공용 카탈로그 내의 오픈소스 모델로 고정됩니다. 독점 가중치를 활용하고 데이터 프라이버시를 확보하려면 Chat UI 자체 배포가 유일한 해결책입니다. - 콜드 스타트(Scale-to-Zero): 유휴 시간 비용 절감을 위해 0개 복제본으로 자동 축소되도록 설정한 경우, 첫 메시지 발송 시 GPU 컨테이너 초기화 시간으로 인해 UI에서 타임아웃이 발생할 수 있습니다. 상시 운영 환경에서는 최소 복제본을 1개 이상 유지하는 것이 안정적입니다.
- 스트리밍(Streaming): Chat UI는 Server-Sent Events(SSE) 방식으로 응답을 실시간 렌더링합니다. TGI와 vLLM은 스트리밍을 기본 지원하지만, Nginx 등의 리버스 프록시를 사용할 경우 버퍼링을 해제(
proxy_buffering off;)해야 부드러운 출력이 보장됩니다.