DEV Community: matias yoon

로컬 LLM 셋업 가이드 (v50)

matias yoon — Tue, 26 May 2026 07:42:44 +0000

로컬 LLM 셋업 가이드 (v50)

1. 개요 및 전제 조건

로컬 LLM(대형 언어 모델)은 클라우드 서비스 의존성에서 벗어나 개인 정보 보호와 성능 개선을 목표로 합니다. 이 가이드는 Linux 기반 시스템에서 최적의 로컬 LLM 환경을 구축합니다.

전제 조건:

Linux 시스템 (Ubuntu 20.04 이상 권장)
GPU: NVIDIA GTX 3060 이상 (CUDA 지원)
RAM: 최소 16GB, 권장 32GB 이상
저장 공간: 최소 50GB 여유 공간

2. 프레임워크 비교

프레임워크	장점	단점
llama.cpp	빠른 성능, CPU/ GPU 모두 지원, 최소 의존성	복잡한 설치 과정, 직접 컴파일 필요
Ollama	간단한 설치, 커뮤니티 지원, GUI 포함	메모리 사용량이 높음
vLLM	초고속 추론, 대규모 모델 처리	복잡한 설정, 최신 CUDA 필요
LocalAI	REST API 기반, 다양한 모델 지원	빌드가 필요하며 상대적으로 오래 걸림

추천: 단순하고 빠른 구동을 원한다면 llama.cpp를 사용하세요. 빠른 프로토타이핑과 높은 성능을 원한다면 Ollama 또는 vLLM을 고려하세요.

3. 설치 단계 (llama.cpp 기반)

3.1 의존성 설치

sudo apt update
sudo apt install -y build-essential git cmake python3-pip
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

3.2 llama.cpp 설치

cd /opt
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
make clean
make -j$(nproc)

3.3 모델 다운로드 및 변환

# 모델 다운로드
mkdir -p models
cd models
wget https://huggingface.co/TheBloke/Mistral-7B-v0.1-GGUF/resolve/main/mistral-7b-v0.1.Q4_K_M.gguf

3.4 실행 테스트

cd /opt/llama.cpp
./main -m models/mistral-7b-v0.1.Q4_K_M.gguf -p "Hello, how are you?" --temp 0.7

4. 모델 선택 가이드

4.1 개발자용 모델

모델	메모리 요구량	추천 사례	양자화
Mistral-7B-v0.1	4GB	일반 텍스트 생성	Q4_K_M
Llama-3-8B	8GB	코드 생성, 복잡한 대화	Q5_K_M
Phi-3-mini	2GB	빠른 추론	Q4_K_M

4.2 실제 예제

# Mistral-7B 실행
./main -m models/mistral-7b-v0.1.Q4_K_M.gguf -p "Write a Python function to calculate factorial" --temp 0.3 -n 150

5. 양자화 유형 설명

5.1 Q4_K_M vs Q5_K_M

Q4_K_M: 4비트 양자화, 최대 압축률
Q5_K_M: 5비트 양자화, 정확도 향상

5.2 변환 명령어

# GGUF로 변환
python3 convert-hf-to-gguf.py /path/to/model --outtype q4_k_m --outfile model.Q4_K_M.gguf

5.3 성능 비교

# Q4_K_M vs Q5_K_M 성능 테스트
time ./main -m model.Q4_K_M.gguf -p "Test prompt" --temp 0.7 -n 100
time ./main -m model.Q5_K_M.gguf -p "Test prompt" --temp 0.7 -n 100

6. API 설정 및 통합

6.1 FastAPI 서버 구축

# server.py
from fastapi import FastAPI
from pydantic import BaseModel
import subprocess

app = FastAPI()

class PromptRequest(BaseModel):
    prompt: str
    model: str = "mistral-7b-v0.1.Q4_K_M.gguf"

@app.post("/generate")
async def generate_text(request: PromptRequest):
    cmd = f"./main -m models/{request.model} -p \"{request.prompt}\" --temp 0.7 -n 150"
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
    return {"response": result.stdout}

6.2 서버 실행

pip install fastapi uvicorn
uvicorn server:app --host 0.0.0.0 --port 8000

6.3 API 호출 예제

curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Explain quantum computing in simple terms"}'

7. 시스템 서비스 설정

7.1 systemd 서비스 파일 생성

sudo nano /etc/systemd/system/llm.service

[Unit]
Description=Local LLM Service
After=network.target

[Service]
Type=simple
User=developer
WorkingDirectory=/opt/llama.cpp
ExecStart=/opt/llama.cpp/main -m /opt/llama.cpp/models/mistral-7b-v0.1.Q4_K_M.gguf -p "Hello" --port 8080
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

7.2 서비스 시작

sudo systemctl daemon-reload
sudo systemctl enable llm
sudo systemctl start llm
sudo systemctl status llm

8. 모니터링 및 성능 튜닝

8.1 메모리 사용량 추적

# 실시간 모니터링
watch -n 1 nvidia-smi

# 메모리 사용량 확인
free -h

8.2 성능 최적화 설정

# CPU 스레드 설정
./main -m models/mistral-7b-v0.1.Q4_K_M.gguf -p "Test" --temp 0.7 -n 100 -t 8

# GPU 메모리 최적화
./main -m models/mistral-7b-v0.1.Q4_K_M.gguf -p "Test" --temp 0.7 -n 100 --ctx-size 2048 --gpu-layers 30

8.3 로그 수집

# 로그 저장
sudo journalctl -u llm -f > /var/log/llm.log

# 성능 로그
./main -m models/mistral-7b-v0.1.Q4_K_M.gguf -p "Test" --temp 0.7 -n 100 -v

9. 실제 사용 사례

9.1 코드 생성 예제

# Python 코드 생성
./main -m models/mistral-7b-v0.1.Q4_K_M.gguf -p "Write a Python script that reads CSV and displays statistics" --temp 0.3 -n 200

9.2 문제 해결 예제

# 디버깅 도우미
./main -m models/mistral-7b-v0.1.Q4_K_M.gguf -p "I'm getting 'ModuleNotFoundError' for pandas. How to fix it?" --temp 0.5 -n 150

9.3 성능 기준

작업	시간	메모리
단순 텍스트 생성	0.2초	3GB
코드 생성	0.8초	4GB
복잡한 질문 답변	1.2초	5GB

10. 고급 설정 및 문제 해결

📥 Get the full guide on Gumroad: https://gumroad.com/l/auto ($7)

LangGraph 워크플로우 템플릿 (v50)

matias yoon — Tue, 26 May 2026 07:28:01 +0000

LangGraph 워크플로우 템플릿 (v50)

실용적인 LangChain/LangGraph 워크플로우 템플릿 가이드

Python 개발자들을 위한 AI 에이전트 구축 솔루션

1. LangGraph 아키텍처 개요

LangGraph는 LangChain과 함께 사용되는 상태 기반 워크플로우 프레임워크입니다. 다음과 같은 핵심 구성 요소로 작동합니다:

노드 (Nodes): 워크플로우의 각 단계
엣지 (Edges): 노드 간의 전이 조건
상태 (State): 모든 노드 간 공유되는 데이터 구조
체크포인트 (Checkpointing): 실패 시 복구를 위한 상태 저장

from typing import Annotated
from langgraph.graph import StateGraph, END
from langchain_core.messages import BaseMessage

# 상태 정의
class GraphState(TypedDict):
    messages: Annotated[list[BaseMessage], operator.add]
    user_input: str
    context: str

# 워크플로우 생성
workflow = StateGraph(GraphState)

2. 템플릿 1: 단순 RAG 에이전트 (검색 → 생성 → 검증)

문제: RAG 시스템에서 검색, 생성, 검증 단계를 잘 통합하는 것이 어렵습니다.

from langchain_core.tools import tool
from langchain_core.prompts import PromptTemplate
from langchain_openai import ChatOpenAI
from langchain_community.vectorstores import Chroma
from langchain_core.runnables import RunnablePassthrough

# 검색 노드
def retrieve_node(state):
    question = state["user_input"]
    vectorstore = Chroma(persist_directory="chroma_db")
    retriever = vectorstore.as_retriever()
    docs = retriever.invoke(question)
    return {"context": "\n".join([doc.page_content for doc in docs])}

# 생성 노드
def generate_node(state):
    prompt = PromptTemplate.from_template(
        "Context: {context}\n\nQuestion: {user_input}\n\nAnswer:"
    )
    llm = ChatOpenAI(model="gpt-4")
    chain = prompt | llm
    response = chain.invoke(state)
    return {"messages": [response]}

# 검증 노드
def validate_node(state):
    # 간단한 검증 로직 (실제 구현은 더 복잡)
    if len(state["messages"][0].content) < 10:
        return {"messages": [state["messages"][0]]}  # 재시도
    return {"messages": [state["messages"][0]]}

# 워크플로우 구성
workflow = StateGraph(GraphState)
workflow.add_node("retrieve", retrieve_node)
workflow.add_node("generate", generate_node)
workflow.add_node("validate", validate_node)

# 엣지 정의
workflow.add_edge("retrieve", "generate")
workflow.add_edge("generate", "validate")
workflow.add_edge("validate", END)

# 시작 노드
workflow.set_entry_point("retrieve")

3. 템플릿 2: 다중 도구 에이전트 (계획 → 실행 → 관찰 → 결정)

문제: 여러 도구를 순차적으로 실행하고 상태를 관리하는 것이 복잡합니다.

from typing import List
from langchain_core.tools import Tool
from langchain_core.pydantic_v1 import BaseModel, Field

# 도구 정의
class SearchInput(BaseModel):
    query: str = Field(description="검색어")

class CalculatorInput(BaseModel):
    expression: str = Field(description="수학 표현식")

# 검색 도구
@tool("search")
def search_tool(query: str) -> str:
    return f"검색 결과: {query}"

# 계산 도구
@tool("calculator")
def calculator_tool(expression: str) -> str:
    try:
        result = eval(expression)
        return f"계산 결과: {result}"
    except:
        return "계산 오류"

# 계획 노드
def plan_node(state):
    # 사용자 요청을 기반으로 작업 계획 생성
    plan = [
        {"action": "search", "input": state["user_input"]},
        {"action": "calculator", "input": "2+2"}
    ]
    return {"plan": plan, "current_action": 0}

# 실행 노드
def execute_node(state):
    plan = state["plan"]
    current = state["current_action"]

    if current >= len(plan):
        return {"messages": [f"모든 작업 완료"]}

    action = plan[current]
    tool_map = {"search": search_tool, "calculator": calculator_tool}

    # 도구 실행
    tool = tool_map[action["action"]]
    result = tool.invoke(action["input"])

    return {
        "messages": [result],
        "current_action": current + 1
    }

# 관찰 노드
def observe_node(state):
    # 실행 결과를 분석하여 다음 단계 결정
    return {"messages": [f"관찰 결과: {state['messages'][-1]}"]}

# 결정 노드
def decide_node(state):
    if state["current_action"] >= len(state["plan"]):
        return "end"
    return "execute"

# 워크플로우 구성
workflow = StateGraph(GraphState)
workflow.add_node("plan", plan_node)
workflow.add_node("execute", execute_node)
workflow.add_node("observe", observe_node)
workflow.add_node("decide", decide_node)

# 엣지 정의
workflow.add_edge("plan", "execute")
workflow.add_edge("execute", "observe")
workflow.add_edge("observe", "decide")

# 조건부 엣지
def route_decision(state):
    if state["current_action"] >= len(state["plan"]):
        return "end"
    return "execute"

workflow.add_conditional_edges("decide", route_decision)
workflow.set_entry_point("plan")

4. 템플릿 3: 인간-중개 워크플로우 (일시정지 → 검토 → 계속)

