README_CONTEXT_LORA.md

Lily LLM - 컨텍스트 관리 및 LoRA/QLoRA 시스템

📋 개요

Lily LLM 프로젝트에 단기 기억(컨텍스트 창) 기능과 LoRA/QLoRA 지원을 추가하여 더욱 강력하고 효율적인 AI 대화 시스템을 구축했습니다.

🚀 주요 기능

1. 컨텍스트 관리 시스템 (Context Management)

🔧 핵심 기능

• 대화 히스토리 관리: 사용자와 AI 간의 대화를 순차적으로 저장
• 메모리 최적화: 설정된 제한에 도달하면 자동으로 컨텍스트 압축
• 세션 관리: 여러 대화 세션을 독립적으로 관리
• 컨텍스트 검색: 저장된 대화 내용에서 특정 정보 검색

📊 컨텍스트 전략

• Sliding Window: 최근 메시지 우선 유지
• Priority Keep: 시스템 프롬프트와 최근 메시지 우선
• Circular Buffer: 순환 방식으로 메모리 관리

💾 데이터 관리

• 내보내기/가져오기: JSON 형식으로 컨텍스트 저장 및 복원
• 메타데이터 지원: 각 메시지에 추가 정보 첨부 가능
• 통계 정보: 메모리 사용량 및 효율성 지표 제공

2. LoRA/QLoRA 지원 시스템

🔗 LoRA (Low-Rank Adaptation)

• 효율적인 파인튜닝: 전체 모델 대신 일부 파라미터만 훈련
• 메모리 절약: GPU 메모리 사용량 대폭 감소
• 빠른 어댑터 전환: 여러 작업별 어댑터를 빠르게 교체

📈 QLoRA (Quantized LoRA)

• 4비트 양자화: 모델 크기와 메모리 사용량 추가 감소
• 고품질 훈련: 양자화된 모델에서도 높은 품질의 훈련 가능
• 하드웨어 효율성: 저사양 GPU에서도 훈련 가능

🎯 지원 모델

• Causal Language Models: GPT, LLaMA, Kanana 등
• Sequence-to-Sequence: T5, BART 등
• Classification Models: BERT, RoBERTa 등

🛠️ 설치 및 설정

1. 의존성 설치

pip install -r requirements.txt

2. 추가 패키지 설치

# LoRA/QLoRA 지원
pip install peft>=0.7.0
pip install bitsandbytes>=0.41.0

# 선택적: 더 나은 성능을 위한 패키지
pip install accelerate
pip install transformers[torch]

3. 환경 변수 설정

# GPU 사용 설정
export CUDA_VISIBLE_DEVICES=0

# 메모리 최적화
export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128

📖 사용법

1. 컨텍스트 관리

기본 사용법

import requests

# 시스템 프롬프트 설정
response = requests.post("http://localhost:8001/context/set-system-prompt", 
                        data={"prompt": "당신은 한국어 AI 어시스턴트입니다."})

# 사용자 메시지 추가
response = requests.post("http://localhost:8001/context/add-message",
                        data={
                            "role": "user",
                            "content": "안녕하세요!",
                            "metadata": '{"session_id": "session_1"}'
                        })

# 어시스턴트 응답 추가
response = requests.post("http://localhost:8001/context/add-message",
                        data={
                            "role": "assistant",
                            "content": "안녕하세요! 무엇을 도와드릴까요?",
                            "metadata": '{"session_id": "session_1"}'
                        })

# 컨텍스트 조회
response = requests.get("http://localhost:8001/context/get")
context = response.json()["context"]

고급 기능

# 컨텍스트 검색
response = requests.get("http://localhost:8001/context/search?query=날씨&max_results=5")

# 컨텍스트 내보내기
response = requests.post("http://localhost:8001/context/export",
                        data={"file_path": "my_context.json"})

# 컨텍스트 가져오기
response = requests.post("http://localhost:8001/context/import",
                        data={"file_path": "my_context.json"})

# 컨텍스트 통계
response = requests.get("http://localhost:8001/context/summary")

2. LoRA/QLoRA 사용

기본 모델 로드

# 기본 모델 로드
response = requests.post("http://localhost:8001/lora/load-base-model",
                        data={
                            "model_path": "/path/to/your/model",
                            "model_type": "causal_lm"
                        })

LoRA 설정 생성

# LoRA 설정 생성
response = requests.post("http://localhost:8001/lora/create-config",
                        data={
                            "r": 16,                    # LoRA 랭크
                            "lora_alpha": 32,           # LoRA 알파
                            "target_modules": "q_proj,v_proj,k_proj,o_proj",  # 타겟 모듈
                            "lora_dropout": 0.1,        # 드롭아웃
                            "bias": "none",             # 바이어스 처리
                            "task_type": "CAUSAL_LM"    # 작업 타입
                        })

어댑터 적용 및 사용

# LoRA 어댑터 적용
response = requests.post("http://localhost:8001/lora/apply",
                        data={"adapter_name": "my_adapter"})

