Docker로 Dify 설치하고 나만의 AI 에이전트 만들기 — 로컬 환경 구축부터 워크플로우 자동화까지

로컬 환경 구축부터 워크플로우 자동화까지

Dify는 오픈소스 AI 애플리케이션 개발 플랫폼으로, 코드를 거의 작성하지 않고도 AI 에이전트와 워크플로우를 구축할 수 있습니다. OpenAI, Claude, Gemini 등 다양한 LLM을 통합하고, 시각적 인터페이스로 복잡한 AI 로직을 조합할 수 있죠.

이 글에서는 Docker를 이용해 로컬 환경에 Dify를 설치하고, 실제로 동작하는 AI 에이전트를 만드는 전체 과정을 단계별로 설명합니다. 환경 설정부터 LLM API 연결, 첫 번째 워크플로우 생성까지 실제 경험을 바탕으로 작성했습니다.

이 튜토리얼을 따라가면, 자신만의 로컬 AI 플랫폼을 구축하고, 자동화된 워크플로우를 실행할 수 있게 됩니다. Mac, Linux, Windows 모두에서 작동합니다.

목차

• Docker 사전 준비사항
• docker-compose로 Dify 설치하기
• Dify 초기 설정 및 접근
• LLM API 연결 (OpenAI, Anthropic Claude)
• 첫 번째 AI 에이전트 워크플로우 만들기
• 실전 예제: 텍스트 분석 에이전트
• 문제 해결 및 트러블슈팅

1. Docker 사전 준비사항

Dify를 Docker로 실행하려면 먼저 Docker와 Docker Compose가 설치되어 있어야 합니다. 만약 아직 설치하지 않았다면, 공식 웹사이트에서 다운로드받을 수 있습니다.

Docker 설치 확인

터미널을 열고 다음 명령어로 Docker가 제대로 설치되었는지 확인합니다:

docker --version
docker-compose --version

정상 설치 시 버전 정보가 출력됩니다. 만약 명령을 찾을 수 없다는 에러가 나면, Docker를 다시 설치해야 합니다.

Docker 데몬 실행

Docker 명령어를 실행하기 전에 Docker 데몬이 실행 중이어야 합니다. Mac과 Windows에서는 Docker Desktop을 실행하면 자동으로 시작됩니다. Linux 사용자는 다음 명령어로 데몬을 시작합니다:

sudo systemctl start docker
sudo systemctl enable docker

데몬이 실행 중인지 확인하려면:

docker ps

이 명령어가 실행되면 Docker 데몬이 정상 작동 중입니다.

시스템 요구사항

Dify 실행에 필요한 최소 요구사항은 다음과 같습니다:

• CPU: 2코어 이상 권장
• 메모리: 4GB 이상 권장 (8GB 이상 권장)
• 디스크: 20GB 이상의 여유 공간
• Docker: 20.10 이상
• Docker Compose: 1.29 이상

2. docker-compose로 Dify 설치하기

Dify는 여러 마이크로서비스로 구성되어 있으며, Docker Compose를 사용하면 한 번에 모든 서비스를 관리할 수 있습니다. 공식 저장소에서 docker-compose.yml을 다운로드하는 것이 가장 간단합니다.

Dify 저장소 클론하기

먼저 Dify 공식 저장소를 클론합니다:

git clone https://github.com/langgenius/dify.git
cd dify/docker

docker 디렉토리로 이동하면 필요한 설정 파일들을 찾을 수 있습니다.

환경 설정 파일 준비

Dify를 실행하기 전에 환경 변수를 설정해야 합니다. docker 디렉토리에서 .env.example 파일을 복사합니다:

cp .env.example .env

.env 파일을 텍스트 에디터로 열어 주요 설정을 확인합니다. 로컬 개발 환경에서는 다음과 같이 설정하면 됩니다:

# .env 파일의 주요 설정
EXPOSE_API_PORT=5001
EXPOSE_API_KEY=sk-dify-local-testing
POSTGRES_PASSWORD=dify-postgres-password
REDIS_PASSWORD=dify-redis-password
DIFY_VERSION=0.6.0

프로덕션 환경에서는 반드시 안전한 암호를 생성하고 설정해야 합니다.

docker-compose.yml 구조

Dify의 docker-compose.yml 파일은 다음과 같은 서비스들로 구성됩니다:

version: '3.8'