문제: 인간의 판단이 필요한 AI 작업에서 인간과의 협업 흐름을 구현해야 합니다.

from typing import Literal
from langchain_core.messages import HumanMessage

# 일시정지 노드
def pause_node(state):
    # 사용자 검토를 위한 메시지 생성
    review_message = f"작업 완료: {state['messages'][-1].content}\n\n계속하시겠습니까? (y/n)"
    return {"messages": [HumanMessage(content=review_message)]}

# 검토 노드
def review_node(state):
    # 사용자 응답 처리
    user_response = state.get("user_response", "").lower()
    if user_response == "n":
        return {"messages": [HumanMessage(content="작업 취소")]}
    return {"messages": [HumanMessage(content="작업 재개")]}

# 계속 노드
def continue_node(state):
    return {"messages": [HumanMessage(content="계속 진행")]}

# 워크플로우 구성
workflow = StateGraph(GraphState)
workflow.add_node("start", lambda s: s)
workflow.add_node("work", lambda s: {"messages": [f"작업 중: {s['user_input']}"]})
workflow.add_node("pause", pause_node)
workflow.add_node("review", review_node)
workflow.add_node("continue", continue_node)

# 엣지 정의
workflow.add_edge("start", "work")
workflow.add_edge("work", "pause")
workflow.add_edge("pause", "review")

def route_review(state):
    user_response = state.get("user_response", "").lower()
    return "continue" if user_response == "y" else "end"

workflow.add_conditional_edges("review", route_review)
workflow.add_edge("continue", END)

workflow.set_entry_point("start")

5. 템플릿 5: 병렬 실행 에이전트 (분산 → 처리 → 집계)

문제: 여러 작업을 동시에 처리하고 결과를 통합하는 병렬 워크플로우가 필요합니다.


python
from concurrent.futures import ThreadPoolExecutor
import asyncio

# 분산 노드
def fan_out_node(state):
    # 여러 작업을 생성
    tasks = [
        {"task": "process_data", "input": "데이터1"},
        {"task": "process_data", "input": "데이터2"},
        {"task": "process_data", "input": "데이터3"}
    ]
    return {"tasks": tasks, "results": []}

# 처리 노드
def process_node(state):
    task = state["current_task"]
    # 실제 처리 로직
    result = f"처리 결과: {task['input']}"

    return {
        "results": state["results"] + [result],
        "current_task": None
    }

# 집계 노드
def aggregate_node(state):
    # 모든 결과를 집계
    aggregated = " | ".join(state["results"])
    return {"messages": [f"집계 결과: {aggregated}"]}

# 병렬 처리 워크플로우
workflow

---

📥 **Get the full guide on Gumroad**: https://gumroad.com/l/auto ($5)

터미널 AI 에이전트 구축 (v49)

matias yoon — Tue, 26 May 2026 07:13:17 +0000

터미널 AI 에이전트 구축 (v49)

개발자들을 위한 로컬 터미널 AI 에이전트 구축 가이드

개발자들은 점점 더 AI를 코드 작성에 통합하고 있습니다. 하지만 기존 도구들은 성능 저하, 비공개 데이터 문제, 느린 응답 속도 등의 문제를 가지고 있습니다. 이 가이드에서는 로컬에서 실행되는 빠르고 안전한 터미널 AI 에이전트를 구축하는 방법을 실습 중심으로 설명합니다.

1. CLI AI 에이전트 생태계 분석

주요 도구들

# Aider: GitHub Copilot과 유사한 기능
pip install aider

# Continue.dev: VSCode 확장에서 유래된 터미널 버전
npm install -g continue.dev

# OpenCode: 오픈소스 CLI AI 에이전트
git clone https://github.com/opencode/opencode.git

Aider vs Continue vs Custom

도구	장점	단점	성능
Aider	GitHub 통합, 코드 생성	API 속도 제한	⭐⭐⭐
Continue	VSCode 통합	클라우드 기반	⭐⭐
Custom	완전 제어	개발 시간 필요	⭐⭐⭐⭐

2. 로컬 LLM API 엔드포인트 설정

우리는 로컬 LLM 서버를 설정하여 데이터 보안과 속도 향상을 실현합니다.

# 1. Ollama 설치 (가장 간단한 방법)
curl -fsSL https://ollama.com/install.sh | sh

# 2. 모델 다운로드
ollama pull llama3
ollama pull codellama:7b

# 3. API 서버 시작
ollama serve

# 4. Python에서 API 호출 테스트
curl http://localhost:11434/api/generate -d '{
  "model": "llama3",
  "prompt": "Python으로 factorial 함수를 작성하세요"
}'

3. Python CLI 에이전트 구축

# smart_agent.py
import openai
import json
import subprocess
import sys
from typing import List, Dict, Any

class TerminalAIAgent:
    def __init__(self):
        self.client = openai.OpenAI(
            base_url="http://localhost:11434/v1",
            api_key="ollama"
        )
        self.system_prompt = """
        You are a senior Python developer. Your task is to help with code generation,
        debugging, and analysis. Always respond in JSON format with the following structure:
        {
            "action": "generate|analyze|fix",
            "content": "your response",
            "code_blocks": ["code1", "code2"]
        }
        """

    def get_file_context(self, filepath: str) -> str:
        """파일 내용을 가져와 컨텍스트로 활용"""
        try:
            with open(filepath, 'r') as f:
                return f.read()
        except Exception as e:
            return f"Error reading {filepath}: {str(e)}"

    def call_llm(self, user_prompt: str, context: str = "") -> Dict[str, Any]:
        """LLM 호출 함수"""
        full_prompt = f"{self.system_prompt}\n\nContext:\n{context}\n\nUser: {user_prompt}"

        response = self.client.chat.completions.create(
            model="llama3",
            messages=[
                {"role": "system", "content": self.system_prompt},
                {"role": "user", "content": full_prompt}
            ],
            temperature=0.3,
            response_format={"type": "json_object"}
        )

        return json.loads(response.choices[0].message.content)

# 실행 예시
if __name__ == "__main__":
    agent = TerminalAIAgent()
    result = agent.call_llm("Python으로 factorial 함수를 작성하세요")
    print(json.dumps(result, indent=2, ensure_ascii=False))

4. tmux와 통합

터미널 다중화기를 사용하여 AI 에이전트를 편리하게 사용합니다:

# tmux 설정
cat >> ~/.tmux.conf << EOF
bind-key C-a send-keys C-a
bind-key C-b send-keys C-b
set -g mouse on
EOF

# tmux 세션 생성 및 AI 에이전트 실행
tmux new-session -d -s ai_agent
tmux send-keys -t ai_agent 'python smart_agent.py' Enter

5. 사용자 정의 도구 개발

# tools.py - 사용자 정의 도구 집합
import subprocess
import os
from pathlib import Path

class CodeTools:
    @staticmethod
    def search_code(pattern: str, directory: str = ".") -> List[str]:
        """코드 검색"""
        try:
            result = subprocess.run([
                'find', directory, '-name', '*.py', '-exec', 'grep', '-l', pattern, '{}', '+'
            ], capture_output=True, text=True)
            return result.stdout.strip().split('\n') if result.stdout.strip() else []
        except Exception as e:
            return [f"Error: {str(e)}"]

    @staticmethod
    def get_git_status() -> str:
        """Git 상태 확인"""
        try:
            result = subprocess.run(['git', 'status', '--porcelain'], 
                                  capture_output=True, text=True)
            return result.stdout
        except Exception as e:
            return f"Git error: {str(e)}"

    @staticmethod
    def file_operations(operation: str, source: str, target: str = None) -> str:
        """파일 작업"""
        try:
            if operation == "copy":
                subprocess.run(['cp', source, target])
                return f"Copied {source} to {target}"
            elif operation == "move":
                subprocess.run(['mv', source, target])
                return f"Moved {source} to {target}"
            elif operation == "create":
                with open(target, 'w') as f:
                    f.write("")
                return f"Created {target}"
        except Exception as e:
            return f"Error: {str(e)}"

# 도구 사용 예시
tools = CodeTools()
print(tools.search_code("def main"))
print(tools.get_git_status())

6. 컨텍스트 윈도우 관리

대규모 코드베이스에서 성능 문제를 피하기 위해 컨텍스트 윈도우 관리:

# context_manager.py
class ContextWindowManager:
    def __init__(self, max_tokens: int = 4000):
        self.max_tokens = max_tokens
        self.context = []

    def add_file_context(self, filepath: str, max_lines: int = 50) -> str:
        """파일 컨텍스트 추가 - 최대 라인 수 제한"""
        try:
            with open(filepath, 'r') as f:
                lines = f.readlines()
                # 최대 라인 수 제한
                if len(lines) > max_lines:
                    lines = lines[:max_lines] + [f"... ({len(lines)-max_lines} more lines)"]

                content = ''.join(lines)
                self.context.append(f"File: {filepath}\n{content}")
                return content
        except Exception as e:
            return f"Error: {str(e)}"

    def get_context_str(self) -> str:
        """전체 컨텍스트 문자열 생성"""
        return '\n\n'.join(self.context)

    def trim_context(self) -> None:
        """컨텍스트 크기 조정"""
        total_length = sum(len(ctx) for ctx in self.context)
        while total_length > self.max_tokens and self.context:
            self.context.pop(0)
            total_length = sum(len(ctx) for ctx in self.context)

# 사용 예시
context_manager = ContextWindowManager(max_tokens=3000)
context_manager.add_file_context("main.py")
context_manager.add_file_context("utils.py")

7. 비용/성능 최적화

# 1. 모델 최적화
ollama pull llama3:8b
ollama pull codellama:7b

# 2. 추론 최적화
export OLLAMA_NUM_PARALLEL=1
export OLLAMA_MAX_LOADED_MODELS=1

# 3. 비용 절감을 위한 로컬 캐싱
mkdir -p ~/.cache/llm_cache


python
# performance_optimizer.py
import time
import psutil
from functools import wraps

