windpacer/ExperionCrawler
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
908bfe151fde371e731089bca07adb8dfc4b1fba
ExperionCrawler/plans/LLM채팅+지식증강-phase5-사용자체크리스트.md
windpacer 908bfe151f feat: Knowledge Base RAG 시스템 + 채팅 LLM 개선 (Phase 0~5 완료) 
- KB RAG 전체 파이프라인: 업로드, 파싱(xlsx/pdf/docx/text), 임베딩, Qdrant 인덱싱
- KB 관리 UI(14번 탭): 로그인, 문서 목록, 업로드, 삭제, 재인덱스
- OllamaController: 한글 시스템 프롬프트, plant_context.md 외부 파일화, SSE tool_start/tool_result 이벤트
- 프론트: 툴 실행 카드, KB 인용 링크, 표 자동 렌더, 추천 질문 칩
- nl2sql_worker: history_table.recorded_at 사용, tag_metadata 응답 개선
- DB: KB 테이블 5개 DDL + 시드, pgcrypto 확장
2026-05-13 20:22:27 +09:00

6.6 KiB
Raw Blame History

❯ 현재까지 작업한 것의 사용자가 해야할 일 정리해줘

● 사용자 액션 가이드 (Phase 0~5 구현물 사용 절차)

  1. 사전 환경 셋업 (1회만)

1.1 Python 의존성 추가 설치 — Phase 2에서 openpyxl/python-docx/pdfplumber를 추가했으므로 mcp-server 가상환경에 설치 필요: cd ~/projects/ExperionCrawler/mcp-server uv pip install -e .

1.2 외부 서비스 동작 확인 — 셋 다 떠 있어야 함: curl -s http://localhost:6333/collections | jq # Qdrant curl -s http://localhost:11434/api/tags | jq # Ollama (nomic-embed-text 필요) curl -s http://localhost:8000/v1/models | jq # vLLM (Qwen3.6-27B-FP8)

  • Ollama에 nomic-embed-text 모델이 없으면: ollama pull nomic-embed-text

1.3 (선택) 관리자 초기 비번을 환경변수로 미리 설정 — 콘솔 로그에 비번 노출이 싫으면: export KB_ADMIN_INITIAL_PASSWORD='원하는초기비번' 설정 안 하면 첫 부팅 시 자동 생성 후 콘솔에 1회 출력.

  1. 첫 부팅

2.1 mcp-server 재시작 — 새 도구(parse_document, search_kb) 등록:

기존 프로세스 종료 후

cd ~/projects/ExperionCrawler/mcp-server

기존 기동 방식 그대로 (예: uv run / python server.py --http 등)

2.2 ExperionCrawler 앱 빌드/기동: cd ~/projects/ExperionCrawler dotnet build src/Web/ExperionCrawler.csproj dotnet run --project src/Web/ExperionCrawler.csproj

또는 deploy.sh 사용

2.3 콘솔 로그 확인 — 다음 두 줄이 보이는지: [Kb] 관리자 초기 비밀번호 자동 생성: XXXXXXXXXXXXXXXX ← 즉시 변경하세요 [Kb] Qdrant 컬렉션 ensure 완료: 5건 랜덤 비번을 즉시 메모. (env var 사용했다면 "환경변수 사용" 로그 1줄만 출력)

2.4 Qdrant 컬렉션 5개 생성 확인: curl -s http://localhost:6333/collections | jq '.result.collections[] | .name'

kb_system_instrument, kb_plant_operation, kb_procedure, kb_report, kb_vendor_doc

포함되어야 함

  1. 관리자 첫 로그인 + 비번 변경 (필수)

  2. 브라우저 → http://localhost:5000 → 사이드바 14 RAG 관리 클릭

  3. 콘솔에서 받은 초기 비번 입력 → 로그인

  4. 상단 [비밀번호 변경] → 새 비번 (6자 이상) 설정 → 자동 로그아웃

  5. 새 비번으로 재로그인

  1. (선택) plant_context.md 작성

prompts/plant_context.md는 현재 빈 골격입니다. 채워두면 채팅의 시스템 프롬프트에 자동 주입되어 답변 품질이 좋아집니다: nano prompts/plant_context.md 채울 항목 (파일 안 주석 참고):

  • 단위 (Unit A: 압축, Unit B: 분리 …)
  • 계기 prefix 약어 (FIC/PT/TI/XV …)
  • 태그 명명 규칙 (소문자, .pv/.sp/.op/.instate0~7)
  • 시간대 (UTC 저장, KST 표시)
  • 예시 질문 → 도구 매핑

