작성일: 2026-07-15 상태: 계획 단계 (개발 미착수) — 이 글은 구축 계획이며, 코드/스캐폴딩은 포함하지 않음. 대상 시스템: hermes-agents (Mattermost 채널별 다중 프로필 봇 위에 문서 RAG 계층 추가)

1. 목표

Mattermost 채널별 전담 봇(sales / finance / dev / qna)이 사내 지식과 실시간 데이터를 근거로 답변하도록, Hermes 위에 문서 RAG(검색 증강) 계층과 ERP 실시간 도구를 추가한다.

  • 지식 소스: 구글드라이브 문서 + Mattermost 업로드 파일 (색인) / ERP·외부시스템 (실시간 호출)
  • 질의 채널: Mattermost 로 통일 (부서별 봇)
  • 격리 원칙: 부서(dept) 수준. 각 봇은 자기 부서 지식만 검색.

2. 확정된 결정사항 (Locked)

# 축 결정 근거
D1 ERP/외부시스템 실시간 도구호출 (색인 안 함) 재고·잔액 등 '현재 값'이 중요 → 색인은 낡음
D2 지식 격리 부서(dept) 수준 구현 단순, 대부분 사내봇이 이 수준. 부서 내 민감파일은 색인 제외로 처리
D3 벡터 저장소 C안 = 임베디드 벡터스토어 별도 서버 컨테이너 없이 단일 파일, 메모리 부담 최소
D4 임베딩 API 임베딩 메모리 0, 대형 로컬모델 불필요 (Docker VM 여유 부족)
D5 질의 통로 Mattermost 통일 (부서봇) 기존 5개 프로필 봇 재사용

2.1 부서 내 민감파일 처리 (D2 파생)

부서 수준 격리를 택했으므로, 같은 부서라도 일부만 봐야 하는 파일(급여·인사 등)은 색인 대상에서 제외한다. 제외 판정 방식은 아래 "확정 필요 O5" 참고.

3. 미확정 결정 & 권장 기본값 (구축 착수 전 확정 필요)

아래는 계획을 구체화하려면 사용자가 확정해야 하는 항목. 각 항목에 권장값을 제시.

# 항목 권장 기본값 대안 영향
O1 벡터 라이브러리 sqlite-vec Chroma(임베디드) 코드 구조, Hermes SQLite 생태계 정합성
O2 임베딩 API 모델 다국어 지원 모델(예: text-embedding-3-large / voyage-3 / cohere embed-multilingual) 3-small(저렴, 다국어 약함) 한국어 검색 품질 좌우
O3 봇 연결 방식 MCP 서버(도구 2개를 하나로 묶음) Hermes skill search_docs·erp_query 노출 방식
O4 수집기 실행 위치 별도 수집 컨테이너 hermes 컨테이너 내부 크론 관심사 분리, hermes 재시작과 무관
O5 부서 매핑 & 민감파일 판정 드라이브 폴더 구조 기반(폴더→dept 매핑표, 특정 폴더/라벨=색인제외) 파일명 규칙, MM 채널→dept 색인 정확성·보안
O6 대상 봇 범위 sales·finance·dev·qna (default 제외) 일부만 초기 롤아웃 범위
O7 드라이브 동기 주기 15~30분 증분 실시간 webhook 최신성 vs API 비용
O8 예상 문서 규모 (미확인 — 확정 필요) — 저장소/비용 상한 검증

4. 목표 아키텍처

[색인 대상 — RAG]
  구글드라이브 ─┐ (증분동기, Docs→텍스트, PDF OCR)
  MM 업로드파일 ┴─→ 정규화 → 청킹 → [API 임베딩] → [벡터스토어(sqlite-vec)]
                                                      │ 메타: {source, dept, sensitivity, url, doc_id, mtime}
[실시간 — 도구호출]                                     │
  ERP/외부시스템 ─── (색인 안 함) ─────────────────┐   │
                                                  ↓   ↓
[질의 — Mattermost 통일]                        [Hermes 봇 도구 (MCP)]
  사용자 → 부서봇 → ① search_docs(query, dept=고정) → 벡터검색+필터 → 근거
                  → ② erp_query(...)  ─ 실시간 ────→ 최신 데이터
                  → LLM 종합 → 답(출처 인용)

핵심: 소스가 몇 개든 정규화→벡터스토어로 합류. 질의는 Mattermost 하나로 수렴. 봇은 "두 손"을 가짐 — 왼손=문서검색(고정 지식), 오른손=ERP호출(실시간 값). LLM이 질문 성격에 따라 선택.

5. 컴포넌트 명세

각 컴포넌트는 하나의 목적 / 명확한 인터페이스 / 독립 테스트 가능하도록 분리.

