로컬 LLM으로 프라이빗 AI 코딩 에이전트 구축하기 — Ollama + Python 완전 가이드

저희 팀은 금융권 고객사 프로젝트를 맡으면서 난관에 부딪혔어요. 보안정책상 코드를 외부로 전송할 수 없는데, 레거시 리팩토링 작업량이 3개월치로 쌓여 있었거든요. Claude API를 쓰고 싶었지만 사내망 밖으로 코드 한 줄도 못 내보내는 상황. 그때 Ollama로 로컬 에이전트를 돌려봤더니 인터넷 차단 환경에서도 코드 생성·리뷰 자동화가 가능했습니다.

이 글을 읽고 나면 여러분도 클라우드 API 비용 없이 자기 컴퓨터에서 코딩 에이전트를 돌릴 수 있어요. Ollama 설치부터 Python 에이전트 루프 연결, 메모리 최적화까지 제가 직접 테스트한 방법을 단계별로 보여드릴게요.

준비물

시작하기 전에 필요한 것들이에요:

• 하드웨어: 최소 16GB RAM 권장. 저는 32GB 환경에서 테스트했어요. GPU는 선택사항인데, NVIDIA GPU(8GB VRAM 이상)가 있으면 추론 속도가 3~5배 빨라집니다.
• 운영체제: macOS, Linux, Windows(WSL2) 모두 가능. 저는 Ubuntu 22.04 환경에서 진행했습니다.
• Python: 3.8 이상. 가상환경 설정 추천.
• Ollama: 로컬 LLM 런타임. 공식 사이트에서 설치 파일을 받을 수 있어요.

Ollama는 어떻게 설치하고 모델은 어떻게 고르나요?

Ollama 설치

Linux 환경이라면 한 줄로 끝나요:

curl -fsSL https://ollama.com/install.sh | sh

설치가 끝나면 ollama --version으로 확인해보세요. 저는 0.1.29 버전이 설치됐어요. macOS는 DMG 파일로, Windows는 WSL2에서 같은 명령어로 설치하면 됩니다.

코드 특화 모델 다운로드

코딩 에이전트용으로는 세 가지 모델을 테스트했어요:

• codellama:7b: 7GB, 가장 가볍지만 복잡한 코드 생성은 약함
• deepseek-coder:6.7b: 6.7GB, 코드 완성 정확도 좋음
• qwen2.5-coder:7b: 7GB, 다국어 코드 이해 강점

제 경험상 deepseek-coder:6.7b가 Python 코드 생성과 리팩토링에서 가장 나았어요. 다운로드는 이렇게:

ollama pull deepseek-coder:6.7b

첫 다운로드는 6.7GB라서 5분 정도 걸렸어요. ollama list로 설치된 모델을 확인할 수 있습니다. 폐쇄망이나 인터넷 차단 환경이라면 외부 접속 가능한 PC에서 모델을 먼저 받아두고, ~/.ollama/models/ 디렉토리를 USB로 옮겨 쓸 수 있어요. 한 번만 다운받으면 그 뒤론 인터넷 없이 계속 사용 가능합니다.

Python 에이전트 루프는 어떻게 만드나요?

Python SDK 설치와 첫 연결

먼저 Ollama Python SDK를 설치하세요:

pip install ollama

간단한 테스트 코드를 작성해볼게요:

import ollama

response = ollama.chat(
    model='deepseek-coder:6.7b',
    messages=[{
        'role': 'user',
        'content': 'Python으로 피보나치 수열 함수를 작성해줘'
    }]
)
print(response['message']['content'])

이걸 실행하면 → 로컬에서 LLM이 돌면서 피보나치 함수 코드를 생성해줘요. 첫 추론은 CPU 환경에서 15초 정도 걸렸는데, GPU로 돌리니 3초로 줄었습니다.

에이전트 루프 구축

단순 질의응답이 아니라 '도구를 사용하는 에이전트'로 만들려면 루프가 필요해요. 제가 만든 간단한 버전이에요:

import ollama
import json

def execute_code(code):
    """코드를 실행하고 결과를 반환"""
    try:
        exec_globals = {}
        exec(code, exec_globals)
        return {"status": "success", "output": str(exec_globals.get('result', 'No result'))}
    except Exception as e:
        return {"status": "error", "message": str(e)}

def agent_loop(task, max_iterations=5):
    messages = [{
        'role': 'system',
        'content': '너는 Python 코드를 작성하고 실행할 수 있는 에이전트야. 결과를 JSON 형식으로 반환해.'
    }, {
        'role': 'user',
        'content': task
    }]
    
    for i in range(max_iterations):
        response = ollama.chat(
            model='deepseek-coder:6.7b',
            messages=messages
        )
        
        assistant_msg = response['message']['content']
        messages.append({'role': 'assistant', 'content': assistant_msg})
        
        # 코드 블록 추출
        if '```python' in assistant_msg:
            code = assistant_msg.split('```python')[1].split('```')[0].strip()
            result = execute_code(code)
            
            messages.append({
                'role': 'user',
                'content': f"실행 결과: {json.dumps(result, ensure_ascii=False)}"
            })
            
            if result['status'] == 'success':
                return result
        else:
            break
    
    return {"status": "incomplete", "iterations": i+1}

