AI 관리 콘솔
AI 스택에는 관리 콘솔이 하나 딸려 있습니다. GPU 가 얼마나 바쁜지, LLM 이 느려지지 않았는지, 문서 색인이 제대로 돌았는지를 서버에 로그인하지 않고 브라우저에서 봅니다.
이 문서는 화면 하나에 절 하나입니다. 절마다 화면 그림이 있고, 그림의 번호(① ② ③)가 아래 표의 번호와 같습니다. 번호는 화면을 위에서 아래로 읽는 순서입니다. 처음 여시는 분은 둘러보기를 따라 한 바퀴 돌아 보시고, 그다음은 필요한 화면의 절을 찾아보십시오.
현장 운영자와 시스템 관리자입니다. 콘솔은 읽는 화면이 대부분이라 잘못 눌러서 무언가가 망가지는 일은 거의 없습니다. 값을 바꾸는 화면은 절마다 주의 로 따로 표시해 두었습니다.
접속과 로그인
주소는 셋 중 하나입니다. 관리자에게 어느 쪽인지 확인하십시오.
| 형태 | 주소 | 비고 |
|---|---|---|
| 사내망에서 IP 로 (HTTP) | http://<AI_SERVER_IP>:5959 | PI_ADMIN_WEB_PORT, 기본 5959 |
| 사내망에서 IP 로 (HTTPS) | https://<AI_SERVER_IP>:5960 | PI_ADMIN_WEB_TLS_PORT, 기본 5960. 프록시(plantpulse-proxy)가 TLS 를 끊고 콘솔로 넘깁니다 |
| 도메인을 붙인 설치 | https://admin.<COMPANY_DOMAIN> | 프록시의 443 을 거칩니다 |
HTTP 와 HTTPS 는 둘 다 열려 있습니다. HTTP 로 들어와도 HTTPS 로 넘기지 않습니다.
2026.09 까지는 콘솔이 9080 에 있었습니다. 2026.10 부터 9080 은 쓰지 않습니다 — 북마크와 방화벽
규칙을 5959 · 5960 으로 바꾸십시오. 포트 전체는 서비스 포트 맵 에 있습니다.
로그인 화면(/login/)에서 아이디 와 비밀번호 를 넣습니다. 기본 아이디는 admin 이고, 비밀번호는
설치할 때 관리자가 정합니다. 로그인하면 원래 열려던 화면으로 돌아갑니다.
콘솔은 사용자별 계정을 두지 않습니다. 운영팀이 공유하는 계정 하나로 들어갑니다. 비밀번호는 팀 밖으로 나가지 않게 관리하십시오. 계정 설정은 계정과 세션 에 있습니다.
8시간이 지나면 다시 로그인해야 합니다. 보던 화면 주소는 기억되므로, 로그인하면 그 자리로 돌아옵니다.
콘솔은 English · 한국어 두 언어입니다. 로그인 화면의 언어 버튼이나, 로그인한 뒤 왼쪽 레일 아래쪽의
언어 (Language) 버튼으로 바꿉니다. 주소 끝에 ?lang=ko 를 붙여 열어도 한국어로 뜹니다.
이 문서는 한국어 화면의 이름을 굵게 적고, 영어 화면의 이름을 괄호로 함께 달았습니다.
화면 지도
왼쪽 세로 띠(레일)가 서비스를 고르고, 그 오른쪽 사이드바가 그 서비스의 화면을 보여 줍니다. 홈 · GPU 에는 사이드바가 없습니다. 레일 아래쪽에는 운영 매뉴얼 ↗ · 언어 · 로그아웃 이 붙어 있습니다.
GPU 와 LLM 이 서비스들보다 위에 있는 것은 의도된 순서입니다. 무엇이 느리거나 죽었는지는 대개 그 아래 인프라에서 시작하므로, 위에서 아래로 훑는 순서가 문제를 빨리 찾습니다. MCP 게이트웨이는 LLM 바로 다음입니다 — 모델과, 그 모델이 쓰는 도구가 지나가는 관문을 나란히 봅니다.
| 레일 (영어 화면) | 사이드바의 화면 |
|---|---|
| 홈 (Home) | — |
| GPU | — |
| LLM | 대시보드 · 채팅 시험 · 모델 등록 · API 키 · API 엔드포인트 · 업스트림 상태 · 로그 · 설정 |
| MCP 게이트웨이 (MCP Gateway) | 개요, 게이트웨이 묶음(서버 · 도구 · 권한 · 클라이언트 API 키), 도구 검색 묶음(검색 시험대 · 검색 설정), 모니터링 묶음(호출 기록·지표) + 공통 메뉴 (2026.10 재릴리즈(2026-10-20)) |
| RAG API | 대시보드, 색인 묶음(문서 · 동영상 · 동기화 이력 · 도면 대장), API 묶음(질의 시험) + 공통 메뉴 |
| 시계열 인사이트 (Timeseries Insight) | 대시보드, 분석 묶음(자산 · 생산 · OEE · RAM · EMS · 알람 · 시스템), AI 자율 · 프로파일링 · 피처 스토어 + 공통 메뉴 |
| 문서 파싱 (Document Parsing) | 문서 점검, 도면 묶음(도면 판독 시험) + 공통 메뉴 |
| 비전 (Vision) | 비전 점검 + 공통 메뉴 |
| 디지털 스레드 (Digital Thread) | 연동 지도 · 그래프 거울 + 공통 메뉴 |
| 자동화 샌드박스 (Automation Sandbox) | 개요, 실행 묶음(실행 이력 · 상한) + 공통 메뉴(MCP 서버 정보 는 없음) |
공통 메뉴는 RAG API · 시계열 인사이트 · 문서 파싱 · 비전 · 디지털 스레드 · MCP 게이트웨이 여섯이 똑같이 갖습니다(자동화 샌드박스는 MCP 서버 정보만 빼고 같습니다) — MCP 서버 정보 · API 엔드포인트(MCP 묶음), 로그 · API 키(운영 묶음), 그리고 목록 끝의 설정. 한 번 익히면 여섯 곳에서 같습니다. 이 문서 끝의 공통 메뉴 절에서 한 번에 설명합니다.
작업 준비도 · 설비 타임라인 · 도면의 판 표찰처럼 현장 사람이 보는 것은 코파일럿에 있습니다(현장 › 디지털 스레드
/thread, 설비 화면의 타임라인, 채팅의 도면 카드) → 코파일럿 화면 지도. 이 콘솔의
디지털 스레드 레일은 커넥터를 붙이고 거울을 지켜보는 운영자 화면만 둡니다. 운영자는 판정 결과가 아니라 «판정에 무엇이 붙어 있나» 를 봅니다 →
준비도 원천.
레일의 운영 매뉴얼 은 외부 사이트(docs.kopens.io)로 나갑니다. 인터넷이 없는 현장에서는
열리지 않습니다. 서버 안에 매뉴얼 사본이 함께 설치되어 있으니 관리자에게 문의하십시오.
좁은 화면 — 메뉴가 서랍으로 접힙니다
창 폭이 1024px 보다 좁으면 레일과 사이드바가 화면 왼쪽에서 사라지고, 화면 맨 위에 띠 하나가 생깁니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 위 띠 왼쪽 ☰ | 메뉴 열기 — 레일과 사이드바가 서랍으로 열립니다 |
| ② | 위 띠 | 로고와 제품 이름 |
| ③ | 서랍(오른쪽 장면) | 넓은 화면의 레일 · 사이드바와 같은 메뉴입니다. 열리면 위 띠의 ① · ② 를 덮습니다 |
| ④ | 서랍 바깥의 어두운 막 | 누르면 서랍이 닫힙니다 |
서랍은 Esc · 바깥 누르기 · 메뉴 항목 누르기 · 화면 이동 · 창을 1024px 이상으로 넓히기 중 하나로 닫힙니다.
둘러보기
처음 여신 분은 이 순서대로 한 바퀴 돌아 보십시오. 아무것도 바꾸지 않고 보기만 합니다.
- 홈 — 시스템 상태 줄의 다운 이 0 이면 일단 안심하셔도 됩니다.
- GPU — XID 오류 가 0 인지 봅니다.
- LLM → 대시보드 — 모델별 P95 가 평소와 비슷한지 봅니다.
- RAG API → 문서 — 색인된 문서가 있는지만 확인합니다.
- 같은 사이드바의 로그 — 최근 로그가 최신순으로 나옵니다. SSH 로
docker logs를 치지 않아도 됩니다.
홈에서 전체 상태를 보고 → 이상한 서비스로 들어가 → 로그를 본다. 콘솔에서 하는 일의 대부분이 이 한 줄입니다.
홈 — /
AI 스택 전체의 건강 상태를 한눈에 보고, 각 서비스 화면으로 들어가는 출발점입니다. 상태는 20초마다 저절로 갱신됩니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 제품 이름과 부제 — 설치마다 바꿔 달 수 있는 머리말입니다 |
| ② | 시스템 상태 (System Status) | 감시하는 서비스 전부를 전체 · 정상 · 주의 · 다운 개수로 셉니다. 머리의 점이 전체 판정이고, 옆에 마지막 갱신 시각과 새로고침 버튼이 있습니다. 상세 보기 를 펼치면 서비스별 상태와 응답 시간이 나옵니다 |
| ③ | 서비스 카드 | 서비스 하나가 카드 하나입니다. 서비스 API · 모델 서빙 · 저장소 · 게이트웨이 · 추적 순으로 묶여, 장애가 났을 때 «부르는 쪽 → 서빙하는 쪽 → 저장·관측하는 쪽» 순서로 내려가 볼 수 있게 합니다 |
카드는 이렇게 읽습니다.
- 오른쪽의 상태 점은 감시하는 서비스에만 있습니다.
- 화살표가 있는 카드는 누르면 들어갑니다. RAG API · 시계열 인사이트 · 비전 · 문서 이해 · 디지털 스레드는 콘솔 안의 화면으로, LLM 프록시 · 그래프 DB 는 새 창으로 그 도구의 화면이 열립니다.
- 화살표가 없는 카드는 상태만 보는 카드입니다. 브라우저에서 직접 닿을 수 없는 내부 서비스입니다.
- 카드의 둘째 줄은 그 서비스가 하는 일을 두 줄 안으로 적은 설명입니다. 예를 들어 RAG API 는 「에셋 문서(PDF·Office)·도면(DXF·PDF)·동영상·음성을 색인하고 검색한다」, 시계열 추론 모델 서버는 「TSPulse 이상탐지·TTM 예측 모델 서버」 입니다.
자주 하는 작업
- 상세 보기 를 펼칩니다. 한 번 펼쳐 두면 다음에 들어와도 펼쳐진 채로 뜹니다.
- 주의(노란불)인 서비스의 상태 표시에 마우스를 올립니다. 서비스가 직접 보고한 원래 상태가 툴팁에 함께 나옵니다 — 예를 들어 서비스는 살아 있는데 데이터베이스 연결이 끊긴 경우입니다.
- 그 서비스로 들어가 로그 를 봅니다.
상태를 아직 받지 못한 동안은 점이 회색(미측정)입니다. 회색은 「정상」이 아니라 「아직 모른다」입니다.
GPU — /gpu/
GPU 장치의 사용률·온도·오류를 봅니다. 값은 5초마다 새로 수집됩니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 마지막 수집 시각 — 값이 멈춰 있지 않은지 여기서 봅니다 |
| ② | 요약 줄 | 장치 · 통합 메모리 · 호스트 CPU · XID 오류 — 장비 전체가 지금 얼마나 차 있는지, 하드웨어 오류가 있었는지 한 줄로 |
| ③ | 장치 표 | GPU 한 대가 한 줄입니다. SM(사용률) · 메모리 대역폭 · 온도 · 메모리 온도 · 전력 · SM 클럭 · 인코드 / 디코드 · XID 를 세로로 비교해 어느 GPU 가 튀는지 찾습니다 |
| ④ | 추이 | 최근 60분 그래프 — 지금 값이 잠깐 튄 것인지 계속 높은 것인지 가립니다 |
XID 는 NVIDIA 하드웨어나 드라이버가 낸 오류입니다. 0 이 아니면 그 줄에 빨간 표시가 붙습니다. 조용히 지나가면 다음 증상은 보통 서버 다운입니다. 그 값을 그대로 적어 시스템 관리자에게 알리십시오.
LLM 대시보드 — /llm/
모델 서빙 엔진의 응답 속도와 처리량을 봅니다. 값은 5초마다 수집됩니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 마지막 수집 시각 |
| ② | 요약 줄 | 모델 · 실행 중 · 대기열 · 최악 P95 — 엔진이 밀리고 있는지 한 줄로. 최악 P95 옆에 경고 임계가 함께 나옵니다 |
| ③ | 모델 표 | 모델 하나가 한 줄입니다. 상태 · 실행 중 · 대기열 · 처리량 · P50 · P95 · P99 · 1분 중단 · KV 캐시 · 30분 TPS 로 어느 모델이 느린지 찾습니다. 대시(—)는 아직 표본이 없다는 뜻입니다 |
| ④ | 추이 | 한 모델의 최근 60분(1분 창) 그래프 — 느려진 시점을 찾습니다 |
「요즘 답변이 느리다」는 이야기가 나오면 P95(느린 쪽 100건 중 5번째) 열을 보십시오. 평소보다 크게 올라가 있으면 체감이 맞는 것입니다.
채팅 시험 — /llm/playground/
모델 게이트웨이(LiteLLM)로 프롬프트 하나를 보내 봅니다. 애플리케이션이 부르는 것과 같은 경로라, «모델은 살아 있는데 앱만 안 된다» 를 가를 때 씁니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 게이트웨이가 알려 준 모델 수 |
| ② | 프롬프트 카드 | 모델 버튼으로 보낼 모델을 고르고, 시스템 프롬프트 (선택) · 최대 토큰 · 프롬프트를 넣어 보내기 합니다(Ctrl+Enter). 아래에 답변 · 걸린 시간 · 입력/출력 토큰이 나옵니다 |
무엇을 적든 서버가 2048 토큰에서 자릅니다. 답은 한 번에 옵니다(스트리밍은 일부러 꺼 두었습니다). 모델이 답하기 전에 «생각» 하므로, 예산이 작으면 답 글자가 나오기 전에 끝날 수 있습니다 — 그때는 화면이 그렇다고 알려 줍니다. 같은 GPU 가 코파일럿도 처리하므로 긴 답은 시간이 걸립니다.
모델 등록 — /llm/models/
외부 모델 엔드포인트를 게이트웨이에 등록합니다. 사내·상용을 가리지 않고 OpenAI 호환이면 됩니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 새로고침 |
| ② | 요약 줄 | 서빙 중 · 설정 파일 · 여기서 등록 — 게이트웨이가 라우팅하는 모델을 출처별로 셉니다. 여기서 고칠 수 있는 것은 «여기서 등록» 한 것뿐입니다 |
| ③ | 모델 추가 (Add a model) | 새 엔드포인트를 등록합니다 — 모델 이름 · 제공자 경로 · 엔드포인트 · 제공자 API 키 · API 버전 · 종류 를 넣고 연결 시험 뒤 등록 |
| ④ | 서빙 중인 모델 | 지금 서빙 중인 모델 목록 — 출처 가 «이 콘솔» 인 줄만 삭제할 수 있습니다 |
자주 하는 작업
- 모델 이름(부르는 쪽이
model로 넘길 이름), 제공자 경로(LiteLLM 형식, 예:openai/gpt-4o), 엔드포인트 를 넣습니다. 키가 필요한 엔드포인트면 제공자 API 키 를 넣습니다. API 버전 은 Azure OpenAI 일 때만 씁니다. - 종류(채팅 · 완성 · 임베딩 · 리랭크)를 맞게 고릅니다. 잘못 고르면 멀쩡한 엔드포인트가 고장 난 것처럼 보입니다.
- 연결 시험 으로 응답을 확인한 뒤 등록 합니다.
- 출처가 설정 파일(
litellm-config.yaml)인 기본 모델은 여기서 고칠 수 없습니다 — 그 파일이 정본입니다. - 삭제하면 그 이름으로 부르던 쪽이 바로 실패하기 시작합니다.
- 등록 · 시험 · 삭제는 감사 로그에 남습니다(제공자 키는 기록되지 않고 지문만 남습니다).
여기서 넣은 제공자 API 키는 PI_LITELLM_SALT_KEY 로 암호화되어 저장됩니다. 솔트를 바꾸면 등록한
모델이 목록에는 그대로 보이면서 호출만 조용히 실패합니다 →
비밀번호 · API 키 변경
LLM API 키 — /llm/api-keys/
애플리케이션에 줄 가상 키를 발급·재발급·삭제합니다. 공통 메뉴의 API 키 와 이름은 같지만 하는 일이 다릅니다 — 저쪽은 «우리 키가 통하는지» 를 재고, 여기는 «남에게 줄 키» 를 찍습니다.
| 자리 | 하는 일 |
|---|---|
| 요약 줄 | 키 · 사용액 · 차단됨 — 발급한 키가 얼마나 쓰였고 막힌 것이 있는지 |
| 키 발급 (Issue a key) | 이름 · 최대 예산 (USD) · 만료까지(예: 30d, 24h, 1mo) 를 걸어 발급. 비워 두면 제한이 없습니다 |
| 발급된 키 표 | 키마다 해시 · 모델 · 사용 / 예산 · 상태 · 만료, 줄 끝에 재발급 · 삭제 |
콘솔도 게이트웨이도 평문을 저장하지 않습니다. 발급 직후에 복사하지 못했으면 재발급해야 합니다. 재발급·삭제하면 지금 값은 즉시 동작을 멈춥니다. 발급 · 재발급 · 삭제는 감사 로그에 남습니다(키 값은 남지 않습니다).
LLM 에도 API 엔드포인트(/llm/api-endpoints/)가 있습니다. 게이트웨이의 전체 API 목록이며, 모양은
공통 메뉴의 것과 같습니다.
업스트림 상태 — /llm/operations/
게이트웨이 뒤의 모델이 실제로 답하는지 찔러 봅니다. 점검 한 번이 실제 호출 한 번입니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 점검 실행 — 누를 때만 모든 모델을 실제로 한 번씩 부릅니다 |
| ② | 요약 줄 | 건전 · 불건전 개수 — 답하지 않는 모델이 있는지 한눈에 |
| ③ | 엔드포인트 표 | 모델마다 상태 와 상세 — 게이트웨이가 준 값을 바꾸지 않고 그대로 보여 주므로, 실패 사유를 그대로 읽을 수 있습니다 |
LLM 로그 — /llm/logs/
게이트웨이를 지난 요청 하나가 한 줄입니다. 공통 메뉴의 로그(서비스 로그 파일)와 다릅니다.
| 자리 | 하는 일 |
|---|---|
| 화면 위 | 시작 · 끝 → 적용 — 볼 구간을 정합니다 |
| 표 | 시각 · 모델 · 종류 · 토큰 · 지연 · 비용 · 요청 id — 어느 요청이 느렸거나 비쌌는지 찾습니다 |
프롬프트와 답 본문은 여기 없습니다 — Phoenix 트레이스에 있습니다.
LLM 설정 — /llm/config/
콘솔이 LLM 스택에 닿는 방식과 게이트웨이가 알려 주는 값을 봅니다. 보기 전용입니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 새로고침 |
| ② | 게이트웨이 (Gateway) | 콘솔이 쓰는 게이트웨이 주소와 키. 키는 지문만 보이고, 눈 아이콘을 누를 때만 평문이 오며 그 요청은 사용자명과 함께 감사 로그에 남습니다 |
| ③ | 지표 수집 대상 (Metric poll targets) | LLM 대시보드 가 직접 긁는 엔진 목록 — 대시보드가 비면 여기서 대상이 빠졌는지 봅니다 |
| ④ | 게이트웨이가 아는 모델 (Models the gateway knows) | 게이트웨이가 알려 준 모델 목록 그대로 — 콘솔은 자기 목록을 따로 두지 않습니다 |
게이트웨이의 마스터 키는 콘솔 서버가 쥐고 있고 브라우저로 보내지 않습니다. 애플리케이션에는 LLM API 키 화면에서 발급한 가상 키를 주십시오 — 예산·만료·폐기를 따로 걸 수 있습니다.
RAG 대시보드 — /rag/
챗봇이 사내 문서를 근거로 답하게 해 주는 서비스(RAG API)의 색인 상태를 봅니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 색인 운영 (Indexing Operations) | 화면 이름, 마지막 갱신 시각, 새로고침 |
| ② | 요약 줄 | 전체 문서 · 색인됨 · 대기 · 실패 — 플랫폼 원장의 문서가 색인까지 갔는지 셉니다 |
| ③ | 스케줄러 | 다음 실행 · 마지막 실행 과 그 회차의 결과 요약 — 동기화가 제때 도는지 봅니다 |
그 아래에 백엔드 도달성 표(LightRAG · PostgreSQL · 그래프 DB · 벡터 DB · 플랫폼이 닿는지)와 자산별 색인 상태 가 이어집니다. 실패 가 0 이 아니거나 연결 불가 가 있으면 그 서비스의 로그 를 봅니다.
문서 — /rag/documents/
색인된 문서를 보고, 문서를 올리거나 다시 색인합니다. 「챗봇이 문서를 못 찾는다」 는 문의가 오면 여기부터 봅니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 올리기(올리기 대화상자를 엽니다) · 새로고침 · 지금 동기화(플랫폼 문서를 바로 다시 가져옵니다) · 전체 재색인 |
| ② | 요약 줄 | 문서 · 색인됨 · 대기 · 실패 — 색인이 끝나지 않았거나 실패한 문서가 있는지 |
| ③ | 문서 표 | 자산 · 문서 · 상태 · 색인 시각 · 동작. 줄 끝 동작으로 상세 보기 · 다시 색인 · 원본 내려받기 · 이 문서로 검색 시험 · 코퍼스에서 제외/다시 포함 · 삭제(직접 올린 문서만) |
자주 하는 작업 — 챗봇이 문서를 못 찾을 때
- 표에서 그 문서가 있는지 봅니다 — 없으면 색인이 안 된 것입니다.
- 있으면 줄 끝의 이 문서로 검색 시험 이나 질의 시험 화면에서 사용자가 물어본 것과 비슷한 말로 찾아봅니다.
- 동기화 이력 에서 마지막 동기화가 실패로 끝나지 않았는지 확인합니다.
색인이 돌고 있는 동안에는 상태가 1초마다 저절로 갱신되므로 새로고침하지 않아도 됩니다.
도면 색인(DRAWING_INGEST_ENABLED)이 켜져 있으면, 도면 줄은 문서 이름 아래에 도면 번호 · 판 · 품번과 판 표찰
(최신판 · 옛 판 (최신 …) · 변경 진행 · 확인 불가)을 함께 보입니다. 도면을 판별로 모아 보려면
도면 대장 을 엽니다.
- 표제란에서 도면 번호를 읽지 못한 PDF 도면도 도면 줄로 보입니다 — 이름 아래에 「도면 · 표제란에서 도면번호를 읽지 못했습니다」 가 붙습니다. 일반 문서처럼 보이지 않게 하려는 표시입니다.
- 도면 줄의 검색 제외는 도면이 들어온 길에 따라 다릅니다.
- 플랫폼 원장에서 들어온 도면(출처
PLATFORM)은 일반 문서처럼 코퍼스에서 제외 / 다시 포함 단추가 눌립니다. 원장이 정본이라 지울 수는 없으므로, 검색에서 빼려면 이것을 씁니다. - 콘솔에서 직접 올린 도면은 단추가 눌리지 않습니다(흐리게 보임). 마우스를 올리면 「수동으로 올린 도면은 검색에서 제외할 수 없습니다 — 도면을 지우거나 다시 색인하세요 (플랫폼 원장 도면은 제외할 수 있습니다)」 가 뜹니다.
- 다시 색인 · 원본 내려받기는 어느 도면이든 되고, 삭제는 직접 올린 것만 됩니다.
- 플랫폼 원장에서 들어온 도면(출처
그 말은 LLM 이 그때그때 만들어 내므로 매번 다릅니다. 특정 문구로 판단하지 마시고, 색인 건수가 0 인지로 판단하십시오.
삭제는 직접 올린 문서(수동 표시)에만 있습니다. 지운 문서는 챗봇이 더 이상 근거로 쓰지 못하고, 다시 넣으려면 원본 파일을 새로 올려야 합니다. 원본 파일이 손에 없다면 지우지 마십시오. 플랫폼에서 온 문서는 지우는 대신 코퍼스에서 제외 합니다.
전체 재색인 은 플랫폼 문서 «전부» 를 다시 색인합니다. 문서는 점진적으로 다시 수집되어 색인 공백은 없고, 직접 올린 문서는 영향받지 않습니다. 그래도 시간이 걸리는 작업이니 필요할 때만 누르십시오.
올리기 대화상자 — 문서 · 도면 대장 · 동영상 공통
세 화면이 같은 대화상자를 엽니다. 여는 자리에 따라 처음 값과 받는 형식만 다릅니다.
| 여는 곳 | 단추 | 대화상자 |
|---|---|---|
| 문서 | 올리기 | 아래 모든 형식을 받습니다. PDF 는 처음에 문서로 잡힙니다 |
| 도면 대장 | 도면 올리기 | 제목이 「도면 올리기」이고, PDF 가 처음에 도면으로 잡힙니다 |
| 동영상 | 영상 올리기 | 제목이 「영상·음성 올리기」이고, 영상 · 음성 · 자막만 받습니다. 문서 · 도면을 끌어다 놓으면 「여기서는 영상·음성·자막만 받습니다」 로 막습니다 |
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 자산 | 자산 ID · 이름으로 검색해 고릅니다. 고르지 않으면 공용(_manual) 으로 올라가고 자산에 묶이지 않습니다 |
| ② | 끌어다 놓는 자리 · 받는 형식 | 파일을 여러 개 한꺼번에 놓거나 파일 선택 으로 고릅니다. 아래 띠가 지금 받는 형식과 형식별 최대 크기를 보입니다 — 꺼진 형식은 끔 입니다 |
| ③ | 파일 목록 | 파일마다 종류(아래 표)와 상태(준비됨 · 차단됨 · 올리는 중 · 완료 · 실패). PDF 줄에는 문서 / 도면 을 고르는 단추가 있고, 모든 PDF 로 한꺼번에 바꿉니다 |
| ④ | 차단된 줄 | 보내기 전에 막힌 이유가 그 줄에 적힙니다(아래) |
| ⑤ | N개 올리기 | 파일을 하나씩 차례로 보냅니다 — RAG 색인이 한 번에 하나만 쓰기 때문입니다 |
| 확장자 | 종류 |
|---|---|
pdf · docx · pptx · xlsx · md · txt | 문서 (PDF 는 문서 / 도면 중 고름) |
dxf | 도면 |
mp4 · mov · mkv · webm | 동영상 |
m4a · mp3 · wav | 음성 |
srt · vtt | 자막 |
PDF 를 도면으로 고르면 도면으로 색인합니다(document_kind=drawing 을 함께 보냅니다). 도면 색인(DRAWING_INGEST_ENABLED)이 꺼진
설치에서는 「도면 색인이 꺼져 있습니다 … PDF 는 일반 문서로 색인됩니다」 가 뜨고 PDF 는 일반 문서가 됩니다.
보내기 전에 막는 것
| 막는 경우 | 줄에 뜨는 사유 |
|---|---|
.dwg | 「DWG 는 받지 않습니다 — DXF 나 PDF 로 내보내 올리세요.」 |
| 영상 · 음성인데 영상·음성 수집이 꺼짐 | 「영상·음성 수집이 꺼져 있습니다 — 설치 env 에 PI_MEDIA_ENABLED=true 를 켜세요 …」 |
| 자막인데 자막 수집이 꺼짐 | 「자막 수집이 꺼져 있습니다(MEDIA_TEXT_TRACKS).」 |
| DXF 인데 도면 색인이 꺼짐 | 「도면 색인이 꺼져 있어(DRAWING_INGEST_ENABLED) DXF 를 색인할 수 없습니다.」 |
| 크기 초과 | 「너무 큽니다 — … 로 상한 … 을 넘습니다.」 상한은 문서 · 도면이 SYNC_MAX_FILE_MB(번들 값 50 MB), 영상 · 음성이 MEDIA_MAX_FILE_MB(기본 2048 MB), 자막이 5 MB 입니다 |
| 빈 파일 | 「빈 파일입니다.」 |
- 켜진 기능과 상한은 대화상자가 정하지 않고 RAG API 의 설정을 읽어 정합니다. 설정을 읽지 못하면 「rag-api 설정을 읽지 못했습니다 —
형식과 크기는 서버가 판정합니다.」 가 뜨고,
.dwg와 모르는 확장자만 막습니다. - 여기서 올린 파일은 수동(직접 올린 것)으로 남고 동기화가 지우지 않습니다.
- 도면을 올리면 결과 줄에 도면 번호 · 판 · 치수 · 부품표 행 수가 나오고, 영상 · 음성은 「전사·색인 대기열에 들어갔습니다」 로 끝납니다 — 녹취는 처리 시간대에 시작합니다.
- 같은 이름이 다른 방식(도면 / 일반 문서)으로 이미 색인돼 있으면 서버가 거절합니다 — 먼저 지우거나 파일 이름을 바꿉니다.
동영상 — /rag/videos/
수리 · 교육 · 설비 운영 영상과 음성을 파일마다 봅니다 — 녹취가 됐는지, 장면 그림이 생겼는지, 검색 색인에 들어갔는지. 채팅에서 영상이 답의 근거로 나오지 않을 때 여기부터 봅니다. 영상이 채팅에서 어떻게 쓰이는지는 동영상 검색 에 있습니다.
화면에 「영상·음성 수집이 꺼져 있습니다」 상자만 뜨고 표는 없습니다. 설치 env 파일의 PI_MEDIA_ENABLED=true 가 켜는 스위치입니다 —
켜고 스택을 다시 만들면 RAG API 가 영상 수집을 받고 녹취(ASR) 서버가 뜹니다. 그 전에는 RAG API 에 영상 경로가 없고 영상 업로드는
거절됩니다 → 환경 설정
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 설명 |
| ② | 요약 줄 | 파일 · 색인됨 · 대기·처리 중 · 실패(실패 · 건너뜀) · 녹취 비어 있음 · 검색에서 빠짐(색인됐는데 검색 색인에 없는 구간 수) |
| ③ | 도구 줄 | 파일·자산 검색(파일 이름 · 자산 ID · 자산 이름 일부) · 문제만(실패 · 건너뜀 · 녹취가 빈 것 · 검색에서 빠진 구간이 있는 것만) · 새로고침 · 영상 올리기(올리기 대화상자를 영상 · 음성 · 자막만 받게 엽니다) |
| ④ | 도구 줄 오른쪽 | 처리 시간대 — 녹취 · 색인을 언제 시작하는지(아래) |
| ⑤ | 표 | 파일 · 자산 · 길이 · 상태 · 녹취(글자 수 · 구간 수) · 장면(장면 그림 수) · 올린 시각 · 동작 |
| ⑥ | 펼친 줄 | 줄을 펼치면 재생기, 시각 칩이 붙은 녹취(칩을 누르면 그 시각부터 재생), 영상과 짝지은 자막 파일, 처리 정보(언어 · 색인된 구간 · ASR 모델 · 갱신 시각 등) |
| ⑦ | 줄 끝 동작 | 상태에 맞는 단추만 섭니다 — 그림의 색인된 줄에는 다시 녹취(↻)와 삭제(직접 올린 것만), 실패 · 건너뜀 줄에는 다시 시도(아래) |
처리 시간대. 영상 녹취는 GPU 를 오래 쓰므로 정한 시간대에만 시작합니다. 줄에는 셋 중 하나가 보입니다.
- 「처리 시간대 … — 지금 처리 중」
- 「처리 시간대 … — 대기 파일은 … 에 시작」
- 「처리 시간대 제한 없음」
시간대는 MEDIA_PROCESSING_WINDOW 로 정합니다. 비워 두면 20:00-06:00(설치 시간대 PP_TZ 기준)이고, always 면 언제든
시작합니다. 시간대는 처리의 «시작»에만 걸립니다 — 시작한 처리는 시간대가 닫혀도 끝까지 갑니다 → 환경 설정
상태
| 상태 | 뜻 |
|---|---|
| 대기 중 | 처리 시간대를 기다립니다 |
| 가져오는 중 · 녹취 중 · 색인 중 | 처리 중입니다 |
| 색인됨 | 검색에 쓰입니다 |
| 소리 없음 · 말 없음 | 소리 트랙이 없거나 말소리를 찾지 못했습니다 — 말이 있는 영상이면 다시 녹취 합니다 |
| 건너뜀 · 실패 | 처리하지 못했습니다 — 펼쳐서 사유를 보고 다시 시도 합니다 |
| 지우는 중 | 삭제가 진행 중입니다 |
동작
| 동작 | 보이는 줄 | 하는 일 |
|---|---|---|
| 다시 시도 | 실패 · 건너뜀 | 대기열에 다시 넣습니다. 다음 처리 시간대에 시작합니다 |
| 다시 녹취 | 색인됨 · 말 없음 · 소리 없음 | 처음부터 다시 녹취합니다. 지금 녹취록은 버리고, 새 구간이 색인되면 옛 구간을 대신합니다 |
| 삭제 | 직접 올린 것(수동)만 | 구간 · 녹취록 · 보관 원본을 지웁니다. 플랫폼 원장에서 온 영상은 여기서 지울 수 없습니다 |
- 처리 중인 줄이 있으면 화면이 5초마다 저절로 다시 읽습니다. 대기 중만 있으면 다시 읽지 않습니다(시간대를 기다리는 데 몇 시간이 걸리므로).
- 녹취 비어 있음 이 0 이 아니면 그대로 넘기지 마십시오. 말이 있는 영상인데 녹취가 비면 채팅이 그 영상을 근거로 쓰지 못합니다 — 펼친 줄의 안내대로 ASR 모델을 확인한 뒤 다시 녹취(또는 다시 시도) 합니다.
- 2026.10 재릴리즈 4 부터 녹취가 무음 · 소음 뒤에 붙은 첫 문장을 버리지 않고, 남긴 문장의 시각을 실제 말소리로 당깁니다. 그 전에
녹취한 영상은 저절로 다시 하지 않으므로, 첫 문장이 빠졌거나 출처 시각이 어긋난 영상은 다시 녹취 합니다 — 처리 시간대(비워 두면
20:00-06:00)에 다시 받아 적습니다. - 시각(올린 시각 · 다음 시작)은 설치 시간대(
PP_TZ)로 보입니다. 녹취 칩의m:ss는 영상 안의 위치입니다.
동기화 이력 — /rag/sync-history/
플랫폼의 자산 문서를 가져오는 동기화 회차의 이력입니다. 재시작해도 남습니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름, 기록된 회차 수, 새로고침 |
| ② | 표 | 회차마다 시작 · 계기 · 자산 · 원장 · 색인 · 사라짐 · 카드 · 소요 · 결과 — 언제 무엇이 들어오고 빠졌는지, 실패한 회차가 있는지 봅니다 |
맨 위 줄의 결과 가 오류 이면, 그 시각 전후로 RAG API 의 로그 를 봅니다.
도면 대장 — /rag/drawings/
RAG 에 색인된 도면(DXF · 벡터 PDF)을 도면 번호로 묶어 판마다 한 줄로 봅니다. 같은 판의 파일이 여럿이면(DXF 와 PDF, 플랫폼 원장과 직접 올린 것) 한 줄에 묶입니다. 「현장에 걸린 도면이 최신판인가」, 「표제란을 제대로 읽었나」 를 가릴 때 엽니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 설명 |
| ② | 요약 줄 | 도면 · 판 · 옛 판 · 판독 안 됨 — 옛 판과 판독 실패가 몇 장인지 |
| ③ | 거르기 줄 | 검색 칸(도면번호 또는 품번 — 문서 이름 일부로도 찾고, 대소문자를 가리지 않습니다) · 옛 판만 · 판독 실패만 · 새로고침 · 도면 올리기(PDF 가 처음부터 «도면» 으로 잡힌 올리기 대화상자) |
| ④ | 표 | 도면번호 · 판 · 품번 · 판 상태 · 파일 · 판독 · 올린 시각. 같은 도면번호 안에서는 새 판이 위입니다. 줄 왼쪽 화살표로 펼치면 쪽 미리보기(쪽 넘김)와 표제란 판독값이 열립니다 |
| ⑤ | 파일 열 | 이 판의 파일 형식 칩 — 진한 칩이 대표 파일(채팅 카드 · 미리보기가 여는 파일) |
| ⑥ | 펼친 줄 오른쪽 | 이 판의 파일 N개 — 형식 · 원장/수동 업로드 · 자산 · 파일 이름, 대표에는 「(대표 — 이 파일로 엽니다)」. 대표는 쓸 수 있는 파일 → DXF 원본 → 플랫폼 원장 순으로 고릅니다 |
| ⑦ | 비교 열 | 같은 도면번호에 판이 둘 이상이면 새 판 줄에 ○ 판과 비교 단추가 섭니다 — 바로 아래 판과 견줍니다 |
| 칸 | 값 | 뜻 |
|---|---|---|
| 판 상태 | 최신판 · 옛 판 (최신 ○) · 변경 진행 · 확인 불가 | PLM 의 배포 판과 설계 변경을 품번으로 물어 얻은 답입니다. 확인 불가 는 «최신» 이 아니라 «모른다» 입니다 — PLM 커넥터가 없거나 답하지 않았습니다 → 디지털 스레드 |
| 판독 | 표제란 읽음 · 표제란 없음 · 실패(사유와 함께) · 처리 중 | 표제란에서 도면 번호를 읽었는지와 색인 실패만 말합니다. 도면 번호를 읽지 못한 PDF 도면도 대장에 오르고 표제란 없음 으로 판독 안 됨 에 셉니다 |
| 올린 시각 | — | 설치 시간대(PP_TZ)로 보입니다 |
비교 를 누르면 그 줄 아래에 요약 · 신뢰도 · 비교 못 함 항목 · 변경 표(표제란 · 치수 · 부품표 · 주기의 추가 · 삭제 · 변경)와, 새 판 그림 위에 바뀐 영역이 열립니다. 다시 누르면 닫힙니다.
화면 위에 「rag-api 의 도면 색인이 꺼져 있습니다(DRAWING_INGEST_ENABLED)」 가 뜨고, 쪽 미리보기 · 판 상태 · 판 비교를 쓸 수 없습니다. 출하 기본은 꺼짐입니다. 켜는 법은 환경 설정 에 있습니다.
대장의 판독 칸은 표제란과 색인 실패만 말합니다. 같은 파일을 도면 판독 시험 에 올려 보십시오 — RAG 가 도면을 색인할 때 쓰는 판독기와 같습니다.
질의 시험 — /rag/query/
색인된 문서를 대상으로 검색을 직접 해 봅니다. 소비자가 쓰는 질의 API 와 같은 계약이라, 챗봇이 무엇을 근거로 받는지 그대로 재현됩니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 설명 |
| ② | 질의 상자 | 질문을 넣고 검색 방식(hybrid · local · global · naive · mix, 기본 hybrid)을 골라 질의 실행(Ctrl+Enter). 아래에 답변 · 걸린 시간 · 출처 가 나옵니다 |
원하는 문서가 출처 에 안 나오면 모드를 바꿔 다시 해 봅니다.
시계열 인사이트 대시보드 — /insight/
설비 데이터에서 이상 징후를 찾고 앞일을 예측하는 엔진(시계열 인사이트)의 상태를 봅니다. 메뉴가 가장 많은 서비스입니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름 |
| ② | 상태 알림 | 서비스와 그 의존 구성요소가 모두 응답하는지 — 정상 / 비정상 / 서버 연결 오류로 갈립니다 |
| ③ | 요약 줄 | 이상 탐지 · 예측 · MCP 도구 · 스케줄러 — 이 엔진이 내주는 분석·도구와 예약 작업의 개수 |
| ④ | 파이프라인 표 | 피처 스토어 파이프라인마다 마지막 실행 시각 — 분석의 재료가 제때 만들어지고 있는지 봅니다 |
그 아래에 분석 영역 설명과 시스템 정보(AI 모델 · 가동 시간 · 스케줄러 · 예측 모델)가 이어집니다.
이상 탐지 — /insight/anomaly/asset/ 외
대상의 최근 데이터에 이상 점수를 매기고, 어느 태그·지표가 평소와 가장 달랐는지 순위를 냅니다. 아래 여섯 화면이 같은 모양입니다(알람의 빈도 이상 은 아래 알람 분석 절).
| 사이드바 | 경로 | 대상 |
|---|---|---|
| 자산 › 이상 탐지 | /insight/anomaly/asset/ | 설비 하나의 센서 태그 |
| 생산 › 이상 탐지 | /insight/anomaly/order/ | 최근 작업 지시 (축이 시각이 아니라 오더 순서) |
| OEE › 이상 탐지 | /insight/anomaly/oee/ | 누적 OEE 를 변화량(델타)으로 바꿔 본 가동률·성능·품질 |
| RAM › 이상 탐지 | /insight/anomaly/ram/ | 신뢰성 · 가용성 · 정비성(MTBF/MTTR) |
| EMS › 이상 탐지 | /insight/anomaly/ems/ | 누적 에너지(전력·연료)를 변화량으로 바꿔 본 소비 |
| 시스템 › 이상 탐지 | /insight/anomaly/system/ | 수집 호스트의 CPU·메모리·디스크 |
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 쓰는 모델 |
| ② | 파라미터 | 분석할 자산과 범위(데이터 간격 · 행 수 제한 · 임계값 · 조회 범위 · 최근 구간 · 상위 K)를 정하고 이상탐지 실행. 결과로 요약 줄, 시계열 + 이상 점수, 이상 순위, 응답 데이터 와 안내 카드가 그 아래에 열립니다 |
자주 하는 작업
- 자산 ID 를 고르고 이상탐지 실행 을 누릅니다.
- 이상 순위 맨 위 태그를 집어 시계열 + 이상 점수 에서 점수가 솟은 시각의 실제 값을 봅니다.
- 같은 자산으로 예측 화면을 열어 앞으로 어디로 가는지 봅니다.
점수는 요청한 창 «안에서» 0~1 로 다시 맞춘 값이라, 조용한 창에서도 1 에 가까운 점이 나옵니다. 창을 바꾸면 같은 점의 점수도 달라집니다. 결과 아래 안내 카드의 오해하기 쉬운 것 을 함께 읽으십시오.
예전 판에서는 이 세 묶음이 사이드바에 없고 주소로만 열렸습니다. 이제 자산 · 생산 아래에 묶음으로 보입니다.
예측 — /insight/forecast/asset/ 외
대상의 다음 구간을 예측하고 신뢰 구간을 띠로 함께 그립니다. 아래 여섯 화면이 같은 모양입니다(알람의 고장 예측 은 아래 알람 분석 절).
| 사이드바 | 경로 | 대상 |
|---|---|---|
| 자산 › 예측 | /insight/forecast/asset/ | 설비 하나의 센서 태그 |
| 생산 › 품질 예측 | /insight/forecast/order/ | 다음 몇 오더의 품질·OEE·에너지 |
| OEE › 예측 | /insight/forecast/oee/ | OEE 의 앞으로의 추이 |
| RAM › 예측 | /insight/forecast/ram/ | 신뢰성 · 가용성 · 정비성(MTBF/MTTR) |
| EMS › 예측 | /insight/forecast/ems/ | 에너지 소비 |
| 시스템 › 예측 | /insight/forecast/system/ | 수집 호스트의 CPU·메모리·디스크 |
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 쓰는 모델 |
| ② | 파라미터 | 예측할 자산과 길이(데이터 간격 · 행 수 제한 · 컨텍스트 길이 · 예측 길이 · 조회 범위 · 신뢰구간)를 정하고 예측 실행. 결과로 요약 줄(소요 · 모델 · 신뢰 구간 · 컨텍스트), 예측 결과, 응답 데이터 와 안내 카드가 열립니다 |
요약 줄의 모델 이 TTM 이어야 진짜 예측입니다. NAIVE 는 TTM 이 실패해 대체값을 돌려준 것입니다. 예측 길이는 96 점까지이고, 그보다 크게 주면 잘리지 않고 거절됩니다.
건강 지수 — /insight/asset/health/
설비 하나를 0~100 점 한 수로 보고, 그 점수를 깎은 감점까지 같이 봅니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름 — 센서 · OEE · RAM · EMS · 알람을 합친 점수라는 설명 |
| ② | 파라미터 와 안내 카드 | 자산 ID · 데이터 간격 을 정하고 건강 지수 확인. 결과로 점수 · 영역별 점수 · 응답 데이터 가 열립니다. 안내 카드(자세히 / 접기)가 점수를 어떻게 읽고 다음에 어느 화면으로 갈지 알려 줍니다 |
60초 안에 다시 누르면 새로 계산하지 않고 직전 결과를 보여 줍니다. 데이터가 없는 영역은 정상으로 세지 않고 점수에서 뺍니다 — 관측이 모자라면 등급이 「-」로 보류됩니다.
셋업 · 계획 정지 · 캘린더 휴무 · 교대 밖은 감점하지 않습니다. 이력이 짧은 영역은 0점이 아니라 판정 보류로 빠지고(응답 데이터 의
held_domains), 그때 낸 등급은 잠정(grade_provisional)입니다 → 시계열 인사이트 도구 — 건강지수를 읽는 법
알람 분석 — /insight/alarm/…
사이드바 알람 묶음의 다섯 화면입니다. 모두 위쪽 파라미터 에 자산과 범위를 넣고 실행 버튼을 누르면 아래에 결과와 응답 데이터, 안내 카드가 열리는 같은 모양입니다. 그림은 빈도 이상 입니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 설명 |
| ② | 파라미터 | 자산 · 우선순위 · 집계 창 · 행 수 제한 · 임계값 · 상위 K 를 정하고 이상탐지 실행. 실행 전에는 결과 자리에 안내 문구만 있습니다 |
| 사이드바 | 경로 | 실행 버튼 | 보는 것 |
|---|---|---|---|
| 빈도 이상 | /insight/alarm/anomaly/ | 이상탐지 실행 | 알람이 어느 시간대에 몰렸는지 |
| 고장 예측 | /insight/alarm/forecast/ | 예측 실행 | 앞으로 창마다 알람이 몇 건 올라올지 |
| 지속시간 분석 | /insight/alarm/duration/ | 지속시간 분석 | 같은 알람이 갈수록 오래 켜져 있는지(열화 감지) |
| 센서 상관 | /insight/alarm/correlation/ | 상관 분석 | 알람이 어느 센서 태그에 걸려 있는지 |
| 통계 | /insight/alarm/stats/ | 통계 조회 | 알람 건수 · 우선순위 분포 · 상위 알람 설정과 태그 |
태그별·시간대별로 알람을 «세는» 화면입니다. 함께 자주 나타난 태그이지, 함께 움직인다고 입증된 태그가 아닙니다. 통계 에서 기간 안에 알람이 없으면 오류가 아니라 0 과 빈 목록으로 나옵니다.
AI 발견 — /insight/findings/
AI 가 현장에서 알아챈 것(오더 미달 · 데이터 끊김 · AI 변경 · 공정 이상 · 센서 고장)을 봅니다. 열린 것이 먼저 나옵니다. 사이드바의 AI 자율 묶음에 있습니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 새로고침 |
| ② | 요약 줄 | 열림 · 긴급 · 심각도 높음 · 확인됨 — 지금 사람이 봐야 할 것이 몇 건인지 |
| ③ | 상태 거르기 | 닫히지 않은 것 · 열림 · 확인됨 · 닫힘 으로 목록을 좁힙니다. 옆에서 종류와 자산으로도 좁힐 수 있습니다 |
| ④ | 표 | 발견마다 종류 · 자산 · 심각도 · 내용 · 마지막 관측 · 상태, 줄 끝 확인 · 닫기 — 보고 있다는 표시와 처리 완료를 남깁니다 |
자주 하는 작업
- 열린 발견의 내용 을 읽고, 보고 있다는 뜻으로 확인 을 누릅니다.
- 처리가 끝났으면 닫기 를 누르고 확인 대화에서 한 번 더 확인합니다.
확인·닫기는 로그인한 관리자 이름으로 기록되고, 콘솔 감사 로그(insight.write)에도 남습니다.
자율 개선 — /insight/autonomy/
AI 가 스스로 무엇을 왜 바꿨는지 보고, 멈추거나 되돌리는 곳입니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 새로고침 |
| ② | 지금 모드 (Current mode) | 지금 모드(자동 · 제안만 · 끔)와 누가 언제 정했는지, 마지막 야간 실행. 모드 전환 버튼과 비상 정지 끄기 가 여기 있습니다 |
| ③ | 대상 표 | 개선 대상마다 지금 쓰는 버전 · 시험 중 · 대기 후보 · 상태, 줄 끝 되돌리기 · 재개(멈췄을 때) · 교체 승인(제안만 모드에서 준비된 것) |
그 아래 변경 이력 (Change log)에 언제 · 어디 · 무슨 일 · 누가 가 한 줄씩 남습니다.
- 기간(7 · 30 · 90일, 기본 7일)과 결정으로 거릅니다. 50건씩 보이고, 더 보기 로 이어 받습니다.
- 건너뜀 줄은 기본으로 숨깁니다. 건너뜀도 보기 로 켭니다. 줄 위의 문구가 창 전체 수 · 보이는 수 · 숨긴 수를 말합니다.
| 모드 | 하는 일 |
|---|---|
| 자동 | AI 가 스스로 기준을 점검·시험·교체하고, 결과가 나빠지면 스스로 되돌립니다 |
| 제안만 | 새 버전을 점검·시험한 뒤, 바꾸기 전에 승인을 기다립니다 |
| 끔 | 아무것도 점검·교체·되돌리지 않습니다. 지금 쓰는 것은 그대로 둡니다 |
모드 전환 · 끄기 · 교체 승인 · 되돌리기 · 재개는 확인 대화를 거친 뒤 바로 적용되고, 바꾼 모드는 재시작해도
유지됩니다. 모든 조작은 로그인한 관리자 이름으로 변경 이력 과 콘솔 감사 로그(insight.write)에 남습니다.
급할 때는 끄기 가 비상 정지입니다.
점수기 비교(그림자) — /insight/shadow/
모델 없는 점수기를 자산의 최근 데이터에 돌려, 켰다면 무엇을 잡았을지 봅니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 설명 |
| ② | 입력 | 자산 ID · 최근 분 을 넣고 채점 실행. 결과로 경보 구간 · 경보 분 · 판정 안 함 · 센서 이상 요약과, 사용한 기준·구간별 표가 열립니다 |
아무것도 저장하지 않고 알림도 보내지 않습니다. 운영 중인 이상 판정은 그대로입니다.
자산 프로파일링 — /insight/profile/asset/
실제 데이터로 자산의 태그를 자동으로 이해합니다 — 각 태그가 무엇을 재는지, 정상 범위, 그 신뢰도.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름, 오른쪽에 자산 고르기와 프로파일 다시 불러오기 |
| ② | 본문 | 자산을 고르기 전에는 안내 문구만 있습니다. 고르면 요약 줄과 태그 이해 · 관계 그래프 탭이 열립니다 |
태그 이해 탭은 태그마다 종류 · 정상 범위 · 알람 한계 · 신뢰도 를 보여 주고, 관계 그래프 탭의 관계 분석 실행 은 함께 움직이는 태그와 선행 → 후행 관계를 계산합니다(수십 초 걸릴 수 있습니다).
파이프라인 상태 — /insight/feature/status/
위 분석들이 먹는 가공 데이터(피처 스토어)가 지금 정상적으로 만들어지고 있는지 봅니다. 분석 결과가 비어 있거나 낡았다면 대개 여기가 원인입니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름, 새로고침, 전체 실행 — 파이프라인을 지금 한꺼번에 돌립니다 |
| ② | 스케줄러 작업 | 작업마다 계기 와 다음 실행 — 예약이 살아 있는지 봅니다 |
| ③ | 파이프라인 | 파이프라인마다 마지막 실행 과 계기, 줄마다 실행 버튼 — 오래 안 돈 것을 찾아 그것만 돌립니다 |
그 아래 백필 상태 카드에 진행 중인 백필과 마지막 오류가 나옵니다.
같은 피처 스토어 묶음의 나머지 세 화면입니다.
| 사이드바 | 경로 | 하는 일 |
|---|---|---|
| 실행 이력 (Run History) | /insight/feature/history/ | 파이프라인의 지난 실행 — 실행 시각 · 소요 · 처리 · 상태 · 비고 |
| 피처 데이터 (Feature Data) | /insight/feature/data/ | 자산 피처 조회(자산 ID · 주기 · 조회 개수 → 피처 조회)와 텍스트 검색, 유사 자산 (벡터 검색) |
| 백필 (Backfill) | /insight/feature/backfill/ | 시작일 · 종료일 · 파이프라인 을 골라 백필 시작 — 빠진 구간을 다시 채웁니다. 실행 중인 백필이 있으면 새로 시작할 수 없습니다 |
과거 구간을 다시 계산하는 작업이라 범위가 넓으면 오래 걸리고 서버 부하가 올라갑니다. 생산이 한가한 시간에, 필요한 구간만 좁혀서 돌리십시오. 처음이라면 관리자와 상의하시길 권합니다.
문서 파싱 점검 — /parser/
문서 하나를 올려, 문서 파싱 서비스가 그것을 어떻게 읽는지(RAG 가 색인했을 텍스트) 그대로 확인합니다. RAG 색인 결과를 믿기 전에 쓰는 화면입니다. 사이드바 이름은 문서 점검 입니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 이 화면이 부르는 서비스 |
| ② | 입력 | 파싱 프로필(default · fast · ocr · scan)을 고르고 문서(PDF · DOCX · PPTX · XLSX · 이미지)를 끌어 놓거나 파일 선택. default 는 RAG 색인과 같은 설정이고, 다른 것을 고르면 «기본과 다름» 이 표시됩니다 |
| ③ | ② 아래 | 안내 카드 — 고른 프로필이 무엇을 하는지(default 면 「RAG 는 이 문서를 어떻게 읽었나」). 접기 로 접습니다 |
결과는 옆 파싱된 마크다운 카드에 나오고, 위 요약 줄에 소요 · 신뢰도 · 글자 수 · 줄 수 가 붙습니다.
결과가 비어 있고 스캔 문서라면 scan 프로필로 다시 해 봅니다.
고른 프로필마다 ② 아래에 안내 카드(③)가 붙어, 그 프로필이 무엇을 하는지 · 언제 쓰는지 · 무엇을 조심할지를 말합니다.
| 프로필 | 카드 제목 | 요점 |
|---|---|---|
default | 「RAG 는 이 문서를 어떻게 읽었나」 | RAG 색인과 같은 파싱 옵션입니다. 여기 나온 글이 RAG 가 색인했을 글이고, 여기서 빠진 내용은 RAG 도 모릅니다 |
fast | 「OCR 을 끄고 빠르게 읽으면 이 문서는 어떻게 보이나」 | OCR 이 꺼져 있어 스캔본 · 이미지 속 글자는 나오지 않습니다. RAG 가 본 것과 다릅니다 |
ocr | 「이 문서에서 글자만 뽑으면 무엇이 나오나」 | 표 구조를 인식하지 않아 표가 줄글로 풀립니다. 비전 콘솔의 OCR 연산이 이 프로필을 씁니다 |
scan | 「텍스트 레이어를 버리고 전부 OCR 하면 이 문서는 어떻게 읽히나」 | 멀쩡한 텍스트 층까지 버리고 OCR 로 읽습니다. 디지털로 만든 PDF 는 default 가 더 정확합니다 |
- 카드가 함께 알리는 한도 — 콘솔을 거치는 업로드는 100 MB 가 상한입니다(넘으면 413). 서비스 자체 상한(
MAX_DOCUMENT_BYTES, 기본 200 MiB)보다 콘솔 상한이 먼저 막습니다. 화면은 2초마다 진행을 물어 약 5분이 지나도 끝나지 않으면 기다리기를 멈춥니다 — 파싱을 취소하는 것은 아닙니다. - 여기서 올린 문서는 결과만 보여 주고 버립니다. RAG 에 색인되지 않습니다.
scan이 확실히 낫더라도 이 화면의 프로필은 RAG 설정을 바꾸지 않습니다. RAG 에서도 같은 결과를 얻으려면 문서 파싱의 OCR 설정(DOCLING_*)을 바꿔야 합니다.- 도면(DXF · PDF)은 이 화면이 아니라 도면 판독 시험 에서 봅니다.
도면 판독 시험 — /parser/drawings/
도면 파일 하나를 올려, 문서 이해 서비스가 그 도면에서 무엇을 어디서 읽는지 봅니다. 사이드바 도면 묶음에 있습니다. RAG 가 도면을 색인할 때 쓰는 판독기와 같으므로, 「챗봇이 도면의 치수를 엉뚱하게 말한다」 를 가를 때 씁니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 설명 |
| ② | 도면 | 파일을 끌어 놓거나 눌러 고르고 도면 판독. 허용 형식과 크기 상한은 서비스가 정하며, 올리는 자리 아래 글이 그 안내입니다 |
| ③ | 요약 줄 | 형식 · 쪽 · 치수 · 부품표 행 · 표제란(찾음 · 못 찾음) · 경고 |
| ④ | 쪽 그림 | 판독한 위치를 쪽 그림 위에 색 상자로 그립니다. 종류 단추(표제란 · 치수 · 부품표 · 주기)로 상자를 켜고 끕니다 |
| ⑤ | 판독 표 | 표제란 · 치수(공차) · 부품표 · 주기 · 구역을 표로. 표의 줄을 누르면 그 상자가 강조됩니다 |
| ⑥ | 두 판 비교 시험 | 같은 도면의 옛 판 · 새 판 두 파일을 올려 비교 — 표제란 · 치수 · 부품표 · 주기 변경과 바뀐 영역을 봅니다 |
치수 표의 «상·하한» 열. 치수마다 허용 범위를 어디서 얻었는지 함께 적습니다.
| 칸에 보이는 것 | 뜻 |
|---|---|
| «아래 ~ 위» 값 + (공식) | 도면의 끼워맞춤 기호(예: H7)로 ISO 끼워맞춤 계산식이 낸 추정값입니다 — 규격 표와 µm 단위로 다를 수 있습니다 |
| «아래 ~ 위» 값 + (도면) | 도면에 ± 로 적힌 값 그대로입니다 |
| 계산 안 함 | 계산하지 않았습니다 — 마우스를 올리면 사유가 보입니다 |
| 일반공차 … | 공차가 없는 치수에 도면이 지정한 일반공차 등급입니다(수치는 내지 않습니다) |
«공식» 값이 하나라도 있으면 표 아래에 「«공식» 은 ISO 끼워맞춤 계산식 추정값입니다 — … 합부 판정은 보유한 규격 문서로 확인하세요.」 가 붙습니다.
기하공차 틀 검사 카드. 도면의 기하공차 틀이 규칙에 맞는지 봅니다. 머리에 도면의 일반공차 지정과 데이텀 글자가 나오고, 줄마다 심각도(오류 · 경고 · 정보) · 대상 글자 · 내용 · 근거(규격 번호 · 개념 이름)가 나옵니다. 치수와 이어진 줄을 누르면 그 치수가 그림에서 강조됩니다. 어긋난 틀이 없으면 「규칙에 어긋난 틀이 없습니다.」 입니다.
안내 카드. 올리는 자리 아래 「이 도면에서 무엇을 읽어 냈나」, 비교 시험 아래 「두 판 사이에 무엇이 바뀌었나」 카드가 무엇을 · 언제 · 어떻게 읽을지를 말합니다. 요점은 이렇습니다.
- RAG 의 도면 색인도 이 판독 결과를 씁니다. 여기서 빠진 치수는 RAG 도 모릅니다.
- 여기서 올린 도면은 결과만 보여 주고 버립니다. RAG 에 색인되지 않습니다 — 색인된 도면은 도면 대장 에서 봅니다.
- 글자 층이 없는 스캔 PDF 는 그 쪽의 글자를 읽지 못합니다. 이 판독기는 OCR 을 하지 않습니다.
- 비교에서 변경이 하나도 없으면 두 판이 같거나 비교하지 못한 것입니다 — 비교하지 못한 것 목록과 신뢰도로 가릅니다.
표제란 못 찾음 · 글자 층 없음(스캔 쪽) · 구역 격자 기본값(테두리 눈금 없음) 은 서비스가 «어떻게 읽었는지» 를 알려 주는 것입니다. 스캔 PDF 는 글자 층이 없어 치수를 읽지 못합니다.
허용 형식 밖의 파일은 서비스가 사유와 함께 거절합니다. DWG 는 CAD 에서 DXF 나 PDF 로 내보내 올리십시오.
비전 점검 — /vision/
이미지 하나를 올려, 비전 서비스가 실제로 무엇을 보는지 확인합니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 이 화면이 부르는 서비스 |
| ② | 요청 | 연산(점검 · 계기 판독 · 텍스트 추출 · 분류 · 자유 질문 · 객체 탐지)을 고르고 이미지를 올려 실행 |
| ③ | 안내 카드 | 고른 연산이 무엇을 하는지, 결과를 어떻게 읽는지(자세히 / 접기) |
실행하면 표본 · 일치 · 서로 다름 요약 줄과 이미지 · 결과 카드가 나옵니다. 객체 탐지면 이미지에 박스가 그려집니다.
비전 서비스는 모델에게 여러 번 묻고 충분히 많은 답이 일치해야 결과를 냅니다(대개 3 중 2, 계기 판독은 5 중 4). 답이 갈리면 값을 지어내지 않고 판정 불가 로 돌려줍니다. 다시 눌러도 같은 답이 나오니, 사진을 다시 찍으십시오. 자유 질문 은 이 일치 검사를 거치지 않으므로 판독값이나 판정에 쓰지 마십시오.
연동 지도 — /thread/
디지털 스레드가 외부 시스템과 어떻게 이어져 있는지 한 지도로 봅니다. 커넥터 등록 · 칸 바인딩 · 동기화 절차는 디지털 스레드 를 보십시오.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 보기 단추(지도 · 목록 · 준비도 원천), 커넥터 추가(옆 창에서 등록 네 단계), 새로고침 |
| ② | 요약 줄 | 커넥터 · 켜짐 · 적합성 실패 · 도구 — 연동이 몇 개 살아 있는지 |
| ③ | 지도 | 위 거르기 줄(가족 · 상태)과 지도. 외부 시스템 → 커넥터 → 도구 → 바인딩 → 공장 그래프 를 왼쪽에서 오른쪽으로. 초록 = 켜짐, 빨강 = 적합성 실패, 회색 = 꺼짐. 노드를 누르면 옆 창에 설정·적합성 결과·최근 행동 호출이 열리고, 지도는 그 노드의 사슬만 밝힙니다 |
지도는 이렇게 다룹니다.
- 처음에는 1배 크기로 가운데에 맞춰 열립니다. 커넥터는 가족 순서 ERP → MES → PLM → SCM → 일정을 먼저 두고, 나머지 가족은 이름 순으로 놓입니다.
- 끌어서 옮기고, 휠로 위아래, Ctrl+휠 로 확대합니다. 오른쪽 위 단추가 확대 · 축소 · 전체 보기 입니다.
- 지도 위 거르기 줄에서 가족 · 상태 로 커넥터를 좁힙니다(지도에만 걸립니다). 거르기 지우기 로 되돌립니다.
- 지도 축소판 은 기본으로 숨겨져 있습니다. 조작 단추의 축소판 보기 로 켭니다.
- 커넥터가 많아 지도가 읽히지 않으면 목록 으로 표를 봅니다 — 이름 · 가족 · 시스템 · 엔드포인트 · 상태 · 레벨 · 도구 · 자격증명 · 적합성.
- 커넥터 추가 의 가족 목록은 처음에
erp·mes·plm·scm·sched·qm을 보입니다.
커넥터 옆 창의 지금 동기화 는 그 커넥터의 바인딩을 바로 거울에 싣고, 원천에서 사라진 연결을 닫습니다(지우지 않고 끝난 시각을 적습니다 — 연결 이력이 그것으로 섭니다). 끝나면 「객체 N개 · 연결 N개를 동기화했습니다」 가 뜹니다. 커넥터가 돌려준 목록이 잘렸으면 노란 줄 「이번 동기화는 사라진 연결을 닫지 않았습니다 — 수집이 잘렸습니다(…). 끝까지 읽은 동기화에서 닫힙니다.」 가 함께 뜹니다 — 잘린 목록으로 연결을 닫으면 멀쩡한 연결까지 닫히기 때문입니다. 켜진 커넥터는 서비스가 주기로도 동기화합니다 → 디지털 스레드 — 커넥터 동기화
커넥터 등록·수정·삭제·발견·시험·동기화·칸 바인딩은 로그인한 관리자 이름으로 콘솔 감사 로그(thread.write)에
남습니다. 행동 도구(🔒)는 콘솔에서 부르지 않습니다 — 코파일럿이 승인된 제안 카드로 중계합니다.
준비도 원천 — 연동 지도의 셋째 보기
코파일럿의 반장 작업 준비도(공정마다 Go/No-Go)가 무엇을 보고 판정하는지를 운영자 쪽에서 봅니다. 판정 결과(어느 공정이 막혔나)는 여기 없고 코파일럿 화면에 있습니다. 여기서 보는 것은 «항목마다 어느 커넥터가 붙어 있고, 그 자료가 신선한가, 빠지면 판정이 어떻게 되나» 입니다. 디지털 스레드 서비스가 이 기능을 내는 판일 때만 보기 단추가 보입니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 머리 줄 | 마지막 판정 시각과 상태(판정함 · 낡은 원천 — 판정 멈춤 · MES 없음 — 판정 안 함), 지금 재기 |
| ② | 항목 · 배선 | 여덟 항목마다 배선됨(초록) · 부분 배선(주황) · 없음(회색) |
| ③ | 원천(가족 · 도구 → 커넥터) | 입력마다 필수 · 둘 중 하나 · 선택, 어느 가족의 어느 도구로 읽는지, 그 도구를 내는 커넥터 이름. 자료가 상한보다 오래되면 주황 낡음 표찰이 붙습니다. 커넥터 이름을 누르면 지도로 돌아가 그 커넥터의 옆 창이 열립니다 |
| ④ | 빠지면 | 원천이 없을 때 판정이 어떻게 되는지 — 판정 «알 수 없음», 또는 MES 작업지시가 없으면 판정 전체를 하지 않는다. 입력마다 무엇을 모르게 되는지 한 줄이 붙습니다(예: 「자재 부족을 모른다 — 자재가 모름」). 최근 판정에서 실제로 못 읽은 입력은 «최근 판정에서 못 읽음» 으로 적힙니다 |
여덟 항목과 그것을 대는 가족입니다(정본은 디지털 스레드 서비스의 선언 한 곳이고, 판정과 이 화면이 같은 선언을 읽습니다).
| 항목 | 읽는 원천 |
|---|---|
| (바닥) | MES 작업지시 — 없으면 어떤 항목도 판정하지 않습니다 |
| 선행 공정 | MES 작업지시 |
| 자재 | SCM 결품(없으면 MES 가 내는 같은 도구) |
| 공구·교정 | 공구 관리(작업별 공구 목록 — 필수, 공구 대장 — 선택) |
| 인원·자격 | MES 공정의 자격 요구 + ERP 인원(없으면 MES 인원) |
| 허가·격리 | 안전(EHS) 작업 허가(필수) · 격리(선택) |
| 품질 막힘 | 품질(QM) 부적합(없으면 MES 부적합) |
| 설비 정비 | 정비(CMMS) 예방정비 창 · 정비 작업지시 중 하나 이상 |
| 도면 판 | PLM 설계 변경(필수) · PLM BOM(선택) · 작업장 도면(디지털 스레드 거울 — RAG 가 색인한 도면) |
- 신선도는 마지막 판정 기준입니다. 판정 기록이 없으면 「아직 판정 기록이 없다」 가 뜹니다 — 지금 재기 가 판정을 한 번 돌려(읽기만 합니다) 새로 잽니다.
- 신선도 상한은 가족마다 다릅니다 → 디지털 스레드 — 자료가 낡으면
- 지도의 커넥터 옆 창에도 준비도 항목 줄이 있어, 그 커넥터가 어느 항목을 대는지 보입니다.
판정이 틀린 것이 아니라 원천이 안 붙은 것입니다. 여기서 없음(회색)인 항목을 찾아, 그 가족의 커넥터를 붙입니다. «모름» 은 GO 가 아닙니다 — 원천이 빠진 항목을 통과로 세지 않습니다.
그래프 거울 — /thread/mirror/
플랫폼 원장과 학습된 간선을 공장 그래프로 주기적으로 옮겨 담는(투영) 상태를 봅니다. 읽기 전용입니다. 자세한 내용은 디지털 스레드 를 보십시오.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 새로고침 |
| ② | 요약 줄 | 투영 · 마지막 성공 · Dt 객체 · 투영된 연결 — 투영이 제때 성공하고 있는지 |
| ③ | 마지막 실행 | 끝난 시각 · 회차 · 연속 실패 · 단계별 결과 — 어느 단계가 실패했는지 찾습니다 |
| ④ | 거울에 담긴 것 | 항목별 출처 와 건수 — 무엇이 얼마나 담겼는지 |
MCP 게이트웨이 — /mcp-gateway/
AI 가 부르는 모든 MCP 도구가 지나가는 관문입니다. 플랫폼 통합 MCP, 이 설치의 AI 서비스(시계열 인사이트 · RAG · 문서 이해 · 비전 ·
디지털 스레드 · 공학 계산), 운영자가 붙인 외부 MCP 서버의 도구를 모아 주소 하나(plantpulse-mcp-gateway-api:7160/mcp/)로 냅니다.
코파일럿은 이 주소 하나만 보고, 도구를 켜고 끄는 것도 여기서 합니다(2026.10 재릴리즈(2026-10-20) — 그 전에는 코파일럿 관리 콘솔의 도구 서버(MCP) 화면이었습니다).
| 화면 | 주소 | 하는 일 |
|---|---|---|
| 개요 | /mcp-gateway/ | 게이트웨이 상태(데이터베이스 · 임베딩 · 플랫폼 MCP · MCP 서버), 서버 요약, 지난 24시간 호출 · 오류 · 지연 p95 · 검색 수 |
| 서버 | /mcp-gateway/servers/ | 게이트웨이 뒤의 서버 — 종류(플랫폼 · 내장 · 외부) · 접두사 · 상태 · 켜진 도구 수 · 인증 · 회로 · 마지막 발견. 재발견 · 켜기/끄기, 외부 서버의 서버 등록 · 수정 · 인증 · 삭제 |
| 도구 | /mcp-gateway/tools/ | 발견한 도구 전부 — 노출 이름 · 서버 · 설명 · 검색어와 그 출처 · 상태 · 검색 색인. 도구마다 켜고 끄는 자리이고, 설명(4000자)과 검색어를 덮어쓸 수 있습니다 → 도구 검색어 |
| 권한 | /mcp-gateway/permissions/ | 어느 호출자(코파일럿 · 발급한 키 각각)가 어느 서버의 도구를 보나 |
| 클라이언트 API 키 | /mcp-gateway/client-keys/ | 외부 MCP 클라이언트(다른 에이전트 · 데스크톱 앱)에 줄 키(ppgw_…) 발급 · 범위 · 폐기 |
| 검색 시험대 | /mcp-gateway/search/ | 질문 하나를 넣어 게이트웨이가 모델에 줄 도구를 봅니다 — 점수 · 어휘 순위 · 임베딩 순위 · 고른 이유 |
| 검색 설정 | /mcp-gateway/search-settings/ | 도구 검색 사용 · 예산(턴마다 주는 도구 수) · 계열 보장 · 의존 보강 |
| 호출 기록·지표 | /mcp-gateway/calls/ | 서버 · 오류별 호출 수와 호출 한 건마다 시각 · 호출자 · 서버 · 도구 · 결과(성공 · 도구 실패 · 전송 실패) · 소요 · 결과 크기 → 호출 기록 |
도구 켬/끔 — 처음 값은 정책이 정합니다
도구는 처음 발견될 때 게이트웨이 정책대로 켜지거나 꺼진 채 들어옵니다. 그 뒤로는 도구 화면에서 바꾼 값이 남고, 기동이나 판 올림이 덮지 않습니다.
| 서버 | 처음 |
|---|---|
| 플랫폼 통합 MCP | 전부 켬 |
| 시계열 인사이트 | 34종 켬 · 4종 꺼짐 · 쓰기 1종은 켤 수 없음 |
| 디지털 스레드 | 9종 켬 |
| 공학 계산 | 4종 켬 |
| RAG · 문서 이해 · 비전 | 켬(2 · 2 · 5종 전부) — 문서 검색 rag_search 를 끄면 채팅이 문서를 못 찾습니다 |
| 외부 서버 | 꺼짐 |
도구마다의 목록은 MCP 도구 지도에 있습니다.
- 켤 수 없는 도구가 있습니다 — 쓰기로 의심되는 도구(
readOnlyHint=false를 선언했거나 이름 · 설명이 쓰기)와, 디지털 스레드가 아닌 서버가 낸 커넥터 도구(mes_·erp_…)입니다. 플랫폼 도구는 게이트웨이가 막지 않고, 쓰기라면 코파일럿의 승인 게이트가 사람의 승인을 받습니다. - 두 서버가 같은 노출 이름을 내면 먼저 등록된 쪽이 이기고 나중 것은 «충돌» 로 노출되지 않습니다. 나중 서버의 접두사를 바꿉니다.
- 덮어쓴 설명은 모델이 읽는 설명과 검색 색인을 함께 바꿉니다. 비우면 원래 서버의 설명으로 돌아갑니다.
외부 MCP 서버를 붙인다
- 서버 › 서버 등록 — 이름 · Streamable HTTP 주소 · 도구 접두사(소문자 · 숫자,
_로 끝남, 필수) · 호출 시간 상한(1~600초, 기본 120). 서버는 꺼진 채, 아무에게도 허용되지 않은 채 생깁니다. - 인증이 필요하면 인증 에 헤더 이름과 값을 넣습니다. 값은 봉인되고 다시 보이지 않습니다(«설정됨» 만).
- 켜기 → 재발견. 외부 도구는 꺼진 채 들어옵니다. 🔴 외부 도구의 설명과 인자는 모델 프롬프트에 그대로 들어가므로 도구 화면에서 읽어 보고 도구마다 켭니다. 켜 둔 외부 도구의 정의가 바뀌면 게이트웨이가 그 도구를 끄고 다시 보라고 표시합니다.
- 권한 에서 코파일럿(또는 발급한 키)에게 그 서버나 도구를 허용합니다.
- 외부 도구는 코파일럿에 쓰기로 넘어갑니다 — 코파일럿은 사람의 승인 없이 부르지 않습니다.
- 주소가 루프백 · 링크로컬 · 클라우드 메타데이터 주소로 풀리면 붙지 않습니다. 사내망(10/8 · 172.16/12 · 192.168/16)은 됩니다.
- 플랫폼 · 내장 서버는 설치가 정하므로 끄기만 되고 수정 · 삭제는 안 됩니다.
- 🔴 MES · ERP · PLM 같은 외부 시스템 커넥터는 여기가 아니라 연동 지도에 붙입니다.
권한과 클라이언트 API 키
- 내장 서버는 처음부터 코파일럿에 모든 도구로 허용돼 있습니다. «모든 도구» 는 나중에 발견되는 도구까지 포함합니다.
- 새 외부 서버와 새 키는 아무것도 허용되지 않은 채 생깁니다. 「도구가 하나도 안 보인다」 면 먼저 권한 을 보십시오.
- 키의 원문은 발급할 때 한 번만 보입니다. 목록에는 앞 12자만 남습니다. 폐기는 바로 먹습니다.
- 키에는 범위(설비 · 사이트 · 프로젝트 · 고객 PO · 협력사)와 등급을 줍니다. 범위가 없는 키는 외부 서버 도구만 부를 수 있고, 내장 도구는 그 범위 · 등급으로 좁혀 읽습니다. 플랫폼 도구는 범위가 설치 전체 인 키만 부릅니다(플랫폼은 범위로 거르지 않습니다).
- 이 키는
/mcp/만 씁니다. 공통 메뉴의 API 키 와는 다른 화면입니다. - 바깥의 MCP 클라이언트가 붙는 주소는
https://<호스트>/mcp/gateway/입니다 → API 연동 가이드
도구 검색 — 기본 켬, 예산 20
켠 도구를 질문마다 다 싣지 않고, 질문에 맞는 것만 골라 코파일럿에 줍니다. 처음 값은 켬 · 예산 20 · 계열 보장 켬 · 의존 보강 켬 입니다.
이름으로 ID 를 찾는 search_domains 와 문서 검색 rag_search 는 예산과 상관없이 늘 실립니다(그 계정에 허용된 경우).
- 검색 설정에서 끄면 코파일럿이 허용된 도구 전부를 받습니다 — 도구가 70여 종이면 모델이 고르는 데 자주 실패합니다. 켜는 기준은 오프라인 평가의 재현율@20 0.95 이상이고, 기준 아래에서 켜려 하면 화면이 경고합니다(막지는 않습니다).
- 운영자가 바꿔 저장한 값이 이깁니다 — 판을 올려도 기본값으로 돌아가지 않습니다.
- 🔴 검색은 임베딩 서비스에 기댑니다. 임베딩이 죽으면 검색이
503 search_unavailable이고 대체 경로가 없습니다 — 개요 의 «임베딩» 을 보십시오. - 검색 시험대 는 검색이 꺼져 있어도 순위를 냅니다. 「이 질문에 왜 이 도구가 안 불렸나」 를 볼 때 씁니다.
도구 검색어 — 한국어 질문을 도구에 잇는 낱말
도구 설명은 영어라, 「알람 확인 처리」 같은 한국어 질문은 검색어로 도구에 이어집니다. 검색어는 낱말 검색(BM25)에만 쓰이고, 임베딩하지 않으며 모델에게 보이지도 않습니다. 도구 화면의 설명 칸 아래에 도구마다 지금 쓰는 검색어와 출처가 보입니다.
| 출처 | 뜻 |
|---|---|
| 이 설치 덮어쓰기 | 이 설치의 운영자가 덮어썼습니다 — 아래 셋보다 이깁니다 |
| 서버 선언 | MCP 서버가 도구와 함께 선언했습니다(시계열 인사이트 · 디지털 스레드 · 공학 계산 · RAG · 문서 이해 · 비전) |
| 게이트웨이 기본값 | 선언하지 않는 서버(플랫폼 통합 MCP)에 게이트웨이가 붙이는 값입니다 |
| 검색어 없음 | 이름과 설명만으로 색인합니다 |
- 검색어는 잘리지 않고 전부 보입니다. 외부 서버가 선언한 검색어도 켜기 전에 다 읽어 보십시오.
- 검색어 단추로 한국어(ko) 검색어를 한 줄에 하나(또는 쉼표로) 고칩니다. 다른 언어 검색어는 그대로 남고 창에 함께 보입니다.
- 🔴 상한은 도구 하나에 언어 4개, 모든 언어를 합쳐 8개 · 64자입니다. 넘으면 저장 단추가 잠깁니다.
- 바꾸지 않으면 저장 단추가 잠깁니다 — 서버 값의 복사본이 덮어쓰기로 굳어, 나중에 서버가 값을 바꿔도 가려지는 일을 막습니다.
- 비워 저장하면 그 도구는 «한국어 검색어 없음» 입니다. 창 위 «이 설치가 검색어를 덮어쓰고 있습니다» 띠의 덮어쓰기 해제는 서버 선언 · 게이트웨이 기본값으로 돌아갑니다. 둘은 다른 단추입니다.
- 서버가 틀린 모양이나 상한을 넘게 낸 검색어, 상한을 넘어 버려진 저장된 덮어쓰기는 그 사유가 경고 줄로 보입니다(버린 값은 없는 것으로 치고 다음 출처를 씁니다). 버려진 덮어쓰기도 덮어쓰기 해제로 지웁니다.
- 화면 위 검색 칸은 이름 · 설명 · 검색어를 함께 거릅니다. 켜 둔 외부 도구의 검색어가 바뀌면 정의가 바뀐 것으로 보고 게이트웨이가 그 도구를 끕니다.
이럴 땐
| 증상 | 볼 것 |
|---|---|
| 서버 상태가 «다운» | 서버 의 회로(연속 실패 3회면 120초 동안 부르지 않습니다)와 발견 오류 |
| 외부 서버가 «주의», 인증 «설정 안 됨» | 인증 헤더는 정했는데 값이 없습니다 — 인증 에서 다시 넣습니다 |
호출이 upstream_auth | 그 서버가 401/403 을 냈습니다 — 인증 값을 확인합니다 |
호출이 result_too_large | 결과가 1 MiB 를 넘었습니다 |
| 발급한 키로 도구가 하나도 안 보임 | 새 키는 권한이 없습니다 — 권한 |
| 한국어로 물으면 맞는 도구가 안 실림 | 검색 시험대에 그 질문을 넣어 순위를 보고, 도구 화면에서 그 도구의 검색어와 출처를 봅니다 → 도구 검색어 |
| 호출은 «도구 실패» 인데 서버는 정상 | 뒷단이 답했지만 결과가 실패입니다 — 서버가 아니라 도구 결과(인자 · 원천 자료)를 봅니다 → 호출 기록 |
발급한 키의 호출이 forbidden_scope | 그 키에 범위가 없거나, 플랫폼 도구인데 범위가 설치 전체가 아닙니다 — 클라이언트 API 키 |
호출 기록 — 도구 실패와 전송 실패
호출 기록·지표의 결과는 셋입니다. 오류 수는 도구 실패를 포함하고, 옆에 «도구 N · 전송 N» 으로 나눠 보입니다. 서버별 표에도 도구 실패 열이 있습니다.
| 결과 | 뜻 |
|---|---|
| 성공 | 도구가 답했고 결과도 성공입니다 |
| 도구 실패 | 뒷단 서버는 답했지만 결과가 실패입니다 — isError, 비지 않은 error, {"ok": false}, error_code 와 status: "error"(코파일럿이 실패로 보는 규칙과 같습니다) |
| 전송 실패 | 뒷단에 닿지 못했거나 게이트웨이가 막았습니다 — 오류 코드가 이유입니다 |
결과 거르기는 전체 · 성공 · 실패(전체) · 도구 실패 입니다. 「서버는 멀쩡한데 답이 이상하다」 면 도구 실패로 거릅니다.
호출 기록에는 인자 · 결과 · 인증 값이 남지 않습니다. 사람 단위로 «누가 무엇을 물었나» 는 코파일럿의 감사 기록입니다 → 코파일럿 관리
자동화 샌드박스 — /sandbox/
자동화 단계의 파이썬 코드(앞 단계 도구 결과를 numpy · pandas · scipy 로 처리해 JSON · 표 · 그림 · 글로 내는 것)를 돌리는 서비스의 화면입니다. 레일에서는 MCP 게이트웨이와 따로 있는 자동화 샌드박스 입니다. 콘솔은 읽기만 합니다 — 실행은 코파일럿의 승인된 자동화 계획이 하고, 콘솔에서 샌드박스로 가는 쓰기는 막혀 있습니다.
샌드박스 컨테이너 자체가 gVisor(runsc) 위에서 돌고, 실행마다 그 안에서 새 네임스페이스(user · net · pid · mount)로 격리된 프로세스를 띄웁니다. 실행마다 새 gVisor 를 띄우는 것이 아닙니다. 실행 안에는 네트워크가 없어 도구나 REST 를 부르지 못하고, 루트 파일 시스템은 읽기 전용입니다.
| 화면 | 주소 | 하는 일 |
|---|---|---|
| 개요 | /sandbox/ | 격리(gVisor 판 · 플랫폼 · 아키텍처 · 네트워크, 마지막 자기 시험), 실행 중 · 대기열, 기간별 실행 · 오류 · 돌려보냄, 결과 코드별 실행 수 |
| 실행 이력 | /sandbox/runs/ | 실행마다 받은 시각 · 결과 · 오류 코드 · 코드 SHA-256 · 크기 · 대기 · 소요. 펼치면 입력 · 출력 크기 · 한도 · 맥락. 보존은 기본 30일 |
| 상한 | /sandbox/limits/ | 실행 한 번의 한도(시간 · 메모리, 코드 · 입력 · 출력 · 표 · 그림 · /tmp · 프로세스), 동시 실행 · 대기 한도, import 할 수 있는 패키지와 판. 샌드박스가 실제로 거는 값입니다 |
결과는 성공 · 오류 · 돌려보냄 셋입니다. 돌려보냄은 실행하지 않은 요청이고, 실행 이력에서 소요가 «—» 입니다.
| 코드 | 결과 | 뜻 |
|---|---|---|
ok | 성공 | 끝나서 결과를 돌려주었습니다 |
syntax | 오류 | 코드가 컴파일되지 않았습니다 — 아무것도 돌지 않았습니다 |
forbidden | 오류 | 계산 단계가 할 수 없는 일(네트워크 · 프로세스 · 네이티브 코드 · /tmp 밖 파일)을 시도했습니다 |
timeout | 오류 | 벽시계 또는 CPU 한도를 넘었습니다 |
memory | 오류 | 메모리 한도를 넘었습니다 |
output_too_large | 오류 | 출력 · 표 · 그림 · /tmp 가운데 하나가 상한을 넘었습니다 |
runtime | 오류 | 그 밖의 예외이거나 결과를 JSON 으로 바꾸지 못했습니다 |
queue_full | 돌려보냄 | 대기열이 가득 찼습니다 |
queue_timeout | 돌려보냄 | 빈 자리를 너무 오래 기다렸습니다 |
sandbox_unavailable | 돌려보냄 | 격리를 준비하지 못했습니다 — 코드를 돌리지 않았습니다 |
- 🔴 코드 원문은 여기 없습니다. 샌드박스는 코드 · 입력 · 출력을 남기지 않고 크기와 코드 SHA-256 만 남깁니다. 원문은 같은 해시의 코파일럿 승인 계획에 있습니다.
sandbox_unavailable이 쌓이거나 개요에 「격리 자기 시험이 실패했습니다」 가 뜨면 격리 준비가 실패하고 있다는 뜻입니다. 개요 › 격리 의 런타임 판과 마지막 자기 시험을 보고, 샌드박스의 로그를 봅니다.- 「실행 기록이 저장되지 않고 있습니다」 가 뜨면 실행 기록 저장소(PostgreSQL)에 쓰지 못하는 것입니다. 실행은 계속되지만 그동안의 실행은 기록과 숫자에서 빠집니다.
- 공통 메뉴는 API 엔드포인트 · 로그 · API 키 · 설정 입니다. 샌드박스에는 MCP 서버가 없어 MCP 서버 정보 는 없습니다.
공통 메뉴
RAG API · 시계열 인사이트 · 문서 파싱 · 비전 · 디지털 스레드 · MCP 게이트웨이 여섯 서비스에 똑같이 있는 다섯 화면입니다.
주소의 <서비스> 자리는 rag · insight · parser · vision · thread · mcp-gateway 입니다. 그림은 RAG API 의 것입니다.
자동화 샌드박스(sandbox)는 MCP 서버 정보 를 뺀 넷이 같습니다.
MCP 서버 정보 — /(서비스)/mcp-info/
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 이 서비스의 MCP 주소와 요약(도구 · 리소스 · 프롬프트 개수) — 서비스에 직접 물어 실시간으로 채웁니다 |
| ② | 도구 표 | AI 코파일럿이 부를 수 있는 도구 목록 — 도구 · 설명 · 파라미터. 줄을 누르면 파라미터의 종류 · 필수 · 기본값 이 펼쳐집니다 |
그 아래에 리소스 · 프롬프트 표가 이어집니다.
도구가 하나도 없는 MCP 서버는 «도구 없음» 이 아니라 목록을 읽는 데 실패한 것으로 보십시오.
API 엔드포인트 — /(서비스)/api-endpoints/
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 엔드포인트 개수와 설명 — 서비스의 OpenAPI 스키마에서 만듭니다 |
| ② | 표 | 메서드 · 경로 · 설명 · 도메인 — 연동 개발자가 부를 API 를 찾습니다 |
MCP 엔드포인트(POST /mcp)는 OpenAPI 스키마에 없습니다 — MCP 서버 정보 를 보십시오.
로그 — /(서비스)/logs/
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 자동 5초(켜 두면 5초마다 다시 읽습니다) · 새로고침 |
| ② | 머리 줄 | 읽고 있는 로그 파일 · 크기 · 기록 수 — 파일이 비었거나 손상된 줄이 있는지 |
| ③ | 로그 tail | 로그 파일의 끝부분, 최신이 맨 위 — 시각 · 레벨 · 이벤트 · 필드 |
화면 위쪽에서 줄 수 · 레벨 · 검색어(Enter)로 좁힐 수 있습니다. SSH 로 docker logs 를 치지 않아도 됩니다.
API 키 — /(서비스)/api-keys/
이 서비스의 인바운드 API 키 인증이 실제로 켜져 있는지 잽니다. 키 «값» 을 보는 화면이 아닙니다.
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 화면 이름과 점검 실행 — 누를 때만 키 없이·키를 싣고 두 번 불러 봅니다 |
| ② | 요약 줄 | 콘솔 키(콘솔이 키를 들고 있는지와 그 지문) · 인증(점검 결과) · 서비스 간 공유(여러 서비스가 같은 키를 쓰는지) |
| ③ | 왕복 시험 (Round trip) | 키 없이 · 키를 싣고 의 응답 코드와 판정 · 뜻 — 닫힌 서비스는 401 다음 200 으로 답합니다 |
| ④ | 배선 (Wiring) | 서비스마다 콘솔 환경변수 · 서비스 환경변수 · 키 · 업스트림 — 키가 어느 이름으로 어디에 들어가는지. 지문 옆 눈 아이콘을 누르면 평문이 보이고, 그 동작은 사용자명과 함께 감사 로그에 남습니다 |
| ⑤ | 표 아래 설명 | 호출자가 X-API-Key 로 보내야 하는 키이며, 콘솔과 서비스가 각각 어느 환경변수로 들고 있는지 |
| 판정 | 뜻 |
|---|---|
| 강제됨 | 키 없는 호출을 거부하고 콘솔의 키는 받습니다 — 정상 |
| 열림 | 키 없이도 응답합니다 — 경로가 닿는 누구나 접근할 수 있습니다 |
| 강제 안 됨 | 콘솔은 키를 들고 있지만 서비스가 키 없이도 응답합니다 |
| 키 불일치 | 서비스는 닫혀 있지만 콘솔이 든 키를 거부합니다 |
| 콘솔 키 없음 | 서비스는 닫혀 있는데 콘솔에 키가 없습니다 |
| 연결 불가 | 서비스가 답하지 않았습니다 — «통과» 가 아닙니다 |
다섯 서비스는 인바운드 키(PI_INBOUND_API_KEY)가 비면 기동을 거부합니다. 예외는 설치 env 에 PI_INBOUND_AUTH_DISABLED=true 를
적어 인증을 일부러 끈 경우뿐이고, 그때 서비스는 키 없이 뜹니다 — 컨테이너는 healthy 라 아무 신호가 없습니다.
그래서 점검 실행 을 눌러 잽니다 — 화면을 여는 것만으로 서비스에 401 이 쌓이지 않게 한 것입니다. 키 없이도
응답하면(열림) 표보다 먼저 경고 상자가 뜹니다. 점검은 키 없는 요청을 일부러 한 번 보내므로, 401 을 감시하는
알림이 있다면 울릴 수 있습니다 → API 연동 가이드 — 인바운드 키
설정 — /(서비스)/config/
| 번호 | 자리 | 하는 일 |
|---|---|---|
| ① | 화면 위 | 키 개수와 새로고침 |
| ② | 구성요소 표 | 서비스가 쓰는 구성요소마다 상태 · 엔드포인트 — 어느 의존이 끊겼는지 봅니다 |
| ③ | 설정 표 | 지금 적용된 런타임 설정 키 · 값 — 비밀번호·토큰 같은 민감한 값은 가려져 나옵니다 |
값을 보여 줄 뿐 바꿀 수 없습니다. 실제로 바꾸려면 비밀번호 · API 키 변경 과 서비스 운영 을 보십시오.
이럴 땐 이렇게
| 증상 | 먼저 볼 곳 | 그다음 |
|---|---|---|
| 챗봇이 문서를 못 찾는다 | RAG API → 문서 | 질의 시험 으로 직접 검색 → 동기화 이력 |
| 챗봇 답변이 느리다 | LLM 대시보드의 P95 | GPU 사용률·온도 |
| 모델이 답을 안 한다 | LLM → 업스트림 상태 | LLM → 채팅 시험 으로 직접 한 번 |
| 분석 결과가 비어 있다 | 시계열 인사이트 → 파이프라인 상태 | 실행 이력 의 실패 건 |
| 뒷단이 인증 없이 열려 있지 않은지 | 해당 서비스 → API 키 → 점검 실행 | 비밀번호 · API 키 변경 |
화면에 … rejected the console's inbound API key (401) - check <환경변수> | 그 서비스의 키와 콘솔이 든 키가 다릅니다(오류 사유 upstream_auth, 502) | 해당 서비스 → API 키 의 배선 표 → 메시지에 적힌 환경변수를 맞추고 콘솔을 다시 띄웁니다 |
LLM 화면(API 키 · 로그 · 모델 등록 등)이 502, 사유 llm_upstream | 게이트웨이(LiteLLM)나 그 DB 가 5xx 를 냈습니다. 콘솔 고장이 아닙니다 — upstream_status 가 게이트웨이의 상태 코드입니다 | docker compose logs plantpulse-litellm → 문제 해결 |
| 연동 지도에 「커넥터 등록부를 쓸 수 없습니다: 503 … config_error …」 | 디지털 스레드의 등록부 저장소(DT_PG_*)나 암호 키(DT_SECRET_KEY)가 비어 있습니다 | 관리자에게 설정을 요청합니다. 그래프 거울 은 이와 무관하게 돕니다 |
| 도면 대장에 「도면 색인이 꺼져 있습니다」 | rag-api 의 DRAWING_INGEST_ENABLED 가 꺼져 있습니다(출하 기본) | 환경 설정 에서 켜고 rag-api 를 다시 띄웁니다 |
| 동영상 화면에 「영상·음성 수집이 꺼져 있습니다」 · 영상 업로드가 차단됨 | 설치 env 의 PI_MEDIA_ENABLED 가 켜져 있지 않습니다(출하 기본 꺼짐) | 환경 설정 에서 켜고 스택을 다시 만듭니다 |
| 올린 영상이 오래 대기 중 이다 | 처리 시간대 밖입니다 — 동영상 화면의 처리 시간대 줄이 다음 시작 시각을 말합니다 | 시간대를 바꾸려면 MEDIA_PROCESSING_WINDOW → 환경 설정 |
| 채팅이 영상을 근거로 쓰지 않는다 | RAG API → 동영상 의 녹취 비어 있음 · 검색에서 빠짐 | 그 줄을 펼쳐 안내대로 다시 녹취 |
| 도면 대장의 판 상태 가 모두 확인 불가 | 판을 물을 PLM 커넥터가 없거나 답하지 않습니다 | 디지털 스레드 → 연동 지도 에서 PLM 커넥터가 켜졌는지 → 디지털 스레드 |
| 반장 준비도가 «알 수 없음» 투성이다 | 그 항목의 원천 커넥터가 안 붙었거나 자료가 낡았습니다 | 디지털 스레드 → 연동 지도 → 준비도 원천 |
| 홈에 노란불이 떴다 | 상세 보기 를 펼쳐 툴팁 확인 | 해당 서비스 → 로그 |
| 홈에 빨간불이 떴다 | 해당 서비스 → 로그 | 서비스 운영 의 재기동 절차 |
| 화면이 비어 있고 오류 띠가 뜬다 | 그 서비스가 아직 안 떴을 수 있습니다 | 홈에서 상태 확인 |
서비스가 콘솔의 키를 거부하면, 콘솔은 그것을 로그인 만료로 보지 않고 오류 줄 하나(502, upstream_auth)로
보여 줍니다. 다시 로그인해도 풀리지 않으니, 메시지에 적힌 환경변수를 확인하십시오.
콘솔은 데이터를 못 가져왔을 때 빈 표로 위장하지 않고 오류 띠를 띄웁니다. 오류 띠가 보인다면 데이터가 없는 게 아니라 연결이 안 된 것입니다.
계정과 세션
콘솔 계정은 데이터베이스가 아니라 환경변수로 정합니다(/etc/kopens/plantpulse-ai.env).
| 환경변수 | 뜻 | 기본값 |
|---|---|---|
PI_ADMIN_USER | 로그인 아이디 | admin |
PI_ADMIN_PASSWORD | 로그인 비밀번호 | 없음 — 반드시 지정 |
PI_ADMIN_SESSION_SECRET | 세션 서명 키 | 설치기가 만듭니다 |
ADMIN_SESSION_MAX_AGE | 로그인 유지 시간(분) | 480 (8시간) |
컨테이너 안에서는 ADMIN_AUTH_USERNAME · ADMIN_AUTH_PASSWORD · ADMIN_SESSION_SECRET 이라는 이름으로
보이지만, compose 가 위 값을 옮겨 넣는 것이므로 고치는 것은 PI_* 쪽입니다.
PI_ADMIN_PASSWORD 를 비워 두면 콘솔이 기동을 거부합니다. 인증 없는 관리 포털이
조용히 열려 있는 것을 막기 위한 것이라, 정상 동작입니다.
PI_ADMIN_SESSION_SECRET 이 바뀌면 그때까지의 로그인이 모두 풀립니다. 설치기가 한 번 만든 값을
그대로 두면 재기동해도 로그인이 유지됩니다.
bin/passwd.sh 로 바꿀 수 없습니다bin/passwd.sh 가 관리하는 키 목록에 콘솔 계정은 들어 있지 않습니다
(비밀번호 · API 키 변경 의 표를 보십시오).
바꾸려면 환경 파일에서 직접 고치고 서비스를 재기동해야 합니다. 관리자에게
요청하십시오.
관련 문서
- 서비스 포트 맵 — 콘솔 주소와 각 서비스가 열려 있는 자리
- 서비스 운영 — 기동·정지·재기동 절차
- 비밀번호 · API 키 변경 — 키 회전
- 로그 및 모니터링 — 서버에서 직접 로그를 볼 때
- 디지털 스레드 — 연동 지도·그래프 거울·준비도 원천의 개념과 커넥터 등록 절차
- 환경 설정 — 도면 색인 · 영상·음성 수집 스위치(
DRAWING_INGEST_ENABLED·PI_MEDIA_ENABLED), 처리 시간대(MEDIA_PROCESSING_WINDOW) - 동영상 검색 — 색인된 영상이 채팅에서 쓰이는 방식
- 코파일럿 관리 — 행동 도구 승인이 일어나는 쪽
- MCP 도구 지도 — 서버마다의 도구와 처음 켜 두는 것