Windows 11 환경에서 동작하는 로컬 AI 코드 생성 도구

Windows 11 환경에서 AI 기반 코드 생성 도구 개발 환경을 설치하고, 샘플 실행까지 할 수 있는 개발자용 가이드입니다.  

 

로컬 PC에 GPU가 장착되어 있고, Docker와 Python 기반 개발 환경을 구성할 수 있는 조건을 전제로 합니다.

 🧑‍💻 Windows 11 기반 AI 코드 생성 도구 개발자 용 가이드

- Windows 11 + NVIDIA GPU (RTX 30xx/40xx 권장) 환경에서
- 자연어 → 코드 생성 기능 구현
- FastAPI 기반 API 서버 + React 프론트엔드
- GGUF 형식의 오픈소스 LLM (예: Code Llama, OpenChatCode 등)


사전 요구사항

| 항목 | 설명 |
|------|------|
| OS | Windows 11 Pro 이상 |
| GPU | NVIDIA RTX 시리즈 (최소 16GB VRAM 권장) |
| CUDA 드라이버 | 최신 버전 설치 (CUDA 12.1 추천) |
| Python | Python 3.10 이상 |
| Docker Desktop | 설치 필요 (WSL2 활성화 필수) |
| Git | GitHub 리포지토리 클론용 |


1단계: 개발 환경 설정

1.1 WSL2 및 Linux 컨테이너 활성화

# WSL2 설치

wsl --install -d Ubuntu

# WSL2 확인

wsl --list --verbose

> Docker Desktop은 반드시 "Use the WSL2 based engine" 옵션을 활성화해야 합니다.


1.2 Docker Desktop 설치

🔗 다운로드 링크: [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/)

설치 후 Docker Desktop 실행하여 WSL2 통합 상태 확인


1.3 Python 가상 환경 설정
# Python 설치 확인

python --version

# pip 업그레이드

python -m pip install --upgrade pip

# 가상 환경 생성

python -m venv venv
.\venv\Scripts\activate

# 필요한 패키지 설치

pip install fastapi uvicorn torch transformers accelerate

## 🤖 2단계: AI 모델 준비 (GGUF 형식 사용)

### 2.1 GGUF 형식의 Code LLM 다운로드

- 추천 모델:
  - `OpenChatCode-13B` (가벼움)
  - `CodeLlama-70B-Instruct-GGUF` (정확도 높음, VRAM 24GB 필요)

#### 예시: HuggingFace CLI를 이용한 모델 다운로드
# HuggingFace CLI 설치

pip install huggingface-cli

# GGUF 모델 다운로드 예시
huggingface-cli download imoneoi/openchat-3.5-13b-20240320 --filename "ggml-model-Q4_K_M.gguf"

> 다운로드된 파일 경로: `C:\Users\YourName\models\ggml-model-Q4_K_M.gguf`

🏗️ 3단계: 로컬 AI 서버 구성 (llama.cpp 기반)

3.1 llama.cpp 설치 및 빌드

방법 1: 이미 빌드된 Windows 바이너리 사용

