본문으로 건너뛰기

제약 사항

제품 사용 중 만날 수 있는 알려진 제약과 그 대응 방법을 정리한다. "개선 예정" 표기 항목은 로드맵에 반영되어 있으며 버전 업데이트 시 이 문서가 갱신된다.

1. 운영 배포는 Dagster 모드를 사용해야 한다​

경량 실행 모드(queue_worker.enabled: true, Dagster 없이 API 서버 내장 워커로 인제스트)는 평가·개발 용도다. 이 모드에서는 이미 실행이 시작된 인제스트 작업을 중단할 수 없다 — 문서 강제 실패 처리나 커넥터 동기화 중단을 호출해도 백그라운드 작업이 끝까지 실행되어 상태를 덮어쓸 수 있다 (강제 실패 API는 이 경우 응답에 경고 필드를 포함한다).

대응: 운영 환경은 Dagster 모드(기본값)로 배포한다. Dagster 모드에서는 실행 중 작업의 강제 종료·복구가 완전하게 지원된다.

2. 유사 문서를 동시에 대량 업로드하면 중복 감지가 누락될 수 있다​

중복 문서 감지는 이미 저장된 문서와 비교하는 방식이라, 내용이 유사한 문서 여러 건이 같은 순간에 병렬로 인제스트되면 서로를 중복으로 인식하지 못할 수 있다. (개선 예정)

대응: 유사 문서가 많은 대량 초기 적재는 배치 단위로 나눠 순차 업로드한다. 이미 중복이 들어간 경우 해당 문서를 삭제 후 재업로드하면 정상 감지된다.

3. 커넥터 동기화 중단 시 문서 1건이 처리될 수 있다​

동기화 중단(abort) 요청이 내부 처리의 아주 짧은 순간과 겹치면, 이미 큐에서 꺼내진 문서 1건이 중단 대상에서 빠져 정상 처리될 수 있다. 데이터 정합성 문제는 아니며, 해당 문서만 의도와 달리 인덱싱된 상태로 남는다.

대응: 필요 시 해당 문서를 개별 삭제한다.

4. 문서 삭제 직후 즉시 재인덱싱하면 실패로 남을 수 있다​

삭제가 완료되기 전에 같은 문서의 재인덱싱을 요청하면, 원본 파일이 이미 삭제되어 인제스트가 실패할 수 있다. 실패한 문서는 이미 삭제된 상태이므로 검색·목록에 노출되지 않으며 데이터 정합성에는 영향이 없다.

대응: 삭제 완료(문서 상태 deleted 또는 404 확인) 후 재업로드한다.

5. 커넥터의 일시적 수집 오류는 다음 동기화에서 자동 재시도된다​

Confluence 첨부파일 목록 조회 등에서 일시적 네트워크 오류가 나면 해당 페이지만 건너뛰고 동기화는 계속 진행된다. 페이지 단위 실패는 다음 동기화에서 자동 재수집되므로 데이터가 영구 유실되지 않는다. 단, 동일 항목이 매번 실패하는 경우(권한 문제 등)는 현재 API로 노출되지 않고 서버 로그에만 남는다. (가시성 개선 예정)

대응: 특정 문서가 반복적으로 누락되면 서버 로그에서 커넥터 오류를 확인한다.

6. 커넥터 동기화 스케줄(cron) 변경은 파이프라인 재시작이 필요하다​

커넥터의 sync_schedule 값을 새로 설정하거나 변경하면 Dagster 컨테이너 재시작 후 반영된다. schedule_enabled 켜기/끄기 토글은 재시작 없이 즉시 반영된다.

대응: 스케줄 표현식 변경은 점검 시간대에 수행한다.

7. 리랭킹은 외부 API 장애 시 자동으로 기본 순위로 폴백한다​

리랭커(Jina API) 호출이 실패해도 검색은 실패하지 않고 하이브리드 기본 순위(RRF)로 결과를 반환한다. 이때 검색 응답의 rerank_fallback: true로 폴백 여부를 확인할 수 있다. 폴백은 조용히 일어나므로, 리랭킹 품질이 중요한 환경은 이 필드를 모니터링할 것을 권장한다.

8. Python 3.13 이상에서 소스 설치가 불가하다​

코드 청킹에 사용하는 서드파티 패키지가 Python 3.13+ 를 지원하지 않는다. 컨테이너 이미지는 3.12로 고정되어 있어 영향이 없으며, 소스로 직접 설치하는 경우에만 해당한다.

대응: 소스 설치 시 Python 3.12를 사용한다.

9. (Enterprise) 관리 콘솔은 새로고침 시 재로그인이 필요하다​

보안상 액세스 토큰을 브라우저 저장소에 남기지 않고 메모리에만 보관하는 의도된 설계다. 페이지 새로고침 시 SSO 재인증이 일어난다 (IdP 세션이 살아 있으면 자동으로 통과된다).

10. (Enterprise) 사용자별 API 호출 한도를 초과하면 429 응답이 반환된다​

단일 사용자의 대량 호출이 서비스 전체 성능에 영향을 주지 않도록, 인증된 사용자 단위로 API 호출 한도가 적용된다 (검색, 업로드, 재인덱싱, MCP 등 경로 카테고리별로 별도 한도). 한도를 초과한 요청은 HTTP 429와 함께 Retry-After 헤더(재시도 가능 시점까지의 초)를 반환하며, 해당 요청만 거부된다. 같은 시각의 다른 사용자는 영향을 받지 않는다.

대응: 429 수신 시 Retry-After 초만큼 대기 후 재시도한다. 대량 초기 적재 등으로 한도 조정이 필요하면 settings.yaml의 rate_limit 섹션에서 카테고리별 한도를 변경할 수 있다 (enabled: false로 전체 비활성화 가능).