MaxKB: 기업급 AI 에이전트 구축을 위한 완벽 가이드

⏱️ 예상 읽기 시간: 15분

MaxKB 소개

MaxKB는 기업급 AI 에이전트 구축을 위한 강력하고 사용자 친화적인 오픈소스 플랫폼입니다. 1Panel 팀에서 개발한 이 종합적인 솔루션은 GitHub에서 18,000개 이상의 스타를 받으며 현재 사용 가능한 가장 인기 있는 기업 AI 에이전트 플랫폼 중 하나가 되었습니다.

MaxKB의 특별함

MaxKB는 경쟁이 치열한 AI 에이전트 영역에서 다음과 같은 특징으로 차별화됩니다:

기업 준비 아키텍처: 확장성과 보안을 염두에 두고 구축
다중 모델 지원: Llama3, DeepSeek-R1, Qwen3 등 다양한 LLM과 호환
지식베이스 통합: 고급 RAG(검색 증강 생성) 기능
시각적 워크플로우 빌더: 복잡한 에이전트 워크플로우 생성을 위한 사용자 친화적 인터페이스
오픈소스 유연성: 활발한 커뮤니티 지원과 함께 GPL-3.0 라이선스

기술 아키텍처 개요

핵심 기술 스택

MaxKB는 현대적이고 견고한 기술 스택을 활용합니다:

프론트엔드: 반응형 사용자 인터페이스를 위한 TypeScript 기반 Vue.js
백엔드: 강력한 API 서비스를 위한 Django 프레임워크 기반 Python
LLM 프레임워크: 원활한 AI 모델 통합을 위한 LangChain
데이터베이스: 벡터 저장을 위한 pgvector 확장을 갖춘 PostgreSQL
배포: 컨테이너화된 배포를 위한 Docker 및 Docker Compose

주요 기능

에이전트 관리: 여러 AI 에이전트 생성, 구성 및 관리
지식베이스: RAG 애플리케이션을 위한 문서 업로드 및 관리
모델 통합: 다양한 LLM 제공자 및 모델 지원
대화 관리: 컨텍스트 인식을 갖춘 고급 채팅 인터페이스
API 액세스: 기존 시스템과의 통합을 위한 RESTful API
멀티 테넌트 아키텍처: 여러 조직 및 사용자 지원

설치 및 설정 가이드

전제 조건

MaxKB를 설치하기 전에 시스템이 다음 요구사항을 충족하는지 확인하세요:

운영체제: Linux, macOS 또는 WSL2가 있는 Windows
Docker: 버전 20.10 이상
Docker Compose: 버전 2.0 이상
메모리: 최소 4GB RAM (8GB 권장)
저장공간: 최소 10GB 여유 공간

방법 1: Docker Compose 배포 (권장)

1단계: 리포지토리 클론

# MaxKB 리포지토리 클론
git clone https://github.com/1Panel-dev/MaxKB.git
cd MaxKB

# 최신 안정 버전으로 전환
git checkout v2

2단계: 환경 변수 구성

# 환경 구성 생성
cp .env.example .env

# 구성 파일 편집
nano .env

필수 환경 변수:

# 데이터베이스 구성
POSTGRES_DB=maxkb
POSTGRES_USER=maxkb
POSTGRES_PASSWORD=your_secure_password

# Redis 구성
REDIS_PASSWORD=your_redis_password

# MaxKB 구성
SECRET_KEY=your_secret_key_here
DEBUG=false
ALLOWED_HOSTS=localhost,127.0.0.1,your-domain.com

# 저장소 구성
MEDIA_ROOT=/opt/maxkb/media
STATIC_ROOT=/opt/maxkb/static

3단계: MaxKB 실행

# 모든 서비스 시작
docker-compose up -d

# 서비스 상태 확인
docker-compose ps

# 로그 보기
docker-compose logs -f

4단계: 초기 설정

# 초기 설정을 위한 컨테이너 접근
docker-compose exec maxkb python manage.py migrate