def monitor_performance(func):
    """성능 모니터링 장식자"""
    @wraps(func)
    def wrapper(*args, **kwargs):
        start_time = time.time()
        start_memory = psutil.Process().memory_info().rss / 1024 / 1024

        result = func(*args, **kwargs)

        end_time = time.time()
        end_memory = psutil.Process().memory_info().rss / 1024 / 1024

        print(f"Execution time:

---

📥 **Get the full guide on Gumroad**: https://gumroad.com/l/auto ($5)

RAG 시스템 실전 구축 (v49)

matias yoon — Tue, 26 May 2026 06:58:31 +0000

RAG 시스템 실전 구축 (v49)

1. RAG 기초 개념

RAG(Retrieval-Augmented Generation)은 검색 기반 생성 모델로, LLM이 외부 문서를 검색하고 이를 기반으로 생성하는 방식입니다.

검색-증강-생성 루프

# 간단한 RAG 루프 구현
class SimpleRAG:
    def __init__(self, embedding_model, vector_db, llm):
        self.embedding_model = embedding_model
        self.vector_db = vector_db
        self.llm = llm

    def retrieve(self, query, k=5):
        # 1. 쿼리 임베딩
        query_embedding = self.embedding_model.encode(query)
        # 2. 벡터 DB에서 유사 문서 검색
        results = self.vector_db.search(query_embedding, k)
        return results

    def generate(self, query, context):
        # 3. 증강된 쿼리 생성
        prompt = f"Context: {context}\n\nQuestion: {query}"
        response = self.llm.generate(prompt)
        return response

    def process(self, query):
        # 전체 루프
        context = self.retrieve(query)
        answer = self.generate(query, context)
        return answer

2. 청킹 전략

1. 문맥 기반 청킹 (Semantic Chunking)

import numpy as np
from sentence_transformers import SentenceTransformer
from sklearn.cluster import KMeans

class SemanticChunker:
    def __init__(self, model_name="all-MiniLM-L6-v2"):
        self.model = SentenceTransformer(model_name)

    def chunk_document(self, text, min_chunk_size=100, max_chunk_size=500):
        # 문장 분리
        sentences = self._split_sentences(text)
        embeddings = self.model.encode(sentences)

        # 클러스터링을 통한 청킹
        chunks = self._cluster_chunks(sentences, embeddings, 
                                    min_chunk_size, max_chunk_size)
        return chunks

    def _split_sentences(self, text):
        import re
        sentences = re.split(r'[.!?]+', text)
        return [s.strip() for s in sentences if s.strip()]

    def _cluster_chunks(self, sentences, embeddings, min_size, max_size):
        # 클러스터링 기반 청킹
        n_clusters = max(1, len(sentences) // 5)
        kmeans = KMeans(n_clusters=n_clusters, random_state=42)
        labels = kmeans.fit_predict(embeddings)

        chunks = []
        current_chunk = []
        current_length = 0

        for i, (sentence, label) in enumerate(zip(sentences, labels)):
            if current_length + len(sentence) > max_size:
                if current_chunk:
                    chunks.append(' '.join(current_chunk))
                current_chunk = [sentence]
                current_length = len(sentence)
            else:
                current_chunk.append(sentence)
                current_length += len(sentence)

        if current_chunk:
            chunks.append(' '.join(current_chunk))

        return [chunk for chunk in chunks if len(chunk) >= min_size]

2. 재귀적 청킹 (Recursive Chunking)

class RecursiveChunker:
    def __init__(self, chunk_size=500, overlap=50):
        self.chunk_size = chunk_size
        self.overlap = overlap

    def chunk_text(self, text):
        chunks = []
        start = 0

        while start < len(text):
            end = min(start + self.chunk_size, len(text))
            chunk = text[start:end]

            # 오버랩 처리
            if start > 0:
                overlap_start = max(0, start - self.overlap)
                chunk = text[overlap_start:end]

            chunks.append(chunk)
            start = end - self.overlap

        return chunks

3. 에이전트 기반 청킹

class AgentChunker:
    def __init__(self, model):
        self.model = model

    def smart_chunk(self, text, context_length=1000):
        # 텍스트를 여러 단위로 분할하고 의미를 판단
        sentences = self._split_sentences(text)
        chunks = []
        current_chunk = []
        current_length = 0

        for sentence in sentences:
            if current_length + len(sentence) > context_length:
                if current_chunk:
                    chunks.append(' '.join(current_chunk))
                current_chunk = [sentence]
                current_length = len(sentence)
            else:
                current_chunk.append(sentence)
                current_length += len(sentence)

        if current_chunk:
            chunks.append(' '.join(current_chunk))

        return chunks

3. 임베딩 모델 선택 및 비교

모델 비교 클래스

import torch
from sentence_transformers import SentenceTransformer
from transformers import AutoTokenizer, AutoModel
import numpy as np

class EmbeddingComparison:
    def __init__(self):
        self.models = {
            'all-MiniLM-L6-v2': SentenceTransformer('all-MiniLM-L6-v2'),
            'all-mpnet-base-v2': SentenceTransformer('all-mpnet-base-v2'),
            'sentence-t5-base': SentenceTransformer('sentence-t5-base'),
            'gte-small': SentenceTransformer('sentence-t5-base')
        }

    def compare_models(self, texts, model_names):
        results = {}
        for name in model_names:
            model = self.models[name]
            embeddings = model.encode(texts)
            results[name] = {
                'mean_similarity': np.mean(
                    [np.dot(embeddings[i], embeddings[i+1]) 
                     for i in range(0, len(embeddings)-1, 2)]
                ),
                'embedding_dim': embeddings.shape[1],
                'latency': self._measure_latency(model, texts)
            }
        return results

    def _measure_latency(self, model, texts):
        import time
        start = time.time()
        model.encode(texts)
        return time.time() - start

# 사용 예시
comparator = EmbeddingComparison()
texts = ["This is a sample text.", "Another example text."]
results = comparator.compare_models(texts, ['all-MiniLM-L6-v2', 'all-mpnet-base-v2'])
print(results)

성능 기준

# 최적의 모델 선택
class OptimalEmbeddingSelector:
    def __init__(self, models_config):
        self.models_config = models_config

    def select_best_model(self, benchmark_data):
        scores = {}
        for model_name, config in self.models_config.items():
            # 점수 계산 (정확도, 속도, 메모리 사용량)
            score = (
                config['accuracy'] * 0.5 +
                (1/config['latency']) * 0.3 +
                (1/config['memory']) * 0.2
            )
            scores[model_name] = score

        return max(scores, key=scores.get)

4. 벡터 DB 비교

Chroma vs Qdrant vs pgvector


python
# Chroma 구현
import chromadb
from chromadb.config import Settings

class ChromaVectorDB:
    def __init__(self, collection_name="rag_collection"):
        self.client = chromadb.Client()
        self.collection = self.client.get_or_create_collection(collection_name)

    def add_documents(self, documents, embeddings, ids):
        self.collection.add(
            documents=documents,
            embeddings=embeddings,
            ids=ids
        )

    def search(self, query_embedding, k=5):
        results = self.collection.query(
            query_embeddings=[query_embedding],
            n_results=k
        )
        return results['documents'][0]

# Qdrant 구현
from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Filter, FieldCondition

class QdrantVectorDB:
    def __init__(self, host="localhost", port=6333, collection_name="rag_collection"):
        self.client = QdrantClient(host=host, port=port)
        self.collection_name = collection_name

        # 컬렉션 생성
        if not self.client.collection_exists(collection_name):
            self.client.recreate_collection(
                collection_name=collection_name,
                vectors_config=VectorParams(size=384, distance="Cosine")
            )

    def add_documents(self, documents, embeddings, ids):
        points = [
            {
                "id": id,
                "vector": embedding.tolist(),
                "payload": {"text": doc}
            }
            for id, doc, embedding in zip(ids, documents, embeddings)
        ]
        self.client.upsert(
            collection_name=self.collection_name,
            points=points
        )

    def search(self, query_embedding, k=5):
        results = self.client.search(
            collection_name=self.collection_name,
            query_vector=query_embedding.tolist(),
            limit=k
        )
        return [hit

---

📥 **Get the full guide on Gumroad**: https://gumroad.com/l/auto ($7)

로컬 LLM 셋업 가이드 (v49)

matias yoon — Tue, 26 May 2026 06:43:40 +0000

로컬 LLM 셋업 가이드 (v49)

1. 개요 및 사전 요구사항

로컬 LLM 실행은 AI 개발자에게 중요한 기술이 되고 있습니다. 이 가이드는 Linux 기반 시스템에서 로컬 LLM을 효율적으로 구축하고 운영하는 실용적인 방법을 제공합니다.

사전 요구사항:

OS: Ubuntu 22.04 LTS 이상
CPU: 최소 8코어, 권장 16코어 이상
RAM: 최소 32GB, 권장 64GB 이상
GPU: NVIDIA RTX 4090 이상 (CUDA 12.x 필요)
스토리지: SSD 최소 200GB (모델 파일 포함)

최소 성능 기준:

# RAM 확인
free -g
# CPU 확인
lscpu | grep "CPU(s):"
# GPU 확인
nvidia-smi

2. 프레임워크 비교: llama.cpp vs Ollama vs vLLM vs LocalAI

프레임워크	장점	단점	적합성
llama.cpp	최소 종속성, 직접 컴파일 가능	복잡한 설정 필요	전문 개발자
Ollama	쉬운 설치 및 관리, Docker 기반	GPU 최적화 제한	개발용, 테스트
vLLM	높은 성능, 멀티 GPU 지원	복잡한 구조, 메모리 요구량 높음	프로덕션
LocalAI	다중 모델 지원, REST API	리소스 소모 큼	실시간 서비스

3. 추천 설정: llama.cpp + Ollama 조합

llama.cpp 설치:

# 의존성 설치
sudo apt update
sudo apt install -y build-essential cmake git

# 소스 코드 클론 및 컴파일
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
make clean
make

# 테스트
./main -m ./models/7B/ggml-model-q4_0.bin -p "Hello, world!"

Ollama 설치:

# Ollama 설치 (Ubuntu)
curl -fsSL https://ollama.com/install.sh | sh

# 서비스 시작
sudo systemctl start ollama
sudo systemctl enable ollama

# 모델 다운로드
ollama pull llama3
ollama pull codellama:7b

4. 모델 선택 가이드

일반 목적 모델:

Llama3 8B: 일반적인 작업에 최적화
Phi-3 Mini: 빠른 추론 속도

코드 전용 모델:

CodeLlama 7B: 코드 생성 및 분석
StarCoder 15B: 다양한 프로그래밍 언어 지원

성능 기준:

# 모델 성능 테스트 (llama.cpp)
./main -m ./models/7B/ggml-model-q4_0.bin -p "Write a Python function to reverse a string" -n 200

# Ollama 성능 테스트
ollama run llama3 "Explain quantum computing in simple terms"

5. 양자화 유형 설명

Q4_K_M vs Q5_K_M:

Q4_K_M: 4비트 양자화, 50% 메모리 절약
Q5_K_M: 5비트 양자화, 25% 메모리 절약 + 높은 정확도

양자화 명령어:

# GGUF 포맷 변환
python convert-hf-to-gguf.py ./models/Llama-3-8B-Instruct/ --outtype q4_k_m --outfile ./models/Llama-3-8B-Instruct-q4_k_m.gguf

# 모델 병렬화
./llama-bench -m ./models/Llama-3-8B-Instruct-q4_k_m.gguf --parallel 8

6. API 설정 및 툴 통합

REST API 서버 실행:

# llama.cpp API 서버
./server -m ./models/Llama-3-8B-Instruct-q4_k_m.gguf -c 2048 --host 0.0.0.0 --port 1234

# Ollama API 통신
curl http://localhost:11434/api/generate -d '{
  "model": "llama3",
  "prompt": "Explain neural networks in simple terms",
  "stream": false
}'

VS Code 통합 설정:

// .vscode/settings.json
{
  "llm.server.url": "http://localhost:1234",
  "llm.model": "Llama-3-8B-Instruct-q4_k_m.gguf"
}

7. Systemd 서비스 설정 (24/7 운영)

서비스 파일 생성:

sudo nano /etc/systemd/system/llama-server.service

[Unit]
Description=LLM Server
After=network.target

[Service]
Type=simple
User=developer
WorkingDirectory=/home/developer/llama.cpp
ExecStart=/home/developer/llama.cpp/server -m /home/developer/models/Llama-3-8B-Instruct-q4_k_m.gguf -c 2048 --host 0.0.0.0 --port 1234
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

서비스 시작:

# 서비스 등록 및 시작
sudo systemctl daemon-reload
sudo systemctl enable llama-server
sudo systemctl start llama-server

# 상태 확인
sudo systemctl status llama-server

8. 모니터링 및 성능 튜닝

성능 모니터링:

# CPU/MEM 사용량
htop

# GPU 사용량
nvidia-smi -l 1

# 로그 모니터링
journalctl -u llama-server -f

성능 최적화:

# 메모리 최적화 실행
./main -m ./models/Llama-3-8B-Instruct-q4_k_m.gguf -c 2048 -n 128 --temp 0.7 --repeat_penalty 1.1

# 성능 벤치마크
./llama-bench -m ./models/Llama-3-8B-Instruct-q4_k_m.gguf -p 512 -n 256 -t 8

9. 실제 사용 예제

코드 생성 예제:

# Python 코드 생성
curl http://localhost:1234/generate -d '{
  "prompt": "Write a Python function to calculate fibonacci numbers",
  "max_tokens": 200
}'

API 연동 예제:

# Python API 연동
import requests

def call_local_llm(prompt):
    response = requests.post('http://localhost:1234/generate', json={
        "prompt": prompt,
        "max_tokens": 500
    })
    return response.json()['response']

# 사용 예시
result = call_local_llm("Explain machine learning in simple terms")
print(result)

10. 성능 벤치마크

테스트 명령어:

# 128토큰 성능 테스트
./llama-bench -m ./models/Llama-3-8B-Instruct-q4_k_m.gguf -p 128 -n 100 -t 4

# 512토큰 성능 테스트
./llama-bench -m ./models/Llama-3-8B-Instruct-q4_k_m.gguf -p 512 -n 50 -t 8

# 메모리 사용량 측정
valgrind --tool=memcheck --leak-check=full ./main -m ./models/Llama-3-8B-Instruct-q4_k_m.gguf -p "test"

예상 성능:

Q4_K_M: 128토큰/초 15~20
Q5_K_M: 128토큰/초 10~15
FP16: 128토큰/초 5~8

이 가이드는 실제 개발 환경에서 안정적으로 로컬 LLM을 운영할 수 있도록 설계되었습니다. 설정 후에는 다양한 작업을 병렬로 실행할 수 있으며, 필요한 경우 서비스 재시작이나 성능 조정을 통해 최적화할 수 있습니다.

📥 Get the full guide on Gumroad: https://gumroad.com/l/auto ($7)

LangGraph 워크플로우 템플릿 (v49)

matias yoon — Tue, 26 May 2026 06:28:51 +0000

LangGraph 워크플로우 템플릿 (v49)

개요

이 가이드는 Python 개발자들을 위한 LangGraph 기반 AI 에이전트 워크플로우 템플릿을 제공합니다. 3-7달러 범위의 실용적인 도구로, 로컬 AI 솔루션과 에이전트 기반 워크플로우를 구축할 때 발생하는 핵심 문제들을 해결합니다.

1. LangGraph 아키텍처 개요

LangGraph는 상태 기반의 워크플로우 시스템으로, 다음 구성 요소로 이루어집니다:

핵심 구성 요소:

Nodes: 각 작업 단계 (함수 또는 클래스)
Edges: 노드 간의 연결과 조건
State: 워크플로우 상태 (데이터 구조)
Checkpointing: 상태 저장 및 복원 기능

from typing import TypedDict, Annotated
from langgraph.graph import StateGraph
from langgraph.checkpoint.memory import MemorySaver

class GraphState(TypedDict):
    messages: Annotated[list, operator.add]
    context: str

# 상태 기반 그래프 생성
workflow = StateGraph(GraphState)
workflow.add_node("process", process_node)
workflow.add_edge("process", "validate")
workflow.add_conditional_edges(
    "validate",
    route_message,
    {"continue": "process", "end": END}
)

2. 템플릿 1: 간단한 RAG 에이전트 (검색 → 생성 → 검증)

이 템플릿은 로컬 RAG 시스템에서 가장 일반적인 패턴을 구현합니다. 특히 긴 문맥 처리를 위한 최적화를 포함합니다.

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_community.vectorstores import FAISS
from langchain.embeddings import HuggingFaceEmbeddings
import operator

class RAGAgent:
    def __init__(self, vectorstore, llm):
        self.vectorstore = vectorstore
        self.llm = llm

    def retrieve(self, state):
        query = state["query"]
        # 상하위 3개 문서 검색 (성능 최적화)
        docs = self.vectorstore.similarity_search(query, k=3)
        context = "\n\n".join([doc.page_content for doc in docs])
        return {"context": context, "documents": docs}

    def generate(self, state):
        prompt = PromptTemplate.from_template("""
        주어진 컨텍스트를 기반으로 질문에 답변하세요:
        {context}

        질문: {query}
        """)

        chain = prompt | self.llm | StrOutputParser()
        answer = chain.invoke({
            "context": state["context"],
            "query": state["query"]
        })
        return {"answer": answer}

    def validate(self, state):
        # 답변 검증 로직
        if len(state["answer"]) < 10:
            return {"validation": "fail", "retry": True}
        return {"validation": "pass", "retry": False}

# 워크플로우 구성
def create_rag_workflow(agent):
    workflow = StateGraph(RAGState)
    workflow.add_node("retrieve", agent.retrieve)
    workflow.add_node("generate", agent.generate)
    workflow.add_node("validate", agent.validate)

    workflow.set_entry_point("retrieve")
    workflow.add_edge("retrieve", "generate")
    workflow.add_edge("generate", "validate")

    workflow.add_conditional_edges(
        "validate",
        lambda x: "retry" if x["retry"] else "end",
        {"retry": "retrieve", "end": END}
    )
    return workflow.compile()

# 사용 예시
rag_agent = RAGAgent(vectorstore, llm)
rag_workflow = create_rag_workflow(rag_agent)
result = rag_workflow.invoke({"query": "AI 기술의 미래는?"})

3. 템플릿 2: 멀티-도구 에이전트 (계획 → 실행 → 관찰 → 결정)

복잡한 작업을 위한 계획-실행-관찰 패턴을 구현하여, 다양한 도구를 효율적으로 활용합니다.

from langchain.tools import Tool
from langchain_core.runnables import RunnableLambda

class MultiToolAgent:
    def __init__(self, tools):
        self.tools = tools
        self.tool_map = {tool.name: tool for tool in tools}

    def plan(self, state):
        # 작업 계획 생성
        prompt = PromptTemplate.from_template("""
        다음 작업을 수행할 도구를 선택하세요:
        {tasks}

        사용 가능한 도구: {available_tools}
        """)

        # 도구 선택 및 계획 생성
        plan = self.llm.invoke({
            "tasks": state["tasks"],
            "available_tools": [t.name for t in self.tools]
        })
        return {"plan": plan, "execution_plan": self.parse_plan(plan)}

    def execute(self, state):
        # 계획된 작업 실행
        results = []
        for task in state["execution_plan"]:
            tool = self.tool_map.get(task["tool"])
            if tool:
                try:
                    result = tool.run(task["input"])
                    results.append({"tool": task["tool"], "result": result})
                except Exception as e:
                    results.append({"tool": task["tool"], "error": str(e)})
        return {"execution_results": results}

    def observe(self, state):
        # 실행 결과 관찰 및 피드백 수집
        return {"feedback": self.analyze_results(state["execution_results"])}

    def decide(self, state):
        # 다음 단계 결정
        if any(r.get("error") for r in state["execution_results"]):
            return {"next_step": "retry"}
        return {"next_step": "complete"}

# 도구 정의 예시
calculator = Tool(
    name="calculator",
    func=lambda x: eval(x),
    description="수학 계산을 위한 도구"
)

search_tool = Tool(
    name="search",
    func=lambda x: f"검색 결과: {x}",
    description="웹 검색 도구"
)

# 워크플로우 구성
def create_multitool_workflow(agent):
    workflow = StateGraph(MultiToolState)
    workflow.add_node("plan", agent.plan)
    workflow.add_node("execute", agent.execute)
    workflow.add_node("observe", agent.observe)
    workflow.add_node("decide", agent.decide)

    workflow.set_entry_point("plan")
    workflow.add_edge("plan", "execute")
    workflow.add_edge("execute", "observe")
    workflow.add_edge("observe", "decide")

    workflow.add_conditional_edges(
        "decide",
        lambda x: x["next_step"],
        {"retry": "plan", "complete": END}
    )
    return workflow.compile()

4. 템플릿 3: 인간-중개 워크플로우 (일시정지 → 검토 → 계속)

사람의 개입이 필요한 작업을 처리하는 데 유용한 템플릿입니다.


python
import asyncio
from datetime import datetime
from enum import Enum

class ApprovalStatus(Enum):
    PENDING = "pending"
    APPROVED = "approved"
    REJECTED = "rejected"

class HumanInLoopAgent:
    def __init__(self, llm, human_reviewer):
        self.llm = llm
        self.human_reviewer = human_reviewer

    def pause_for_review(self, state):
        # 사용자 검토를 위한 일시정지
        review_request = {
            "task": state["current_task"],
            "context": state["context"],
            "timestamp": datetime.now().isoformat()
        }

        # 데이터베이스에 요청 저장 (실제로는 DB 연결)
        self.save_pending_review(review_request)

        return {"status": "waiting_for_approval", "review_id": str(id(review_request))}

    def review(self, state):
        # 인간 검토 처리
        if state["approval_status"] == ApprovalStatus.APPROVED:
            return {"status": "approved", "next_step": "continue"}
        elif state["approval_status"] == ApprovalStatus.REJECTED:
            return {"status": "rejected", "next_step": "retry"}
        return {"status": "pending"}

    def continue_workflow(self, state):
        # 검토 이후 계속 진행
        return {"status": "completed", "result": self.process_final_result(state)}

# 인간 검토 처리 예시
async def human_review_handler(review_id):
    """실제 인간 검토 처리"""
    # 웹훅 또는 메시지 큐를 통한 처리
    await asyncio.sleep(2)  # 시뮬레이션
    return ApprovalStatus.APPROVED

# 워크플로우 구성
def create_human_in_loop_workflow(agent):
    workflow = StateGraph(HumanInLoopState)
    workflow.add_node("process", agent.process)
    workflow.add_node("pause_for_review", agent.pause_for_review)
    workflow.add_node("review", agent.review)
    workflow.add_node("continue_workflow", agent.continue_workflow)

    workflow.set_entry_point("process")
    workflow.add_edge("process", "pause_for_review")
    workflow.add_edge

---

📥 **Get the full guide on Gumroad**: https://gumroad.com/l/auto ($5)

터미널 AI 에이전트 구축 (v48)

matias yoon — Tue, 26 May 2026 06:14:02 +0000

터미널 AI 에이전트 구축 (v48)

개발자들을 위한 로컬 AI 코딩 에이전트 구축 가이드

1. CLI AI 에이전트 생태계

현재 CLI AI 에이전트 시장은 다양한 솔루션으로 분산되어 있습니다:

주요 플랫폼 비교

Aider: GitHub Copilot 기반의 실시간 코드 작성 도구

pip install aider
aider --help

Continue.dev: VSCode 기반 AI 코딩 도우미

npm install -g continue

OpenCode: 커스텀 AI 모델 연동 가능

git clone https://github.com/open-code/open-code.git

커스텀 스크립트: 최대한의 커스터마이징이 가능한 방법

2. 로컬 LLM API 엔드포인트 설정

로컬 LLM을 사용하여 프라이버시와 성능 문제를 해결합니다:

LMStudio 설치 및 실행

# macOS
brew install lmstudio
# 또는 Windows/Linux
wget https://github.com/lmstudio-ai/LMStudio/releases/download/v0.1.25/LMStudio-0.1.25-x86_64.AppImage

# 서버 실행 (기본 포트 1234)
./LMStudio-0.1.25-x86_64.AppImage --port 1234 --model-path ./models/

API 테스트

curl -X POST http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-model",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ],
    "temperature": 0.7
  }'

