ENVIRONMENT_VARIABLES.md

🔧 환경 변수 설정 가이드

🏠 로컬 개발 환경

.env 파일 설정

프로젝트 루트에 .env 파일을 생성하고 다음 변수들을 설정하세요:

# 기본 서버 설정
HOST=0.0.0.0
PORT=8001
PYTHONPATH=/app
PYTHONUNBUFFERED=1

# 환경 감지
IS_LOCAL=true
ENVIRONMENT=local
DOCKER_ENV=local

# 모델 설정
DEFAULT_MODEL=kanana-1.5-v-3b-instruct
MAX_NEW_TOKENS=256
TEMPERATURE=0.7

# 로컬 모델 경로 (선택사항)
LOCAL_MODEL_PATH=./lily_llm_core/models/kanana_1_5_v_3b_instruct

로컬 Docker 실행

# 로컬 개발용 Docker 빌드
docker build -f Dockerfile.local -t lily-llm-local .

# 로컬 실행 (포트 8001)
docker run -p 8001:8001 --env-file .env lily-llm-local

☁️ Hugging Face Spaces 환경

필수 환경 변수

Hugging Face Spaces Settings > Variables에서 다음 변수들을 설정하세요:

기본 서버 설정

HOST=0.0.0.0
PORT=7860
PYTHONPATH=/app
PYTHONUNBUFFERED=1

Hugging Face 설정

# 캐시 디렉토리
TRANSFORMERS_CACHE=/app/cache/transformers
HF_HOME=/app/cache/huggingface
HF_HUB_CACHE=/app/cache/huggingface

# 모델 설정
HF_MODEL_NAME=gbrabbit/lily-math-model
DEFAULT_MODEL=kanana-1.5-v-3b-instruct

# 토큰화 병렬 처리 비활성화 (메모리 절약)
TOKENIZERS_PARALLELISM=false

성능 최적화

# CPU 스레드 제한 (메모리 절약)
OMP_NUM_THREADS=1
MKL_NUM_THREADS=1

# PyTorch 설정
TORCH_HOME=/app/cache/torch
PYTORCH_TRANSFORMERS_CACHE=/app/cache/transformers

AI 모델 설정

# 생성 파라미터
MAX_NEW_TOKENS=256
TEMPERATURE=0.7
TOP_P=0.9
TOP_K=40

선택적 환경 변수

디버깅

# 로그 레벨
LOG_LEVEL=INFO
DEBUG=false

# 상세 로깅
TRANSFORMERS_VERBOSITY=warning
HF_HUB_VERBOSITY=warning

보안 (필요시)

# API 키 (필요한 경우)
HF_TOKEN=your_huggingface_token
API_SECRET_KEY=your_secret_key

🚀 자동 모델 다운로드 동작 방식

1단계: 로컬 모델 확인

• /app/lily_llm_core/models/kanana_1_5_v_3b_instruct/ 경로 확인
• 파일이 있으면 로컬 모델 사용

2단계: Hugging Face Hub 다운로드

• 로컬 모델이 없으면 gbrabbit/lily-math-model에서 자동 다운로드
• /app/cache/transformers/ 경로에 캐시 저장

3단계: 모델 로딩

• 캐시된 모델을 메모리에 로드
• 서버 시작 완료

📊 예상 동작

첫 번째 배포

🌐 Hugging Face Hub에서 다운로드: gbrabbit/lily-math-model
📥 모델 다운로드 중... (약 2-5분)
✅ 모델 로드 완료
🚀 서버 시작: 0.0.0.0:7860

이후 재시작

🗂️ 캐시된 모델 사용: /app/cache/transformers/
✅ 모델 로드 완료 (약 30초)
🚀 서버 시작: 0.0.0.0:7860

🔍 문제 해결

모델 다운로드 실패

# 네트워크 연결 확인
curl -I https://huggingface.co/gbrabbit/lily-math-model

# Hugging Face Hub 상태 확인
curl -I https://huggingface.co/api/models/gbrabbit/lily-math-model

메모리 부족

# 더 작은 모델 사용 또는 양자화 적용
# Hardware 업그레이드 고려 (CPU upgrade 또는 GPU)

캐시 문제

# 캐시 디렉토리 권한 확인
ls -la /app/cache/

# 캐시 삭제 후 재시작
rm -rf /app/cache/transformers/*