🔗 공식 GitHub Releases: [https://github.com/ggerganov/llama.cpp/releases](https://github.com/ggerganov/llama.cpp/releases)

- `llama-cpp-server.exe` 다운로드 후 적절한 폴더에 저장

#### 방법 2: 직접 빌드 (선택적)

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
mkdir build && cd build
cmake .. -DLLAMA_CUBLAS=on
cmake --build . --config Release

3.2 GGUF 모델 로딩 및 서버 실행
llama.cpp 서버 실행 (GPU 사용)

llama-cpp-server.exe -m C:\models\ggml-model-Q4_K_M.gguf -ngl 9999

> `-ngl 9999`: 전체 모델을 GPU에 로드 (VRAM 여유가 있을 경우)

서버 기본 포트: `8080`


4단계: FastAPI 기반 백엔드 서버 구성

4.1 디렉토리 구조
/code-assistant/
├── backend/
│   ├── main.py
│   └── requirements.txt
├── models/
│   └── ggml-model-Q4_K_M.gguf
└── docker-compose.yml

4.2 `main.py` 예시
python

from fastapi import FastAPI
import httpx

app = FastAPI()

LLM_SERVER_URL = "http://localhost:8080/completion"

@app.post("/generate")
async def generate_code(prompt: str):
    async with httpx.AsyncClient() as client:
        response = await client.post(LLM_SERVER_URL, json={
            "prompt": prompt,
            "temperature": 0.2,
            "max_tokens": 200
        })
        return response.json()

4.3 requirements.txt

fastapi>=0.95.0
uvicorn>=0.21.1
httpx>=0.24.0

5단계: 서버 실행 및 테스트

powershell

# FastAPI 서버 실행
uvicorn backend.main:app --host 0.0.0.0 --port 8000

 

> FastAPI 문서: `http://localhost:8000/docs`

### POST 요청 예시:
json

{
  "prompt": "Write a Python function to calculate the factorial of a number."
}

6단계: React 기반 UI 개발 시작

6.1 Create React App 생성
powershell

npx create-react-app code-assistant-ui
cd code-assistant-ui
npm install axios monaco-editor

6.2 간단한 코드 에디터 UI 예시 (`App.js`)
jsx

import React, { useState } from 'react';
import axios from 'axios';
import Editor from '@monaco-editor/react';

function App() {
  const [prompt, setPrompt] = useState('');
  const [code, setCode] = useState('');

  const handleGenerate = async () => {
    const res = await axios.post('http://localhost:8000/generate', { prompt });
    setCode(res.data.content);
  };

  return (
    <div style={{ padding: 20 }}>
      <h2>AI Code Generator</h2>
      <textarea value={prompt} onChange={(e) => setPrompt(e.target.value)} />
      <button onClick={handleGenerate}>Generate Code</button>
      <Editor height="500px" defaultLanguage="python" value={code} />
    </div>
  );
}

export default App;

📦 7단계: Docker Compose로 통합 배포

```yaml
# docker-compose.yml
version: '3.8'

services:
  llm-server:
    image: ggerganov/llama.cpp
    container_name: llm-server
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    command: ["--server", "-m", "/models/ggml-model-Q4_K_M.gguf", "-ngl", "9999"]

  api-server:
    build: ./backend
    ports:
      - "8000:8000"
    depends_on:
      - llm-server

  web:
    build: ./code-assistant-ui
    ports:
      - "3000:3000"
    depends_on:
      - api-server


## 📁 8단계: 전체 디렉토리 구조 정리

/code-assistant/
├── backend/
│   ├── main.py
│   └── requirements.txt
├── code-assistant-ui/
│   ├── src/App.js
│   └── package.json
├── models/
│   └── ggml-model-Q4_K_M.gguf
├── docker-compose.yml
└── README.md

- GPU 메모리 부족 시 `-ngl` 값을 낮추어 CPU/GPU 혼합 사용 가능
- 모델 크기 선택 시 자신의 GPU VRAM에 맞게 조정 (예: Q2_K / Q4_0 등)
- 보안 강화를 위해 JWT 인증 추가 가능
- MariaDB/Oracle 연동 시 SQLAlchemy 또는 JDBC 사용

/code-assistant/
├── backend/
│   ├── main.py
│   └── requirements.txt
├── code-assistant-ui/
│   ├── src/App.js
│   └── package.json
├── models/
│   └── ggml-model-Q4_K_M.gguf
├── docker-compose.yml
└── README.md


다음 단계 제안
- “Docker Compose로 모든 서비스 일괄 실행”
- “React UI에 Monaco Editor 확장 기능 추가”
- “JWT 기반 인증 모듈 추가”
- “MariaDB 연동 샘플 코드 제공”