Skip to main content
지식기반에 대용량 파일을 업로드하면 텍스트 추출, 청킹, 임베딩 생성, 벡터 DB 저장까지 상당한 시간이 걸립니다. 이 작업이 메인 서버에서 실행되면 다른 사용자의 채팅 응답도 느려질 수 있습니다. 외부 워커는 이런 무거운 백그라운드 작업을 별도 프로세스로 분리합니다. Redis Streams를 통해 작업 큐를 관리하며, 워커가 없으면 메인 서버가 기존처럼 직접 처리합니다.
구분워커 미사용워커 사용
파일 처리메인 서버에서 직접외부 워커가 처리
채팅 영향동시 사용 시 느려짐영향 없음
확장성서버 1대 한계워커 수평 확장 가능

​
설정

관리자 > 설정 > 외부 워커 탭에서 설정합니다.

​
활성화

External Worker 스위치를 켜면 지원되는 작업이 Redis 큐로 전달됩니다.
활성화 전에 Redis 서버가 연결되어 있어야 합니다. 연결 상태는 설정 화면 상단의 Redis Status에서 확인할 수 있습니다.

​
작업 유형 선택

워커에 위임할 작업 유형을 선택합니다. 선택하지 않은 작업은 메인 서버에서 직접 처리됩니다.
작업 유형설명
Knowledge File Processing텍스트 추출, 청킹, 임베딩 생성, 벡터 DB 저장
DB Schema ExtractionDbSphere의 LLM 기반 테이블/컬럼 설명 자동 생성
Scheduled Task Execution에이전트, 모델, 대시보드 예약 작업 실행
Auto EvaluationJudge LLM 기반 대화 품질 자동 평가

​
워커 서비스 키

외부 워커가 메인 서버에 콜백(처리 완료 알림)을 보낼 때 인증에 사용하는 API 키입니다.
1

키 생성

Generate Key 버튼을 클릭하면 sk-worker- 접두사의 키가 생성됩니다.
2

키 복사

생성된 키를 복사하여 워커의 환경 변수(WORKER_CALLBACK_API_KEY)에 설정합니다.
키를 **폐기(Revoke)**하면 해당 키를 사용하는 모든 워커가 즉시 인증에 실패합니다. 새 키를 생성하고 워커에 다시 설정해야 합니다.

​
큐 모니터링

설정 화면에서 현재 큐 상태를 실시간으로 확인할 수 있습니다.
지표설명
Redis StatusRedis 서버 연결 상태
Total큐에 있는 전체 작업 수
Pending아직 처리되지 않은 대기 작업 수
Consumers현재 연결된 워커(소비자) 수
큐 작업 목록: 대기 중인 작업을 개별 삭제하거나, Clear Queue로 전체 대기열을 비울 수 있습니다.

​
파일 처리 현황

워커가 처리 중이거나 최근 실패한 파일 목록을 확인할 수 있습니다.
상태설명
processing현재 워커에서 처리 중
queued큐에 등록되어 대기 중
failed처리 실패 — 재시도 가능
실패한 파일은 재업로드 없이 재시도할 수 있습니다.

​
워커 배포

외부 워커는 Docker 컨테이너로 배포합니다.

​
환경 변수

변수설명예시
REDIS_URLRedis 서버 연결 URLredis://host.docker.internal:6379/0
WORKER_NAME워커 식별 이름worker-docker
WORKER_CONCURRENT_TASKS동시 처리 작업 수4
WORKER_CALLBACK_URL메인 서버 URL (콜백용)http://host.docker.internal:8080
WORKER_CALLBACK_API_KEY위에서 생성한 서비스 키sk-worker-...

​
Docker Compose 실행

docker-compose -f docker-compose.worker.yml up -d
워커는 메인 서버와 동일한 .env 파일을 사용합니다. 벡터 DB, LLM API 등의 설정이 메인 서버와 일치해야 파일 처리가 정상 동작합니다.

​
동작 원리

사용자가 파일 업로드
    ↓
메인 서버: Redis Streams에 작업 등록
    ↓
외부 워커: 큐에서 작업 수신
    ↓
워커: 텍스트 추출 → 청킹 → 임베딩 → 벡터 DB 저장
    ↓
워커: 메인 서버에 콜백 (처리 완료/실패 알림)
    ↓
메인 서버: 파일 상태 업데이트 → 사용자에게 알림
워커가 연결되지 않거나 Redis가 비활성화된 경우, 메인 서버가 자동으로 **폴백(fallback)**하여 직접 처리합니다. 워커 장애가 서비스 중단으로 이어지지 않습니다.

​
관련 페이지

지식기반

파일 업로드 및 RAG 설정

예약 작업

워커가 처리하는 예약 작업 설정

데이터베이스

스키마 추출 대상인 DbSphere 설정