3. 간단한 Python CLI 에이전트 구축

# smart_agent.py
import openai
import json
import os
import subprocess
from typing import Dict, List
import argparse

class TerminalAgent:
    def __init__(self, api_key: str = None, model: str = "gpt-4"):
        # 로컬 API 설정
        if api_key:
            openai.api_key = api_key
        else:
            # 로컬 모델을 위한 설정
            openai.base_url = "http://localhost:1234/v1/"
            openai.api_key = "not-needed"

        self.model = model
        self.functions = [
            {
                "name": "run_command",
                "description": "터미널 명령어 실행",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "command": {"type": "string", "description": "실행할 명령어"}
                    },
                    "required": ["command"]
                }
            },
            {
                "name": "read_file",
                "description": "파일 내용 읽기",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "file_path": {"type": "string", "description": "파일 경로"}
                    },
                    "required": ["file_path"]
                }
            }
        ]

    def run_command(self, command: str) -> str:
        """명령어 실행 및 결과 반환"""
        try:
            result = subprocess.run(
                command, 
                shell=True, 
                capture_output=True, 
                text=True,
                timeout=30
            )
            return result.stdout + result.stderr
        except Exception as e:
            return f"Error: {str(e)}"

    def read_file(self, file_path: str) -> str:
        """파일 내용 읽기"""
        try:
            with open(file_path, 'r') as f:
                return f.read()
        except Exception as e:
            return f"Error reading file: {str(e)}"

    def process_function_call(self, function_name: str, arguments: Dict) -> str:
        """함수 호출 처리"""
        if function_name == "run_command":
            return self.run_command(arguments['command'])
        elif function_name == "read_file":
            return self.read_file(arguments['file_path'])
        return "Unknown function"

    def ask(self, question: str) -> str:
        """질문에 대한 답변 생성"""
        response = openai.ChatCompletion.create(
            model=self.model,
            messages=[
                {"role": "system", "content": "You are a helpful coding assistant that can execute commands and read files."},
                {"role": "user", "content": question}
            ],
            functions=self.functions,
            function_call="auto"
        )

        message = response.choices[0].message
        if message.get('function_call'):
            function_name = message['function_call']['name']
            arguments = json.loads(message['function_call']['arguments'])
            result = self.process_function_call(function_name, arguments)
            return result
        return message.content

