exAichatbot_agent/exAiChatBot-chatbot2.0-agent/old_docs/OFFLINE_QUICKSTART.md

# 오프라인 배포 빠른 가이드

## 🚀 3단계로 끝내는 오프라인 배포

### 현재 PC (온라인 환경)

```bash
# 1. 패키징 스크립트 실행
cd /Users/parkjiwon/src/rag
./create-offline-package.sh

# 2. 완료! 패키지 위치 확인
ls -lh ~/rag-offline-package.tar.gz
```

**결과**: `~/rag-offline-package.tar.gz` (약 2.5GB)

---

### 오프라인 서버 (Linux)

```bash
# 1. 패키지 압축 해제
tar -xzf rag-offline-package.tar.gz
cd rag-offline-package

# 2. 배포 실행 (자동)
./deploy.sh
```

**끝!** 프롬프트를 따라 .env 설정만 하면 완료됩니다.

---

## 📦 패키지 내용

```
rag-offline-package.tar.gz (2.5GB)
└── rag-offline-package/
    ├── rag-api.tar          (1.2GB) - API 서비스 이미지
    ├── rag-batch.tar        (1.1GB) - 배치 작업 이미지
    ├── deploy.sh            - 자동 배포 스크립트
    ├── README.txt           - 간단 설명
    └── rag-project/         - 전체 소스 코드
        ├── docker-compose.yml
        ├── scripts/
        ├── data/
        └── env.template
```

---

## ⚡ 빠른 명령어 참조

### 온라인 PC

```bash
# 패키지 생성
./create-offline-package.sh

# USB로 복사
cp ~/rag-offline-package.tar.gz /Volumes/USB/

# 또는 SCP 전송 (일시적 연결 가능 시)
scp ~/rag-offline-package.tar.gz user@server:/home/user/
```

### 오프라인 서버

```bash
# 압축 해제 및 배포
tar -xzf rag-offline-package.tar.gz
cd rag-offline-package
./deploy.sh

# 배포 후 확인
cd rag-project
docker-compose ps
curl http://localhost:28012/health
```

---

## 🔧 수동 배포 (deploy.sh 없이)

자동 스크립트를 사용하고 싶지 않다면:

```bash
cd rag-offline-package

# 1. 이미지 로드
docker load -i rag-api.tar
docker load -i rag-batch.tar

# 2. 프로젝트 설정
cd rag-project
cp env.template .env
vi .env  # LLM_HOST, TEI_EMBED_HOST 등 수정

# 3. 배치 작업
docker-compose up preprocess embed index

# 4. API 시작
docker-compose up -d api

# 5. 확인
curl http://localhost:28012/health
```

---

## 📋 체크리스트

### 온라인 PC
- [ ] `./create-offline-package.sh` 실행
- [ ] `~/rag-offline-package.tar.gz` 생성 확인
- [ ] 파일을 USB/SCP로 전송

### 오프라인 서버
- [ ] Docker 설치됨 (`docker --version`)
- [ ] 패키지 압축 해제
- [ ] `./deploy.sh` 실행
- [ ] .env 파일 설정 (LLM/TEI 서버 IP)
- [ ] 배치 작업 완료
- [ ] API 서비스 실행 중
- [ ] 헬스체크 성공

---

## ❓ FAQ

**Q: 패키지 크기가 너무 큰데 분할할 수 있나요?**
```bash
# 1GB 단위로 분할
split -b 1G ~/rag-offline-package.tar.gz rag-pkg.part

# 서버에서 합치기
cat rag-pkg.part* > rag-offline-package.tar.gz
```

**Q: Docker가 없는 오프라인 서버는 어떻게 하나요?**
- Docker 설치 파일도 함께 가져가야 합니다
- 또는 서버에 Docker가 사전 설치되어 있어야 합니다

**Q: .env 파일에서 무엇을 수정해야 하나요?**
```bash
# 필수 3가지
LLM_HOST=192.168.1.100        # LLM 서버 IP
TEI_EMBED_HOST=192.168.1.100  # TEI 서버 IP
TEI_RERANK_HOST=192.168.1.100 # TEI 서버 IP
```

**Q: 배포 후 테스트는 어떻게 하나요?**
```bash
# 헬스체크
curl http://localhost:28012/health

# 실제 질의
curl -X POST http://localhost:28012/ask \
  -H "Content-Type: application/json" \
  -d '{"query":"충전 카드 구매 방법"}'
```

---

## 📞 문제 해결

### 이미지 로드 실패
```bash
# 무결성 확인
tar -tzf rag-offline-package.tar.gz > /dev/null
echo $?  # 0이면 정상

# 디스크 공간 확인
df -h  # 5GB 이상 필요
```

### 외부 API 연결 실패
```bash
# 네트워크 확인
ping 192.168.1.100

# 포트 접근 확인
telnet 192.168.1.100 16000
curl http://192.168.1.100:16000/health
```

### 컨테이너 시작 실패
```bash
# 로그 확인
cd rag-project
docker-compose logs api

# 재시작
docker-compose restart api
```

---

## 🔗 상세 문서

- 전체 가이드: `OFFLINE_DEPLOYMENT.md`
- 배포 가이드: `DEPLOYMENT.md`
- RAG 파이프라인: `RAG_PIPELINE.md`
- 내부 LLM 가이드: `INTERNAL_LLM_GUIDE.md`

---

**마지막 업데이트**: 2024-12-30