C1. 벡터 저장소 (Vector Store)

  • 목적: 문서 청크 + 임베딩 + 메타데이터 보관 및 유사도 검색.
  • 구현: sqlite-vec 기반 단일 DB 파일 (권장 O1).
  • 데이터 모델 (chunks 테이블 개념):
    컬럼 설명
    id 청크 고유 ID
    doc_id 원본 문서 ID (upsert/삭제 단위)
    source gdrive / mattermost
    dept sales / finance / dev / qna
    sensitivity internal(색인) — confidential은 애초 색인 안 함
    text 청크 원문
    url 출처 링크 (인용용)
    mtime 원본 수정시각 (최신성 판단)
    embedding 벡터
  • 인터페이스: upsert(chunks), delete(doc_id), search(query_vec, dept, k).
  • 의존: 임베딩 API(질의 벡터화), 수집기(쓰기).

C2. 구글드라이브 수집기 (Drive Connector)

  • 목적: 드라이브 문서를 증분으로 가져와 색인.
  • 동작: 서비스계정/OAuth → Drive changes API로 변경분만 → Google Docs는 텍스트 export, PDF/이미지는 OCR → 청킹 → 임베딩 → upsert. 삭제 감지 시 delete(doc_id).
  • 부서 태깅: 폴더→dept 매핑표(O5) 기반. 색인제외 폴더/라벨은 스킵.
  • 스케줄: 크론(O7).
  • 의존: Drive API, OCR, 임베딩 API, 벡터 저장소.

C3. Mattermost 파일 수집기 (MM File Connector)

  • 목적: 채널에 업로드된 파일을 색인.
  • 동작: 게이트웨이 파일 업로드 이벤트 감지 → 다운로드 → 추출/OCR → 청킹 → 임베딩 → upsert.
  • 부서 태깅: 업로드된 채널 → dept 자동 매핑.
  • 의존: Mattermost 이벤트/훅, OCR, 임베딩 API, 벡터 저장소.

C4. 문서검색 도구 (search_docs)

  • 목적: 봇이 호출하는 검색 도구. 부서 필터로 관련 청크 반환.
  • 인터페이스: search_docs(query, k) — dept는 봇마다 코드로 고정 바인딩(LLM이 바꿀 수 없음, D2 보안장치).
  • 동작: query를 동일 임베딩 API로 벡터화 → search(query_vec, dept, k) → 청크+출처 반환.
  • 노출: MCP 서버(O3).

C5. ERP 실시간 도구 (erp_query)

  • 목적: 질문 시점에 ERP/외부시스템 API를 호출해 최신 데이터 반환 (색인 아님, D1).
  • 인터페이스: erp_query(...) — 부서별 호출 가능 엔드포인트/자격증명 분리 → 부서 스코프 유지.
  • 노출: C4와 같은 MCP 서버로 묶음(O3).
  • 의존: ERP API (구체 시스템은 O 확정 필요).

C6. 봇 연결/바인딩 (Bot Wiring)

  • 목적: 각 프로필 봇에 도구를 연결하고 dept를 고정.
  • 동작: sales/finance/dev/qna 각 프로필에 MCP 도구 등록, search_docs의 dept를 프로필별로 고정, ERP 도구는 해당 부서 자격증명으로.
  • 원칙: default 프로필은 건드리지 않음(기존 메모리 규칙 준수).

6. 데이터 흐름

색인(쓰기) 경로

  1. 소스 이벤트/스케줄 → 수집기(C2/C3)가 원본 획득
  2. 텍스트 추출(+OCR) → 청킹 → 임베딩 API 호출
  3. 메타데이터(부서·민감도·출처) 부여 → 벡터 저장소 upsert
  4. 원본 삭제/수정 → doc_id 기준 delete/replace

질의(읽기) 경로

  1. 사용자가 Mattermost 부서 채널에서 봇에게 질문
  2. LLM이 도구 선택: 고정지식→search_docs, 실시간값→erp_query
  3. search_docs: 질의 임베딩 → 부서필터 벡터검색 → top-k 청크
  4. LLM이 청크/ERP응답을 근거로 답변 생성 (출처 인용 포함)

7. 엣지케이스 & 처리방안

브레인스토밍에서 도출된 위험 지점. 구현 시 반드시 다룰 것.