def main():
    parser = argparse.ArgumentParser(description='Terminal AI Agent')
    parser.add_argument('question', nargs='*', help='질문 내용')
    args = parser.parse_args()

    agent = TerminalAgent()
    question = ' '.join(args.question) if args.question else "help"

    print(f"Question: {question}")
    answer = agent.ask(question)
    print(answer)

if __name__ == "__main__":
    main()

4. tmux와 통합

tmux 세션을 활용한 멀티탭 환경 구축:

# tmux 세션 생성
tmux new-session -s smart_agent -d

# 세션에 윈도우 추가 (코드 편집용)
tmux new-window -t smart_agent -n editor
# 세션에 윈도우 추가 (터미널용)
tmux new-window -t smart_agent -n terminal

# 세션 실행
tmux attach -t smart_agent

tmux 스크립트 파일

# agent_tmux.sh
#!/bin/bash
SESSION="smart_agent"

# 세션이 없으면 생성
if ! tmux has-session -t $SESSION 2>/dev/null; then
    tmux new-session -d -s $SESSION
    tmux new-window -t $SESSION -n "editor"
    tmux new-window -t $SESSION -n "terminal"
    tmux new-window -t $SESSION -n "logs"
fi

# 세션에 연결
tmux attach -t $SESSION

5. 사용자 정의 도구 개발

코드 검색 도구

# tools/code_search.py
import os
import re
from pathlib import Path

class CodeSearcher:
    def __init__(self, root_path: str = "."):
        self.root_path = Path(root_path)

    def search_function(self, function_name: str, file_extensions: list = ['.py', '.js', '.ts']) -> list:
        """함수 정의 검색"""
        results = []

        for file_path in self.root_path.rglob("*"):
            if file_path.suffix in file_extensions:
                try:
                    with open(file_path, 'r') as f:
                        content = f.read()
                        if f"def {function_name}" in content or f"function {function_name}" in content:
                            lines = content.split('\n')
                            for i, line in enumerate(lines):
                                if function_name in line and ('def ' in line or 'function ' in line):
                                    results.append({
                                        'file': str(file_path),
                                        'line': i + 1,
                                        'content': line.strip()
                                    })
                except:
                    continue
        return results

    def search_pattern(self, pattern: str, case_sensitive: bool = True) -> list:
        """정규표현식으로 패턴 검색"""
        results = []
        regex = re.compile(pattern, 0 if case_sensitive else re.IGNORECASE)

        for file_path in self.root_path.rglob("*"):
            if file_path.is_file():
                try:
                    with open(file_path, 'r') as f:
                        content = f.read()
                        matches = regex.finditer(content)
                        for match in matches:
                            results.append({
                                'file': str(file_path),
                                'line': content[:match.start()].count('\n') + 1,
                                'content': match.group().strip()
                            })
                except:
                    continue
        return results

Git 연동 도구


python
# tools/git_tools.py
import subprocess
import json
from typing import Dict, List

class GitTools:
    def __init__(self):
        pass

    def get_staged_files(self) -> List[str]:
        """스테이징된 파일 목록"""
        try:
            result = subprocess.run(['git', 'diff', '--cached', '--name-only'], 
                                   capture_output=True, text=True)
            return result.stdout.strip().split('\n') if result.stdout.strip() else []
        except:
            return []

    def get_git_log(self, limit: int = 10) -> List[Dict]:
        """Git 로그 가져오기"""
        try:
            result = subprocess.run([
                'git', 'log', '--oneline', f'-{limit}'
            ], capture_output=True, text=True)

            logs

---

📥 **Get the full guide on Gumroad**: https://gumroad.com/l/auto ($5)

RAG 시스템 실전 구축 (v48)

matias yoon — Tue, 26 May 2026 05:59:04 +0000

RAG 시스템 실전 구축 (v48)

실제 ML 엔지니어와 백엔드 개발자가 RAG 시스템을 빠르게 구축하고 운영할 수 있는 실전 가이드

1. RAG 기초 원리 (Retrieval → Augmentation → Generation 루프)

RAG (Retrieval-Augmented Generation)는 다음과 같은 세 가지 핵심 단계로 구성됩니다:

Retrieval (검색): 입력 쿼리와 가장 관련성이 높은 문서/조각을 찾습니다
Augmentation (보완): 검색된 정보를 프롬프트에 포함시켜 LLM의 컨텍스트를 확장합니다
Generation (생성): 확장된 컨텍스트를 기반으로 정확한 응답을 생성합니다

쿼리 → [검색] → 문서 조각 → [보완] → 프롬프트 → [생성] → 응답

이 루프는 대규모 모델의 지식 제한을 극복하고, 특정 도메인 지식을 활용할 수 있게 해줍니다.

2. Chunking 전략 (Semantic, Recursive, Agentic)

2.1 Semantic Chunking

Semantic Chunking은 의미 단위로 텍스트를 분할하여 의미적 연결이 강한 문장들을 묶습니다.

from sentence_transformers import SentenceTransformer
import numpy as np
from sklearn.cluster import KMeans