services:
  # PostgreSQL 데이터베이스
  postgres:
    image: postgres:15.0-alpine
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  # Redis 캐시
  redis:
    image: redis:7.0-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"

  # Dify 백엔드 API
  dify-api:
    image: langgenius/dify-api:${DIFY_VERSION}
    environment:
      DATABASE_URL: postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/dify
      REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379/0
    ports:
      - "5001:5001"
    depends_on:
      - postgres
      - redis

  # Dify 웹 프론트엔드
  dify-web:
    image: langgenius/dify-web:${DIFY_VERSION}
    ports:
      - "3000:3000"
    depends_on:
      - dify-api

volumes:
  postgres_data:
  redis_data:

이것은 기본 구조입니다. 실제 docker-compose.yml 파일은 더 많은 환경 변수와 설정을 포함합니다.

Docker Compose로 Dify 시작하기

이제 실제로 Dify를 실행합니다. docker 디렉토리에서 다음 명령어를 실행합니다:

docker-compose up -d

-d 플래그는 백그라운드에서 실행한다는 의미입니다. 모든 이미지가 다운로드되고 컨테이너가 시작될 때까지 몇 분 기다립니다.

실행 상태 확인

서비스 상태를 확인하려면:

docker-compose ps

모든 서비스가 Up 상태여야 합니다. 만약 특정 서비스가 실패했다면, 다음 명령어로 로그를 확인합니다:

docker-compose logs dify-api
docker-compose logs dify-web

3. Dify 초기 설정 및 접근

Docker 서비스가 모두 시작되면, 웹 브라우저에서 Dify에 접근할 수 있습니다.

웹 인터페이스 접근

브라우저를 열고 다음 주소로 이동합니다:

http://localhost:3000

첫 번째 접근 시 Dify 초기 설정 화면이 나타납니다. 사용자 계정을 생성하고 조직 이름을 입력합니다.

초기 계정 생성

초기 관리자 계정을 설정합니다. 메일 주소와 비밀번호를 입력하면, 이후로 이 계정으로 로그인할 수 있습니다. 로컬 개발 환경이므로 아무 메일 주소나 입력해도 됩니다.

데이터베이스 마이그레이션

Dify가 처음 시작될 때 자동으로 데이터베이스 테이블이 생성됩니다. 이 과정은 몇 초 정도 걸립니다. 만약 데이터베이스 연결 에러가 발생하면, 다음 명령어로 수동으로 마이그레이션을 실행할 수 있습니다:

docker-compose exec dify-api flask db upgrade

API 접근 확인

Dify API는 포트 5001에서 실행 중입니다. 다음 명령어로 API 상태를 확인할 수 있습니다:

curl http://localhost:5001/health

정상 응답이 돌아오면 API도 정상 작동 중입니다.

4. LLM API 연결 (OpenAI, Anthropic Claude)

Dify에서 AI 기능을 사용하려면 LLM API를 연결해야 합니다. 가장 일반적으로 사용되는 OpenAI와 Anthropic Claude를 연결하는 방법을 설명합니다.

OpenAI API 키 설정

Dify 웹 인터페이스의 설정 메뉴에 접근합니다. 좌측 네비게이션 메뉴에서 "설정"을 클릭합니다.

모델 공급자 섹션에서 OpenAI를 찾아 클릭합니다. OpenAI API 키를 입력해야 합니다. OpenAI 계정이 없다면 platform.openai.com에서 생성할 수 있습니다.

# .env 파일에 환경 변수로 설정할 수도 있습니다
OPENAI_API_KEY=sk-your-actual-api-key-here
OPENAI_API_BASE=https://api.openai.com/v1

OpenAI API 키를 준비했다면, Dify 설정 화면에 붙여넣습니다. "테스트" 버튼을 클릭해 연결이 정상인지 확인합니다.

Anthropic Claude API 연결

Claude를 사용하려면 먼저 Anthropic 계정을 만들고 API 키를 생성해야 합니다. console.anthropic.com에서 API 키를 발급받을 수 있습니다.

Dify 설정에서 "모델 공급자"를 찾아 Anthropic을 선택합니다. 발급받은 API 키를 입력합니다:

# .env 파일의 설정 예시
ANTHROPIC_API_KEY=sk-ant-your-actual-key-here

역시 "테스트" 버튼으로 연결을 확인합니다.

여러 LLM 모델 관리

Dify의 강점은 여러 LLM을 동시에 관리할 수 있다는 것입니다. 워크플로우를 구축할 때 상황에 맞게 다른 모델을 선택할 수 있습니다. 예를 들어, 빠른 응답이 필요한 경우 GPT-3.5를 사용하고, 복잡한 분석이 필요한 경우 GPT-4를 사용할 수 있습니다.

5. 첫 번째 AI 에이전트 워크플로우 만들기