# 실행 예시
result = agent_loop("1부터 100까지 소수를 찾아줘")
print(result)

이 코드를 돌리면 → 에이전트가 코드를 생성하고 → 실행하고 → 결과를 받아서 다시 판단하는 루프가 돌아요. 소수 찾기 태스크는 2 iteration 만에 성공했습니다.

메모리와 성능 튜닝

기본 설정으로 돌리면 메모리를 8GB 가까이 먹어요. 배치 크기를 줄이면 메모리를 절약할 수 있습니다:

response = ollama.chat(
    model='deepseek-coder:6.7b',
    messages=messages,
    options={
        'num_ctx': 2048,  # 컨텍스트 길이 (기본 4096)
        'num_gpu': 1,     # GPU 레이어 수
        'num_thread': 8   # CPU 스레드 수
    }
)

num_ctx를 2048로 줄이니 메모리 사용량이 4.5GB로 떨어졌어요. 대신 긴 코드 맥락을 처리할 때는 정확도가 약간 떨어집니다.

흔한 실수와 해결법

모델 크기를 무시하고 13B 모델을 선택

처음엔 "크면 좋겠지" 싶어서 codellama:13b를 받았어요. 그런데 16GB RAM 환경에서는 스왑을 계속 쓰면서 추론이 2분씩 걸렸습니다. 7B 모델로 바꾸니 15초로 줄었어요. 하드웨어에 맞는 모델을 고르는 게 중요해요.

프롬프트에 "반드시 실행 가능한 코드만 출력"을 안 넣음

에이전트가 설명과 코드를 섞어서 내놓으면 파싱이 깨져요. 시스템 프롬프트에 "코드 블록은 ```python으로 감싸고, 다른 설명은 최소화"라고 명시하니 성공률이 70%에서 90%로 올랐습니다.

GPU 메모리 부족 에러

RuntimeError: CUDA out of memory가 뜨면 num_gpu 값을 줄이세요. 0으로 설정하면 CPU 전용 모드로 돌아가는데, 느리지만 안정적이에요.

Ollama 서비스가 자동 시작되지 않음

초기 설치 후 ollama list 명령어가 "connection refused" 에러를 내뱉었어요. Ollama 데몬이 안 떠 있었던 거죠. ollama serve를 수동으로 실행하거나, 시스템 서비스로 등록해야 합니다. Linux에서는 systemctl enable ollama로 부팅 시 자동 시작하도록 설정했더니 해결됐어요. macOS는 앱을 한 번만 실행하면 백그라운드로 계속 돌아가니까 문제없었습니다.

다음 단계

로컬 LLM 에이전트를 돌려봤다면 이제 도구를 확장해보세요. 파일 읽기·쓰기, 웹 검색, 데이터베이스 연결 등을 추가하면 완전한 자동화 에이전트가 됩니다. 출처: Ollama 공식 문서 및 Python SDK에서 더 많은 고급 옵션을 확인할 수 있어요.

폐쇄망 환경이라면 모델을 한 번만 다운받아두면 인터넷 없이도 계속 쓸 수 있다는 게 가장 큰 장점이에요. API 요금 걱정 없이 마음껏 실험해보세요.

자주 묻는 질문

Q. GPU 없이도 쓸 수 있나요?

A. 네, CPU만으로도 돌아가요. 다만 7B 모델 기준 추론 속도가 GPU 대비 3~5배 느립니다. 16GB RAM 환경에서 CPU 전용으로 돌려봤는데, 간단한 코드 생성은 15~20초 정도 걸렸어요.

Q. 어떤 모델이 한국어 코드 주석 생성에 좋나요?

A. qwen2.5-coder:7b가 한국어 주석과 변수명 생성에서 가장 나았어요. deepseek-coder는 영어 주석이 기본이라 프롬프트에 "한국어로 주석 작성"을 명시해야 합니다.

Q. API 호출과 비교해서 정확도는 어떤가요?

A. GPT-4나 Claude Sonnet 대비 복잡한 아키텍처 설계는 약해요. 하지만 단순 함수 작성, 버그 수정, 코드 리팩토링 수준에서는 70~80% 정도 쓸 만했습니다. 프라이버시가 중요한 사내 도구 개발에는 충분하다고 봐요.

Q. 모델 업데이트는 어떻게 하나요?

A. ollama pull <모델명> 명령어를 다시 실행하면 최신 버전을 받아요. 기존 모델은 자동으로 대체됩니다. 버전 관리가 필요하면 <모델명>:<태그> 형식으로 특정 버전을 고정할 수 있어요.