# 슈퍼유저 계정 생성
docker-compose exec maxkb python manage.py createsuperuser

# 정적 파일 수집
docker-compose exec maxkb python manage.py collectstatic --noinput

방법 2: 수동 설치

1단계: 의존성 설치

# Python 의존성 설치
pip install -r requirements.txt

# 프론트엔드용 Node.js 의존성 설치
cd ui
npm install
npm run build
cd ..

2단계: 데이터베이스 설정

# PostgreSQL 및 pgvector 설치
# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# pgvector 확장 활성화
sudo -u postgres psql
CREATE DATABASE maxkb;
CREATE USER maxkb WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE maxkb TO maxkb;
CREATE EXTENSION vector;
\q

3단계: 구성

# Django 설정 구성
export DATABASE_URL=postgresql://maxkb:your_password@localhost/maxkb
export SECRET_KEY=your_secret_key
export DEBUG=False

# 마이그레이션 실행
python manage.py migrate

# 슈퍼유저 생성
python manage.py createsuperuser

# 개발 서버 시작
python manage.py runserver 0.0.0.0:8000

구성 및 설정

1. 초기 로그인 및 설정

웹 인터페이스 접근: 브라우저에서 http://localhost:8000으로 이동
로그인: 설정 중에 생성한 슈퍼유저 자격 증명 사용
시스템 구성: 초기 시스템 설정 마법사 완료

2. 모델 구성

OpenAI 모델 추가

{
  "provider": "openai",
  "api_key": "your_openai_api_key",
  "base_url": "https://api.openai.com/v1",
  "models": [
    {
      "name": "gpt-4",
      "max_tokens": 8192,
      "temperature": 0.7
    },
    {
      "name": "gpt-3.5-turbo",
      "max_tokens": 4096,
      "temperature": 0.7
    }
  ]
}

로컬 모델 추가 (Ollama)

# Ollama 설치
curl -fsSL https://ollama.ai/install.sh | sh

# 모델 다운로드
ollama pull llama3
ollama pull qwen2

# MaxKB에서 구성
{
  "provider": "ollama",
  "base_url": "http://localhost:11434",
  "models": ["llama3", "qwen2"]
}

3. 지식베이스 설정

문서 업로드 및 처리

지식베이스 생성: 지식베이스 → 새로 만들기로 이동
문서 업로드: PDF, DOCX, TXT, MD 형식 지원
청킹 구성: 청크 크기 및 중복 매개변수 설정
임베딩 모델: 언어에 적합한 임베딩 모델 선택

벡터 데이터베이스 구성

# 벡터 데이터베이스 설정
vector_db:
  type: "pgvector"
  connection:
    host: "localhost"
    port: 5432
    database: "maxkb"
    user: "maxkb"
    password: "your_password"
  embedding:
    model: "text-embedding-ada-002"
    dimensions: 1536

첫 번째 AI 에이전트 생성

1단계: 에이전트 생성

에이전트로 이동: 메인 네비게이션에서 “에이전트” 클릭
새 에이전트 생성: “에이전트 생성” 버튼 클릭
기본 정보:
- 에이전트 이름: “고객 지원 봇”
- 설명: “고객 문의를 위한 AI 어시스턴트”
- 아바타: 사용자 정의 아바타 이미지 업로드

2단계: 모델 선택

{
  "model_provider": "openai",
  "model_name": "gpt-4",
  "temperature": 0.7,
  "max_tokens": 1000,
  "top_p": 1.0,
  "frequency_penalty": 0.0,
  "presence_penalty": 0.0
}

3단계: 지식베이스 통합

지식베이스 선택: 관련 지식베이스 선택
RAG 설정 구성:
- 유사도 임계값: 0.7
- 최대 검색 문서 수: 5
- 검색 전략: “similarity”

4단계: 프롬프트 엔지니어링

