Skip to main content
이 페이지는 운영 중 자주 마주치는 증상과 조치를 모아둔 참고서입니다. 증상별로 무엇을 확인하고 무엇을 실행할지 순서대로 정리했으며, 관리자 권한이 필요한 항목은 그 사실을 함께 적었습니다. 새 기능과 변경 이력은 최신 업데이트를 참조하세요.
먼저 확인하세요. 아래 항목의 상당수는 특정 버전 이상에서 해결됩니다. 조치를 시작하기 전에 관리자 패널 > 설정 > 일반의 버전 값을 확인하세요 — 버전이 낮다면 업그레이드가 가장 빠른 해결책입니다. 증상이 카테고리에 정확히 맞지 않으면 인접 항목도 확인하세요. 멀티워커 환경·인코딩처럼 하나의 원인이 여러 영역에 걸쳐 나타나는 경우가 많습니다.

​
AI 모델 응답 이슈

증상: Gemini 모델로 긴 응답을 생성할 때 응답이 끝까지 나오지 않고 중간에서 끊깁니다.원인: 출력 토큰 상한에 걸린 경우가 대부분입니다. 같은 질문을 GPT·Claude 계열 모델로 바꿨을 때 정상적으로 끝나면 이 경우에 해당합니다.해결: 모델의 출력 토큰 상한을 올립니다.
  • 워크스페이스 > 에이전트 > (에이전트 수정) > 고급 매개변수의 최대 토큰(num_predict) 을 8192 등으로 상향
  • 인스턴스 전체에 적용하려면 관리자가 관리자 패널 > 설정 > 모델에서 해당 모델의 값을 조정
증상: 특정 모델을 골랐는데 응답이 다른 공급자에서 온 것처럼 보이거나, 그 연결의 설정이 무시됩니다.원인: 서로 다른 AI 공급자 연결이 같은 모델 ID 를 노출하면 한쪽이 조용히 우선합니다.해결: 관리자 패널 > 설정 > 연결에서 연결을 열어 다음을 지정합니다.
  • 모델 ID — 그 연결이 서빙할 모델을 명시해 다른 연결과 겹치지 않게 합니다
  • 접두사 ID — 겹치는 ID가 불가피하면 한쪽 연결에 접두사를 지정합니다. 모델이 접두사.모델ID 형태로 노출됩니다(구분자는 점입니다)
등록된 모델 ID 목록은 관리자 패널 > 설정 > 모델에서 확인할 수 있습니다.
증상: OSS 모델이 도구를 호출해야 할 시점에 자연어로만 응답하고 실제 도구 실행 없이 끝납니다.원인: OSS 모델은 OpenAI 호환 function-calling 지원이 약하거나 없는 경우가 많습니다.해결: 최신 버전은 gpt-oss·gemma·llama 계열에 대해 우회 처리를 적용합니다. 다만 도구가 붙으려면 두 조건을 만족해야 합니다.
  • 그 모델이 등록된 모델(에이전트) 이어야 합니다 — 등록되지 않은 베이스 모델을 채팅에서 그대로 고르면 도구가 동작하지 않습니다
  • 스트리밍 응답이어야 합니다(아래 항목 참조)
그래도 동작하지 않으면 도구 개수를 줄이거나, function-calling 지원이 확실한 모델로 교체하세요.
증상: 외부 API에서 stream=false로 호출했는데 에이전트(지식 기반 · DbSphere) 라우팅이 되지 않고 단순 LLM 호출로만 처리됩니다.원인: 이전 버전의 라우팅 조건이 stream=true 에만 한정되어 있었습니다.해결: OpenAI · Azure · Vertex 계열 모델은 stream=false 여도 에이전트로 라우팅됩니다. 다만 Ollama 모델은 stream=true 일 때만 에이전트 도구가 동작하므로, 외부 API로 Ollama 에이전트를 호출할 때는 stream=true 로 보내세요.

​
채팅·파일 업로드