수정 후 앱 재기동 없이 즉시 반영됩니다 (요청 시마다 파일 읽음).

  1. KB 문서 업로드 워크플로우

  2. 14번 탭 → [📁 파일 업로드] 클릭

  3. 컬렉션 선택 (5종 중 1개): - system_instrument — 계기 datasheet, P&ID 사양서 - plant_operation — 재고, 생산현황, 정비이력, 교대일지 - procedure — SOP, 정비 절차, 알람 대응 매뉴얼 - report — 일/주/월 보고서 - vendor_doc — 벤더 카탈로그, 매뉴얼

  4. 제목(기본: 파일명) / 태그(콤마 구분, 예: unit-a, P-6201) 입력

  5. 파일 선택 → [업로드]

  6. 목록에 새 행이 pending 상태로 등장 → 1.5초마다 자동 갱신 → parsing → embedding → indexed ✓

  7. 실패(failed) 시 해당 행의 에러 메시지 확인, [↻] 재인덱스 가능

지원 형식: .xlsx / .xlsm / .pdf / .docx / .md / .txt

  1. 채팅에서 KB 활용

  2. 사이드바 13 로컬 LLM 채팅 클릭

  3. LLM 종류 = vLLM 선택 (tool 사용은 vLLM 전용)

  4. 모델 = Qwen3.6-27B-FP8 선택

  5. MCP 도구 ✓ 체크박스 켜기

  6. welcome 화면의 추천 칩 중 하나 클릭 (예: "P-6201 펌프의 정비 이력") → 자동으로 입력창에 채워짐 → Enter

  7. 진행 상황 가시화: - 회색 spinning 카드: 툴 호출 시작 - 녹색 ✓: 성공 + 결과 (클릭하면 전체 펼침, 표/KB hits 자동 렌더) - 빨간 ✗: 실패 + 에러 메시지

  8. KB에서 가져온 문서 제목이 답변 본문에 점선 밑줄 링크로 자동 표시됨 → 클릭하면 원본 파일 다운로드

  1. 검증 (옵션)

항목: 작은 txt 업로드 → 30초 내 indexed 확인 방법: 14번 탭에서 상태 칩 색상 변화 ──────────────────────────────────────── 항목: 큰 PDF 실패 시 재시도 동작 확인 방법: jobs 테이블 attempts 누적 (앱 콘솔 로그) ──────────────────────────────────────── 항목: 세션 60분 자동 만료 확인 방법: 60분 방치 후 동작 시 재로그인 요구 ──────────────────────────────────────── 항목: KB 인용 다운로드 확인 방법: search_kb 호출 후 답변 안의 제목 링크 클릭 ──────────────────────────────────────── 항목: Qdrant 청크 확인 확인 방법: curl http://localhost:6333/collections/kb_plant_operation | jq '.result.points_count'

  1. 운영 팁
  • 재인덱스: 청킹 정책을 바꿨거나 파일 손상 시 → 행의 [↻] 버튼
  • 임시 숨김: 잘못 올렸지만 보관은 유지 → [🚫] (비활성화, 검색 결과에서 제외)
  • 영구 삭제: [✖] 또는 하단 [비활성화 영구삭제(90일 이상)]
  • 동일 제목 일괄 비활성화: 재업로드 후 구버전 한 번에 비활성화 — 하단 [🚫 동일 제목 일괄 비활성화]
  • 로그 위치: mcp-server/logs/, dotnet 콘솔 — [Kb] [Kb][Worker] [Kb][Qdrant] 접두사로 grep
  1. 알려진 제약 / 다음 단계
  • 시계열 시각화는 표만 자동 렌더됨 (스파클라인 보류)
  • 툴 실행 카드는 스트리밍 중에만 보임 — 메시지 영구 보존은 Phase 6 이후
  • 이벤트/알람 도구 (active_alarms 등), find_tags, generate_status_report 매크로는 Phase 6에서 추가 예정 — 현재 추천 칩 중 일부는 모델이 직접 SQL을 짜서 답변
  • run_sql 안전장치 (자동 LIMIT, statement_timeout)도 Phase 6

막힘이 있는 단계가 있으면 어디서 멈췄는지 알려주시면 함께 보겠습니다.

Reference in New Issue View Git Blame Copy Permalink