# LoRA 모델로 텍스트 생성
response = requests.post("http://localhost:8001/lora/generate",
                        data={
                            "prompt": "안녕하세요!",
                            "max_length": 100,
                            "temperature": 0.7
                        })

# 어댑터 저장
response = requests.post("http://localhost:8001/lora/save-adapter",
                        data={"adapter_name": "my_adapter"})

3. 통합 사용 (컨텍스트 + LoRA)

# 컨텍스트를 사용한 텍스트 생성
response = requests.post("http://localhost:8001/generate",
                        data={
                            "prompt": "이전 대화를 참고해서 답변해주세요.",
                            "use_context": "true",
                            "session_id": "session_1"
                        })

🔍 API 엔드포인트

컨텍스트 관리

메서드	엔드포인트	설명
POST	/context/set-system-prompt	시스템 프롬프트 설정
POST	/context/add-message	메시지 추가
GET	/context/get	컨텍스트 조회
GET	/context/summary	컨텍스트 요약
POST	/context/clear	컨텍스트 초기화
DELETE	/context/message/{message_id}	메시지 제거
PUT	/context/message/{message_id}	메시지 수정
GET	/context/search	컨텍스트 검색
POST	/context/export	컨텍스트 내보내기
POST	/context/import	컨텍스트 가져오기

LoRA 관리

메서드	엔드포인트	설명
POST	/lora/load-base-model	기본 모델 로드
POST	/lora/create-config	LoRA 설정 생성
POST	/lora/apply	LoRA 어댑터 적용
POST	/lora/load-adapter	저장된 어댑터 로드
POST	/lora/save-adapter	어댑터 저장
GET	/lora/adapters	어댑터 목록
GET	/lora/stats	어댑터 통계
POST	/lora/switch	어댑터 전환
POST	/lora/unload	어댑터 언로드
POST	/lora/generate	LoRA 모델로 생성
POST	/lora/merge	어댑터 병합

📊 성능 최적화

1. 메모리 관리

• 컨텍스트 압축: 자동 메모리 최적화
• 토큰 제한: 설정 가능한 최대 토큰 수
• 세션 분리: 독립적인 메모리 공간

2. LoRA 최적화

• 랭크 조정: r 값으로 정확도와 효율성 균형
• 타겟 모듈 선택: 필요한 레이어만 선택적 훈련
• 그래디언트 체크포인팅: 메모리 사용량 감소

3. 하드웨어 최적화

• GPU 메모리: 효율적인 메모리 할당
• CPU 스레드: 멀티스레딩 최적화
• 배치 처리: 대량 데이터 처리 최적화

🧪 테스트

테스트 스크립트 실행

python test_context_lora.py

수동 테스트

# 서버 시작
python run_server.py

# 다른 터미널에서 테스트
curl -X POST "http://localhost:8001/context/set-system-prompt" \
     -d "prompt=당신은 한국어 AI 어시스턴트입니다."

curl -X GET "http://localhost:8001/context/summary"

🔧 설정 옵션

컨텍스트 관리자 설정

# ContextManager 초기화 시 설정
context_manager = ContextManager(
    max_tokens=4000,        # 최대 토큰 수
    max_turns=20,           # 최대 대화 턴 수
    strategy="sliding_window"  # 압축 전략
)

LoRA 설정

# LoRA 설정 예시
lora_config = LoraConfig(
    r=16,                    # LoRA 랭크 (높을수록 정확도 향상, 메모리 증가)
    lora_alpha=32,          # LoRA 알파 (스케일링 팩터)
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],  # 타겟 모듈
    lora_dropout=0.1,       # 드롭아웃 비율
    bias="none",            # 바이어스 처리 방식
    task_type="CAUSAL_LM"   # 작업 타입
)

🚨 주의사항

1. 메모리 관리

• 컨텍스트 길이: 너무 긴 컨텍스트는 메모리 부족을 야기할 수 있습니다
• LoRA 랭크: 높은 랭크는 정확도를 높이지만 메모리 사용량도 증가합니다

2. 성능 고려사항

• GPU 메모리: LoRA 훈련 시 충분한 GPU 메모리가 필요합니다
• CPU 사용량: 컨텍스트 압축 시 CPU 리소스가 사용됩니다

3. 호환성

• 모델 타입: 모든 모델이 LoRA를 지원하지 않을 수 있습니다
• 버전 호환성: PEFT와 Transformers 버전 호환성을 확인하세요

📚 추가 자료

관련 문서

• PEFT 공식 문서
• LoRA 논문
• QLoRA 논문

예제 코드

• test_context_lora.py: 통합 테스트 스크립트
• examples/: 추가 사용 예제들

커뮤니티

• Hugging Face PEFT
• GitHub Issues

🤝 기여하기

버그 리포트, 기능 제안, 코드 기여를 환영합니다!

1. 이슈 생성
2. 포크 후 브랜치 생성
3. 변경사항 커밋
4. Pull Request 생성

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.

---

Lily LLM - 더 스마트한 AI 대화를 위한 컨텍스트 관리 및 LoRA 시스템 🚀