시스템 프롬프트:
당신은 [회사명]의 도움이 되는 고객 지원 어시스턴트입니다. 
지식베이스에 접근할 수 있으며 사용 가능한 정보를 바탕으로 
정확하고 도움이 되는 응답을 제공해야 합니다.

가이드라인:
- 항상 정중하고 전문적으로 행동하세요
- 모르는 것이 있으면 인정하고 에스컬레이션을 제안하세요
- 가능한 한 구체적인 해결책을 제공하세요
- 필요할 때 명확한 질문을 하세요

사용 가능한 지식:
{context}

5단계: 에이전트 테스트

테스트 인터페이스: 내장된 채팅 인터페이스를 사용하여 응답 테스트
지식 검색: 관련 문서가 올바르게 검색되는지 확인
응답 품질: 응답의 정확성과 유용성 평가

고급 기능 및 사용자 정의

1. 워크플로우 자동화

MaxKB는 시각적 빌더를 통해 복잡한 워크플로우 자동화를 지원합니다:

다단계 워크플로우 생성

{
  "workflow": {
    "name": "고객 문의 처리기",
    "steps": [
      {
        "id": "intent_detection",
        "type": "classification",
        "model": "gpt-4",
        "prompt": "고객 의도를 분류하세요: 지원, 영업, 결제, 기술"
      },
      {
        "id": "route_to_specialist",
        "type": "conditional",
        "conditions": {
          "지원": "일반_지원_에이전트",
          "기술": "기술_전문가",
          "결제": "결제_에이전트"
        }
      },
      {
        "id": "knowledge_search",
        "type": "rag",
        "knowledge_base": "customer_support_kb",
        "max_results": 3
      },
      {
        "id": "response_generation",
        "type": "generation",
        "model": "gpt-4",
        "template": "다음 컨텍스트를 기반으로: {context}\n\n다음에 대한 도움이 되는 응답을 제공하세요: {query}"
      }
    ]
  }
}

2. API 통합

MaxKB는 시스템 통합을 위한 포괄적인 REST API를 제공합니다:

인증

import requests

# 로그인 및 토큰 획득
login_response = requests.post('http://localhost:8000/api/auth/login/', {
    'username': 'your_username',
    'password': 'your_password'
})
token = login_response.json()['token']

# 인증된 요청을 위한 토큰 사용
headers = {'Authorization': f'Bearer {token}'}

에이전트 상호작용 API

# 에이전트에게 메시지 전송
def chat_with_agent(agent_id, message, conversation_id=None):
    url = f'http://localhost:8000/api/agents/{agent_id}/chat/'
    payload = {
        'message': message,
        'conversation_id': conversation_id
    }
    
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

# 사용 예시
result = chat_with_agent(
    agent_id='123',
    message='비밀번호를 재설정하는 방법은 무엇인가요?',
    conversation_id='conv_456'
)

print(result['response'])

지식베이스 관리

# 지식베이스에 문서 업로드
def upload_document(kb_id, file_path):
    url = f'http://localhost:8000/api/knowledge-bases/{kb_id}/documents/'
    
    with open(file_path, 'rb') as file:
        files = {'file': file}
        response = requests.post(url, files=files, headers=headers)
    
    return response.json()

# 지식베이스 검색
def search_knowledge(kb_id, query, limit=5):
    url = f'http://localhost:8000/api/knowledge-bases/{kb_id}/search/'
    payload = {
        'query': query,
        'limit': limit,
        'threshold': 0.7
    }
    
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

3. 사용자 정의 모델 통합

사용자 정의 LLM 제공자 추가

# 예시: 사용자 정의 모델 제공자 통합
class CustomModelProvider:
    def __init__(self, api_key, base_url):
        self.api_key = api_key
        self.base_url = base_url
    
    def generate_response(self, prompt, model_config):
        headers = {
            'Authorization': f'Bearer {self.api_key}',
            'Content-Type': 'application/json'
        }
        
        payload = {
            'model': model_config['model'],
            'prompt': prompt,
            'max_tokens': model_config.get('max_tokens', 1000),
            'temperature': model_config.get('temperature', 0.7)
        }
        
        response = requests.post(
            f'{self.base_url}/completions',
            headers=headers,
            json=payload
        )
        
        return response.json()['choices'][0]['text']