증상: 지식 기반에 여러 파일을 한 번에 올렸는데 일부가 사라지고 마지막 파일만 처리됩니다.원인: 이전 버전의 업로드 동시성 문제입니다. 파일을 하나씩 순차로 올리면 재현되지 않습니다.해결: 최신 버전에서 해결되었습니다. 진행 상태는 한 번에 올린 개수에 따라 다른 곳에 표시됩니다.
  • 5개 이상을 한 번에 올리면 배치로 전환되어 우측 상단 알림(벨)에 진행률이 표시됩니다
  • 4개 이하는 벨에 뜨지 않고, 지식 기반의 파일 목록에서 파일별 상태로 표시됩니다
  • 실패한 파일이 있으면 파일 목록의 실패한 파일 재시도로 다시 처리할 수 있습니다
채팅에 첨부한 파일은 알림 센터에 표시되지 않습니다.
증상: 파일을 채팅에 첨부하면 응답까지 시간이 오래 걸립니다.원인: 채팅에 첨부한 파일은 업로드 시점에 저장만 되고, 본문 추출은 AI가 그 파일을 실제로 읽는 시점에 수행됩니다. 그래서 지연이 업로드가 아니라 응답 생성 도중에 나타납니다.해결:
  • 업로드가 끝나기 전에는 전송이 차단됩니다. 업로드 표시가 사라진 뒤 보내세요
  • 20MB를 넘는 파일은 본문 추출을 건너뜁니다. AI가 “대용량 문서라 아직 본문이 처리되지 않았습니다”라고 답하면 이 경우입니다
  • 크거나 반복해서 참조할 문서는 미리 지식 기반에 업로드해 두고 참조하세요. 지식 기반은 백그라운드에서 미리 인덱싱하므로 응답 중 추출 지연이 없습니다
증상: 이미지를 채팅에 첨부했지만 AI가 “이미지를 받지 못했다”고 응답합니다.원인: 선택한 모델이 이미지 입력(Vision)을 지원하지 않으면 이미지가 전달되지 않습니다.해결: 이미지 인식이 되는 다른 모델로 바꿔 다시 시도하세요. 현재 화면에는 모델별 이미지 지원 여부 표시가 없고 경고도 뜨지 않으므로, 어떤 모델이 이미지를 지원하는지는 관리자에게 확인하세요.
증상: 파일 업로드가 실패했는데 무엇이 문제인지 알기 어렵습니다.해결: 표시되는 메시지별 의미와 조치입니다.
  • “파일 사이즈가 N MB를 초과하면 안됩니다.” — 관리자가 정한 업로드 상한을 넘었습니다. 상한은 관리자 패널 > 설정 > 문서 > 파일 > 업로드 최대 사이즈에서 바꿉니다(비워 두면 무제한)
  • [ERROR: File type '.xxx' is not allowed. Allowed types: ...] — 관리자가 허용 확장자를 지정한 경우입니다. 허용 목록이 메시지에 함께 표시되며, 설정 위치는 같은 화면의 허용 파일 확장자입니다(비워 두면 전체 허용)
  • 형식은 맞는데 내용이 인식되지 않으면 지식 기반의 지원 파일 형식 목록을 확인하세요
서버가 돌려주는 메시지 일부는 한국어 화면에서도 영어로 표시됩니다.

​
한글·인코딩

증상: 한글을 입력할 때 자음이 두 번 들어가거나 조합 중인 글자가 깨집니다.원인: 입력 도중에 값이 다시 계산되면서 한글 조합이 끊기는 문제입니다. 지식 기반 > 필터 설정의 필터 옵션 입력란에서 보고되었고, 영문 입력에서는 재현되지 않습니다.해결: 최신 버전에서 해결되었습니다. 이전 화면이 브라우저에 캐시돼 있을 수 있으니 강력 새로고침(Ctrl+Shift+R)으로 최신 화면을 받은 뒤 다시 확인하세요. 그래도 조합이 끊기면 입력란 밖을 한 번 클릭했다가 다시 입력하거나, 값을 다른 곳에서 완성해 붙여넣으세요.
증상: 사용자 일괄 등록 CSV에서 한글 이름이 ? 또는 깨진 문자로 들어갑니다.원인: CSV 파일을 저장하는 시점에 이미 한글이 ? 로 바뀐 경우입니다. CP949 · EUC-KR 로 저장된 파일은 자동으로 인식되므로 인코딩 자체는 원인이 아닙니다.해결:
  • Excel에서 저장할 때 “CSV UTF-8 (.csv)” 형식을 선택하세요. 메모장·VS Code에서 UTF-8로 다시 저장해도 됩니다. BOM 포함 여부는 상관없습니다
  • 첫 행은 머리글로 간주해 무조건 건너뜁니다. 머리글 없이 첫 줄부터 데이터를 넣으면 그 사용자가 조용히 누락됩니다
  • 값에 쉼표를 넣지 마세요. 열은 이름 · 이메일 · 비밀번호 · 역할 4개로 고정이며, 값에 쉼표가 있으면 열 수가 어긋나 그 행이 거부됩니다
