@llm-translate/cli 1.0.0-next.1

package/docs/ko/guide/ollama.md

@@ -0,0 +1,410 @@
+# Ollama를 사용한 로컬 번역
+
+::: info 번역
+모든 비영어 문서는 Claude Sonnet 4를 사용하여 자동으로 번역됩니다.
+:::
+
+Ollama를 사용하여 llm-translate를 완전히 오프라인으로 실행합니다. API 키가 필요하지 않으며, 민감한 문서에 대한 완전한 프라이버시를 제공합니다.
+
+::: warning 모델에 따라 품질이 달라집니다
+Ollama 번역 품질은 **모델 선택에 크게 의존합니다**. 신뢰할 수 있는 번역 결과를 위해서는:
+
+- **최소**: 14B+ 매개변수 모델 (예:`qwen2.5:14b `,` llama3.1:8b`)
+- **권장**: 32B+ 모델 (예:`qwen2.5:32b `,` llama3.3:70b`)
+- **권장하지 않음**: 7B 미만 모델은 일관성이 없고 종종 사용할 수 없는 번역을 생성합니다
+
+작은 모델(3B, 7B)은 간단한 콘텐츠에서는 작동할 수 있지만 기술 문서에서는 자주 실패하고, 불완전한 출력을 생성하거나, 형식 지침을 무시합니다.
+:::
+
+## Ollama를 사용하는 이유는?
+
+- **프라이버시**: 문서가 컴퓨터를 떠나지 않습니다
+- **API 비용 없음**: 초기 설정 후 무제한 번역
+- **오프라인**: 인터넷 연결 없이 작동
+- **사용자 정의 가능**: 도메인에 맞게 모델 미세 조정
+
+## 시스템 요구사항
+
+### 최소 요구사항 (14B 모델)
+
+- **RAM**: 16GB (qwen2.5:14b와 같은 14B 모델용)
+- **저장공간**: 20GB 여유 공간
+- **CPU**: 최신 멀티코어 프로세서
+
+### 권장 사양
+
+- **RAM**: 32GB+ (qwen2.5:32b와 같은 대형 모델용)
+- **GPU**: 16GB+ VRAM을 가진 NVIDIA 또는 Apple Silicon (M2/M3/M4)
+- **저장공간**: 여러 모델을 위한 100GB+
+
+### GPU 지원
+
+| 플랫폼 | GPU | 지원 |
+|----------|-----|---------|
+| macOS | Apple Silicon (M1/M2/M3/M4) | 우수 |
+| Linux | NVIDIA (CUDA) | 우수 |
+| Linux | AMD (ROCm) | 양호 |
+| Windows | NVIDIA (CUDA) | 양호 |
+| Windows | AMD | 제한적 |
+
+## 설치
+
+### macOS
+
+```bash
+# Using Homebrew (recommended)
+brew install ollama
+
+# Or download from https://ollama.ai
+```
+
+### Linux
+
+```bash
+# One-line installer
+curl -fsSL https://ollama.ai/install.sh | sh
+
+# Or using package managers
+# Ubuntu/Debian
+curl -fsSL https://ollama.ai/install.sh | sh
+
+# Arch Linux
+yay -S ollama
+```
+
+### Windows
+
+[ollama.ai](https://ollama.ai/download/windows)에서 설치 프로그램을 다운로드하세요.
+
+### Docker
+
+```bash
+# CPU only
+docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama
+
+# With NVIDIA GPU
+docker run -d --gpus=all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama
+```
+
+## 빠른 시작
+
+### 1. Ollama 서버 시작
+
+```bash
+# Start the server (runs in background)
+ollama serve
+```
+
+::: tip
+macOS와 Windows에서는 설치 후 Ollama가 백그라운드 서비스로 자동 시작됩니다.
+:::
+
+### 2. 모델 다운로드
+
+```bash
+# Recommended: Qwen 2.5 14B (best multilingual support for local)
+ollama pull qwen2.5:14b
+
+# Alternative: Llama 3.2 (lighter, good for English-centric docs)
+ollama pull llama3.2
+```
+
+### 3. 번역
+
+```bash
+# Basic translation with qwen2.5:14b
+llm-translate file README.md -o README.ko.md -s en -t ko --provider ollama --model qwen2.5:14b
+
+# With specific model
+llm-translate file doc.md -s en -t ja --provider ollama --model qwen2.5:14b
+```
+
+::: tip 번역을 위한 Qwen 2.5
+Qwen 2.5는 한국어, 일본어, 중국어 및 모든 주요 유럽 언어를 포함한 29개 언어를 지원합니다. 14B 버전은 16GB RAM에서 실행되면서 번역 작업에 우수한 품질을 제공합니다.
+:::
+
+## 번역을 위한 권장 모델
+
+### 최고 품질 (32B+)
+
+| 모델 | 크기 | VRAM | 언어 | 품질 |
+|-------|------|------|-----------|---------|
+|`llama3.3`| 70B | 40GB+ | 100+ | 우수 |
+|`qwen2.5:32b`| 32B | 20GB+ | 29 | 우수 |
+|`llama3.1:70b`| 70B | 40GB+ | 8 | 매우 좋음 |
+
+### 최고의 언어 지원을 가진 경량 모델
+
+제한된 리소스를 가진 시스템의 경우, **Qwen2.5**가 최고의 다국어 지원(29개 언어)을 제공합니다.
+
+| 모델 | 매개변수 | RAM | 언어 | 품질 | 최적 용도 |
+|-------|-----------|-----|-----------|---------|----------|
+|`qwen2.5:3b`| 3B | 3GB | 29 | 좋음 | **균형잡힌 (권장)** |
+|`qwen2.5:7b`| 7B | 6GB | 29 | 매우 좋음 | 품질 우선 |
+|`gemma3:4b`| 4B | 4GB | 다수 | 좋음 | 번역 최적화 |
+|`llama3.2`| 3B | 4GB | 8 | 좋음 | 영어 중심 문서 |
+
+### 초경량 (< 2GB RAM)
+
+| 모델 | 매개변수 | RAM | 언어 | 품질 |
+|-------|-----------|-----|-----------|---------|
+|`qwen2.5:1.5b`| 1.5B | 2GB | 29 | 기본 |
+|`qwen2.5:0.5b`| 0.5B | 1GB | 29 | 기본 |
+|`gemma3:1b`| 1B | 1.5GB | 다수 | 기본 |
+|`llama3.2:1b`| 1B | 2GB | 8 | 기본 |
+
+::: tip 다국어를 위한 Qwen
+Qwen2.5는 한국어, 일본어, 중국어 및 모든 주요 유럽 언어를 포함하여 29개 언어를 지원합니다. 영어가 아닌 번역 작업의 경우, Qwen이 종종 최고의 경량 선택입니다.
+:::
+
+### 모델 다운로드
+
+```bash
+# List available models
+ollama list
+
+# Recommended for translation (14B+)
+ollama pull qwen2.5:14b   # Best multilingual (29 languages)
+ollama pull qwen2.5:32b   # Higher quality, needs 32GB RAM
+ollama pull llama3.1:8b   # Good quality, lighter
+
+# Lightweight options (may have quality issues)
+ollama pull qwen2.5:7b    # Better quality than 3B
+ollama pull llama3.2      # Good for English-centric docs
+
+# Other options
+ollama pull mistral-nemo
+```
+
+## 구성
+
+### 환경 변수
+
+```bash
+# Default server URL (optional, this is the default)
+export OLLAMA_BASE_URL=http://localhost:11434
+
+# Custom server location
+export OLLAMA_BASE_URL=http://192.168.1.100:11434
+```
+
+### 구성 파일
+
+```json
+{
+  "provider": {
+    "name": "ollama",
+    "model": "qwen2.5:14b",
+    "baseUrl": "http://localhost:11434"
+  },
+  "translation": {
+    "qualityThreshold": 75,
+    "maxIterations": 3
+  }
+}
+```
+
+::: tip
+로컬 모델의 경우, 과도한 개선 반복을 피하기 위해 더 낮은 `qualityThreshold`(75)를 권장합니다. 안정적인 결과를 위해서는 14B+ 모델을 사용하세요.
+:::
+
+### 모델별 설정
+
+다양한 문서 유형에 대해:
+
+```bash
+# Best quality - qwen2.5:14b (recommended for most use cases)
+llm-translate file api-spec.md -s en -t ko \
+  --provider ollama \
+  --model qwen2.5:14b \
+  --quality 75
+
+# Higher quality with 32B model (requires 32GB RAM)
+llm-translate file legal-doc.md -s en -t ko \
+  --provider ollama \
+  --model qwen2.5:32b \
+  --quality 80
+
+# README files - lighter model for simple content
+llm-translate file README.md -s en -t ko \
+  --provider ollama \
+  --model llama3.2 \
+  --quality 70
+
+# Large documentation sets - balance speed and quality
+llm-translate dir ./docs ./docs-ko -s en -t ko \
+  --provider ollama \
+  --model qwen2.5:14b \
+  --parallel 2
+```
+
+## 성능 최적화
+
+### GPU 가속
+
+#### NVIDIA (Linux/Windows)
+
+```bash
+# Check CUDA availability
+nvidia-smi
+
+# Ollama automatically uses CUDA if available
+ollama serve
+```
+
+#### Apple Silicon (macOS)
+
+Metal 가속은 M1/M2/M3/M4 Mac에서 자동으로 적용됩니다.
+
+```bash
+# Check GPU usage
+sudo powermetrics --samplers gpu_power
+```
+
+### 메모리 관리
+
+```bash
+# Set GPU memory limit (Linux with NVIDIA)
+CUDA_VISIBLE_DEVICES=0 ollama serve
+
+# Limit CPU threads
+OLLAMA_NUM_PARALLEL=2 ollama serve
+```
+
+### 대용량 문서 최적화
+
+```bash
+# Reduce chunk size for memory-constrained systems
+llm-translate file large-doc.md --target ko \
+  --provider ollama \
+  --chunk-size 512
+
+# Disable caching to reduce memory usage
+llm-translate file doc.md --target ko \
+  --provider ollama \
+  --no-cache
+
+# Single-threaded processing for stability
+llm-translate dir ./docs ./docs-ko --target ko \
+  --provider ollama \
+  --parallel 1
+```
+
+## 원격 Ollama 서버
+
+### 서버 설정
+
+서버 머신에서:
+
+```bash
+# Allow external connections
+OLLAMA_HOST=0.0.0.0 ollama serve
+```
+
+::: warning 보안
+신뢰할 수 있는 네트워크에서만 Ollama를 노출하세요. 원격 접근을 위해서는 VPN 또는 SSH 터널 사용을 고려하세요.
+:::
+
+### SSH 터널 (권장)
+
+```bash
+# Create secure tunnel to remote server
+ssh -L 11434:localhost:11434 user@remote-server
+
+# Then use as normal
+llm-translate file doc.md --target ko --provider ollama
+```
+
+### 직접 연결
+
+```bash
+# Set remote server URL
+export OLLAMA_BASE_URL=http://remote-server:11434
+
+llm-translate file doc.md --target ko --provider ollama
+```
+
+### 팀 서버용 Docker Compose
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  ollama:
+    image: ollama/ollama
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    restart: unless-stopped
+
+volumes:
+  ollama_data:
+```
+
+## 문제 해결
+
+### 연결 오류
+
+```
+Error: Cannot connect to Ollama server at http://localhost:11434
+```
+
+**해결책:**
+
+```bash
+# Check if Ollama is running
+curl http://localhost:11434/api/tags
+
+# Start the server
+ollama serve
+
+# Check for port conflicts
+lsof -i :11434
+```
+
+### 모델을 찾을 수 없음
+
+```
+Error: Model "llama3.2" not found. Pull it with: ollama pull llama3.2
+```
+
+**해결책:**
+
+```bash
+# Download the model
+ollama pull llama3.2
+
+# Verify installation
+ollama list
+```
+
+### 메모리 부족
+
+```
+Error: Out of memory. Try a smaller model or reduce chunk size.
+```
+
+**해결책:**
+
+```bash
+# Use a smaller model
+ollama pull llama3.2:1b
+llm-translate file doc.md --target ko --provider ollama --model llama3.2:1b
+
+# Reduce chunk size
+llm-translate file doc.md --target ko --provider ollama --chunk-size 256
+
+# Close other applications to free RAM
+```
+
+### 느린 성능
+
+**해결책:**

package/docs/ko/guide/prompt-caching.md

@@ -0,0 +1,221 @@
+# 프롬프트 캐싱
+
+::: info 번역
+모든 비영어 문서는 Claude Sonnet 4를 사용하여 자동으로 번역됩니다.
+:::
+
+프롬프트 캐싱은 반복되는 콘텐츠에 대해 API 비용을 최대 90%까지 절감하는 비용 최적화 기능입니다.
+
+## 작동 원리
+
+문서를 번역할 때 프롬프트의 특정 부분은 일정하게 유지됩니다:
+
+- **시스템 지침**: 번역 규칙 및 가이드라인
+- **용어집**: 도메인별 전문 용어
+
+이러한 내용은 캐시되어 여러 청크에서 재사용되므로 상당한 비용을 절약할 수 있습니다.
+
+```
+Request 1 (First Chunk):
+┌─────────────────────────────────┐
+│ System Instructions (CACHED)    │ ◀─ Written to cache
+├─────────────────────────────────┤
+│ Glossary (CACHED)              │ ◀─ Written to cache
+├─────────────────────────────────┤
+│ Source Text (NOT cached)       │
+└─────────────────────────────────┘
+
+Request 2+ (Subsequent Chunks):
+┌─────────────────────────────────┐
+│ System Instructions (CACHED)    │ ◀─ Read from cache (90% off)
+├─────────────────────────────────┤
+│ Glossary (CACHED)              │ ◀─ Read from cache (90% off)
+├─────────────────────────────────┤
+│ Source Text (NOT cached)       │
+└─────────────────────────────────┘
+```
+
+## 비용 영향
+
+### 가격 (Claude)
+
+| 토큰 유형 | 비용 배수 |
+|------------|-----------------|
+| 일반 입력 | 1.0x |
+| 캐시 쓰기 | 1.25x (첫 사용) |
+| 캐시 읽기 | 0.1x (이후) |
+| 출력 | 1.0x |
+
+### 계산 예시
+
+500토큰 용어집이 있는 10청크 문서의 경우:
+
+**캐싱 없이:**
+```
+10 chunks × 500 glossary tokens = 5,000 tokens
+```
+
+**캐싱 사용:**
+```
+First chunk: 500 × 1.25 = 625 tokens (cache write)
+9 chunks: 500 × 0.1 × 9 = 450 tokens (cache read)
+Total: 1,075 tokens (78% savings)
+```
+
+## 요구사항
+
+### 최소 토큰 임계값
+
+프롬프트 캐싱에는 최소 콘텐츠 길이가 필요합니다:
+
+| 모델 | 최소 토큰 |
+|-------|---------------|
+| Claude Haiku 4.5 | 4,096 |
+| Claude Haiku 3.5 | 2,048 |
+| Claude Sonnet | 1,024 |
+| Claude Opus | 1,024 |
+
+이 임계값 미만의 콘텐츠는 캐시되지 않습니다.
+
+### 제공자 지원
+
+| 제공자 | 캐싱 지원 |
+|----------|-----------------|
+| Claude | ✅ 완전 지원 |
+| OpenAI | ✅ 자동 |
+| Ollama | ❌ 사용 불가 |
+
+## 구성
+
+Claude의 경우 캐싱이 기본적으로 활성화됩니다. 비활성화하려면:
+
+```bash
+llm-translate file doc.md -o doc.ko.md --target ko --no-cache
+```
+
+또는 설정에서:
+
+```json
+{
+  "provider": {
+    "name": "claude",
+    "caching": false
+  }
+}
+```
+
+## 캐시 성능 모니터링
+
+### CLI 출력
+
+```
+✓ Translation complete
+  Cache: 890 read / 234 written (78% hit rate)
+```
+
+### 상세 모드
+
+```bash
+llm-translate file doc.md -o doc.ko.md --target ko --verbose
+```
+
+청크별 캐시 통계를 표시합니다:
+
+```
+[Chunk 1/10] Cache: 0 read / 890 written
+[Chunk 2/10] Cache: 890 read / 0 written
+[Chunk 3/10] Cache: 890 read / 0 written
+...
+```
+
+### 프로그래밍 방식 접근
+
+```typescript
+const result = await engine.translateFile({
+  input: 'doc.md',
+  output: 'doc.ko.md',
+  targetLang: 'ko',
+});
+
+console.log(result.metadata.tokensUsed);
+// {
+//   input: 5000,
+//   output: 6000,
+//   cacheRead: 8000,
+//   cacheWrite: 1000
+// }
+```
+
+## 캐시 효율성 극대화
+
+### 1. 일관된 용어집 사용
+
+동일한 용어집 콘텐츠 = 동일한 캐시 키
+
+```bash
+# Good: Same glossary for all files
+llm-translate dir ./docs ./docs-ko --target ko --glossary glossary.json
+
+# Less efficient: Different glossary per file
+llm-translate file a.md --glossary a-glossary.json
+llm-translate file b.md --glossary b-glossary.json
+```
+
+### 2. 관련 파일 일괄 처리
+
+캐시는 약 5분간 지속됩니다. 파일을 함께 처리하세요:
+
+```bash
+# Efficient: Sequential processing shares cache
+llm-translate dir ./docs ./docs-ko --target ko
+```
+
+### 3. 크기별로 파일 정렬
+
+캐시를 워밍하기 위해 큰 파일부터 시작하세요:
+
+```bash
+# Cache is populated by first file, reused by rest
+llm-translate file large-doc.md ...
+llm-translate file small-doc.md ...
+```
+
+### 4. 전략적으로 큰 용어집 사용
+
+큰 용어집일수록 캐싱의 이점이 더 큽니다:
+
+| 용어집 크기 | 캐시 절약 |
+|---------------|---------------|
+| 100 토큰 | ~70% |
+| 500 토큰 | ~78% |
+| 1000+ 토큰 | ~80%+ |
+
+## 문제 해결
+
+### 캐시가 작동하지 않음
+
+**증상:**`cacheRead` 토큰이 보고되지 않음
+
+**원인:**
+1. 최소 임계값 미만의 콘텐츠
+2. 요청 간 콘텐츠 변경
+3. 캐시 TTL 만료 (5분)
+
+**해결책:**
+- 용어집 + 시스템 프롬프트가 최소 토큰을 초과하는지 확인
+- 파일을 연속적으로 빠르게 처리
+- 디버깅을 위해 상세 모드 사용
+
+### 높은 캐시 쓰기 비용
+
+**증상:** 예상보다 많은 `cacheWrite`
+
+**원인:**
+1. 많은 고유 용어집
+2. 파일 처리 간격이 너무 긺
+3. 실행 간 캐시 무효화
+
+**해결책:**
+- 용어집 통합
+- 일괄 처리 사용
+- 5분 창 내에서 처리