FastAPI와 Stable Diffusion을 사용한 고성능 이미지 변환 API입니다. 기존 이미지와 텍스트 프롬프트를 통해 새로운 스타일의 이미지를 생성할 수 있는 RESTful API를 제공합니다.
- 🚀 주요 기능
- 📋 시스템 요구사항
- 🛠️ 설치 및 실행
- ☁️ AWS 인스턴스 설정 가이드
- 📚 API 사용법
- 📖 API 문서
- ⚙️ 설정 및 환경 변수
- 🔧 개발 및 기여
- 🛠️ 문제 해결
- Image-to-Image: 기존 이미지를 기반으로 한 이미지 변환 (img2img)
- 텍스트 프롬프트: 상세한 텍스트 설명을 통한 이미지 스타일 변경
- RESTful API: 간단하고 직관적인 API 인터페이스
- GPU 가속: NVIDIA GPU를 활용한 빠른 이미지 생성
- Docker 지원: 컨테이너화된 배포로 쉬운 설치 및 관리
- 자동 문서화: Swagger UI 및 ReDoc을 통한 API 문서
- GPU: NVIDIA GPU (최소 8GB VRAM 권장)
- RAM: 최소 16GB (32GB 권장)
- 저장공간: 최소 10GB (모델 파일 포함)
- Docker: 20.10 이상
- Docker Compose: 1.29 이상
- NVIDIA Container Toolkit: GPU 지원을 위해 필요
- CUDA: 11.8 이상 (Docker 이미지에 포함)
- Ubuntu 18.04 이상
- CentOS 7 이상
- Windows 10/11 (WSL2 + Docker Desktop)
- NVIDIA Container Toolkit 설치 (GPU 지원을 위해 필요)
# Ubuntu/Debian
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker- GPU 확인
nvidia-smigit clone https://github.com/eunsoni/stable-diffusion-api.git
cd stable-diffusion-api이 API는 사전 훈련된 Stable Diffusion 1.5 모델을 사용합니다.
모델 파일들이 /mnt/efs/saved_sd15 경로에 있어야 합니다.
# 모델 다운로드 (선택사항 - 자동으로 다운로드됨)
python download_models.py# 백그라운드에서 실행
docker-compose up -d --build
# 로그 확인
docker-compose logs -f
# 서비스 중지
docker-compose down새로운 AWS 인스턴스에서 EFS를 사용하여 이 프로젝트를 실행하는 전체 설정 과정입니다.
# Docker 설치를 위한 필수 패키지를 설치합니다
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release
# Docker의 공식 GPG 키를 추가합니다
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
# Docker의 공식 저장소를 추가합니다
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Docker 엔진과 관련 패키지를 설치합니다
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Docker가 제대로 설치되었는지 확인합니다
sudo systemctl status docker
# sudo 없이 Docker 명령어를 실행하려면 현재 사용자를 docker 그룹에 추가합니다
sudo usermod -aG docker $USER
newgrp docker# NVIDIA 드라이버 자동 설치
sudo apt install -y ubuntu-drivers-common
sudo ubuntu-drivers autoinstall
sudo reboot
# 재접속 후 드라이버 확인
nvidia-smi# NVIDIA Container Toolkit 저장소 추가
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
&& curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
| sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
&& curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list \
| sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
| sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
# NVIDIA Container Toolkit 설치
sudo apt update
sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
# GPU 인식 테스트 (선택사항)
docker run --rm --gpus all nvidia/cuda:12.3.2-base-ubuntu22.04 nvidia-smi# NFS 클라이언트 설치
sudo apt update
sudo apt install -y nfs-common
# EFS 마운트 디렉토리 생성
sudo mkdir -p /mnt/efs
# EFS 마운트 (실제 EFS ID 예시)
sudo mount -t nfs4 -o nfsvers=4.1 fs-040df8c9ef7b96af3.efs.ap-northeast-2.amazonaws.com:/ /mnt/efs
# 정상 마운트 확인
df -h인스턴스 재부팅 시 EFS를 자동으로 마운트하려면:
# fstab 파일 편집
sudo nano /etc/fstab
# 아래 라인 추가 (실제 EFS ID로 변경)
fs-040df8c9ef7b96af3.efs.ap-northeast-2.amazonaws.com:/ /mnt/efs nfs4 defaults,_netdev 0 0가장 간단한 방법은 사전 빌드된 Docker 이미지를 사용하는 것입니다:
# Docker 이미지 실행 (자동으로 Docker Hub에서 다운로드)
docker run --rm -it --gpus all \
-v /mnt/efs/saved_sd15:/mnt/efs/saved_sd15 \
-e CUDA_VISIBLE_DEVICES=0 \
-p 8000:8000 \
eunsunhub/stable-diffusion-api:efs
# 백그라운드 실행
docker run -d --name stable-diffusion-api --gpus all \
-v /mnt/efs/saved_sd15:/mnt/efs/saved_sd15 \
-e CUDA_VISIBLE_DEVICES=0 \
-p 8000:8000 \
--restart unless-stopped \
eunsunhub/stable-diffusion-api:efs
# 컨테이너 상태 확인
docker ps
# 로그 확인
docker logs -f stable-diffusion-api소스코드를 수정하거나 커스터마이징이 필요한 경우:
# 프로젝트 클론
git clone https://github.com/eunsoni/stable-diffusion-api.git
cd stable-diffusion-api
# Docker Compose로 실행
docker-compose up -d --build
# 서비스 상태 확인
docker-compose psAPI 서버에 외부에서 접근하려면 보안 그룹에서 포트 8000을 허용해야 합니다:
- 포트: 8000
- 프로토콜: TCP
- 소스: 0.0.0.0/0 (모든 IP 허용) 또는 특정 IP 범위
python -m venv venv
source venv/bin/activate # Linux/Mac
# venv\Scripts\activate # Windowspip install -r requirements.txtpython main.py서버가 정상적으로 시작되면 http://localhost:8000에서 API에 접근할 수 있습니다.
- Base URL:
http://localhost:8000 - 이미지 변환:
POST /generate
이 API는 Image-to-Image (img2img) 기능만 지원합니다. 기존 이미지를 업로드하고 텍스트 프롬프트를 제공하면 새로운 스타일의 이미지로 변환됩니다.
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
prompt |
string | 필수 | 이미지 생성을 위한 텍스트 프롬프트 |
image |
file | 필수 | 변환할 기본 이미지 (img2img) |
기본 이미지 변환
curl -X POST "http://localhost:8000/generate" \
-H "Content-Type: multipart/form-data" \
-F "prompt=a beautiful sunset over mountains, oil painting style" \
-F "image=@input_image.jpg" \
--output generated_image.png복잡한 프롬프트 예제
curl -X POST "http://localhost:8000/generate" \
-H "Content-Type: multipart/form-data" \
-F "prompt=professional portrait photo of a cyberpunk character, neon lights, detailed face, 4k, high quality" \
-F "image=@portrait.jpg" \
--output cyberpunk_portrait.pngimport requests
# 기본 사용법
def generate_image(prompt, image_path):
url = "http://localhost:8000/generate"
with open(image_path, 'rb') as f:
files = {'image': f}
data = {'prompt': prompt}
response = requests.post(url, files=files, data=data)
if response.status_code == 200:
with open('generated_image.png', 'wb') as output:
output.write(response.content)
print("이미지가 성공적으로 생성되었습니다!")
else:
print(f"오류 발생: {response.status_code}")
# 사용 예제
generate_image(
prompt="a serene landscape with mountains and lake, impressionist style",
image_path="input.jpg"
)const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');
async function generateImage(prompt, imagePath) {
const form = new FormData();
form.append('prompt', prompt);
form.append('image', fs.createReadStream(imagePath));
try {
const response = await axios.post('http://localhost:8000/generate', form, {
headers: form.getHeaders(),
responseType: 'stream'
});
response.data.pipe(fs.createWriteStream('generated_image.png'));
console.log('이미지가 성공적으로 생성되었습니다!');
} catch (error) {
console.error('오류 발생:', error.message);
}
}
// 사용 예제
generateImage(
"a futuristic city skyline at night, cyberpunk style",
"input.jpg"
);성공 응답 (200 OK)
- Content-Type:
image/png - Body: 생성된 이미지 바이너리 데이터
오류 응답
{
"detail": "오류 메시지"
}[원하는 스타일] + [품질 키워드] + [분위기/조명] + [기술적 세부사항]
"oil painting style, highly detailed, warm lighting, masterpiece"- 유화 스타일로 변환"watercolor painting, soft colors, artistic, high quality"- 수채화 스타일로 변환"cyberpunk style, neon lights, futuristic, detailed, 4k"- 사이버펑크 스타일로 변환"pencil sketch, black and white, artistic drawing, detailed"- 연필 스케치로 변환"anime style, colorful, detailed face, high quality"- 애니메이션 스타일로 변환
highly detailed,4k,8k,masterpiece,high qualityprofessional photography,studio lighting,dramatic lightingartstation,concept art,digital art,fine art
서버 실행 후 다음 URL에서 대화형 API 문서를 확인할 수 있습니다:
-
Swagger UI: http://localhost:8000/docs
- 대화형 API 테스트 인터페이스
- 실시간으로 API 호출 테스트 가능
-
ReDoc: http://localhost:8000/redoc
- 깔끔한 API 문서 뷰
- 상세한 스키마 정보 제공
| 변수명 | 기본값 | 설명 |
|---|---|---|
CUDA_VISIBLE_DEVICES |
0 |
사용할 GPU 디바이스 번호 |
MODEL_PATH |
/mnt/efs/saved_sd15 |
모델 파일 저장 경로 |
HOST |
0.0.0.0 |
서버 호스트 주소 |
PORT |
8000 |
서버 포트 번호 |
docker-compose.yml 파일을 수정하여 설정을 변경할 수 있습니다:
version: '3.8'
services:
stable-diffusion-api:
build: .
ports:
- "8000:8000" # 포트 변경 시 수정
environment:
- CUDA_VISIBLE_DEVICES=0 # GPU 설정
runtime: nvidia
volumes:
- /your/model/path:/mnt/efs/saved_sd15 # 모델 경로 변경
restart: unless-stopped- 개발 의존성 설치
pip install -r requirements.txt
pip install pytest black flake8- 코드 포맷팅
black .
flake8 .- 테스트 실행
pyteststable-diffusion-api/
├── main.py # FastAPI 애플리케이션 메인 파일
├── download_models.py # 모델 다운로드 스크립트
├── requirements.txt # Python 의존성
├── Dockerfile # Docker 이미지 빌드 설정
├── docker-compose.yml # Docker Compose 설정
└── README.md # 프로젝트 문서
| 패키지 | 버전 | 용도 |
|---|---|---|
fastapi |
0.104.1 | 웹 API 프레임워크 |
torch |
2.2.2 | 딥러닝 프레임워크 |
diffusers |
0.34.0 | Stable Diffusion 파이프라인 |
transformers |
4.54.1 | 트랜스포머 모델 |
Pillow |
10.1.0 | 이미지 처리 |
# 메모리 효율적인 설정
pipe.enable_memory_efficient_attention()
pipe.enable_xformers_memory_efficient_attention()여러 이미지를 동시에 생성할 때는 배치 처리를 고려하세요:
# 여러 프롬프트 동시 처리
prompts = ["prompt1", "prompt2", "prompt3"]
images = pipe(prompts, num_inference_steps=50)CUDA out of memory
해결방법:
- 이미지 해상도 낮추기 (512x512 권장)
- 배치 크기 줄이기
torch.cuda.empty_cache()사용
FileNotFoundError: Model files not found
해결방법:
- 모델 경로 확인:
/mnt/efs/saved_sd15 download_models.py실행하여 모델 다운로드
Permission denied
해결방법:
sudo usermod -aG docker $USER
newgrp dockercould not select device driver with capabilities: [[gpu]]
해결방법:
- NVIDIA Container Toolkit 재설치
- Docker 재시작:
sudo systemctl restart docker
# Docker 로그 확인
docker-compose logs -f
# 특정 컨테이너 로그
docker logs <container_id># 실시간 GPU 상태 확인
watch -n 1 nvidia-smi
# GPU 메모리 사용량 확인
nvidia-smi --query-gpu=memory.used,memory.total --format=csv- 응답 시간 측정
- 동시 요청 처리 능력 테스트
- 메모리 사용량 모니터링
이 프로젝트에 기여하고 싶으시다면:
- 이 저장소를 Fork하세요
- 새로운 기능 브랜치를 생성하세요 (
git checkout -b feature/AmazingFeature) - 변경사항을 커밋하세요 (
git commit -m 'Add some AmazingFeature') - 브랜치에 Push하세요 (
git push origin feature/AmazingFeature) - Pull Request를 열어주세요
- 코드 스타일: Black 포맷터 사용
- 테스트: 새로운 기능에 대한 테스트 추가
- 문서화: README 및 코드 주석 업데이트
- 이슈 리포트: GitHub Issues
- 기능 요청: GitHub Discussions
- 이메일: your-email@example.com
이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.
- Stability AI - Stable Diffusion 모델 제공
- Hugging Face - Diffusers 라이브러리 및 모델 호스팅
- FastAPI - 훌륭한 웹 프레임워크
⭐ 이 프로젝트가 도움이 되었다면 스타를 눌러주세요!