class SemanticChunker:
    def __init__(self, model_name="all-MiniLM-L6-v2"):
        self.model = SentenceTransformer(model_name)

    def chunk_semantically(self, text, threshold=0.7):
        # 문장별로 분할
        sentences = text.split('. ')
        embeddings = self.model.encode(sentences)

        # 클러스터링으로 의미 단위 분할
        kmeans = KMeans(n_clusters=max(1, len(sentences) // 3))
        kmeans.fit(embeddings)

        # 클러스터별 문장 그룹화
        clusters = {}
        for i, cluster_id in enumerate(kmeans.labels_):
            if cluster_id not in clusters:
                clusters[cluster_id] = []
            clusters[cluster_id].append(sentences[i])

        # 그룹화된 문장들을 하나의 chunk로 결합
        chunks = [' '.join(cluster_sentences) for cluster_sentences in clusters.values()]
        return chunks

# 사용 예시
chunker = SemanticChunker()
text = "RAG 시스템은 검색과 생성을 결합한 아키텍처입니다. 이 시스템은 대규모 언어 모델의 지식 제한을 극복합니다. Semantic Chunking은 의미 단위로 텍스트를 분할합니다."
chunks = chunker.chunk_semantically(text)

2.2 Recursive Chunking

문서를 재귀적으로 분할하여 최적의 chunk 크기를 찾습니다.

class RecursiveChunker:
    def __init__(self, max_chunk_size=500, min_chunk_size=100):
        self.max_chunk_size = max_chunk_size
        self.min_chunk_size = min_chunk_size

    def chunk_recursive(self, text, separators=["\n\n", "\n", " ", ""]):
        chunks = []
        current_chunk = ""

        for separator in separators:
            if separator in text:
                parts = text.split(separator)
                for part in parts:
                    if len(current_chunk) + len(part) + len(separator) <= self.max_chunk_size:
                        current_chunk += part + separator
                    else:
                        if current_chunk:
                            chunks.append(current_chunk.strip())
                        current_chunk = part + separator
                if current_chunk:
                    chunks.append(current_chunk.strip())
                break

        if not chunks:
            chunks = [text]

        return chunks

# 사용 예시
recursive_chunker = RecursiveChunker()
text = "이 문서는 RAG 시스템 구축에 대한 실전 가이드입니다. 각 단계별로 코드 예제와 설명을 포함합니다."
chunks = recursive_chunker.chunk_recursive(text)

2.3 Agentic Chunking

LLM을 사용하여 chunking을 자동화하고, 특정 목적에 맞춘 chunk를 생성합니다.

from openai import OpenAI
import json

class AgenticChunker:
    def __init__(self, api_key):
        self.client = OpenAI(api_key=api_key)

    def generate_chunking_prompt(self, text, target_chunks=5):
        prompt = f"""
        다음 텍스트를 {target_chunks}개의 의미 단위로 분할하세요.
        각 chunk는 최대 1000자 이내여야 하며, 의미가 완전히 끝나야 합니다.
        JSON 형식으로 반환하세요:
        {{
            "chunks": ["chunk1", "chunk2", "..."]
        }}

        텍스트: {text}
        """
        return prompt

    def chunk_agentic(self, text, target_chunks=5):
        response = self.client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": self.generate_chunking_prompt(text, target_chunks)}],
            response_format={"type": "json_object"}
        )
        result = json.loads(response.choices[0].message.content)
        return result["chunks"]

3. Embedding 모델 선택 및 비교

3.1 주요 임베딩 모델

# 다양한 임베딩 모델 비교
from sentence_transformers import SentenceTransformer
from transformers import AutoTokenizer, AutoModel
import torch

class EmbeddingEvaluator:
    def __init__(self):
        self.models = {
            'all-MiniLM-L6-v2': SentenceTransformer('all-MiniLM-L6-v2'),
            'all-mpnet-base-v2': SentenceTransformer('all-mpnet-base-v2'),
            'sentence-t5-xxl': SentenceTransformer('sentence-t5-xxl'),
            'bge-small-en': SentenceTransformer('BAAI/bge-small-en')
        }

    def get_embedding(self, text, model_name):
        model = self.models[model_name]
        return model.encode(text)

    def compare_models(self, texts, reference_embedding):
        results = {}
        for name, model in self.models.items():
            embeddings = model.encode(texts)
            # 코사인 유사도 계산
            similarities = []
            for emb in embeddings:
                sim = np.dot(emb, reference_embedding) / (
                    np.linalg.norm(emb) * np.linalg.norm(reference_embedding)
                )
                similarities.append(sim)
            results[name] = np.mean(similarities)
        return results

# 사용 예시
evaluator = EmbeddingEvaluator()
texts = ["RAG 시스템은 검색 기반 생성 모델입니다.", "검색을 통해 관련 정보를 가져와 생성합니다."]
reference = evaluator.get_embedding("RAG 시스템의 핵심 개념", "all-MiniLM-L6-v2")
results = evaluator.compare_models(texts, reference)

4. Vector Database 비교 (Chroma, Qdrant, pgvector, Milvus)

4.1 Chroma

import chromadb
from chromadb.config import Settings
import numpy as np

class ChromaVectorDB:
    def __init__(self, collection_name="rag_collection"):
        self.client = chromadb.Client(Settings(anonymized_telemetry=False))
        self.collection = self.client.get_or_create_collection(collection_name)

    def add_documents(self, documents, embeddings, ids):
        self.collection.add(
            embeddings=embeddings,
            documents=documents,
            ids=ids
        )

    def search(self, query_embedding, n_results=5):
        results = self.collection.query(
            query_embeddings=[query_embedding],
            n_results=n_results
        )
        return results

4.2 Qdrant

from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Filter, FieldCondition, MatchValue

class QdrantVectorDB:
    def __init__(self, host="localhost", port=6333):
        self.client = QdrantClient(host=host, port=port)
        self.collection_name = "rag_collection"

    def create_collection(self):
        self.client.create_collection(
            collection_name=self.collection_name,
            vectors_config=VectorParams(size=384, distance="Cosine")
        )

    def add_documents(self, documents, embeddings, ids):
        self.client.upsert(
            collection_name=self.collection_name,
            points=[
                {
                    "id": id,
                    "vector": embedding.tolist(),
                    "payload": {"document": doc}
                }
                for id, doc, embedding in zip(ids, documents, embeddings)
            ]
        )

    def search(self, query_embedding, n_results=5):
        results = self.client.search(
            collection_name=self.collection_name,
            query_vector=query_embedding.tolist(),
            limit=n_results
        )
        return [(hit.id, hit.payload["document"]) for hit in results]

4.3 pgvector


python
import psycopg2
from psycopg2.extras import Json
import numpy as np

class PGVectorDB:
    def __init

---

📥 **Get the full guide on Gumroad**: https://gumroad.com/l/auto ($7)

로컬 LLM 셋업 가이드 (v48)

matias yoon — Tue, 26 May 2026 05:44:17 +0000

로컬 LLM 셋업 가이드 (v48)

1. 개요 및 사전 준비

로컬 LLM은 인터넷 연결 없이 AI 모델을 실행하여 코드 품질과 보안을 유지하는 데 필수적입니다. 이 가이드는 개발자들이 빠르고 효율적으로 로컬 LLM을 설정할 수 있도록 돕습니다.

사전 요구사항:

Linux 시스템 (Ubuntu 20.04 이상 권장)
NVIDIA GPU (CUDA 지원) 또는 CPU
최소 16GB RAM (추천 32GB 이상)
최소 20GB 디스크 공간

시스템 확인:

# GPU 확인
nvidia-smi

# RAM 확인
free -h

# 디스크 공간 확인
df -h

2. 프레임워크 비교

프레임워크	장점	단점	적합성
llama.cpp	최소 요구사항, 높은 최적화, 직접 컴파일	설치 복잡, API 부족	고성능, 최적화 필요
Ollama	간단 설치, 웹 UI, 간편 API	GPU 최적화 제한	개발 테스트용
vLLM	높은 성능, 병렬 처리	복잡한 설정, 메모리 사용량 높음	고성능 서버 환경
LocalAI	유연한 API, 다양한 모델 지원	자원 소모가 큼	API 통합 필요

3. 권장 설정 설치 (llama.cpp + Ollama)

llama.cpp 설치:

# 소스 코드 다운로드
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

# 빌드
make clean
make

Ollama 설치:

# Ollama 설치 스크립트 실행
curl -fsSL https://ollama.com/install.sh | sh

# 서비스 시작
sudo systemctl start ollama
sudo systemctl enable ollama

4. 모델 선택 가이드

코드 개발용 모델:

CodeLlama-7B: 7B 파라미터, 코드 생성 최적화
StarCoder2-15B: 고성능, 다양한 언어 지원
Phi-3-medium: 가볍고 빠른 코드 생성

일반 목적 모델:

Llama3-8B: 균형 잡힌 성능
Mistral-7B: 높은 품질

# Ollama에서 모델 다운로드
ollama pull codellama:7b
ollama pull llama3:8b

5. 양자화 유형 설명

유형	성능	크기	사용 사례
Q4_K_M	높음	4.5GB	일반 사용
Q5_K_M	매우 높음	5.5GB	고성능
Q8_0	최대 성능	8GB	테스트
F16	원본 품질	16GB	높은 정확도 필요

양자화 예제:

# 모델을 Q4_K_M로 변환
./convert-hf-to-ggml.py ./models/CodeLlama-7B/ --outtype q4_K_M

6. API 설정 및 통합

로컬 API 서버 시작:

# llama.cpp API 서버 시작
./server -m ./models/CodeLlama-7B/ggml-model-q4_K_M.bin \
         -c 2048 \
         --port 8080 \
         --host 0.0.0.0

# Ollama API 서버 시작
ollama serve

간단한 API 통신:

# curl을 통한 테스트
curl http://localhost:8080/completion \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "def fibonacci(n):",
    "n_predict": 100,
    "temperature": 0.2
  }'

7. Systemd 서비스 설정

로컬 LLM 서비스 파일 생성:

sudo nano /etc/systemd/system/local-llm.service

서비스 파일 내용:

[Unit]
Description=Local LLM Server
After=network.target

[Service]
Type=simple
User=developer
WorkingDirectory=/home/developer/llama.cpp
ExecStart=/home/developer/llama.cpp/server -m /home/developer/models/CodeLlama-7B/ggml-model-q4_K_M.bin -c 2048 --port 8080
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

서비스 시작:

sudo systemctl daemon-reload
sudo systemctl enable local-llm
sudo systemctl start local-llm
sudo systemctl status local-llm

8. 모니터링 및 성능 최적화

시스템 모니터링:

# GPU 사용량 모니터링
nvidia-smi -l 1

# CPU/메모리 사용량
htop

# 로그 확인
journalctl -u local-llm -f

성능 최적화:

# 메모리 최적화 옵션
./server -m model.bin \
         -c 2048 \
         -n 128 \
         --threads 8 \
         --port 8080

9. 실제 사용 예제

코드 생성 테스트:

curl -X POST http://localhost:8080/completion \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "# Python 함수: 리스트에서 최대값 찾기\n\ndef find_max(numbers):",
    "n_predict": 50,
    "temperature": 0.1,
    "stop": ["\n\n"]
  }'

API 연동 예제 (Python):

import requests
import json

def query_llm(prompt):
    response = requests.post(
        'http://localhost:8080/completion',
        json={
            'prompt': prompt,
            'n_predict': 100,
            'temperature': 0.2
        }
    )
    return response.json()['content']

# 사용 예시
result = query_llm("def quicksort(arr):")
print(result)

10. 성능 벤치마크

벤치마크 실행:

# llama.cpp 벤치마크
./bench -m ./models/CodeLlama-7B/ggml-model-q4_K_M.bin -c 2048 --threads 8

# 성능 결과 예시:
# Tokens/sec: 25.3
# Total time: 2.3s

결론

이 가이드를 따라하면 개발자는 로컬 LLM을 쉽게 설정하고 관리할 수 있습니다. 모델 선택과 양자화 전략을 잘 조정하면 높은 성능과 효율성을 동시에 달성할 수 있습니다.

부록: 코드 품질 게이트 도구 개발 계획

로컬 LLM 환경에서 다음과 같은 도구를 개발하여 실제 문제 해결:

IDE 플러그인: 실시간 코드 품질 검사
CI/CD 통합: 자동화된 코드 리뷰 시스템
성능 모니터링: 코드 생성 성능 트래킹

이 도구는 개발자들이 AI 도구를 더 효과적으로 활용하면서 코드 품질을 유지할 수 있도록 지원합니다.

가이드 완료: v48 버전으로 실제 사용 가능한 로컬 LLM 환경 구축이 완료되었습니다.

📥 Get the full guide on Gumroad: https://gumroad.com/l/auto ($7)

LangGraph 워크플로우 템플릿 (v48)

matias yoon — Tue, 26 May 2026 05:29:35 +0000

LangGraph 워크플로우 템플릿 (v48)

개요: LangGraph 아키텍처와 실전 패턴

LangGraph는 LangChain의 고급 워크플로우 엔진으로, 복잡한 AI 에이전트를 구현하는 데 강력한 도구를 제공합니다. 이 템플릿 가이드는 실제 개발자가 자주 겪는 문제를 해결하기 위한 5가지 핵심 패턴을 제공합니다.

기본 구성 요소

Nodes: 워크플로우의 각 단계
Edges: 노드 간의 실행 흐름
State: 모든 노드가 공유하는 상태 객체
Checkpointing: 실행 중단/재개를 위한 상태 저장 기능

핵심 설계 원칙

from typing import TypedDict, Annotated
from langgraph.graph import StateGraph, END
import operator

class AgentState(TypedDict):
    messages: Annotated[list, operator.add]
    # 추가 상태 필드

템플릿 1: 간단한 RAG 에이전트

문제: 문서 검색 및 생성을 통합한 RAG 워크플로우에서 검증 과정이 필요

from langchain_core.messages import HumanMessage, AIMessage
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings

# RAG 에이전트 구현
class RAGAgent:
    def __init__(self, vector_store_path: str):
        self.vector_store = Chroma(persist_directory=vector_store_path)
        self.llm = ChatOpenAI(model="gpt-4o-mini")
        self.retriever = self.vector_store.as_retriever()

    def retrieve(self, state: dict):
        """문서 검색"""
        query = state["messages"][-1].content
        docs = self.retriever.invoke(query)
        return {"retrieved_docs": docs}

    def generate(self, state: dict):
        """문서 기반 생성"""
        context = "\n".join([doc.page_content for doc in state["retrieved_docs"]])
        prompt = ChatPromptTemplate.from_messages([
            ("system", "다음 컨텍스트를 기반으로 답변을 생성하세요: {context}"),
            ("user", "{query}")
        ])

        chain = prompt | self.llm | StrOutputParser()
        response = chain.invoke({
            "context": context,
            "query": state["messages"][-1].content
        })

        return {"generated_response": response}

    def validate(self, state: dict):
        """생성된 응답 검증"""
        # 간단한 검증 규칙
        response = state["generated_response"]
        if len(response) < 10:
            raise ValueError("응답이 너무 짧습니다")
        return {"valid": True}

# 워크플로우 정의
def build_rag_workflow():
    workflow = StateGraph(AgentState)

    workflow.add_node("retrieve", RAGAgent.retrieve)
    workflow.add_node("generate", RAGAgent.generate)
    workflow.add_node("validate", RAGAgent.validate)

    workflow.set_entry_point("retrieve")
    workflow.add_edge("retrieve", "generate")
    workflow.add_edge("generate", "validate")
    workflow.add_edge("validate", END)

    return workflow.compile()

템플릿 2: 다중 도구 사용 에이전트

문제: 여러 도구를 활용한 계획-실행-관찰-결정 워크플로우

from langchain.tools import Tool
from langchain_openai import OpenAI
import json

