hdsp-jupyter-extension 2.0.11__py3-none-any.whl → 2.0.13__py3-none-any.whl

agent_server/langchain/skills/inference.md

@@ -0,0 +1,392 @@
+---
+name: inference
+description: 모델 추론 최적화. 추론 속도가 느리거나 배치 처리가 필요할 때 사용. 배치 추론, 양자화(INT8/FP16), ONNX 변환, TensorRT 가속 가이드 제공.
+---
+
+# Model Inference Optimization Guide
+
+모델 추론 속도를 높이고 리소스 효율을 개선하는 방법을 안내합니다.
+
+## Resource Tiers
+
+### TIER_SMALL: CPU only 또는 단일 추론
+- 배치 처리 불필요
+- ONNX Runtime CPU 권장
+- 동적 양자화(INT8) 적용
+
+### TIER_MEDIUM: GPU 사용, 중간 규모 추론
+- 배치 크기: 8-64
+- FP16 추론
+- ONNX Runtime GPU 또는 TorchScript
+
+### TIER_LARGE: 대규모 서빙, 고성능 필요
+- 배치 크기: 64-256
+- TensorRT 또는 TensorRT-LLM
+- INT8 양자화 + 배치 최적화
+
+---
+
+## 1. 배치 추론 (Batch Inference)
+
+### PyTorch 배치 처리
+```python
+import torch
+
+model.eval()
+
+# 개별 추론 (느림)
+# for item in items:
+#     result = model(item)
+
+# 배치 추론 (빠름)
+batch = torch.stack(items)  # [N, C, H, W]
+with torch.no_grad():
+    results = model(batch)
+```
+
+### 동적 배칭 (Dynamic Batching)
+```python
+def dynamic_batch_inference(items, model, max_batch=32, max_wait_ms=50):
+    """요청을 모아서 배치 처리"""
+    import time
+
+    batch = []
+    start_time = time.time()
+
+    for item in items:
+        batch.append(item)
+
+        # 배치가 꽉 차거나 대기 시간 초과
+        if len(batch) >= max_batch or (time.time() - start_time) * 1000 > max_wait_ms:
+            batch_tensor = torch.stack(batch)
+            with torch.no_grad():
+                yield model(batch_tensor)
+            batch = []
+            start_time = time.time()
+
+    # 남은 배치 처리
+    if batch:
+        batch_tensor = torch.stack(batch)
+        with torch.no_grad():
+            yield model(batch_tensor)
+```
+
+### 최적 배치 크기
+| GPU Memory | 권장 Batch Size | 참고 |
+|------------|----------------|------|
+| 4GB | 8-16 | 작은 모델 |
+| 8GB | 16-32 | 중간 모델 |
+| 16GB | 32-64 | 큰 모델 |
+| 24GB+ | 64-128 | 대형 모델 |
+
+---
+
+## 2. 양자화 (Quantization)
+
+### PyTorch 동적 양자화 (가장 간단)
+```python
+import torch
+
+# 동적 양자화: 추론 시 가중치를 INT8로 변환
+model_int8 = torch.quantization.quantize_dynamic(
+    model,
+    {torch.nn.Linear, torch.nn.LSTM},  # 양자화할 레이어 타입
+    dtype=torch.qint8
+)
+
+# 모델 크기 약 4배 감소
+# 추론 속도 2-4배 향상 (CPU)
+```
+
+### PyTorch 정적 양자화 (더 빠름)
+```python
+import torch
+from torch.quantization import get_default_qconfig, prepare, convert
+
+# 1. 양자화 설정
+model.qconfig = get_default_qconfig('fbgemm')  # CPU용
+# model.qconfig = get_default_qconfig('qnnpack')  # 모바일용
+
+# 2. 준비 (observer 삽입)
+model_prepared = prepare(model)
+
+# 3. 캘리브레이션 (대표 데이터로)
+with torch.no_grad():
+    for data in calibration_loader:
+        model_prepared(data)
+
+# 4. 변환
+model_quantized = convert(model_prepared)
+```
+
+### 양자화 효과
+| Precision | Model Size | Speed (CPU) | Speed (GPU) | Accuracy |
+|-----------|------------|-------------|-------------|----------|
+| FP32 | 1x | 1x | 1x | Baseline |
+| FP16 | 0.5x | 1x | 1.5-2x | ~동일 |
+| INT8 | 0.25x | 2-4x | 2-3x | 약간 감소 |
+
+---
+
+## 3. ONNX 변환 및 최적화
+
+### PyTorch → ONNX 변환
+```python
+import torch
+
+model.eval()
+dummy_input = torch.randn(1, 3, 224, 224)
+
+torch.onnx.export(
+    model,
+    dummy_input,
+    "model.onnx",
+    input_names=["input"],
+    output_names=["output"],
+    dynamic_axes={
+        "input": {0: "batch_size"},   # 동적 배치 지원
+        "output": {0: "batch_size"}
+    },
+    opset_version=17  # 최신 opset 권장
+)
+```
+
+### ONNX Runtime 추론
+```python
+import onnxruntime as ort
+import numpy as np
+
+# CPU 세션
+session = ort.InferenceSession(
+    "model.onnx",
+    providers=['CPUExecutionProvider']
+)
+
+# GPU 세션 (CUDA)
+session = ort.InferenceSession(
+    "model.onnx",
+    providers=['CUDAExecutionProvider', 'CPUExecutionProvider']
+)
+
+# 추론
+input_name = session.get_inputs()[0].name
+output = session.run(None, {input_name: input_data.numpy()})
+```
+
+### ONNX 모델 최적화
+```python
+import onnx
+from onnxruntime.transformers import optimizer
+
+# 자동 최적화 (Transformer 모델용)
+optimized_model = optimizer.optimize_model(
+    "model.onnx",
+    model_type='bert',  # 'gpt2', 'bert', 'vit' 등
+    num_heads=12,
+    hidden_size=768
+)
+optimized_model.save_model_to_file("model_optimized.onnx")
+```
+
+### ONNX 속도 향상
+- PyTorch → ONNX: **CPU 최대 3배**, GPU 1.5-2배 속도 향상
+- 추가 그래프 최적화: 10-30% 추가 향상
+
+---
+
+## 4. TensorRT 가속
+
+### ONNX → TensorRT 변환
+```python
+import tensorrt as trt
+
+logger = trt.Logger(trt.Logger.WARNING)
+builder = trt.Builder(logger)
+network = builder.create_network(1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH))
+parser = trt.OnnxParser(network, logger)
+
+# ONNX 모델 파싱
+with open("model.onnx", "rb") as f:
+    parser.parse(f.read())
+
+# 빌더 설정
+config = builder.create_builder_config()
+config.set_memory_pool_limit(trt.MemoryPoolType.WORKSPACE, 1 << 30)  # 1GB
+
+# FP16 활성화 (Volta 이상)
+config.set_flag(trt.BuilderFlag.FP16)
+
+# INT8 활성화 (캘리브레이션 필요)
+# config.set_flag(trt.BuilderFlag.INT8)
+# config.int8_calibrator = calibrator
+
+# 엔진 빌드
+engine = builder.build_serialized_network(network, config)
+
+# 저장
+with open("model.trt", "wb") as f:
+    f.write(engine)
+```
+
+### Torch-TensorRT (더 간단)
+```python
+import torch
+import torch_tensorrt
+
+model = model.eval().cuda()
+
+# TensorRT 컴파일
+trt_model = torch_tensorrt.compile(
+    model,
+    inputs=[
+        torch_tensorrt.Input(
+            min_shape=[1, 3, 224, 224],
+            opt_shape=[8, 3, 224, 224],
+            max_shape=[32, 3, 224, 224],
+            dtype=torch.float16
+        )
+    ],
+    enabled_precisions={torch.float16},
+    workspace_size=1 << 30
+)
+
+# 추론
+with torch.no_grad():
+    output = trt_model(input_tensor.cuda().half())
+```
+
+### TensorRT 속도 향상
+- PyTorch → TensorRT: **GPU 최대 5배** 속도 향상
+- FP16 + TensorRT: 3-4배 일반적
+- INT8 + TensorRT: 5-8배 가능
+
+---
+
+## 5. Hugging Face Transformers 최적화
+
+### 기본 최적화
+```python
+from transformers import AutoModelForSequenceClassification, AutoTokenizer
+import torch
+
+model = AutoModelForSequenceClassification.from_pretrained("bert-base-uncased")
+tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
+
+# FP16 추론
+model = model.half().cuda()
+
+# BetterTransformer (Flash Attention)
+model = model.to_bettertransformer()
+
+# 추론
+with torch.no_grad():
+    inputs = tokenizer(texts, return_tensors="pt", padding=True).to("cuda")
+    outputs = model(**inputs)
+```
+
+### Optimum + ONNX Runtime
+```python
+from optimum.onnxruntime import ORTModelForSequenceClassification
+from transformers import AutoTokenizer
+
+# ONNX 변환 및 로드
+model = ORTModelForSequenceClassification.from_pretrained(
+    "bert-base-uncased",
+    export=True,
+    provider="CUDAExecutionProvider"
+)
+tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
+
+# 추론
+inputs = tokenizer(texts, return_tensors="pt", padding=True)
+outputs = model(**inputs)
+```
+
+---
+
+## 6. 추론 서버 최적화
+
+### torch.inference_mode (torch.no_grad 보다 빠름)
+```python
+# torch.no_grad() 대신 사용
+with torch.inference_mode():
+    output = model(input_tensor)
+```
+
+### CUDA Graphs (반복 추론용)
+```python
+import torch
+
+# 워밍업
+s = torch.cuda.Stream()
+s.wait_stream(torch.cuda.current_stream())
+with torch.cuda.stream(s):
+    for _ in range(3):
+        output = model(static_input)
+torch.cuda.current_stream().wait_stream(s)
+
+# 그래프 캡처
+g = torch.cuda.CUDAGraph()
+with torch.cuda.graph(g):
+    static_output = model(static_input)
+
+# 추론 (그래프 재생)
+g.replay()
+result = static_output.clone()
+```
+
+---
+
+## 7. 메모리 최적화
+
+```python
+import torch
+
+# 추론 후 캐시 정리
+torch.cuda.empty_cache()
+
+# 그래디언트 비활성화 (메모리 절약)
+for param in model.parameters():
+    param.requires_grad = False
+
+# 스트리밍 추론 (대용량 데이터)
+def stream_inference(dataloader, model):
+    model.eval()
+    with torch.inference_mode():
+        for batch in dataloader:
+            yield model(batch.cuda())
+            torch.cuda.empty_cache()  # 배치마다 정리
+```
+
+---
+
+## Quick Reference: 최적화 선택 가이드
+
+| 상황 | 권장 방법 | 예상 향상 |
+|------|----------|----------|
+| CPU 추론 | ONNX Runtime + INT8 | 3-4x |
+| GPU 추론 (간단) | FP16 + torch.compile | 1.5-2x |
+| GPU 추론 (최대 성능) | TensorRT + FP16/INT8 | 3-5x |
+| Transformer 모델 | BetterTransformer + ONNX | 2-3x |
+| 대량 추론 | 배치 처리 + TensorRT | 5-10x |
+
+### 빠른 적용 체크리스트
+```python
+# 1. 기본 최적화
+model.eval()
+with torch.inference_mode():
+    ...
+
+# 2. FP16 (GPU)
+model = model.half().cuda()
+
+# 3. torch.compile (PyTorch 2.0+)
+model = torch.compile(model, mode="reduce-overhead")
+
+# 4. ONNX 변환 (더 빠른 추론 필요시)
+torch.onnx.export(model, ...)
+
+# 5. TensorRT (최대 성능 필요시)
+torch_tensorrt.compile(model, ...)
+```
+

