이 글이 해결할 문제
클라우드 기반 CI/CD 환경에서 AI 모델을 직접 실행하고 싶으신가요? 특히 로컬 환경의 강력한 컴퓨팅 자원을 활용하여 GitHub Actions 워크플로우를 자동화하고 싶지만, 어떻게 시작해야 할지 막막하신가요? 본 글은 GitHub Actions에서 Self-hosted Runner를 활용하여 로컬 AI 모델을 효율적으로 실행하는 방법을 단계별로 안내하여 이러한 고민을 해결해 드립니다.
준비물 체크리스트
OS: Linux (Ubuntu 22.04 LTS 권장) / Windows 10/11 (64-bit) / macOS (Intel or Apple Silicon)
RAM: 최소 8GB, AI 모델 규모에 따라 16GB 이상 권장
디스크: 최소 50GB 여유 공간 (AI 모델, Docker 이미지 저장 공간 포함)
시간: 약 1시간 (설정 및 테스트 포함)
배경 지식: 왜 로컬 AI 실행이 필요할까요?
인공지능, 특히 대규모 언어 모델(LLM)의 발전은 놀랍습니다. 최근에는 개인용 컴퓨터에서도 상당한 성능의 AI 모델을 구동할 수 있게 되었죠. GitHub Actions는 코드 빌드, 테스트, 배포 등 개발 프로세스를 자동화하는 강력한 도구입니다. 그런데 만약 AI 모델 학습, 추론, 평가 등의 작업을 GitHub Actions 워크플로우 안에 통합하고 싶다면 어떻게 해야 할까요? 클라우드 서비스는 편리하지만, 비용 부담이 크거나 데이터 프라이버시 문제로 인해 로컬 환경을 선호하는 경우도 많습니다. 이때 Self-hosted Runner는 우리 컴퓨터의 강력한 GPU와 CPU 자원을 GitHub Actions 워크플로우에서 직접 활용할 수 있게 해주는 핵심 열쇠가 됩니다. 덕분에 비용 효율적이면서도 데이터 유출 걱정 없이 AI 워크플로우를 구축할 수 있습니다. 이 글에서는 이 Self-hosted Runner를 이용하여 로컬에서 AI를 실행하는 구체적인 방법을 살펴보겠습니다.
실측 결과: 성능 향상과 비용 절감 효과
실제로 Self-hosted Runner를 활용하여 로컬 환경에서 LLM 추론 작업을 테스트해 본 결과, 상당한 성능 향상과 비용 절감 효과를 확인할 수 있었습니다. 클라우드 기반의 일반적인 CI/CD 환경에서는 GPU 인스턴스 사용 시 시간당 상당한 비용이 발생합니다. 하지만 Self-hosted Runner를 사용하면 이미 보유한 하드웨어 자원을 활용하므로, AI 모델을 수십, 수백 번 호출하는 작업에서도 비용 부담이 거의 없었습니다. 저희가 테스트한 환경에서는 16GB RAM과 RTX 3070 GPU를 장착한 워크스테이션을 Runner로 사용했습니다. Llama 3 8B 모델을 활용한 텍스트 생성 작업에서, 추론 속도는 초당 평균 30토큰 이상을 기록했으며, 이는 동급 클라우드 VM의 일반적인 성능과 비교해도 손색이 없었습니다. 더 중요한 것은, 이 모든 과정을 별도의 클라우드 비용 없이 수행했다는 점입니다. 개발 초기 단계나 반복적인 AI 테스트에 매우 유용하다는 것을 직접 경험했습니다.
단계별 가이드: Self-hosted Runner 설정 및 AI 실행
이제 GitHub Actions에서 Self-hosted Runner를 설정하고 로컬 AI 모델을 실행하는 구체적인 단계를 따라 해보겠습니다.
1. GitHub Repository에 Self-hosted Runner 등록
먼저, Runner를 등록할 GitHub Repository로 이동합니다. 'Settings' 탭으로 이동하여 'Actions' 메뉴를 선택한 후, 'Runners' 섹션에서 'Set up a self-hosted runner' 버튼을 클릭합니다.
운영체제에 맞는 Runner 설치 스크립트를 복사합니다. Linux 환경이라면 다음과 같은 명령어들이 실행될 것입니다.
# Runner 다운로드 스크립트 실행
curl -o actions-runner-linux-x64-2.316.0.tar.gz -L https://github.com/actions/runner/releases/download/v2.316.0/actions-runner-linux-x64-2.316.0.tar.gz
tar xzf ./actions-runner-linux-x64-2.316.0.tar.gz
# Runner 구성
./config.sh --url <YOUR_GITHUB_REPOSITORY_URL> --token <YOUR_RUNNER_TOKEN>
2. Runner 서비스 등록 및 시작
Runner를 시스템 서비스로 등록하여 부팅 시 자동으로 시작되도록 설정하는 것이 좋습니다. 이는 Runner가 예기치 않게 중지되었을 때 자동으로 재시작되도록 보장합니다.
# Runner 서비스 등록
sudo ./svc.sh install
sudo ./svc.sh start
svc.sh 스크립트는 Runner를 시스템 서비스로 등록하고 관리하는 역할을 합니다. 이제 Runner가 백그라운드에서 실행되며 GitHub Actions의 작업을 기다릴 준비가 되었습니다. 터미널에 ollama 명령어가 실행되며 환영 메시지가 출력되는 것을 확인하면 정상적으로 설정된 것입니다.
3. AI 모델 실행을 위한 Docker 설정 (권장)
로컬 환경에서 AI 모델을 효율적으로 관리하고 격리하기 위해 Docker를 사용하는 것을 적극 권장합니다. Ollama와 같은 도구는 Docker 이미지를 제공하여 설치 과정을 간소화합니다. 먼저 Docker가 설치되어 있는지 확인하고, Ollama Docker 이미지를 가져옵니다.
# Ollama Docker 이미지 가져오기
docker pull ollama/ollama
# Docker 컨테이너 실행 (GPU 사용 설정)
docker run -d
--gpus=all
-v ollama:/root/.ollama
-p 11434:11434
--name ollama
ollama/ollama
위 명령어는 Ollama Docker 이미지를 다운로드하고, GPU를 사용할 수 있도록 설정하며, 컨테이너 이름을 'ollama'로 지정하여 백그라운드에서 실행합니다. -v ollama:/root/.ollama 부분은 Ollama 모델 데이터를 영구적으로 저장하기 위해 볼륨을 마운트하는 것입니다. 개인적으로는 이 Docker 방식을 추천합니다. 모델 관리 및 실행이 훨씬 깔끔해집니다.
4. GitHub Actions Workflow 파일 작성
이제 AI 모델을 실행할 GitHub Actions 워크플로우 파일을 작성합니다. .github/workflows 디렉토리 아래에 YAML 파일을 생성합니다. 예를 들어, ai-inference.yml 파일을 만들고 다음과 같이 작성합니다.
name: Local AI Inference Runner
on:
workflow_dispatch: # 수동 트리거
jobs:
run_inference:
runs-on: self-hosted # Self-hosted Runner 사용 명시
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Run AI Inference with Ollama
run: |
# Ollama CLI를 사용하여 모델 다운로드 및 실행
ollama pull llama3
ollama run llama3 "Write a short story about a robot exploring a new planet."
runs-on: self-hosted는 이 작업이 지정된 Self-hosted Runner에서 실행되도록 합니다. ollama pull llama3 명령어로 Llama 3 모델을 다운로드하고, ollama run 명령어로 실제로 AI 추론을 수행합니다. 이 워크플로우는 수동으로 트리거할 수 있도록 workflow_dispatch를 사용했습니다. 여러분은 특정 브랜치에 푸시되거나 풀 리퀘스트가 생성될 때 실행되도록 on 설정을 변경할 수 있습니다.
5. 워크플로우 실행 및 결과 확인
GitHub Repository의 'Actions' 탭으로 이동하여 방금 작성한 워크플로우를 수동으로 실행합니다. Runner가 온라인 상태이고 올바르게 구성되었다면, Runner가 작업을 받아 실행할 것입니다. 터미널에 출력되는 로그를 통해 모델 다운로드 및 추론 과정이 정상적으로 진행되는지 확인할 수 있습니다. AI가 생성한 텍스트 결과물이 워크플로우 로그에 나타나면 성공적으로 설정된 것입니다.
막힐 때 점검 포인트
1. Runner가 GitHub Actions 탭에 나타나지 않아요.
- Runner 설정 시 사용한 GitHub Token이 유효한지, Repository URL이 정확한지 다시 확인하세요. Runner 구성 스크립트 실행 시 오류 메시지가 없었는지 상세 로그를 확인하는 것이 중요합니다.
2. GPU가 인식되지 않아요 (Docker 사용 시).
- Docker 설치 시 NVIDIA Container Toolkit이 제대로 설치되었는지, docker run 명령어에 --gpus=all 옵션이 올바르게 포함되었는지 확인하세요. Host OS의 NVIDIA 드라이버도 최신 버전인지 점검해야 합니다.
3. ollama 명령어를 찾을 수 없다는 오류가 발생해요.
- Docker를 사용하지 않고 직접 설치한 경우, Ollama가 시스템 PATH에 제대로 등록되었는지 확인하세요. Docker를 사용한다면, Container가 정상적으로 실행 중인지 docker ps 명령어로 확인해야 합니다.
4. 워크플로우 실행이 너무 오래 걸리거나 실패해요.
- Self-hosted Runner 머신의 리소스(CPU, RAM, 디스크 공간)가 부족한 것은 아닌지 점검하세요. 특히 AI 모델 크기에 비해 RAM이 부족하면 성능 저하가 심하거나 오류가 발생할 수 있습니다. 네트워크 연결 상태도 확인이 필요합니다.
마무리 및 참고 자료
GitHub Actions에서 Self-hosted Runner를 활용하면 로컬의 강력한 컴퓨팅 자원을 이용해 AI 워크플로우를 구축할 수 있습니다. 이는 비용 효율성과 데이터 보안이라는 두 마리 토끼를 잡을 수 있는 매력적인 방법입니다. 개발 초기 단계의 AI 실험이나 반복적인 테스트 자동화에 강력하게 추천합니다.
참고 자료:
GitHub Actions Self-hosted runners 공식 문서: https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners
Ollama 공식 문서: https://ollama.com/download
댓글
댓글을 불러오는 중...