# 엣지케이스 처리방안
E1 권한 누수 — 부서 밖/민감문서가 답변에 노출 dept 고정 바인딩(C4) + confidential 문서 색인 제외(D2/O5)
E2 최신성 — 드라이브 문서 수정·삭제가 색인에 미반영 changes API 증분동기 + doc_id 기준 삭제 처리(C2)
E3 ERP 값 노후화 색인하지 않고 실시간 호출(D1)로 원천 차단
E4 검색 결과 없음 봇이 "근거 문서 없음"을 명시하고 추측 답변 금지 (환각 방지 프롬프트)
E5 OCR 실패/스캔 품질 실패 문서 로깅·스킵, 재시도 큐. 색인 실패가 파이프라인 전체를 막지 않게
E6 한국어 검색 품질 다국어 임베딩 모델 선택(O2), 청킹 시 문장 경계 보존
E7 임베딩 일관성 수집·질의에 반드시 동일 모델 사용. 모델 교체 시 전체 재임베딩 필요 명시
E8 부서 매핑 모호 — 폴더가 여러 부서 걸침 매핑표 명시적 우선순위 규칙, 미매핑 문서는 색인 보류 + 경고
E9 대용량/중복 문서 청킹 크기·중첩 정책, doc_id 해시로 중복 upsert 방지
E10 임베딩 API 비용 폭증 변경분만 재임베딩, 최초 대량색인은 배치·상한 설정, 비용 모니터링
E11 API 레이트리밋/장애 지수 백오프 재시도, 실패 청크 재처리 큐
E12 Docker VM 메모리 부족 수집기 별도 컨테이너(O4), VM 최소 4GB(권장 8GB)로 상향
E13 민감파일 오분류 색인제외는 화이트리스트가 아닌 명시적 규칙 + 기본 보수(불확실하면 제외)

8. 단계별 실행 로드맵 (개발 착수 시 순서)

⚠️ 본 계획서 승인 및 O1~O8 확정 전에는 착수하지 않음.

Phase 0 — 확정 & 준비

  • O1~O8 결정 확정, ERP 시스템/엔드포인트 명세 수집, 폴더→dept 매핑표 작성, Docker VM 메모리 상향.

Phase 1 — 저장소 + 검색도구 (뼈대)

  • C1(벡터 저장소) 스키마 구성, C4(search_docs) + MCP 서버 골격, 봇 1개(예: sales)에 dept 고정 바인딩.
  • 검증: 수동으로 문서 몇 개 넣고 Mattermost sales 봇이 부서필터로 검색·답변하는 왕복 확인.

Phase 2 — 구글드라이브 수집기

  • C2 구현: 증분동기·OCR·청킹·부서태깅·삭제처리·크론.

Phase 3 — Mattermost 파일 수집기

  • C3 구현: 업로드 이벤트 훅·추출·채널→dept 매핑.

Phase 4 — ERP 실시간 도구

  • C5 구현: ERP API 래핑, 부서별 자격증명 분리, MCP에 통합.

Phase 5 — 마감 & 롤아웃

  • 출처 인용 포맷, 환각방지 프롬프트, 권한필터 검증, 나머지 부서봇(finance/dev/qna) 확장, 비용·최신성 모니터링.

9. 테스트 & 검증 전략

  • 단위: 각 컴포넌트 인터페이스별 독립 테스트(청킹, 임베딩 호출, 검색 필터, 삭제 반영).
  • 격리 검증(보안): finance 문서를 넣고 sales 봇에 질문 → 절대 안 나오는지 확인 (E1 회귀 테스트).
  • 최신성 검증: 드라이브 문서 수정/삭제 후 색인 반영 확인 (E2).
  • 환각 검증: 근거 없는 질문에 "모름/근거없음" 응답하는지 (E4).
  • 한국어 품질: 실제 사내문서로 검색 적합도 스팟체크 (E6).
  • E2E: 세 소스(드라이브/MM/ERP) 각각 대표 질문 왕복.

10. 인프라 · 비용 · 리스크 요약

  • 인프라: 벡터스토어(파일) + 수집기 컨테이너 + MCP 도구 서버. Docker VM 메모리 최소 4GB, 권장 8GB.
  • 비용: API 임베딩 — 대부분 최초 색인 + 변경분에서 발생, 질의당 비용은 미미. 규모(O8) 확정 후 상한 산정.
  • 최대 리스크: ① 권한 누수(E1) ② 최신성 미반영(E2) ③ 이 작업은 '설정 튜닝'이 아니라 별도 서비스 개발이라는 규모 인식.

11. 확정 필요 체크리스트 (사용자 액션)

  • O1 벡터 라이브러리 (sqlite-vec 권장)
  • O2 임베딩 API 모델 (다국어 권장)
  • O3 봇 연결 방식 (MCP 권장)
  • O4 수집기 실행 위치 (별도 컨테이너 권장)
  • O5 폴더→dept 매핑표 & 민감파일 색인제외 규칙
  • O6 대상 봇 범위
  • O7 드라이브 동기 주기
  • O8 예상 문서 규모
  • ERP 시스템/엔드포인트/인증 명세
  • Docker VM 메모리 상향 승인

부록 A. 관련 글