agent_server/langchain/skills/model_training.md

@@ -0,0 +1,318 @@
+---
+name: model-training
+description: 모델 훈련 최적화. GPU 메모리 부족, 훈련 속도 개선 시 사용. mixed precision(fp16/bf16), gradient checkpointing, batch size 튜닝, optimizer 최적화 제공.
+---
+
+# Model Training Optimization Guide
+
+GPU/CPU 환경에서 효율적인 모델 훈련 방법을 안내합니다.
+
+## Resource Tiers
+
+### TIER_SMALL: GPU < 8GB 또는 CPU only
+- batch_size: 4-16
+- gradient_checkpointing: 필수
+- mixed precision: 권장
+- optimizer: 8-bit Adam
+
+### TIER_MEDIUM: GPU 8-24GB (RTX 3090, T4, A10)
+- batch_size: 16-64
+- gradient_checkpointing: 선택
+- mixed precision: fp16/bf16 필수
+- optimizer: AdamW 또는 8-bit Adam
+
+### TIER_LARGE: GPU > 24GB (A100, H100)
+- batch_size: 64-256
+- gradient_checkpointing: 불필요
+- mixed precision: bf16 권장
+- optimizer: AdamW, CUDA Graphs 활용
+
+---
+
+## 1. Mixed Precision Training
+
+### PyTorch Native (권장)
+```python
+import torch
+from torch.cuda.amp import autocast, GradScaler
+
+model = model.cuda()
+optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4)
+scaler = GradScaler()
+
+for batch in dataloader:
+    optimizer.zero_grad()
+
+    # Mixed precision forward pass
+    with autocast():
+        outputs = model(batch["input_ids"].cuda())
+        loss = criterion(outputs, batch["labels"].cuda())
+
+    # Scaled backward pass
+    scaler.scale(loss).backward()
+    scaler.step(optimizer)
+    scaler.update()
+```
+
+### Hugging Face Transformers
+```python
+from transformers import TrainingArguments, Trainer
+
+training_args = TrainingArguments(
+    output_dir="./results",
+    per_device_train_batch_size=16,
+
+    # Mixed Precision 선택 (GPU 아키텍처에 따라)
+    fp16=True,   # Volta, Turing, Ampere
+    # bf16=True,  # Ampere 이상 권장 (더 안정적)
+)
+```
+
+### Data Type 선택 가이드
+
+| GPU Architecture | Recommended | Notes |
+|------------------|-------------|-------|
+| Volta (V100) | fp16 | bf16 미지원 |
+| Turing (RTX 20xx, T4) | fp16 | bf16 미지원 |
+| Ampere (A100, RTX 30xx) | bf16 | fp16도 가능, bf16이 더 안정적 |
+| Hopper (H100) | bf16 | FP8도 지원 |
+
+---
+
+## 2. Gradient Checkpointing
+
+메모리 50-80% 절약, 훈련 속도 20-30% 감소 트레이드오프.
+
+### PyTorch
+```python
+from torch.utils.checkpoint import checkpoint_sequential
+
+# 모델 레이어를 청크로 나누어 체크포인팅
+model = nn.Sequential(layer1, layer2, layer3, layer4)
+output = checkpoint_sequential(model, 2, input)  # 2개 청크로 분할
+```
+
+### Hugging Face Transformers
+```python
+from transformers import TrainingArguments
+
+training_args = TrainingArguments(
+    output_dir="./results",
+    per_device_train_batch_size=4,
+    gradient_checkpointing=True,  # 활성화
+    gradient_accumulation_steps=16,  # effective batch = 4 * 16 = 64
+)
+```
+
+### 언제 사용?
+- GPU 메모리 부족 (OOM)
+- 큰 모델 (7B+ 파라미터)
+- 작은 GPU (< 16GB)
+
+---
+
+## 3. Batch Size & Gradient Accumulation
+
+### 최적 Batch Size 찾기
+```python
+# 1. 최대 batch size 찾기 (OOM 직전까지)
+# 2. 2의 거듭제곱 사용 (8, 16, 32, 64, 128)
+# 3. fp16: 8의 배수, A100: 64의 배수
+
+# Gradient Accumulation으로 effective batch size 확보
+training_args = TrainingArguments(
+    per_device_train_batch_size=4,      # GPU에 맞는 최대값
+    gradient_accumulation_steps=16,      # 4 * 16 = 64 effective
+)
+```
+
+### Batch Size 권장표
+
+| GPU Memory | Max Batch (fp32) | Max Batch (fp16) | Recommended |
+|------------|------------------|------------------|-------------|
+| 8GB | 4-8 | 8-16 | 8 (fp16) |
+| 16GB | 8-16 | 16-32 | 16 (fp16) |
+| 24GB | 16-32 | 32-64 | 32 (fp16) |
+| 40GB+ | 32-64 | 64-128 | 64 (bf16) |
+
+---
+
+## 4. Optimizer 최적화
+
+### 8-bit Adam (메모리 절약)
+```python
+# bitsandbytes 설치 필요: pip install bitsandbytes
+import bitsandbytes as bnb
+
+optimizer = bnb.optim.Adam8bit(
+    model.parameters(),
+    lr=1e-4,
+    betas=(0.9, 0.999)
+)
+
+# Hugging Face
+training_args = TrainingArguments(
+    optim="adamw_bnb_8bit",  # 8-bit AdamW
+)
+```
+
+### Adafactor (대용량 모델용)
+```python
+from transformers import Adafactor
+
+optimizer = Adafactor(
+    model.parameters(),
+    scale_parameter=True,
+    relative_step=True,
+    warmup_init=True,
+    lr=None  # relative_step=True면 자동 조절
+)
+```
+
+---
+
+## 5. Data Loading 최적화
+
+```python
+from torch.utils.data import DataLoader
+
+dataloader = DataLoader(
+    dataset,
+    batch_size=32,
+    shuffle=True,
+    num_workers=4,           # CPU 코어 수에 맞게
+    pin_memory=True,         # GPU 전송 가속
+    prefetch_factor=2,       # 미리 로드할 배치 수
+    persistent_workers=True  # 워커 재사용
+)
+
+# Hugging Face
+training_args = TrainingArguments(
+    dataloader_pin_memory=True,
+    dataloader_num_workers=4,
+)
+```
+
+---
+
+## 6. torch.compile (PyTorch 2.0+)
+
+```python
+import torch
+
+# 모델 컴파일 (최대 2x 속도 향상)
+model = torch.compile(model, mode="reduce-overhead")
+
+# Hugging Face
+training_args = TrainingArguments(
+    torch_compile=True,
+    torch_compile_backend="inductor",  # 기본값, 최적
+)
+```
+
+### 컴파일 모드
+
+| Mode | Speed | Memory | Use Case |
+|------|-------|--------|----------|
+| default | Good | Neutral | 일반적인 경우 |
+| reduce-overhead | Best | Slight increase | 긴 훈련 |
+| max-autotune | Best | Neutral | 시간 여유 있을 때 |
+
+---
+
+## 7. sklearn 모델 최적화
+
+### CPU 병렬화
+```python
+from sklearn.ensemble import RandomForestClassifier
+
+# n_jobs=-1: 모든 CPU 코어 사용
+model = RandomForestClassifier(
+    n_estimators=100,
+    n_jobs=-1,  # 병렬 처리
+    random_state=42
+)
+
+# GridSearchCV도 병렬화
+from sklearn.model_selection import GridSearchCV
+grid_search = GridSearchCV(
+    model, param_grid,
+    cv=5,
+    n_jobs=-1  # 병렬 교차 검증
+)
+```
+
+### 점진적 학습 (대용량 데이터)
+```python
+from sklearn.linear_model import SGDClassifier
+
+model = SGDClassifier(warm_start=True)
+
+# 청크별 학습
+for chunk in pd.read_csv("large_data.csv", chunksize=10000):
+    X, y = chunk.drop("target", axis=1), chunk["target"]
+    model.partial_fit(X, y, classes=[0, 1])
+```
+
+---
+
+## 8. 메모리 모니터링
+
+```python
+import torch
+
+# GPU 메모리 확인
+print(f"Allocated: {torch.cuda.memory_allocated() / 1024**3:.2f} GB")
+print(f"Cached: {torch.cuda.memory_reserved() / 1024**3:.2f} GB")
+
+# 메모리 정리
+torch.cuda.empty_cache()
+
+# 훈련 중 주기적 정리 (Hugging Face)
+training_args = TrainingArguments(
+    torch_empty_cache_steps=4,  # 4스텝마다 캐시 정리
+)
+```
+
+---
+
+## Quick Reference: 최적 설정 조합
+
+### TIER_SMALL (GPU < 8GB)
+```python
+TrainingArguments(
+    per_device_train_batch_size=4,
+    gradient_accumulation_steps=16,
+    gradient_checkpointing=True,
+    fp16=True,
+    optim="adamw_bnb_8bit",
+    dataloader_num_workers=2,
+)
+```
+
+### TIER_MEDIUM (GPU 8-24GB)
+```python
+TrainingArguments(
+    per_device_train_batch_size=16,
+    gradient_accumulation_steps=4,
+    bf16=True,  # or fp16
+    optim="adamw_torch",
+    dataloader_pin_memory=True,
+    dataloader_num_workers=4,
+    torch_compile=True,
+)
+```
+
+### TIER_LARGE (GPU > 24GB)
+```python
+TrainingArguments(
+    per_device_train_batch_size=64,
+    bf16=True,
+    optim="adamw_torch",
+    dataloader_pin_memory=True,
+    dataloader_num_workers=8,
+    torch_compile=True,
+    torch_compile_backend="inductor",
+)
+```
+