이제 실제로 Dify에서 AI 에이전트를 만들어봅시다. Dify는 두 가지 주요 기능을 제공합니다: Applications과 Workflows입니다. 우리는 Workflow를 사용해 더 복잡한 자동화를 구축할 것입니다.

새로운 Workflow 생성

Dify 웹 인터페이스에서 "Workflows" 메뉴를 클릭합니다. "Create New" 버튼을 클릭해 새 워크플로우를 시작합니다. 워크플로우 이름은 "간단한 텍스트 분석기"로 설정합니다.

기본 노드 이해하기

Dify의 워크플로우는 노드 기반입니다. 주요 노드 타입들은 다음과 같습니다:

• Start: 워크플로우의 입력 정의
• LLM: 언어 모델 호출
• Code: 파이썬 코드 실행
• Condition: 조건부 분기
• End: 워크플로우의 출력 정의

Start 노드 설정

워크플로우 캔버스에 Start 노드가 기본으로 있습니다. 이 노드를 클릭해 입력값을 설정합니다. "Add Variable"을 클릭하고 다음과 같이 설정합니다:

변수명: text
타입: String
설명: 분석할 텍스트
필수: Yes

LLM 노드 추가

오른쪽의 노드 팔레트에서 "LLM" 노드를 드래그해 캔버스에 놓습니다. 이 노드를 "분석기"라고 이름 지으면 됩니다.

LLM 노드의 설정 패널에서:

• Model: gpt-4 (또는 사용 가능한 최신 모델)
• System Prompt: "당신은 전문적인 텍스트 분석가입니다. 입력된 텍스트의 감정, 핵심 주제, 그리고 주요 엔티티를 분석하세요."
• User Message: "다음 텍스트를 분석해주세요: {{text}}" (여기서 {{text}}는 Start 노드의 변수를 참조)

End 노드 설정

LLM 노드를 End 노드에 연결합니다. End 노드에서 "Add Output"을 클릭하고, LLM 노드의 결과를 선택합니다:

Output name: analysis_result
Type: String
Value: {{분석기.text}}

워크플로우 실행 및 테스트

워크플로우를 저장하고 "Run" 버튼을 클릭해 테스트합니다. 테스트 입력으로 다음과 같은 텍스트를 입력해봅시다:

"나는 이 제품에 매우 만족합니다. 품질이 뛰어나고 가격도 합리적입니다."

몇 초 후 LLM이 분석한 결과가 표시됩니다. 감정, 핵심 주제, 엔티티가 정확하게 분석되었는지 확인합니다.

6. 실전 예제: 텍스트 분석 에이전트

이제 좀 더 복잡한 예제를 만들어봅시다. 사용자 피드백을 분석하고 자동으로 카테고리를 분류하는 에이전트입니다.

다단계 워크플로우 설계

이 워크플로우는 다음과 같은 단계를 거칩니다:

1. 입력 텍스트 받기
2. 감정 분석 (긍정/부정/중립)
3. 조건에 따라 다른 처리
4. 피드백 카테고리 분류
5. 결과 정리 및 출력

Condition 노드 사용

워크플로우에 "Condition" 노드를 추가합니다. 이 노드는 LLM의 출력을 기반으로 워크플로우를 분기시킵니다.

첫 번째 LLM 노드에서 감정을 분석한 후, Condition 노드에서 다음과 같이 설정합니다:

조건: 감정이 "부정" 또는 "매우 부정"
참: "즉시 처리" 경로로 이동
거짓: "일반 처리" 경로로 이동

Code 노드로 커스텀 로직 추가

Condition의 거짓(일반 처리) 경로에 Code 노드를 추가합니다. Python으로 추가 처리를 할 수 있습니다:

import json
from datetime import datetime

# 입력값
text = "{{ start.text }}"
sentiment = "{{ analyzer.sentiment }}"

# 커스텀 처리
result = {
    "processed_at": datetime.now().isoformat(),
    "text": text,
    "sentiment": sentiment,
    "priority": "high" if sentiment in ["negative", "very_negative"] else "normal",
    "needs_review": sentiment in ["negative", "very_negative"]
}

return json.dumps(result)

분류 LLM 노드

다시 LLM 노드를 추가해 피드백을 카테고리로 분류합니다:

Model: gpt-3.5-turbo
System Prompt: "주어진 피드백을 다음 중 하나로 분류하세요:
- 제품 품질
- 배송/물류
- 고객 서비스
- 가격
- 기타"

User Message: "피드백: {{ start.text }}
감정: {{ first_analyzer.sentiment }}
분류 결과:"

최종 End 노드

모든 처리 경로가 End 노드로 수렴하도록 설정합니다:

output_analysis: {{분석_노드.output}}
output_category: {{분류_노드.output}}
output_code: {{커스텀_코드_노드.output}}
timestamp: {{시간_함수.current_time}}

워크플로우 테스트

완성된 워크플로우를 테스트해봅시다. 여러 가지 예시 텍스트를 입력해 정상 작동하는지 확인합니다:

예제 1: "배송이 너무 오래 걸렸습니다. 1주일을 기다렸어요."
예제 2: "정말 좋은 제품입니다. 추천합니다!"
예제 3: "가격은 비싼데 품질이 별로네요."

각 예제에 대해 워크플로우가 올바르게 감정을 분석하고 카테고리를 분류하는지 확인합니다.

7. 문제 해결 및 트러블슈팅

Dify를 사용하다 보면 여러 문제가 발생할 수 있습니다. 가장 흔한 문제들과 해결 방법을 정리했습니다.

Docker 서비스가 시작되지 않는 경우

다음 명령어로 로그를 확인합니다:

docker-compose logs -f

가장 흔한 원인들:

• 포트 충돌: 포트 3000, 5001, 5432가 이미 사용 중인지 확인합니다. 사용 중이면 docker-compose.yml에서 포트를 변경합니다.
• 메모리 부족: Docker에 충분한 메모리가 할당되었는지 확인합니다. Docker Desktop 설정에서 메모리를 증가시킵니다.
• 디스크 부족: 시스템의 여유 디스크 공간을 확인합니다.

API 연결 실패

OpenAI나 Claude API 연결이 실패하면:

# API 키가 정확한지 확인합니다
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.openai.com/v1/models

# Dify API 로그 확인
docker-compose logs dify-api

가장 흔한 원인:

• 잘못된 API 키: 키를 다시 확인하고 공백이 없는지 확인합니다.
• API 비용 초과: 계정의 크레딧을 확인합니다.
• IP 차단: API 제공자에서 IP를 차단했을 수 있습니다.

워크플로우 실행 오류

워크플로우를 실행했을 때 오류가 발생하면:

• 변수 참조 오류: {{변수명}}이 정확한지 확인합니다. 변수명은 대소문자를 구분합니다.
• 타입 불일치: 노드 간의 입출력 타입이 맞는지 확인합니다.
• Code 노드 에러: Python 문법 오류가 없는지 확인합니다.

데이터베이스 연결 문제

PostgreSQL 연결이 실패한 경우:

# 데이터베이스 상태 확인
docker-compose exec postgres pg_isready

# 강제 재시작
docker-compose down
docker-compose up -d

성능 최적화

Dify가 느리게 작동하면:

• Redis 캐시 확인: Redis 서비스가 정상 작동 중인지 확인합니다.
• 데이터베이스 쿼리 최적화: 장시간 워크플로우가 필요한 경우 비동기 처리를 고려합니다.
• LLM 모델 변경: gpt-4보다 gpt-3.5-turbo가 더 빠릅니다.

메모리 누수

Docker 프로세스가 시간이 지남에 따라 더 많은 메모리를 사용하면:

# 컨테이너 재시작
docker-compose restart

# 또는 전체 재시작
docker-compose down
docker-compose up -d

로그 모니터링

정상 작동을 확인하기 위해 로그를 모니터링합니다:

# 실시간 로그 확인
docker-compose logs -f dify-api

# 특정 서비스의 마지막 100줄
docker-compose logs --tail 100 dify-web

# 에러만 필터링
docker-compose logs dify-api | grep -i error

결론

이 튜토리얼에서는 Docker를 이용해 로컬 환경에 Dify를 설치하고, OpenAI와 Claude API를 연결하며, 실제로 동작하는 AI 워크플로우를 만드는 전 과정을 다루었습니다.

Dify의 장점은 코드를 거의 작성하지 않고도 강력한 AI 애플리케이션을 구축할 수 있다는 것입니다. 노드 기반 인터페이스는 직관적이면서도 매우 유연해서, 간단한 자동화부터 복잡한 멀티스텝 워크플로우까지 모두 구현할 수 있습니다.

다음 단계로 추천하는 것은:

• 더 많은 LLM 모델을 통합해 비교 분석해보기
• Webhook을 이용해 외부 시스템과 연동하기
• 지식 베이스(Knowledge Base)를 추가해 RAG 시스템 구축하기
• 완성된 워크플로우를 Docker 이미지로 패키징하기

Dify 커뮤니티도 매우 활발하므로, 어려움이 생기면 공식 문서나 GitHub 이슈를 참고하면 좋습니다. 행운을 빕니다!

이 글에 소개된 서비스와 도구는 작성 시점 기준이며, 업데이트에 따라 변경될 수 있습니다.