class MultiToolAgent:
    def __init__(self):
        self.tools = [
            Tool(
                name="search",
                func=lambda q: f"검색 결과: {q}",
                description="웹 검색을 수행합니다"
            ),
            Tool(
                name="calculator",
                func=lambda e: f"계산 결과: {eval(e)}",
                description="수학 계산을 수행합니다"
            )
        ]
        self.llm = ChatOpenAI(model="gpt-4o-mini")

    def plan(self, state: dict):
        """작업 계획 생성"""
        prompt = ChatPromptTemplate.from_messages([
            ("system", "다음 작업을 위한 계획을 생성하세요: {task}"),
            ("user", "도구 목록: {tools}")
        ])

        plan = self.llm.invoke(prompt.format(
            task=state["messages"][-1].content,
            tools=[tool.name for tool in self.tools]
        ))

        return {"plan": plan.content}

    def execute(self, state: dict):
        """계획 실행"""
        plan = state["plan"]
        # 간단한 실행 로직 (실제 구현에서는 도구 선택 로직 포함)
        return {"execution_result": "실행 완료"}

    def observe(self, state: dict):
        """실행 결과 관찰"""
        # 실제 관찰 로직
        return {"observation": "관찰 완료"}

    def decide(self, state: dict):
        """결정 로직"""
        # 실행 결과에 따라 결정
        return {"decision": "다음 단계로 진행"}

# 워크플로우 구성
def build_multitool_workflow():
    agent = MultiToolAgent()

    workflow = StateGraph(AgentState)
    workflow.add_node("plan", agent.plan)
    workflow.add_node("execute", agent.execute)
    workflow.add_node("observe", agent.observe)
    workflow.add_node("decide", agent.decide)

    workflow.set_entry_point("plan")
    workflow.add_edge("plan", "execute")
    workflow.add_edge("execute", "observe")
    workflow.add_edge("observe", "decide")
    workflow.add_edge("decide", END)

    return workflow.compile()

템플릿 3: 인간-중개 워크플로우

문제: 인간의 검토와 승인을 포함한 결정 워크플로우

import asyncio
from datetime import datetime

class HumanInLoopAgent:
    def __init__(self):
        self.llm = ChatOpenAI(model="gpt-4o-mini")
        self.waiting_for_human = False

    def generate(self, state: dict):
        """생성 작업"""
        prompt = ChatPromptTemplate.from_messages([
            ("system", "다음 내용을 기반으로 생성하세요: {input}"),
            ("user", "결정이 필요한 경우 인간 검토가 필요합니다")
        ])

        response = self.llm.invoke(prompt.format(input=state["messages"][-1].content))
        return {"generated": response.content, "requires_human_review": True}

    def human_review(self, state: dict):
        """인간 검토"""
        # 실제 구현에서는 API 또는 대화형 인터페이스 필요
        # 여기서는 가상의 검토 로직
        return {"review_status": "approved", "reviewed_at": datetime.now()}

    def continue_workflow(self, state: dict):
        """워크플로우 재개"""
        return {"workflow_continued": True}

# 인간-중개 워크플로우
def build_human_in_loop_workflow():
    agent = HumanInLoopAgent()

    workflow = StateGraph(AgentState)
    workflow.add_node("generate", agent.generate)
    workflow.add_node("human_review", agent.human_review)
    workflow.add_node("continue", agent.continue_workflow)

    workflow.set_entry_point("generate")
    workflow.add_edge("generate", "human_review")
    workflow.add_edge("human_review", "continue")
    workflow.add_edge("continue", END)

    return workflow.compile()

템플릿 5: 병렬 실행 에이전트

문제: 여러 작업을 동시에 처리하고 결과를 집계하는 병렬 처리 워크플로우


python
import asyncio
from concurrent.futures import ThreadPoolExecutor
from typing import List

class ParallelAgent:
    def __init__(self):
        self.llm = ChatOpenAI(model="gpt-4o-mini")

    def fan_out(self, state: dict):
        """작업 분산"""
        # 여러 작업으로 분할
        tasks = ["분석1", "분석2", "분석3"]
        return {"tasks": tasks, "task_results": []}

    async def process_task(self, task: str):
        """개별 작업 처리"""
        prompt = ChatPromptTemplate.from_messages([
            ("system", f"{task} 작업을 처리하세요"),
            ("user", "결과를 요약하여 반환하세요")
        ])

        response = self.llm.invoke(prompt.format(task=task))
        return f"{task}_결과: {response.content}"

    def aggregate(self, state: dict):
        """결과 집계"""
        # 병렬 처리 결과를 집계
        results = state["task_results"]
        summary = " ".join(results)
        return {"aggregated_summary": summary}

# 병렬

---

📥 **Get the full guide on Gumroad**: https://gumroad.com/l/auto ($5)

터미널 AI 에이전트 구축 (v47)

matias yoon — Tue, 26 May 2026 05:14:49 +0000

터미널 AI 에이전트 구축 (v47)

CLI AI 에이전트 생태계

터미널에서 작동하는 AI 에이전트는 이미 다양한 형태로 존재합니다. 현재 주요 도구는 다음과 같습니다:

Aider: GitHub Copilot과 유사한 기능을 제공하며, 파일 단위로 코드를 생성하고 수정합니다. 주요 특징은 소스 코드가 있는 파일과 현재 작업 디렉토리 기반의 콘텍스트를 사용하는 것입니다.

# Aider 설치
pip install aider

# Aider 실행
aider --help

Continue.dev: VS Code 확장 기반의 AI 에이전트로, 터미널에서도 사용 가능한 커스텀 에이전트를 지원합니다. GitHub Copilot 기반으로 작동하며, 확장 기능을 사용합니다.

OpenCode: OpenAI API와 연동되는 터미널 기반 툴로, 코드 생성 및 리뷰 기능을 제공합니다. 터미널에서 직접 사용할 수 있는 기능을 중심으로 설계되었습니다.

커스텀 스크립트: 직접 구축한 스크립트는 최대한의 사용자 맞춤형 기능을 제공합니다. 예를 들어, 특정 프로젝트 구조에 맞는 코드 생성기를 만들 수 있습니다.

로컬 LLM API 엔드포인트 설정

터미널에서 AI 에이전트를 구축하기 위해 로컬 LLM (Large Language Model) API 서버를 설정하는 것이 중요합니다.

# llama.cpp를 사용한 로컬 LLM 서버 설정
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
make

# 모델 다운로드 및 변환
wget https://huggingface.co/TheBloke/Mistral-7B-v0.1-GGUF/resolve/main/mistral-7b-v0.1.Q4_K_M.gguf

# 로컬 서버 실행
./server -m mistral-7b-v0.1.Q4_K_M.gguf -c 2048 --host 127.0.0.1 --port 11434

위 명령어는 llama.cpp를 사용하여 로컬에서 LLM 서버를 실행하는 방법입니다. 이 서버는 localhost:11434 포트에서 API를 제공합니다.

간단한 Python CLI 에이전트 구축

다음은 기능 호출(Functions calling)을 포함하는 간단한 Python CLI 에이전트입니다.

#!/usr/bin/env python3
# ai_agent.py
import openai
import json
import subprocess
import sys
from typing import Dict, List, Any

# 로컬 LLM API 설정
openai.api_base = "http://localhost:11434/v1"
openai.api_key = "dummy"

class TerminalAgent:
    def __init__(self):
        self.tools = {
            "run_command": self.run_command,
            "read_file": self.read_file,
            "write_file": self.write_file,
            "search_code": self.search_code
        }

    def run_command(self, command: str) -> str:
        """명령어 실행"""
        try:
            result = subprocess.run(
                command, 
                shell=True, 
                capture_output=True, 
                text=True,
                timeout=30
            )
            return result.stdout + result.stderr
        except Exception as e:
            return f"Error: {str(e)}"

    def read_file(self, filename: str) -> str:
        """파일 읽기"""
        try:
            with open(filename, 'r') as f:
                return f.read()
        except Exception as e:
            return f"Error reading {filename}: {str(e)}"

    def write_file(self, filename: str, content: str) -> str:
        """파일 쓰기"""
        try:
            with open(filename, 'w') as f:
                f.write(content)
            return f"Successfully wrote to {filename}"
        except Exception as e:
            return f"Error writing to {filename}: {str(e)}"

    def search_code(self, pattern: str, directory: str = ".") -> str:
        """코드 검색"""
        try:
            cmd = f"grep -r '{pattern}' {directory}"
            result = subprocess.run(
                cmd, 
                shell=True, 
                capture_output=True, 
                text=True
            )
            return result.stdout
        except Exception as e:
            return f"Error searching code: {str(e)}"

    def call_tool(self, tool_name: str, arguments: Dict[str, Any]) -> str:
        """툴 실행"""
        if tool_name in self.tools:
            return self.tools[tool_name](**arguments)
        return f"Unknown tool: {tool_name}"

    def chat(self, messages: List[Dict[str, str]], tools: List[Dict[str, Any]] = None) -> str:
        """채팅 메시지 처리"""
        if tools:
            # 기능 호출을 위한 메시지 생성
            response = openai.ChatCompletion.create(
                model="mistral",
                messages=messages,
                functions=tools,
                function_call="auto"
            )
            return response.choices[0].message
        else:
            # 일반적인 채팅
            response = openai.ChatCompletion.create(
                model="mistral",
                messages=messages
            )
            return response.choices[0].message.content

def main():
    agent = TerminalAgent()

    # 예제 메시지
    messages = [
        {
            "role": "system",
            "content": "You are a helpful assistant that can execute terminal commands and manipulate files."
        },
        {
            "role": "user",
            "content": "Create a new Python file called 'hello.py' that prints 'Hello, World!'"
        }
    ]

    # 함수 정의
    tools = [
        {
            "name": "write_file",
            "description": "Write content to a file",
            "parameters": {
                "type": "object",
                "properties": {
                    "filename": {"type": "string"},
                    "content": {"type": "string"}
                },
                "required": ["filename", "content"]
            }
        }
    ]

    result = agent.chat(messages, tools)
    print(result)

if __name__ == "__main__":
    main()

tmux와의 통합

터미널 멀티플렉서인 tmux와 통합하여 작업 환경을 향상시킬 수 있습니다.

# tmux 세션 생성
tmux new-session -d -s ai_agent

# 세션 내에서 명령 실행
tmux send-keys -t ai_agent "python ai_agent.py" Enter

# 세션에 연결
tmux attach -t ai_agent

다음은 tmux와 통합된 에이전트입니다:

# tmux_integration.py
import subprocess
import json

class TmuxAgent:
    def __init__(self, session_name="ai_agent"):
        self.session_name = session_name

    def create_session(self):
        """tmux 세션 생성"""
        subprocess.run(["tmux", "new-session", "-d", "-s", self.session_name])

    def send_command(self, command: str):
        """명령어 전송"""
        subprocess.run([
            "tmux", "send-keys", "-t", self.session_name, command, "Enter"
        ])

    def get_session_info(self):
        """세션 정보 확인"""
        result = subprocess.run(
            ["tmux", "list-sessions", "-F", "#{session_name}: #{session_attached}"],
            capture_output=True,
            text=True
        )
        return result.stdout

    def run_agent_command(self, command: str, output_file: str = None):
        """에이전트 명령 실행"""
        # 명령어를 터미널에서 실행
        result = subprocess.run(
            ["python", "ai_agent.py", command],
            capture_output=True,
            text=True
        )

        if output_file:
            with open(output_file, 'w') as f:
                f.write(result.stdout)

        return result.stdout

# 사용 예시
agent = TmuxAgent("my_ai_session")
agent.create_session()
agent.send_command("ls -la")

커스텀 툴 개발

다음은 코드 검색, git 연동, 파일 작업 기능을 포함한 커스텀 툴입니다:


python
# custom_tools.py
import os
import subprocess
import re

class CodeTools:
    @staticmethod
    def search_git_files(pattern: str, repo_path: str = ".") -> list:
        """Git 저장소 내 파일 검색"""
        try:
            cmd = ["git", "ls-files"]
            result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
            files = result.stdout.strip().split('\n')

            matched_files = []
            for file in files:
                if pattern in file:
                    matched_files.append(file)
            return matched_files
        except Exception as e:
            return []

    @staticmethod
    def get_git_diff():
        """Git 변경 사항 확인"""
        try:
            cmd =