증상: 용어집 매칭에서 파일명만으로는 용어가 추출되지 않거나 일부만 추출됩니다.원인: 추출 범위에서 본문을 끄고 파일명만 켠 경우에 발생했습니다.해결: 최신 버전에서 해결되었습니다. 설정은 지식 기반 > (해당 지식 기반) > 필터 설정의 용어집 필터 안 추출 범위에 있습니다.
  • 파일명 · 문서 본문 체크 상태를 확인하세요
  • 본문을 쓸 때는 전체 본문 또는 일부 본문(앞/뒤 N 자)을 고를 수 있습니다. 파일명만으로 매칭되지 않으면 문서 본문을 켜고 다시 추출하세요
증상: 한글이 섞인 텍스트에서 이메일 등 PII 패턴이 감지되지 않습니다.원인: 정규식의 word boundary(\b)가 한글을 단어 문자로 인식해, sim@cloocus.com이 처럼 한글이 바로 이어붙으면 매칭에 실패하던 문제입니다.해결: 최신 버전에서 이메일 · 신용카드 · IP 주소 · MAC 주소 감지가 한글 환경 기준으로 수정되었습니다. 그래도 감지되지 않으면 워크스페이스 > 가드레일 > (해당 가드레일) 에서 순서대로 확인하세요.
  • 개인정보 유형에서 감지할 항목이 선택돼 있는지 — 새로 만든 가드레일은 아무것도 선택돼 있지 않습니다
  • 적용 대상이 입력 · 출력 중 필요한 쪽에 켜져 있는지
  • 내장 유형은 이메일 · 신용카드 · IP 주소 · MAC 주소 · URL · API 키 6종입니다. 주민등록번호처럼 국내 전용 식별자는 내장돼 있지 않으므로 커스텀 패턴 (정규식)에 직접 추가해야 합니다
  • 가드레일 테스트에 실제 문장을 넣어 검출되는지 확인하세요
  • 의미 기반 판정이 필요하면 LLM 기반 탐지를 추가로 켭니다. 규칙 기반 탐지는 끌 수 없고 항상 함께 동작합니다

​
권한·접근

증상: 그룹 권한을 없음으로 설정했지만 사용자가 여전히 해당 기능에 접근합니다.원인: 그룹 권한은 기본 권한 위로 올릴 수만 있고 내릴 수는 없습니다. 기본 권한이 열려 있으면 그룹을 없음으로 바꿔도 접근이 유지됩니다.해결: 관리자 패널 > 사용자 > 그룹 및 권한에서 순서대로 확인하세요.
  • 대상 사용자의 역할이 관리자가 아닌지 — 관리자는 그룹 권한과 무관하게 접근합니다
  • 기본 권한 — 사용자 역할 전원에게 적용되는 바닥값입니다. 여기가 열려 있으면 그룹에서 내릴 수 없습니다
  • 다른 그룹 — 여러 그룹의 권한은 합쳐지며 가장 높은 레벨이 적용됩니다. 조직 단위 매핑으로 그룹이 적용될 수도 있습니다
  • 화면에만 메뉴가 남아 있으면 페이지 새로고침 하세요. 권한은 요청마다 서버에서 다시 계산되므로 재로그인은 필요 없습니다
권한 레벨은 없음 / 접근 / 읽기 / 쓰기 이며, 항목에 따라 노출되는 레벨이 다릅니다.
증상: 조직 단위(OU)에 가드레일을 할당하거나 조직 단위별 권한 현황을 보려는데 화면에서 찾을 수 없습니다.원인: 현재 배포 버전의 관리자 패널 > 사용자 > 조직 화면에는 조직 단위별 가드레일 할당·권한 보기 진입 버튼이 없습니다. 조직을 클릭하면 펼쳐지는 조직 단위 목록에는 이름 · 유형 · 멤버 수만 표시됩니다.해결: 가드레일을 집단에 적용하려면 조직 단위 대신 그룹을 사용하세요 — 관리자 패널 > 사용자 > 그룹 및 권한 > (그룹 편집) > 일반의 채팅 가드레일에서 지정합니다. 조직 단위 기준으로 적용해야 한다면 관리자에게 문의하세요.
증상: 채팅에서 #으로 지식 기반을 선택했는데 에이전트가 다른 지식 기반에서 검색하거나 그 정보를 쓰지 않습니다.원인: #으로 고른 지식 기반은 에이전트의 검색 대상에 추가될 뿐, 검색 범위를 그것 하나로 한정하지는 않습니다. AI가 질문과 관련 있다고 판단한 것을 스스로 고르며, 확신이 없으면 연결된 전체를 검색합니다.해결:
  • 특정 지식 기반만 쓰게 하려면 질문에 그 이름을 함께 적거나, 그 지식 기반만 연결한 에이전트를 사용하세요
  • #으로 넣은 항목은 그 대화 전체에 계속 유지됩니다. 이전 턴에서 넣은 것이 남아 있는지 확인하세요
  • 본인이 그 지식 기반에 읽기 권한이 있는지 확인하세요 — 권한이 없으면 도구 목록에서 조용히 제외됩니다
  • 그 지식 기반의 도구 설명이 비어 있지 않은지 확인하세요(워크스페이스 > 지식 기반 > (해당 지식 기반) > 도구 설명). 에이전트에 연결된 리소스라면 에이전트 편집기에 “도구 설명이 누락되었습니다” 경고가 표시됩니다

​
임베딩·벡터 검색

증상: 임베딩 모델을 바꾼 뒤 파일 업로드·인덱싱이 실패하고, 지식 기반 상세의 파일 목록에 실패가 표시됩니다.원인: 새 임베딩 모델의 벡터 차원이 기존 인덱스와 다릅니다. 모든 지식 기반이 하나의 벡터 인덱스를 공유하므로 차원이 달라지면 전체가 영향을 받습니다.해결: 설정은 관리자 패널 > 설정 > 문서 > 임베딩에 있습니다.
  • 임베딩 차원은 0(자동)을 권장합니다 — 모델 이름으로 자동 추론됩니다. 자체 호스팅 모델처럼 이름이 알려지지 않은 경우에만 직접 입력하세요
  • 차원이 같은 모델로 바꾼 경우에는 관리자 패널 > 설정 > 문서 > 위험 영역 > 지식 베이스 벡터 재색인 의 재색인 으로 해결됩니다. 개별 지식 기반이 아니라 전체 일괄 이며 관리자만 실행할 수 있습니다
  • 차원이 달라진 경우에는 재색인으로 해결되지 않습니다. 재색인은 문서만 지웠다 다시 넣을 뿐 인덱스를 다시 만들지 않기 때문입니다
차원이 달라진 상태에서 재색인을 실행하면 기존 벡터만 지워지고 새 벡터 저장이 실패해 지식 기반이 비어버릴 수 있습니다. 차원을 바꾸려면 벡터 인덱스를 먼저 삭제해야 하는데, 같은 화면의 벡터 저장 공간/지식 기반 초기화 는 인덱스와 함께 등록된 지식 기반까지 모두 삭제 합니다. 실행 전 반드시 백업하고 파일 재업로드 계획을 세우세요.
증상: Azure AI Search를 벡터 DB로 사용할 때 간헐적으로 인덱스 오류 또는 검색 실패가 발생합니다.해결: 최신 버전에서 연결 15초 · 응답 120초 · 단일 작업 120초의 타임아웃과 배치 크기 상한이 적용되어, 무한 대기 대신 실패로 빨리 전환됩니다(AZURE_SEARCH_OP_TIMEOUT · AZURE_SEARCH_BATCH_SIZE 로 조정). 지속 발생 시:
  • 파일 인덱싱 실패는 지식 기반 상세 > 파일 목록에서 실패 표시를 확인하고 실패한 파일 재시도를 실행하세요
  • 채팅 응답 실패는 관리자 패널 > 평가 > 추적에서 Chat ID 또는 Message ID로 조회해 오류 메시지 원문을 확인하세요. HTTP 응답 코드 전용 항목은 없으며, 파일 인덱싱 실패는 추적에 남지 않습니다
  • 동시 요청이 많은 환경이면 Azure 포털에서 검색 서비스의 등급과 복제본 수를 확인하세요

​
이메일·알림

증상: 예약 작업에서 + 알림 추가로 알림을 넣은 뒤 유형 목록에 웹훅 · 직접 입력만 있고 이메일이 없습니다. 웹훅 채널도 없으면 직접 입력 하나만 보입니다.원인: 관리자 패널에 등록된 이메일 채널이 하나도 없는 상태입니다. 이메일 유형은 등록된 이메일 채널이 1개 이상일 때만 목록에 나타납니다.해결: 관리자가 관리자 패널 > 설정 > 채널 > 이메일에서 채널을 추가한 뒤, 예약 작업 화면을 다시 열면 선택할 수 있습니다. 화면을 열어둔 채로는 목록이 갱신되지 않습니다. 이메일 채널 설정 참조.
증상: 실행 이력은 성공으로 표시되지만 수신자에게 메일이 도착하지 않습니다.원인: 알림에 지정된 채널 이름이 현재 등록된 이메일 채널 목록에 없는 경우입니다. 채널을 삭제했거나 이름을 바꾸면, 그 채널을 참조하던 기존 예약 작업은 발송 대상을 찾지 못하고 건너뜁니다. 수신자를 한 명도 넣지 않은 경우에도 마찬가지로 조용히 건너뜁니다. 알림 발송 실패는 작업 상태에 반영되지 않으므로 실행 이력에는 성공으로 남습니다.해결:
  • 예약 작업 편집 화면에서 알림의 채널과 수신자를 다시 확인하고 저장
  • 또는 관리자가 기존과 같은 이름으로 채널을 다시 등록
  • 채널이 정상인데도 오지 않으면 관리자가 채널 편집 화면에서 연결 테스트의 [테스트] · 테스트 이메일 전송의 [보내기]로 발신 설정을 확인 — 이 항목은 채널을 저장한 뒤 다시 열어야 나타납니다
SMTP · 웹훅 공급자별 증상표는 알림 채널 트러블슈팅을 참조하세요.
증상: SMTP 채널의 연결 테스트나 발송이 실패하고, SMTP 서버가 돌려준 도메인 이름 관련 오류가 화면에 그대로 표시됩니다.원인: SMTP 서버가 EHLO 명령에 쓰이는 도메인 이름을 검증하는데, 그 값을 받아들이지 않는 경우입니다.해결: 제품은 EHLO 도메인으로 항상 localhost 를 사용하며 이 값은 설정으로 바꿀 수 없습니다. 따라서 컨테이너 hostname 을 FQDN 으로 바꿔도 해결되지 않습니다. SMTP 서버 쪽에서 EHLO 도메인 검증을 완화하거나, 검증이 느슨한 릴레이 또는 다른 발송 엔진(SendGrid · Microsoft Graph)을 사용하세요.
증상: 가드레일이 차단했지만 사용자는 어떤 패턴이 문제인지 알기 어렵습니다.해결: 차단된 위치에 따라 표시되는 내용이 다릅니다.
  • 응답(출력) 차단 — 차단 사유가 메시지에 함께 표시됩니다
  • 질문(입력) 차단 — 가드레일 이름만 표시되고 사유는 나오지 않습니다
어떤 패턴·단어가 걸렸는지는 관리자가 관리자 패널 > 모니터링 > 가드레일 로그에서 확인합니다. 사용자에게 보이는 문구를 바꾸는 기능은 에이전트 플로우의 가드레일 노드에만 있습니다 — 차단 시 동작을 메시지로 두고 차단 메시지에 문구를 입력합니다. 워크스페이스 가드레일 편집기에는 이 옵션이 없고 처리 전략(차단 · 삭제 · 마스킹 · 해시 · 로그)만 제공합니다.

​
운영·배포

증상: 관리자가 설정을 변경했는데 일부 사용자에게만 반영되거나, 사용자가 받는 응답이 워커마다 다릅니다.원인: 설정값이 워커별 메모리에 캐시되는데, Redis 없이 운영하면 워커 간 동기화가 되지 않습니다. 특히 워커 1개 × 인스턴스 여러 개로 스케일아웃한 구성에서는 프로세스 단위 검사로 이 상태를 막을 수 없습니다.해결:
  • 운영 환경에서는 Redis 필수 — REDIS_URL 환경변수 설정
  • 최신 버전에서 설정 무효화 처리와 일괄 가져오기(bulk import) 반영이 개선되었습니다
  • 자세한 내용은 배포 체크리스트 참조
증상: DATABASE_SCHEMA 환경변수를 설정했는데도 테이블이 public 스키마에 생성됩니다.해결: 최신 버전에서 해결되었습니다. 이미 public 에 테이블이 만들어진 환경이라면 순서를 지켜야 합니다.
public 스키마의 테이블을 먼저 지우지 마세요. 그 테이블이 운영 데이터의 유일한 사본일 수 있습니다. 새 스키마로 마이그레이션해도 데이터는 자동으로 옮겨지지 않고 빈 테이블만 생깁니다.
  1. DB 전체를 백업합니다
  2. public 과 대상 스키마 양쪽의 테이블 목록·행 수를 비교해 데이터가 어디에 있는지 확인합니다. alembic_version 테이블도 스키마마다 따로 존재할 수 있습니다
  3. 데이터가 public 에 있으면 대상 스키마로 옮긴 뒤에만 원본 정리를 검토합니다
  4. DATABASE_SCHEMA=app 처럼 명시적 값을 설정하고 마이그레이션을 다시 실행합니다
  5. 기동 시 SCHEMA VERIFICATION FAILED 가 뜨면 대상 스키마에 테이블이 없다는 뜻입니다 — 이 상태에서는 앱이 시작하지 않으므로 데이터가 손상되지는 않습니다
멀티 프로세스 환경의 마이그레이션 동시 실행 충돌도 함께 해결되었습니다 — DB 잠금으로 직렬화되어 한 워커가 끝날 때까지 나머지가 대기했다가 그대로 통과합니다.
증상: 지식 그래프 동기화 또는 추출 중 PostgreSQL 연결 풀 고갈(PoolError)로 작업이 실패합니다.해결: AGE 그래프 DB 전용 풀 크기를 늘리세요 — AGE_POOL_MAX 환경변수(기본값 32). PoolError 가 반복되면 한 단계 올리고 AGE_POOL_MIN 도 함께 조정합니다. 규모별 권장값은 배포 체크리스트의 표를 따르세요.이 풀은 워커(프로세스)마다 하나씩 만들어지므로 총 연결 수는 워커 수 × AGE_POOL_MAX 입니다. 값을 올리기 전에 PostgreSQL 의 max_connections 와 다른 연결 풀까지 합산한 예산을 확인하세요.배포 체크리스트의 「AGE 풀 크기를 KG 데이터 규모에 맞춰 조정」 항목 참조.

​
더 도움이 필요한 경우

감사 로그

무엇이 언제 변경되었는지 시간순 확인

추적

개별 요청의 LLM 호출·에이전트 흐름·실패 원인 분석

배포 체크리스트

운영 필수 환경변수 및 멀티워커 설정

문의 보내기

관리자에게 문제 보고