RAG (기술 문서 검색)
개요
PlantPulse RAG는 제조 현장의 기술 문서, 매뉴얼, SOP, 규정을 AI가 즉시 검색하고 참조할 수 있게 하는 RAG(Retrieval-Augmented Generation) 검색 서버입니다.
4가지 검색 모드를 통해 정확하고 맥락에 맞는 문서 검색을 제공하며, 문서 속 표·그림·수식도 색인할 때 글로 풀어 함께 검색되게 합니다.
문서 검색은 두 층으로 나뉩니다.
- RAG API (
plantpulse-rag-api) — 사용자와 AI 가 실제로 만나는 층입니다. 문서 관리 화면과 검색 API 를 제공합니다. - LightRAG — 실제 색인·검색을 수행하는 내부 엔진입니다. 외부에 노출되지 않고 RAG API 를 통해서만 접근합니다.
즉 LightRAG 의 주소나 WebUI(/webui)를 직접 여는 방법은 없습니다. 문서 작업은 모두 RAG API
화면에서 합니다. (구 자체 개발 서버 plantpulse-rag 는 아카이브되었고, LightRAG WebUI 직접
업로드 경로는 2026-07-30 자로 아래 Documents 화면이 대체했습니다.)
검색 모드
| 모드 | 설명 | 적합한 상황 |
|---|---|---|
| hybrid (기본) | local + global — 지식 그래프의 엔티티와 관계를 함께 | 일반적인 문서 검색 (권장) |
| naive | 문서 조각의 벡터 유사도만 (그래프 안 씀) | 개념적 질문, 유사 문서 탐색 |
| local | 질문에 나온 엔티티(설비·부품 등) 중심 | 특정 대상의 세부 내용 확인 |
| global | 엔티티 사이 관계 중심 | 여러 문서에 걸친 종합 정보 |
이 넷 밖의 모드 이름을 주면 검색하지 않고 거절합니다(REST 422) → RAG 알고리즘
사용 경로
| 하는 일 | 어디서 |
|---|---|
| 채팅으로 물어보기 | 코파일럿의 묻기 — 에이전트가 MCP 게이트웨이를 거쳐 RAG API 의 rag_search 도구를 자동 호출합니다(아래 «채팅의 문서 검색은 게이트웨이로만»). 답 아래 근거 카드(문서 · 도면 · 영상)를 누르면 문서 원문 · 도면 · 영상이 대화 옆 오른쪽 패널에 열립니다 → 묻기 — 오른쪽 패널 |
| 검색만 직접 해보기 | RAG API 대시보드의 Query 화면 |
| 문서 올리기·지우기·목록 보기 | RAG API 대시보드의 Documents 화면 |
| 자동 동기화 결과 확인 | RAG API 대시보드의 Sync History 화면 |
| 색인 실패 원인 보기 | RAG API 대시보드의 Logs 화면 |
코파일럿에는 내장 문서 검색이 없습니다. 채팅의 문서 검색은 MCP 게이트웨이 뒤의 RAG 도구 rag_search 하나입니다.
- 게이트웨이는
rag_search·rag_list_documents를 처음부터 켜 둡니다. 관리자가 끄면 채팅이 문서를 찾지 못합니다. - 문서를 못 찾으면 관리자는 AI 관리 콘솔 › MCP 게이트웨이 › 서버 에서 RAG Gateway 서버가 켜져 있는지, 도구 에서
rag_search가 켜져 있는지 확인합니다 → AI 관리 콘솔 — MCP 게이트웨이 - 사용자 쪽에는 채팅 도구 권한(
tool:mcp)이 있어야 합니다 → 권한 - 꺼져 있거나 게이트웨이가 응답하지 않으면 매뉴얼 · 도면 · 절차 질문에 답을 짓지 않고 막습니다 — 「문서 검색을 지금 쓸 수 없습니다(MCP 게이트웨이 응답 없음) …」 또는 「문서 검색 도구가 꺼져 있거나 이 계정에 허용되지 않았습니다 …」 → 묻기 — 답이 끊기거나 멈췄을 때
- RAG API 대시보드의 질의 시험 과 문서 원문 · 영상 재생은 게이트웨이를 거치지 않으므로, 이 화면들이 되는데 채팅만 문서를 못 찾으면 게이트웨이 쪽입니다.
채팅에서 문서 원문 열기
묻기의 답 아래 문서 근거 카드를 누르면 그 문서의 원문이 오른쪽 패널에 열립니다. 문서 화면으로 옮겨 가거나 새 탭이 뜨지 않습니다.
| 문서 | 패널에서 |
|---|---|
| 브라우저의 PDF 보기로 패널 안에 그대로 열립니다. 머리줄에 새 탭에서 열기 · 원본 내려받기 | |
| PDF 가 아닌 형식(워드 · 엑셀 · 글 파일 등) | 패널 안에 그리지 않습니다 — 「이 형식은 여기서 볼 수 없습니다. 원본을 내려받아 여세요」 와 원본 내려받기 |
| PDF 를 화면 안에 못 그리는 브라우저(폰 등) | 「이 브라우저에는 PDF 보기가 없습니다. 원본을 내려받아 여세요」 와 원본 내려받기 |
| 통제 등급 문서 | 「통제 등급 문서입니다. 원본을 열거나 내려받을 수 없습니다」 — 열기 · 내려받기 단추가 없습니다 |
- 문서 검색이 답이 기댄 대목을 찾아 주면 카드에 인용 구절(쪽을 아는 PDF 면 「12쪽」 도)이 붙고, 패널은 위에 그 구절을 보이며 그 쪽에서 열립니다. 쪽을 모르는 문서(PDF 가 아닌 문서 · 글을 읽을 수 없는 스캔 PDF · 쪽 정보가 아직 만들어지지 않은 문서)는 1쪽에서 열립니다. 구절이나 쪽이 붙지 않는 출처도 흔합니다 — 특히 그림 · 스캔 쪽이 섞인 문서는 틀린 쪽을 내지 않으려고 쪽을 붙이지 않습니다. 구절은 원문의 문장이거나 표의 한 줄입니다.
- 🔴 글 층이 없는 한국어 스캔 PDF 는 읽지 못합니다. 글 층이 있는 PDF 로 올리십시오.
- 권한과 열람 등급은 열 때마다 다시 확인합니다. 볼 수 없는 문서는 「이 문서를 볼 권한이 없습니다」 로 답합니다 → 권한
- 색인은 남았는데 보관된 원본이 없으면 「원문을 찾을 수 없습니다. 보관된 원본이 없거나 문서가 지워졌습니다」 입니다.
- 제안의 근거에 붙은 문서도 같은 패널로 열립니다.
- 문서 카드의 제목은 「설비 이름 · 문서 이름」 이고(직접 올린 문서는 「공통 문서 · 문서 이름」), 패널 머리줄에는 문서 이름이 보입니다. 같은 문서의 여러 대목은 카드 한 장으로 묶입니다.
- AI 가 검색만 하고 답에 쓰지 않은 문서는 근거 카드로 붙지 않습니다.
대화에 넣은 파일과 다릅니다
묻기 입력칸의 파일 넣기로 넣은 파일은 영상 · 음성까지 이 문서 검색에 들어가지 않습니다. 둘은 따로 있습니다.
| 문서 검색(RAG) | 대화에 넣은 파일 | |
|---|---|---|
| 넣는 사람 | 관리자(Documents 화면 · 관리 콘솔) · 플랫폼 자동 동기화 | 묻는 사람 — 입력칸의 파일 넣기 |
| 쓰이는 곳 | 모든 사람의 모든 대화(권한 · 열람 등급 안에서) | 그 대화 하나 — 그 대화의 주인만 봅니다 |
| AI 가 읽는 법 | rag_search 로 관련 대목을 찾습니다 | 넣은 파일의 쪽 · 시트 · 슬라이드를, 영상 · 음성은 녹취 구간을 직접 읽습니다 |
| 영상 재생 | 로그인한 사람 누구나 | 그 대화의 주인만 |
| 지워지는 때 | 관리자가 지우거나 원장에서 빠질 때 | 대화를 지울 때 함께 |
- 여러 사람이 두고두고 찾을 문서(매뉴얼 · SOP · 규정)는 문서 검색에 올립니다. 지금 이 질문에만 쓸 파일은 대화에 넣습니다.
- 대화에 넣은 파일을 문서 검색으로 옮기는 기능은 없습니다. 같은 파일을 관리자가 따로 올립니다.
- 넣는 법과 상한(50MB · 영상 · 음성 1GB · 60분 · 대화당 20개 · 앞 100쪽)은 AI 채팅 — 파일 넣기에 있습니다.
문서가 들어오는 두 경로
문서는 두 가지 방법으로 색인됩니다. 어느 쪽으로 들어왔는지에 따라 관리 방법이 다릅니다.
| 경로 | 출처 | 설명 |
|---|---|---|
| 자동 동기화 | 플랫폼의 설비 첨부 문서 | 플랫폼에서 설비에 문서를 붙이면 주기적으로 자동 색인됩니다. RAG 쪽에서 따로 올릴 필요가 없습니다 |
| 수동 업로드 | Documents 화면 | 설비에 속하지 않는 문서(공통 규정, 교육 자료 등)를 직접 올립니다. 원본은 별도 보관되어 재색인에도 살아남습니다 |
설비에 딸린 문서를 RAG 에 수동으로 올리면 플랫폼의 문서 원장과 어긋납니다. 설비 문서는 플랫폼에서 설비에 붙이고, RAG 는 자동 동기화에 맡기는 편이 관리가 단순합니다.
문서 속 표·그림
PDF · DOCX · PPTX · XLSX 는 색인할 때 그림·표·수식을 따로 뽑아, 그림에는 Aura 가 설명문을 달아 함께 색인합니다. 그래서 「이 도면의 밸브 번호」처럼 그림 안에 있던 내용도 검색에 걸릴 수 있습니다.
검색어는 글입니다. 채팅에 사진을 붙여 계기 값 · 명판 글자를 읽히는 것은 비전 도구가 하는 일이고, 필요하면 AI 가 그 결과로 다시 문서를 찾습니다 → 묻기 — 사진으로 묻기
도면 · 영상도 검색합니다 — 켜야 씁니다
관리자가 켜면 RAG 는 문서 말고도 도면과 영상 · 음성을 색인합니다. 둘 다 기본으로 꺼져 있습니다.
| 무엇 | 받는 형식 | 답에 붙는 것 | 켜는 스위치 |
|---|---|---|---|
| 도면 | dxf · 벡터 PDF(올릴 때 «도면» 으로 지정, 또는 플랫폼 원장의 문서 종류가 도면) | 도면 카드 — 쪽 미리보기에서 그 자리를 강조, 판 배지, 최신판과 비교 | DRAWING_INGEST_ENABLED |
| 영상 · 음성 | 영상 mp4 · mov · mkv · webm, 음성 m4a · mp3 · wav, 곁 자막 srt · vtt | 장면 카드 — 그 시각부터 답 안에서 재생 | 설치 스위치 PI_MEDIA_ENABLED |
쓰는 법과 한계는 도면으로 묻기 · 영상 · 음성으로 묻기, 켜는 법은 환경 설정에 있습니다. 영상 · 음성을 켜면 묻기 입력칸의 말로 묻기(마이크)도 함께 켜집니다.
문서가 검색되기까지
문서 등록 (플랫폼 설비 첨부 / Documents 화면 업로드)
│
▼
파싱 — PDF·DOCX·이미지에서 텍스트와 표를 추출
│
▼
청킹 — 검색 단위로 잘게 나눔
│
▼
임베딩 — 각 조각을 벡터로 변환
│
├──▶ 벡터 저장소 (유사도 검색)
└──▶ 지식 그래프 (엔티티·관계 추출)
등록 직후에는 아직 검색되지 않습니다. 파싱과 임베딩이 끝나야 결과에 나타나므로, 방금 올린 문서가 안 잡히면 Sync History 화면에서 처리 상태를 먼저 확인하세요.
색인되는 형식은 여섯 가지입니다
PDF · DOCX · PPTX · XLSX · MD · TXT 만 색인합니다(도면 · 영상을 켜면 위 표의 형식이 더해집니다). 자동 동기화가 이 밖의 문서를 만나면 색인하지 않고 건너뛴 이유를 세어 동기화 결과에 남깁니다.
| 건너뛴 이유 | 뜻 | 고칠 곳 |
|---|---|---|
ext_not_allowed | 위 여섯 밖의 확장자 | 형식을 바꿔 다시 붙입니다 |
ext_unknown | 확장자를 알 수 없음 — 원장에 파일 형식이 없고 문서명에도 확장자가 없음 | 플랫폼 쪽 문서 원장 |
size_over_limit | 최대 파일 크기(기본 50 MB)를 넘음 | 파일을 나누거나 상한을 올립니다 |
ingest_failed | 받았지만 색인 단계에서 실패 | plantpulse-lightrag 로그 → 문제 해결 |
/health 의 ingest 로 봅니다저장소가 전부 살아 있어도 문서가 한 건도 안 들어오는 상태가 있습니다. RAG API 의 /health 는
마지막 동기화 결과를 ingest 로 알려 주고, ok · disabled 가 아니면 전체 status 가 degraded 입니다.
ingest | 뜻 |
|---|---|
ok | 마지막 동기화가 성공했습니다 |
error | 마지막 동기화가 실패했습니다 |
unknown | 아직 한 번도 안 돌았거나 이력을 못 읽었습니다 — «정상» 이 아닙니다 |
disabled | 동기화를 꺼 두었습니다 |
운영자가 제외해 둔 문서는 전체 재색인(Reindex All)을 돌려도 제외된 채로 남습니다.
관리 가능한 문서 유형
| 문서 유형 | 예시 | AI 활용 |
|---|---|---|
| 정비 매뉴얼 | 설비별 정기점검 절차, 윤활유 교체 주기 | 이상 감지 시 적절한 조치 방안 즉시 제공 |
| SOP | 공정별 작업 절차, 안전 절차, 품질 검사 기준 | 작업 단계별 정확한 가이드 |
| 안전 규정 | 화학물질 MSDS, 안전보건 규정, 비상 대응 매뉴얼 | 위험 상황 시 즉각적인 규정 참조 |
| 기술 사양서 | 설비 스펙, 센서 사양, 허용 범위 | 이상 판정 기준값 참조 |
| 사고/고장 보고서 | 과거 고장 사례, 원인 분석, 재발 방지 대책 | 유사 사례 기반 원인 추정 |
| 교육 자료 | 신입 교육 교재, 공정 설명서, 품질 교육 | 현장 교육 지원 |
설정
임베딩 모델·청크 크기·Top-K 같은 검색 파라미터는 LightRAG 엔진 쪽 설정이며 화면에서 바꿀 수 없습니다. 현재 적용된 값은 RAG API 대시보드의 Config 화면에서 확인할 수 있습니다 (토큰·비밀번호는 마스킹되어 표시됩니다).
운영 중 조정할 일이 있는 것은 대개 동기화 쪽입니다.
| 항목 | 설명 |
|---|---|
| 동기화 사용 여부 | 플랫폼 설비 문서 자동 색인을 켜고 끕니다 |
| 동기화 주기 | 플랫폼 문서 변경을 확인하는 간격 |
| 한 번에 색인할 문서 수 | 한 주기에 처리할 상한 — 초기 대량 유입 시 부하 조절용 |
| 최대 파일 크기 | 이 크기(기본 50 MB)를 넘는 문서는 건너뜁니다 |
활용 시나리오
| 시나리오 | 검색 예시 |
|---|---|
| 정비 절차 확인 | "주입기 베어링 교체 방법" → 정비 매뉴얼 |
| 안전 규정 참조 | "질소 가스 누출 시 대응 절차" → 비상 대응 매뉴얼 |
| 이상 조치 가이드 | "온도 센서 이상 시 점검 항목" → 점검 SOP |
| 과거 사례 검색 | "작년 3라인 주입기 고장 원인" → 고장 보고서 |
| 도면의 치수 · 판 | "Ø62 H7 어디 있어?" → 도면 · 쪽 · 구역 (도면 수집을 켰을 때) |
| 교육 영상의 장면 | "베어링 압입 전에 뭘 확인해?" → 정비 교육 영상의 그 시각 (영상 · 음성을 켰을 때) |
| 규격 확인 | "주입기 허용 온도 범위" → 기술 사양서 |