---

📥 **Get the full guide on Gumroad**: https://gumroad.com/l/auto ($5)

RAG 시스템 실전 구축 (v47)

matias yoon — Tue, 26 May 2026 04:59:58 +0000

RAG 시스템 실전 구축 (v47)

개요

RAG(Retrieval-Augmented Generation) 시스템은 LLM의 지식 범위를 확장하고, 특정 도메인 전문 지식을 통합하는 데 핵심적인 기술입니다. 이 가이드는 실제 개발 환경에서 RAG 시스템을 구축하는 실전 가이드를 제공하며, 특히 로컬 환경에서의 성능과 비용 효율성을 중심으로 다룹니다.

1. RAG 기본 구조

RAG는 세 가지 핵심 단계로 구성됩니다:

검색(Retrieval): 주어진 쿼리와 관련된 문서 조각을 찾습니다.
보강(Augmentation): 검색된 문서를 프롬프트에 추가합니다.
생성(Generation): LLM이 보강된 프롬프트를 기반으로 응답을 생성합니다.

# RAG 기본 구조 구현
class BasicRAG:
    def __init__(self, embedding_model, vector_db):
        self.embedding_model = embedding_model
        self.vector_db = vector_db

    def retrieve(self, query, k=5):
        query_embedding = self.embedding_model.encode([query])
        return self.vector_db.search(query_embedding, k)

    def generate(self, query, retrieved_docs):
        prompt = f"Query: {query}\n\nRelevant Docs:\n" + "\n\n".join(retrieved_docs)
        return self.llm.generate(prompt)

    def process(self, query):
        docs = self.retrieve(query)
        response = self.generate(query, docs)
        return response

2. Chunking 전략

문서를 적절한 크기로 나누는 전략은 RAG 성능에 결정적 영향을 미칩니다.

2.1 의미적 Chunking

from sentence_transformers import SentenceTransformer
import numpy as np

def semantic_chunking(documents, model, threshold=0.7):
    """의미적 기반으로 문서를 chunking"""
    embeddings = model.encode(documents)

    chunks = []
    current_chunk = []
    current_embedding = np.zeros(embeddings[0].shape)

    for i, (doc, embedding) in enumerate(zip(documents, embeddings)):
        # 이전 chunk와의 유사도 계산
        similarity = np.dot(current_embedding, embedding) / (
            np.linalg.norm(current_embedding) * np.linalg.norm(embedding)
        )

        if similarity < threshold:
            if current_chunk:
                chunks.append(' '.join(current_chunk))
            current_chunk = [doc]
            current_embedding = embedding
        else:
            current_chunk.append(doc)
            # 평균 임베딩 업데이트
            current_embedding = (current_embedding + embedding) / 2

    if current_chunk:
        chunks.append(' '.join(current_chunk))
    return chunks

2.2 Recursive Chunking

def recursive_chunking(text, max_chunk_size=500):
    """재귀적 chunking으로 문장 단위로 분할"""
    chunks = []
    sentences = text.split('. ')

    current_chunk = ""
    for sentence in sentences:
        if len(current_chunk) + len(sentence) < max_chunk_size:
            current_chunk += sentence + ". "
        else:
            if current_chunk:
                chunks.append(current_chunk.strip())
            current_chunk = sentence + ". "

    if current_chunk:
        chunks.append(current_chunk.strip())

    return chunks

3. 임베딩 모델 선택 및 비교

# 임베딩 모델 비교
from sentence_transformers import SentenceTransformer
from transformers import AutoTokenizer, AutoModel
import torch

class EmbeddingComparison:
    def __init__(self):
        self.models = {
            'all-MiniLM-L6-v2': SentenceTransformer('all-MiniLM-L6-v2'),
            'paraphrase-multilingual-MiniLM-v2': SentenceTransformer('paraphrase-multilingual-MiniLM-v2'),
            'bge-small-en': SentenceTransformer('BAAI/bge-small-en'),
            'fast-sentence-bert': SentenceTransformer('sentence-transformers/paraphrase-multilingual-mpnet-base-v2')
        }

    def benchmark_models(self, test_sentences):
        results = {}
        for name, model in self.models.items():
            start_time = time.time()
            embeddings = model.encode(test_sentences)
            end_time = time.time()

            results[name] = {
                'time': end_time - start_time,
                'dimension': embeddings.shape[1],
                'memory': embeddings.nbytes
            }
        return results

# 사용 예시
comparison = EmbeddingComparison()
test_data = ["Hello world", "How are you?", "I am fine"]
results = comparison.benchmark_models(test_data)

4. Vector Database 비교

# Vector DB별 비교
class VectorDBComparison:
    def __init__(self):
        self.dbs = {
            'chroma': ChromaDB(),
            'qdrant': QdrantDB(),
            'pgvector': PostgreSQLVector(),
            'milvus': MilvusDB()
        }

    def test_insert_performance(self, documents, embeddings):
        results = {}
        for name, db in self.dbs.items():
            start_time = time.time()
            db.insert(documents, embeddings)
            end_time = time.time()
            results[name] = end_time - start_time
        return results

# ChromaDB 구현 예시
class ChromaDB:
    def __init__(self, path="./chroma_db"):
        import chromadb
        self.client = chromadb.Client(path)
        self.collection = self.client.get_or_create_collection("docs")

    def insert(self, documents, embeddings):
        self.collection.add(
            documents=documents,
            embeddings=embeddings,
            ids=[f"doc_{i}" for i in range(len(documents))]
        )

    def search(self, query_embedding, k=5):
        results = self.collection.query(
            query_embeddings=query_embedding,
            n_results=k
        )
        return results['documents'][0]

5. 전체 RAG 파이프라인 코드

import numpy as np
from sentence_transformers import SentenceTransformer
import faiss
import time
import pickle

class LocalRAGPipeline:
    def __init__(self, model_name='all-MiniLM-L6-v2'):
        self.embedding_model = SentenceTransformer(model_name)
        self.vector_index = None
        self.documents = []
        self.doc_ids = []

    def create_vector_index(self, documents):
        """문서 벡터 인덱스 생성"""
        # 문서 임베딩 생성
        embeddings = self.embedding_model.encode(documents)
        self.documents = documents

        # FAISS 인덱스 생성
        dimension = embeddings.shape[1]
        self.vector_index = faiss.IndexFlatIP(dimension)
        self.vector_index.add(np.array(embeddings, dtype=np.float32))

        # 문서 ID 매핑
        self.doc_ids = [f"doc_{i}" for i in range(len(documents))]

    def search_relevant_docs(self, query, k=5):
        """관련 문서 검색"""
        query_embedding = self.embedding_model.encode([query])
        distances, indices = self.vector_index.search(
            np.array(query_embedding, dtype=np.float32), k
        )

        relevant_docs = []
        for idx, dist in zip(indices[0], distances[0]):
            if idx < len(self.documents):
                relevant_docs.append({
                    'content': self.documents[idx],
                    'similarity': float(dist)
                })
        return relevant_docs

    def generate_response(self, query, relevant_docs):
        """LLM 응답 생성"""
        # 간단한 프롬프트 생성
        context = "\n\n".join([doc['content'] for doc in relevant_docs])
        prompt = f"""
        주어진 문서 내용을 바탕으로 질문에 답변해주세요.

        문서 내용:
        {context}

        질문: {query}
        """

        # 실제 LLM 호출은 여기서 수행 (예: local LLM)
        # 예시로 간단한 응답 생성
        return f"질문: {query}\n답변: 문서 내용을 바탕으로 답변을 생성했습니다."

    def process_query(self, query):
        """전체 쿼리 처리 파이프라인"""
        relevant_docs = self.search_relevant_docs(query)
        response = self.generate_response(query, relevant_docs)
        return response

# 사용 예시
pipeline = LocalRAGPipeline()

# 샘플 문서
documents = [
    "Python은 고급 프로그래밍 언어로, 간결하고 가독성이 뛰어납니다.",
    "장고(Django)는 웹 프레임워크로, 빠르고 안전한 웹 개발을 지원합니다.",
    "FastAPI는 현대적인 웹 프레임워크로, 높은 성능과 자동 문서화 기능을 제공합니다."
]

# 벡터 인덱스 생성
pipeline.create_vector_index(documents)

# 쿼리 처리
response = pipeline.process_query("Python 프로그래밍 언어의 특징은?")
print(response)

6. 고급 기

📥 Get the full guide on Gumroad: https://gumroad.com/l/auto ($7)

DEV Community: matias yoon

로컬 LLM 셋업 가이드 (v50)

로컬 LLM 셋업 가이드 (v50)

1. 개요 및 전제 조건

전제 조건:

2. 프레임워크 비교

3. 설치 단계 (llama.cpp 기반)

3.1 의존성 설치

3.2 llama.cpp 설치

3.3 모델 다운로드 및 변환

3.4 실행 테스트

4. 모델 선택 가이드

4.1 개발자용 모델

4.2 실제 예제

5. 양자화 유형 설명

5.1 Q4_K_M vs Q5_K_M

5.2 변환 명령어

5.3 성능 비교

6. API 설정 및 통합

6.1 FastAPI 서버 구축

6.2 서버 실행

6.3 API 호출 예제

7. 시스템 서비스 설정

7.1 systemd 서비스 파일 생성

7.2 서비스 시작

8. 모니터링 및 성능 튜닝

8.1 메모리 사용량 추적

8.2 성능 최적화 설정

8.3 로그 수집

9. 실제 사용 사례

9.1 코드 생성 예제

9.2 문제 해결 예제

9.3 성능 기준

10. 고급 설정 및 문제 해결

LangGraph 워크플로우 템플릿 (v50)

LangGraph 워크플로우 템플릿 (v50)

실용적인 LangChain/LangGraph 워크플로우 템플릿 가이드

1. LangGraph 아키텍처 개요

2. 템플릿 1: 단순 RAG 에이전트 (검색 → 생성 → 검증)

3. 템플릿 2: 다중 도구 에이전트 (계획 → 실행 → 관찰 → 결정)

4. 템플릿 3: 인간-중개 워크플로우 (일시정지 → 검토 → 계속)

5. 템플릿 5: 병렬 실행 에이전트 (분산 → 처리 → 집계)

터미널 AI 에이전트 구축 (v49)

터미널 AI 에이전트 구축 (v49)

개발자들을 위한 로컬 터미널 AI 에이전트 구축 가이드

1. CLI AI 에이전트 생태계 분석

주요 도구들

Aider vs Continue vs Custom

2. 로컬 LLM API 엔드포인트 설정

3. Python CLI 에이전트 구축

4. tmux와 통합

5. 사용자 정의 도구 개발

6. 컨텍스트 윈도우 관리

7. 비용/성능 최적화

RAG 시스템 실전 구축 (v49)

RAG 시스템 실전 구축 (v49)

목차

1. RAG 기초 개념

검색-증강-생성 루프

2. 청킹 전략

1. 문맥 기반 청킹 (Semantic Chunking)

2. 재귀적 청킹 (Recursive Chunking)

3. 에이전트 기반 청킹

3. 임베딩 모델 선택 및 비교

모델 비교 클래스

성능 기준

4. 벡터 DB 비교

Chroma vs Qdrant vs pgvector

로컬 LLM 셋업 가이드 (v49)

로컬 LLM 셋업 가이드 (v49)

1. 개요 및 사전 요구사항

사전 요구사항:

최소 성능 기준:

2. 프레임워크 비교: llama.cpp vs Ollama vs vLLM vs LocalAI

3. 추천 설정: llama.cpp + Ollama 조합

llama.cpp 설치:

Ollama 설치:

4. 모델 선택 가이드

일반 목적 모델:

코드 전용 모델: