데이터베이스 모델

AI 스택이 데이터를 어디에 무슨 모양으로 담는지 정리한 문서입니다. 저장소가 넷이고 각각 역할이 다릅니다. 운영 절차는 데이터베이스 관리 를 보세요.

대부분은 AI 가 소유한 것이 아닙니다

PostgreSQL·Aster TSDB 는 PlantPulse 플랫폼 설치본을 공용으로 씁니다. AI 스택이 자기 DB 를 띄우지 않습니다. 그래서 「AI 백업」과 「플랫폼 백업」이 겹칩니다 — 어느 쪽이 무엇을 받는지 정리해 두지 않으면 양쪽 다 빠지는 구간이 생깁니다.

저장소	소유	담는 것
PostgreSQL `pi` · 스키마 `co`	AI (플랫폼 PG 안의 별도 DB)	채팅·이상 접수·설정·MCP (코파일럿)
PostgreSQL `pi` · 스키마 `dt`	AI (〃)	외부 시스템 커넥터 등록부·바인딩·행동 기록 (디지털 스레드)
PostgreSQL `lightrag`	AI (〃)	LightRAG 의 문서 처리 상태(`PGDocStatusStorage`)
PostgreSQL `rag_ingest`	AI (〃)	문서 적재 파이프라인(rag-api)의 상태 — 아래 「PostgreSQL rag_ingest」
PostgreSQL `litellm`	AI (〃)	LiteLLM 게이트웨이의 키·사용량
Aster TSDB `pi`	AI	피처 스토어·이상탐지 산출물
Aster TSDB `pp`	플랫폼 (읽기 전용)	원천 센서·알람·OEE
Neo4j `plantpulse-neo4j`	AI	LightRAG 지식 그래프
Neo4j `plantpulse-digital-thread-neo4j`	AI	디지털 스레드의 공장 그래프 거울 — 참조만
Qdrant	AI	문서 임베딩 벡터
`lightrag-storage` 볼륨	AI	LightRAG 의 KV 캐시 — 로컬 JSON 파일
`lightrag-inputs` 볼륨	AI	업로드된 원본 문서

플랫폼 PG 안에 AI 의 DB 가 «넷» 있습니다

AI 는 자기 PostgreSQL 을 띄우지 않고 플랫폼의 PostgreSQL 을 씁니다. 그 안에 pi · lightrag · rag_ingest · litellm 네 DB 를 만들어(provision-platform-db.sh 가 멱등으로) 씁니다. pi 는 AI 앱들이 함께 쓰는 DB 이고 앱마다 스키마 하나를 갖습니다(co 코파일럿 · dt 디지털 스레드). 2026.09 이하의 DB ch 는 기동 때 pi.co 로 옮겨집니다 → 데이터베이스 관리 Aster TSDB · Valkey · RustFS · MQTT 브로커(설비 알람 구독)도 마찬가지로 플랫폼 것을 붙여 씁니다 — AI 박스를 산정할 때 이 넷을 따로 잡지 마십시오.

PostgreSQL `pi.co` — 대화와 운영 상태

