AI 관리 콘솔

AI 스택에는 관리 콘솔이 하나 딸려 있습니다. GPU 가 얼마나 바쁜지, LLM 이 느려지지 않았는지, 문서 색인이 제대로 돌았는지를 서버에 로그인하지 않고 브라우저에서 봅니다.

이 문서는 콘솔을 처음 여는 분을 위한 것입니다. 먼저 10분 둘러보기를 그대로 따라 해 보시고, 그다음 화면별 설명을 필요할 때 찾아보세요.

누가 쓰나요

현장 운영자와 시스템 관리자입니다. 콘솔은 읽는 화면이 대부분이라 잘못 눌러서 무언가가 망가지는 일은 거의 없습니다. 값을 바꾸는 곳은 문서 업로드·삭제와 피처 백필 세 군데뿐이고, 문서에서 따로 표시해 두었습니다.

접속과 로그인

주소는 설치 형태에 따라 둘 중 하나입니다. 관리자에게 어느 쪽인지 확인하세요.

형태	주소
도메인을 붙인 설치	`https://admin.<COMPANY_DOMAIN>`
사내망에서 IP 로 접속	`http://<AI_SERVER_IP>:9080`

로그인 화면에서 아이디와 비밀번호를 넣습니다. 기본 아이디는 admin 이고, 비밀번호는 설치할 때 관리자가 정합니다.

아이디가 하나뿐입니다

콘솔은 사용자별 계정을 두지 않습니다. 운영팀이 공유하는 계정 하나로 들어갑니다. 누가 무엇을 봤는지 구분되지 않으므로, 비밀번호는 팀 밖으로 나가지 않게 관리하세요.

한 번 로그인하면 8시간

8시간이 지나면 다시 로그인해야 합니다. 보던 화면 주소는 기억되므로, 로그인하면 그 자리로 돌아옵니다. 서비스를 재기동하면 모두 로그아웃될 수 있습니다 — 세션이 자꾸 풀린다면 을 보세요.

화면 글자는 영어입니다

콘솔의 메뉴와 버튼은 영어로 표시됩니다(홈 화면의 서비스 카드 설명만 한국어로 나옵니다). 아래 설명에서는 화면에 실제로 보이는 영어 이름을 굵게 적고 한국어 뜻을 함께 달았습니다.

10분 둘러보기

처음 여신 분은 이 순서대로 한 바퀴 돌아 보세요. 아무것도 바꾸지 않고 보기만 합니다.

1단계 — 로그인하고 홈을 봅니다

로그인하면 바로 홈이 뜹니다. 맨 위에 상태 요약 한 줄이 있습니다.

정상 12   주의 0   중단 0   합계 12

이 숫자가 지금 AI 스택의 건강 상태 전부입니다. 중단 이 0 이면 일단 안심하셔도 됩니다. 숫자는 20초마다 저절로 갱신되므로 새로고침을 누르지 않아도 됩니다.

요약 줄 오른쪽의 펼침 표시를 누르면 어떤 서비스가 어떤 상태인지 목록이 나옵니다. 한 번 펼쳐 두면 다음에 들어와도 펼쳐진 채로 뜹니다.

노란불(주의)이 떴다면

목록에서 그 서비스에 마우스를 올려 보세요. 왜 노란불인지가 툴팁에 나옵니다. 예를 들어 서비스 자체는 살아 있는데 데이터베이스 연결이 끊긴 경우가 여기에 잡힙니다.

2단계 — 서비스 카드를 훑습니다

요약 줄 아래에 서비스 카드가 깔려 있습니다. 카드 하나가 서비스 하나입니다.

테두리 색과 상태 점으로 정상 여부를 표시합니다
클릭하면 그 서비스 화면으로 들어갑니다
클릭되지 않는 카드도 있습니다 — 브라우저에서 직접 닿을 수 없는 내부 서비스입니다. 상태만 보는 카드라고 생각하시면 됩니다

3단계 — GPU 를 봅니다

왼쪽 세로 띠(레일)에서 GPU 를 누릅니다. GPU 장치가 표로 나옵니다.

볼 것	뜻
사용률	지금 GPU 가 얼마나 바쁜지
메모리	모델이 올라가 쓰고 있는 양
온도	높게 유지되면 성능이 떨어집니다
XID	NVIDIA 하드웨어·드라이버 오류 건수

XID 가 0 이 아니면 그냥 넘기지 마세요

XID 는 GPU 하드웨어나 드라이버가 낸 오류입니다. 조용히 지나가면 다음 증상은 보통 서버 다운입니다. 0 이 아닌 숫자를 보셨다면 그 값을 그대로 적어 시스템 관리자에게 알리세요.

4단계 — LLM 응답 속도를 봅니다

레일에서 LLM 을 누릅니다. 모델별로 한 줄씩, 응답 속도와 처리량이 나옵니다.

"요즘 답변이 느리다" 는 이야기가 나오면 여기 P95(느린 쪽 100건 중 5번째) 열을 보세요. 평소보다 크게 올라가 있으면 체감이 맞는 것입니다. 줄 끝의 작은 꺾은선은 최근 추세입니다.

5단계 — 서비스 하나에 들어가 봅니다

레일에서 RAG API 를 누릅니다. 왼쪽에 그 서비스의 메뉴가 펼쳐집니다. Documents(문서)를 눌러 보세요. 색인된 문서 목록이 나옵니다.

여기서는 아무것도 누르지 마시고 몇 건이 색인돼 있는지만 확인하세요. 챗봇이 "관련 문서를 찾지 못했습니다" 라고 답할 때 가장 먼저 볼 자리가 여기입니다.

6단계 — 로그를 봅니다

같은 서비스 메뉴에서 Logs(로그)를 누릅니다. 최근 로그가 최신순(맨 위가 최신) 으로 나옵니다. 서버에 SSH 로 들어가 docker logs 를 치지 않아도 됩니다.

7단계 — 끝입니다

여기까지 오셨으면 콘솔에서 하는 일의 90% 를 보신 것입니다. 정리하면 이렇습니다.

홈에서 전체 상태를 보고 → 이상한 서비스로 들어가 → 로그를 본다.

나머지 화면은 필요할 때 아래 설명에서 찾아보세요.

화면 지도

왼쪽 레일 (항상 보입니다)

메뉴	하는 일
Home	전체 상태 요약 + 서비스 카드
GPU	GPU 장치별 사용률·메모리·온도·XID
LLM	모델별 응답 속도·처리량
RAG API	문서 검색 엔진 — 색인·동기화·검색 시험
Timeseries Insight	설비 데이터 이상탐지·예측 엔진
Document Parsing	문서에서 표·항목을 뽑아내는 서비스
Vision	이미지 판독 서비스 (불량 판정·계기 읽기)
Operations Manual ↗	지금 보고 계신 이 설명서 (새 창)

GPU 와 LLM 이 서비스들보다 위에 있는 것은 의도된 순서입니다. 무엇이 느리거나 죽었는지는 대개 그 아래 인프라에서 시작하므로, 위에서 아래로 훑는 순서가 문제를 빨리 찾습니다.

폐쇄망에서는 매뉴얼 링크가 열리지 않습니다

Operations Manual 은 외부 사이트(docs.plantpulse.io)로 나갑니다. 인터넷이 없는 현장에서는 열리지 않습니다. 서버 안에 매뉴얼 사본이 함께 설치되어 있으니 관리자에게 문의하세요.

네 서비스가 똑같이 갖는 메뉴

RAG API · Timeseries Insight · Document Parsing · Vision 은 아래 네 메뉴를 똑같이 갖습니다. 한 번 익히면 네 곳에서 같습니다.

메뉴	하는 일
MCP Server Info	이 서비스가 AI 코파일럿에 제공하는 도구 목록
API Endpoints	이 서비스가 가진 API 목록 (연동 개발자용)
Logs	최근 로그 (최신이 맨 위)
Settings	지금 적용된 설정값 — 보기 전용입니다

Settings 는 고치는 화면이 아닙니다

값을 보여 줄 뿐 바꿀 수 없습니다. 비밀번호·API 키는 가려진 채로 표시됩니다. 설정을 실제로 바꾸려면 비밀번호 · API 키 변경 과 서비스 운영 을 보세요.

RAG API — 문서 검색

챗봇이 사내 문서를 근거로 답하게 해 주는 서비스입니다. "챗봇이 문서를 못 찾는다" 는 문의가 오면 여기부터 봅니다.

메뉴	하는 일
Documents	색인된 문서 목록. 업로드·삭제가 됩니다
Sync History	동기화가 언제 돌았고 성공했는지 이력
Query Test	검색어를 넣어 무엇이 걸리는지 직접 시험
공통 4종	위 표 참조

챗봇이 문서를 못 찾을 때

Documents 에서 그 문서가 목록에 있는지 봅니다 — 없으면 색인이 안 된 것입니다
있으면 Query Test 에서 사용자가 물어본 것과 비슷한 말로 검색해 봅니다
여기서도 안 나오면 검색 방식을 바꿔 봅니다 — hybrid · local · global · naive · mix 중에서 고를 수 있습니다. 기본은 hybrid 입니다
Sync History 에서 마지막 동기화가 실패로 끝나지 않았는지 확인합니다

Documents 에서 삭제는 되돌릴 수 없습니다

지운 문서는 챗봇이 더 이상 근거로 쓰지 못합니다. 다시 넣으려면 원본 파일을 새로 업로드해야 합니다. 원본 파일이 손에 없다면 지우지 마세요.

Timeseries Insight — 이상탐지와 예측

설비 데이터에서 이상 징후를 찾고 앞일을 예측하는 엔진입니다. 메뉴가 가장 많은 서비스입니다.

분석 화면

대상별로 이상탐지(Anomaly Detection) 와 예측(Forecast) 이 짝을 이룹니다.

묶음	화면
Asset (설비)	Anomaly Detection · Forecast · Health Index(설비 건강 점수)
Production (생산)	Anomaly Detection · Quality Forecast(품질 예측)
Alarm (알람)	Frequency Anomaly(발생 빈도 이상) · Failure Forecast(고장 예측) · Duration Analysis(지속 시간) · Sensor Correlation(센서 상관) · Statistics(통계)
System (시스템)	Anomaly Detection · Forecast
Profiling	Asset Profiling — 설비 하나를 깊게 들여다봅니다

Feature Store — 분석의 재료

위 분석들은 피처 스토어에 쌓인 가공 데이터를 먹고 돕니다. 분석 결과가 비어 있거나 낡았다면 대개 여기가 원인입니다.

메뉴	하는 일
Pipeline Status	데이터 가공이 지금 정상적으로 돌고 있는지
Run History	지난 실행 이력과 성공·실패
Feature Data	실제로 쌓인 값을 조회
Backfill	빠진 구간을 다시 채웁니다

Backfill 은 서버를 바쁘게 만듭니다

과거 구간을 다시 계산하는 작업이라 범위가 넓으면 오래 걸리고 서버 부하가 올라갑니다. 생산이 한가한 시간에, 필요한 구간만 좁혀서 돌리세요. 처음이라면 관리자와 상의하시길 권합니다.

Document Parsing · Vision

두 서비스는 공통 메뉴 네 가지만 갖습니다. 콘솔에서는 잘 살아 있는지 보고, 문제가 생기면 로그를 확인하는 용도입니다.

Document Parsing — 문서에서 레이아웃·표·항목을 뽑아냅니다
Vision — 이미지로 불량을 판정하거나 계기판을 읽습니다

둘 다 브라우저에서 직접 열 수 없는 내부 서비스라 홈 화면 카드도 클릭되지 않습니다. 콘솔이 대신 상태를 물어봐 보여 주는 것입니다.

이럴 땐 이렇게

증상	먼저 볼 곳	그다음
챗봇이 문서를 못 찾는다	RAG API → Documents	Query Test 로 직접 검색 → Sync History
챗봇 답변이 느리다	LLM 의 P95	GPU 사용률·온도
분석 결과가 비어 있다	Insight → Pipeline Status	Run History 의 실패 건
홈에 노란불이 떴다	상태 목록을 펼쳐 툴팁 확인	해당 서비스 → Logs
홈에 빨간불이 떴다	해당 서비스 → Logs	서비스 운영 의 재기동 절차
화면이 비어 있고 오류 띠가 뜬다	그 서비스가 아직 안 떴을 수 있습니다	홈에서 상태 확인

「비어 있다」와 「못 불렀다」는 다릅니다

콘솔은 데이터를 못 가져왔을 때 빈 표로 위장하지 않고 오류 띠를 띄웁니다. 오류 띠가 보인다면 데이터가 없는 게 아니라 연결이 안 된 것입니다.

계정과 세션

콘솔 계정은 데이터베이스가 아니라 환경변수로 정합니다.

환경변수	뜻	기본값
`ADMIN_AUTH_USERNAME`	로그인 아이디	`admin`
`ADMIN_AUTH_PASSWORD`	로그인 비밀번호	없음 — 반드시 지정
`ADMIN_SESSION_SECRET`	세션 서명 키	비우면 기동할 때마다 새로 생성
`ADMIN_SESSION_MAX_AGE`	로그인 유지 시간(분)	`480` (8시간)

비밀번호가 없으면 아예 뜨지 않습니다

ADMIN_AUTH_PASSWORD 를 비워 두면 콘솔이 기동을 거부합니다. 인증 없는 관리 포털이 조용히 열려 있는 것을 막기 위한 것이라, 정상 동작입니다.

세션이 자꾸 풀린다면

ADMIN_SESSION_SECRET 이 비어 있으면 서비스를 재기동할 때마다 서명 키가 새로 만들어져 모두 로그아웃됩니다. 값을 지정해 두면 재기동해도 로그인이 유지됩니다.

콘솔 비밀번호는 bin/passwd.sh 로 바꿀 수 없습니다

bin/passwd.sh 가 관리하는 키 목록에 콘솔 계정은 들어 있지 않습니다 (비밀번호 · API 키 변경 의 표를 보세요). 바꾸려면 환경 파일에서 직접 고치고 서비스를 재기동해야 합니다. 관리자에게 요청하세요.

접속과 로그인​

10분 둘러보기​

1단계 — 로그인하고 홈을 봅니다​

2단계 — 서비스 카드를 훑습니다​

3단계 — GPU 를 봅니다​

4단계 — LLM 응답 속도를 봅니다​

5단계 — 서비스 하나에 들어가 봅니다​

6단계 — 로그를 봅니다​

7단계 — 끝입니다​

화면 지도​

왼쪽 레일 (항상 보입니다)​

네 서비스가 똑같이 갖는 메뉴​

RAG API — 문서 검색​

챗봇이 문서를 못 찾을 때​

Timeseries Insight — 이상탐지와 예측​

분석 화면​

Feature Store — 분석의 재료​

Document Parsing · Vision​

이럴 땐 이렇게​

계정과 세션​

관련 문서​