# 사용자 정의 제공자 등록
custom_provider = CustomModelProvider(
    api_key='your_custom_api_key',
    base_url='https://your-custom-llm-api.com/v1'
)

프로덕션 배포

1. 환경 준비

프로덕션 시스템 요구사항

CPU: 4개 이상의 코어 권장
메모리: 최적 성능을 위해 16GB 이상 RAM
저장공간: 100GB 이상 사용 가능한 SSD
네트워크: 모델 API를 위한 안정적인 인터넷 연결

보안 구성

# docker-compose.prod.yml
version: '3.8'
services:
  maxkb:
    image: maxkb:latest
    environment:
      - DEBUG=false
      - ALLOWED_HOSTS=your-domain.com
      - SECURE_SSL_REDIRECT=true
      - SECURE_HSTS_SECONDS=31536000
      - SECURE_CONTENT_TYPE_NOSNIFF=true
      - SECURE_BROWSER_XSS_FILTER=true
    volumes:
      - ./ssl:/etc/ssl/certs
    ports:
      - "443:8000"

2. 로드 밸런싱 및 확장

Nginx 구성

upstream maxkb_backend {
    server maxkb_1:8000;
    server maxkb_2:8000;
    server maxkb_3:8000;
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /etc/ssl/certs/your-domain.crt;
    ssl_certificate_key /etc/ssl/private/your-domain.key;
    
    location / {
        proxy_pass http://maxkb_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    location /static/ {
        alias /opt/maxkb/static/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

3. 모니터링 및 유지보수

상태 확인 스크립트

#!/bin/bash
# health_check.sh

MAXKB_URL="https://your-domain.com"
HEALTH_ENDPOINT="/api/health/"

# 서비스 가용성 확인
response=$(curl -s -o /dev/null -w "%{http_code}" "${MAXKB_URL}${HEALTH_ENDPOINT}")

if [ $response -eq 200 ]; then
    echo "✅ MaxKB가 정상입니다"
    exit 0
else
    echo "❌ MaxKB 상태 확인 실패 (HTTP $response)"
    # 모니터링 시스템에 알림 전송
    # curl -X POST "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK" \
    #      -H 'Content-type: application/json' \
    #      --data '{"text":"MaxKB 상태 확인 실패"}'
    exit 1
fi

로그 관리

# 로그 순환 구성
echo "/opt/maxkb/logs/*.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 644 maxkb maxkb
    postrotate
        docker-compose restart maxkb
    endscript
}" > /etc/logrotate.d/maxkb

일반적인 문제 해결

1. 설치 문제

Docker 권한 문제

# 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER
newgrp docker

# docker 접근 확인
docker run hello-world

메모리 문제

# 시스템 메모리 확인
free -h

# 필요시 스왑 증가
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

2. 모델 구성 문제

API 키 검증

# OpenAI API 연결 테스트
import openai

try:
    client = openai.OpenAI(api_key="your_api_key")
    response = client.models.list()
    print("✅ API 연결 성공")
    print(f"사용 가능한 모델: {[model.id for model in response.data]}")
except Exception as e:
    print(f"❌ API 연결 실패: {e}")

로컬 모델 문제

# Ollama 서비스 확인
systemctl status ollama

# 필요시 Ollama 재시작
systemctl restart ollama

# 모델 가용성 테스트
ollama list
ollama run llama3 "안녕하세요, 어떻게 지내세요?"

3. 성능 최적화

데이터베이스 최적화

-- PostgreSQL 성능 튜닝
-- postgres 사용자로 실행

-- 벡터 검색을 위한 인덱스 생성
CREATE INDEX CONCURRENTLY idx_documents_embedding 
ON documents USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

-- 테이블 통계 분석
ANALYZE documents;

-- 인덱스 사용량 확인
SELECT schemaname, tablename, indexname, idx_scan, idx_tup_read, idx_tup_fetch
FROM pg_stat_user_indexes
WHERE schemaname = 'public';

캐싱 구성

# 향상된 성능을 위한 Redis 캐싱
CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': 'redis://localhost:6379/1',
        'OPTIONS': {
            'CLIENT_CLASS': 'django_redis.client.DefaultClient',
        },
        'KEY_PREFIX': 'maxkb',
        'TIMEOUT': 3600,  # 1시간 기본 타임아웃
    }
}

# 자주 접근하는 데이터 캐싱
@cache_page(300)  # 5분간 캐시
def get_agent_config(agent_id):
    return Agent.objects.get(id=agent_id).config

모범 사례 및 팁

1. 에이전트 설계 가이드라인

효과적인 프롬프트 엔지니어링

구체적으로 작성: 에이전트의 역할과 기능을 명확히 정의
컨텍스트 제공: 관련 배경 정보 포함
경계 설정: 에이전트가 하지 말아야 할 것을 명시적으로 기술
예시 사용: 복잡한 작업에 대한 few-shot 예시 포함

지식베이스 구성

# 지식베이스를 위한 권장 폴더 구조

고객 지원/
├── 자주묻는질문/
│   ├── 계정_문제.md
│   ├── 결제_질문.md
│   └── 기술_문제.md
├── 정책/
│   ├── 환불_정책.md
│   ├── 개인정보_정책.md
│   └── 이용약관.md
└── 절차/
    ├── 비밀번호_재설정.md
    ├── 계정_설정.md
    └── 문제해결_가이드.md

2. 보안 모범 사례

API 보안

# 속도 제한 구현
from django_ratelimit.decorators import ratelimit

@ratelimit(key='ip', rate='100/h', method='POST')
def chat_endpoint(request):
    # API 엔드포인트 구현
    pass

# 입력 검증
def validate_message(message):
    if len(message) > 4000:
        raise ValidationError("메시지가 너무 깁니다")
    
    # 잠재적으로 해로운 콘텐츠 제거
    cleaned_message = bleach.clean(message, strip=True)
    return cleaned_message

데이터 프라이버시

# 데이터 보존 정책 구현
from celery import task
from datetime import datetime, timedelta

@task
def cleanup_old_conversations():
    cutoff_date = datetime.now() - timedelta(days=90)
    Conversation.objects.filter(
        created_at__lt=cutoff_date,
        is_archived=True
    ).delete()

3. 성능 최적화

벡터 검색 최적화

# 벡터 유사도 검색 최적화
class OptimizedVectorSearch:
    def __init__(self, embedding_model, vector_db):
        self.embedding_model = embedding_model
        self.vector_db = vector_db
        self.cache = {}
    
    def search(self, query, limit=5, threshold=0.7):
        # 먼저 캐시 확인
        cache_key = f"{hash(query)}_{limit}_{threshold}"
        if cache_key in self.cache:
            return self.cache[cache_key]
        
        # 쿼리 임베딩 생성
        query_embedding = self.embedding_model.encode(query)
        
        # 필터와 함께 벡터 검색 수행
        results = self.vector_db.similarity_search(
            query_embedding,
            limit=limit,
            threshold=threshold,
            filter={'status': 'active'}
        )
        
        # 결과 캐시
        self.cache[cache_key] = results
        return results

결론

MaxKB는 기업 AI 에이전트 개발에서 중요한 발전을 나타내며, 강력함과 사용성의 균형을 맞춘 포괄적인 플랫폼을 제공합니다. 오픈소스 특성과 기업급 기능의 결합으로 대규모 AI 에이전트 구현을 원하는 조직에게 탁월한 선택지가 됩니다.

핵심 요점

다재다능한 플랫폼: MaxKB는 고객 지원부터 복잡한 워크플로우 자동화까지 광범위한 사용 사례를 지원
확장 가능한 아키텍처: 적절한 배포와 최적화를 통해 기업 수준의 요구사항을 처리하도록 구축
활발한 커뮤니티: 강력한 커뮤니티 지원과 정기적인 업데이트로 지속적인 개선 보장
비용 효율적: 오픈소스 라이선스로 독점 솔루션 대비 총 소유 비용 절감

다음 단계

MaxKB 여정을 계속하려면:

실험: 간단한 에이전트부터 시작하여 점진적으로 복잡성 증가
커뮤니티 참여: 지원과 기여를 위해 GitHub의 MaxKB 커뮤니티 참여
문서화: 고급 기능을 위한 공식 문서 탐색
사용자 정의 개발: 프로젝트 기여 또는 사용자 정의 확장 개발 고려

추가 리소스

공식 웹사이트: maxkb.cn
GitHub 리포지토리: github.com/1Panel-dev/MaxKB
커뮤니티 포럼: GitHub Discussions를 통해 이용 가능
문서: 리포지토리에서 포괄적인 가이드 제공

MaxKB는 조직이 제어, 보안, 유연성을 유지하면서 AI 에이전트의 전체 잠재력을 활용할 수 있도록 지원합니다. 고객 지원 봇, 내부 지식 어시스턴트, 복잡한 자동화 워크플로우 구축 여부에 관계없이 MaxKB는 성공에 필요한 도구와 프레임워크를 제공합니다.

이 튜토리얼은 포괄적인 AI 및 자동화 시리즈의 일부입니다. 더 고급 튜토리얼과 기업 AI 솔루션은 Thaki Cloud를 방문하세요.

MaxKB 소개

MaxKB의 특별함

기술 아키텍처 개요

핵심 기술 스택

주요 기능

설치 및 설정 가이드

전제 조건

방법 1: Docker Compose 배포 (권장)

1단계: 리포지토리 클론

2단계: 환경 변수 구성

3단계: MaxKB 실행

4단계: 초기 설정

방법 2: 수동 설치

1단계: 의존성 설치

2단계: 데이터베이스 설정

3단계: 구성

구성 및 설정

1. 초기 로그인 및 설정

2. 모델 구성

OpenAI 모델 추가

로컬 모델 추가 (Ollama)

3. 지식베이스 설정

문서 업로드 및 처리

벡터 데이터베이스 구성

첫 번째 AI 에이전트 생성

1단계: 에이전트 생성

2단계: 모델 선택

3단계: 지식베이스 통합

4단계: 프롬프트 엔지니어링

5단계: 에이전트 테스트

고급 기능 및 사용자 정의

1. 워크플로우 자동화

다단계 워크플로우 생성

2. API 통합

인증

에이전트 상호작용 API

지식베이스 관리

3. 사용자 정의 모델 통합

사용자 정의 LLM 제공자 추가

프로덕션 배포

1. 환경 준비

프로덕션 시스템 요구사항

보안 구성

2. 로드 밸런싱 및 확장

Nginx 구성

3. 모니터링 및 유지보수

상태 확인 스크립트

로그 관리

일반적인 문제 해결

1. 설치 문제

Docker 권한 문제

메모리 문제

2. 모델 구성 문제

API 키 검증

로컬 모델 문제

3. 성능 최적화

데이터베이스 최적화

캐싱 구성

모범 사례 및 팁

1. 에이전트 설계 가이드라인

효과적인 프롬프트 엔지니어링

지식베이스 구성

2. 보안 모범 사례

API 보안

데이터 프라이버시

3. 성능 최적화

벡터 검색 최적화

결론

핵심 요점

다음 단계

추가 리소스

참고

UltraRAG 완전 튜토리얼: 로우코드 프레임워크로 고급 RAG 시스템 구축하기

Strix AI 보안 테스팅: 자율적 취약점 탐지를 위한 완전 가이드

opcode: Claude Code 데스크톱 GUI 완전 가이드

Magic Resume: AI 기반 이력서 편집기 완전 가이드