플랫폼 PostgreSQL 안의 별도 데이터베이스 pi 의 스키마 co 입니다 (jdbc:postgresql://<플랫폼호스트>:5432/pi?currentSchema=co). 코파일럿은 이 스키마 하나만 보고 붙으므로, 스키마를 붙이지 않은 표 이름은 전부 co 로 갑니다.

2026.09 이하의 ch 와 같은 표입니다

예전에는 DB ch 의 public 에 있던 표들입니다. 이름도 모양도 그대로이고 자리만 pi.co 로 옮겼습니다.

묶음	테이블
대화	`chats` · `chat_messages` · `prompts` · `prompt_history` — `chats.context` 는 대화에 고정한 맥락(2026.10 재릴리즈)
채팅 행동 · 답변 품질 (2026.10 재릴리즈)	`chat_action` (채팅 답에 실린 초안 제안 한 장 = 한 줄 — 누가 · 언제 · 왜 승인했나) · `chat_turn_metric` (답한 턴마다 지연 · 토큰 · 모델 · 인용 수 · 근거 종류 · 👍👎, 그리고 결과 표지 `outcome` — 비면 정상 답, `no_answer` 다시 시도해도 빈 답, `loop_cut` 반복을 끊음) · `chat_bench_run` (벤치 회차 점수)
사용자	`users` · `user_roles` · `employees` · `web_push_subscription` — `employees.work_role` 은 관리자가 정하는 업무 역할(승인 권한), `employees.home_role` 은 옛 화면에서 본인이 고르던 시작 화면(2026.10 재릴리즈 3 — 새 화면은 쓰지 않습니다) → 업무 역할
이상 접수 (표 이름은 `incident` 그대로)	`incident` · `incident_event` · `assignees`
와치(조건 감시 — 없어진 기능)	`watch` · `watch_run`. 화면 교체 판부터 만들지도 쓰지도 않습니다. 예전 설치에 있던 표는 그대로 남습니다
이상탐지 운영	`anomaly_mute` · `hourly_anomaly` · `asset_tag_profile`
MCP · 도구	`agent_tool_call_log` — 사람이 승인한 행동이면 `approved_by` 에 승인자가 남습니다. 옛 표 `mcp_server` · `mcp_tool_pref` · `mcp_tool_call_log` 는 2026.10 재릴리즈(2026-10-20) 에서 기동이 지웁니다 — 서버 · 켬/끔 · 호출 기록의 정본은 MCP 게이트웨이 DB(`pi` 의 `gw` 스키마)입니다
공개 API	`api_key`
설정	`config` · `config_audit_log` · `metadata`

새 표 · 칸은 기동할 때 저절로 생깁니다

위 «2026.10 재릴리즈» 표와 칸은 코파일럿이 기동할 때 CREATE TABLE IF NOT EXISTS · ADD COLUMN IF NOT EXISTS 로 만듭니다. 손으로 돌릴 이전(migration)은 없습니다. chat_turn_metric 에는 질문 · 답 원문이 없고(원문은 chat_messages), chat_action 에는 음성 · 답변 본문이 없습니다 — 도구 인자와 결과 번호뿐입니다.

도구 호출 원장 agent_tool_call_log

AI 가 부른 도구는 한 건도 빠짐없이 여기에 남습니다 — 시각 · 사용자 · 세션 · 도구 이름 · 출처 MCP 서버 · 인자(비밀값은 *** 로 가림) · 결과(ok · error · denied) · 걸린 시간. denied 는 승인 게이트가 막은 변경 도구 호출입니다 → MCP mcp_tool_call_log 는 등록 MCP 서버별 성공·소요 통계뿐이라 «누가 무엇을» 은 이 표에서 봅니다.

공개 API 키 api_key

키 평문은 저장하지 않습니다 — 해시(key_hash)와 알아보기용 앞자리(key_prefix)만 둡니다. 폐기해도 행을 지우지 않고 revoked_at 을 찍습니다. last_used_at 이 비어 있으면 쓰이지 않는 키입니다 → 코파일럿 관리 콘솔

채팅 이력의 정본은 여기 하나입니다

2026-07 개편 전에는 Aster TSDB 에도 대화 이력이 있었습니다. 지금은 chat_messages 단일 소스입니다. 옛 문서를 보고 Aster TSDB 에서 찾지 마세요.

PostgreSQL `pi.dt` — 디지털 스레드 등록부

디지털 스레드 API 가 소유하는 스키마입니다. 표는 서비스가 기동할 때 만듭니다. 모든 문장이 dt. 로 한정되어 있어 다른 스키마에 닿지 않습니다.

묶음	테이블
커넥터	`dt_connector` · `dt_connector_tool`
바인딩	`dt_binding` · `dt_binding_log` (운영자가 정한 칸 바인딩과 그 변경 기록 — 누가·언제·전후)
행동 기록	`dt_action_log` (승인을 거쳐 외부 시스템에 보낸 초안·요청)
Episode	`dt_episode` · `dt_episode_label`
동일성 선언	`dt_identity` · `dt_identity_log` (「이 현장에서 키 A 와 키 B 는 같은 것」이라는 운영자 선언과 그 변경 기록 — 자동으로 붙이지 않습니다)

커넥터 자격증명은 암호화 키 없이는 못 풉니다

dt_connector 의 자격증명은 PI_DT_SECRET_KEY 로 봉해 저장됩니다. 이 키를 잃으면 DB 를 되살려도 저장된 자격증명을 쓸 수 없어 커넥터마다 다시 넣어야 합니다. 호스트 env 파일을 백업할 때 함께 챙기십시오 → 디지털 스레드

PostgreSQL rag_ingest — 문서 적재 상태

rag-api 가 소유하는 DB 입니다. 표는 rag-api 가 기동할 때 만듭니다(멱등).

묶음	테이블	언제 생기나
동기화	`rag_asset_doc_sync` · `rag_sync_run` · `rag_asset_card`	늘
도면	`rag_drawing_doc` · `rag_drawing_chunk` · `rag_drawing_ident` · `rag_drawing_dim` · `rag_drawing_kg` · `rag_drawing_outbox`	`DRAWING_INGEST_ENABLED=true` 일 때만
영상 · 음성	`rag_media_job` · `rag_media_segment` · `rag_media_sidecar`	영상 · 음성을 켠 설치(`PI_MEDIA_ENABLED=true` — rag-api 안에서는 `MEDIA_INGEST_ENABLED=true`)에서만

rag_drawing_doc.source 는 도면이 어디서 왔는지입니다 — 관리 콘솔에서 올린 것(MANUAL)과, 플랫폼 자산 문서를 가져오는 동기화가 넣은 것(PLATFORM, 2026.10 재릴리즈 3). 후자는 플랫폼이 정본이라 콘솔에서 덮거나 지우지 않습니다.
rag_drawing_dim 은 치수 한 줄마다 상 · 하한(upper_limit · lower_limit)과 그 근거(limits_basis — 도면에 적힌 값인지, 끼워맞춤 공식으로 계산한 «공식 추정» 인지)를 담습니다.
rag_media_job 은 영상 · 음성 파일 한 편 = 한 줄입니다(어디서 왔나 source · 처리 상태 · 시도 횟수 · 썸네일 수 등). 관리 콘솔의 RAG › 색인 › 동영상 화면이 이것을 보여 줍니다 → 동영상 · 음성 검색

도면 원본의 구조 · 미리보기와 영상 녹취는 표가 아니라 객체 저장소 버킷 plantpulse-rag 에 둡니다 → 데이터베이스 관리

Aster TSDB `pi` — 피처 스토어

시계열 인사이트 서비스가 소유·생성하는 12개 테이블입니다. 접두사는 tsi_ 입니다.

묶음	테이블
피처	`tsi_tag_feature_hourly` · `tsi_tag_feature_daily` · `tsi_asset_feature_hourly` · `tsi_asset_feature_daily`
맥락·프로파일	`tsi_asset_context_daily` · `tsi_asset_profile`
이상·고장	`tsi_anomaly_embedding` · `tsi_failure_signature` · `tsi_precursor_alert`
파이프라인	`tsi_pipeline_status` · `tsi_pipeline_history` · `tsi_backfill_status`

테이블은 서비스가 기동할 때 멱등 생성합니다. 다만 키스페이스 pi 자체는 앱이 만들지 않습니다 — 설치 스크립트(provision-platform-db.sh) 소관입니다.

피처가 비면 분석 화면이 통째로 빕니다

관리 콘솔의 이상탐지·예측 화면은 전부 이 테이블들을 읽습니다. 결과가 비어 있으면 모델이 아니라 파이프라인을 먼저 보세요 → 관리 콘솔의 Pipeline Status Run History (AI 관리 콘솔).

코파일럿의 표도 같은 키스페이스에 있습니다

코파일럿도 pi 에 자기 표를 둡니다(아침 카드 등). 2026.10 재릴리즈에 구조화 보고서의 조치 체크 상태를 담는 PI_NAVIGATOR_ACTION_CHECK 가 더해졌고, 코파일럿이 기동할 때 만듭니다.

구 pp.ti_* 는 없습니다

2026-07-30 에 pp 키스페이스에서 pi 로 옮기고 옛 테이블은 DROP 했습니다. 구 이름으로 조회하면 나오지 않습니다.

Aster TSDB `pp` — 플랫폼 원천 (읽기 전용)

AI 는 플랫폼이 모은 데이터를 읽기만 합니다. 여기에 쓰지 않습니다.

테이블	쓰임
`tm_asset_data_based_second` / `_minute` / `_hour`	설비 센서 시계열
`tm_tag_point`	태그 포인트
`tm_asset_alarm`	알람
`tm_kpi_oee_history`	OEE
`tm_kpi_ram_history` · `tm_kpi_ems_history`	RAM · EMS
`tm_monitor_platform_status`	시스템 자원 (CPU·메모리·디스크)

파티션 키가 해상도마다 다릅니다

second : PRIMARY KEY ((asset_id, date, hour), timestamp)
minute : PRIMARY KEY ((asset_id, date), timestamp)
hour   : PRIMARY KEY (asset_id, timestamp)
kpi    : PRIMARY KEY ((asset_id, day), timestamp)   -- tm_kpi_*_history

KPI 이력(tm_kpi_*_history)의 day 는 UTC 날짜(yyyymmdd)입니다. 현지 하루는 UTC 버킷 두 개에 걸치므로, 기간을 UTC 날짜 목록으로 펼쳐 버킷마다 읽습니다. 한 행은 그 시각까지의 오더 누계라 행을 더하지 않습니다. 자세한 규칙은 KPI 테이블 에 있습니다.

조회가 느리다면 해상도부터

초 단위는 설비·날짜·시각까지 파티션에 들어갑니다. 긴 기간을 초 단위로 훑으면 파티션을 수천 개 건드립니다. 넓은 기간은 _hour, 좁은 기간만 _second 로 보세요.

플랫폼 쪽 전체 스키마는 플랫폼 데이터베이스 모델 에 있습니다.

Neo4j · Qdrant — 지식 그래프와 벡터

저장소	담는 것
Neo4j (`plantpulse-neo4j`)	LightRAG 의 지식 그래프 — 문서에서 뽑은 개체·관계
Qdrant	문서 청크의 임베딩 벡터

디지털 스레드의 공장 그래프 거울은 다른 Neo4j 인스턴스(plantpulse-digital-thread-neo4j)에 있습니다. LightRAG 의 저장소가 아니므로 아래 「넷」 에 들지 않습니다.

RAG 엔진(LightRAG)의 저장소는 넷으로 갈려 있습니다. 둘만 알고 있으면 복구가 어긋납니다.

무엇	어디	설정
벡터	Qdrant	`LIGHTRAG_VECTOR_STORAGE=QdrantVectorDBStorage`
그래프	Neo4j	`LIGHTRAG_GRAPH_STORAGE=Neo4JStorage`
KV 캐시	`lightrag-storage` 볼륨의 로컬 JSON	`LIGHTRAG_KV_STORAGE` 미설정 — LightRAG 기본값(`JsonKVStorage`)
문서 처리 상태	플랫폼 PG 의 `lightrag` DB	`LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage`

KV 가 로컬 JSON 인 것은 일부러 그렇게 둔 것입니다 — 인스턴스 한 대에는 충분하고, 플랫폼 Valkey 에 의존하지 않아도 됩니다. 여러 대로 늘릴 때는 LIGHTRAG_KV_STORAGE=RedisKVStorage + REDIS_URI 로 바꿉니다.

넷을 «따로» 복구하면 색인이 어긋납니다

문서 처리 상태만 PostgreSQL 에 있습니다. PG 만 되살리고 Qdrant·Neo4j 를 비워 두면 LightRAG 는 「이미 넣은 문서」로 알고 다시 넣지 않습니다 — 검색은 계속 빈손으로 돌아옵니다. 반대로 그래프·벡터만 되살리면 상태가 맞지 않아 중복 적재가 납니다.

되돌릴 때는 넷을 같은 시점으로 맞추거나, 넷을 모두 비우고 원본에서 다시 넣으십시오. 원본은 lightrag-inputs 볼륨에 있습니다 — 이 볼륨이 사실상의 백업이며, 이것까지 잃으면 색인을 재생성할 방법이 없습니다.

온톨로지 개념은 온톨로지 이해하기 를 보세요.

백업 범위 정리

저장소	누가 받나	없으면
PostgreSQL `pi` (`co` · `dt`)	AI 쪽에서 챙겨야 함	대화·이상 접수·설정, 커넥터 등록부가 사라진다
PostgreSQL `lightrag` · `rag_ingest`	AI 쪽에서 챙겨야 함	문서 처리 상태가 사라진다 — 위 danger 를 보라
PostgreSQL `litellm`	AI	게이트웨이 키·사용량 이력이 사라진다
Aster TSDB `pi`	AI 쪽에서 챙겨야 함	피처가 사라져 분석 화면이 빈다(재계산은 가능하나 오래 걸린다)
Aster TSDB `pp`	플랫폼 백업	—
Neo4j · Qdrant	AI	문서 색인이 사라진다(원본에서 재생성 가능)
디지털 스레드 Neo4j	AI (`bin/backup.sh` 가 볼륨째)	거울이 사라진다(원천에서 재구축 가능)
`lightrag-storage` 볼륨	AI	KV 캐시가 사라진다(재생성 가능)
`lightrag-inputs` 볼륨	AI — 가장 중요	원본 문서가 사라져 색인을 재생성할 방법이 없다

절차는 데이터베이스 관리 를 보세요.

PostgreSQL pi.co — 대화와 운영 상태​

PostgreSQL pi.dt — 디지털 스레드 등록부​

PostgreSQL rag_ingest — 문서 적재 상태​

Aster TSDB pi — 피처 스토어​

Aster TSDB pp — 플랫폼 원천 (읽기 전용)​

파티션 키가 해상도마다 다릅니다​

Neo4j · Qdrant — 지식 그래프와 벡터​

백업 범위 정리​

관련 문서​