codebuff-agent 2.1.74__py3-none-any.whl

codebuff_core/services/rag_collections.py

@@ -0,0 +1,2740 @@
+"""
+RAG Collection Manager — 4개 컬렉션(enterprise_tables, bdp_tables, guide_docs, ds_guide_docs) 관리.
+
+핵심 기능:
+- 동적 CSV 파싱 (관리자 매핑 기반)
+- 마크다운 헤더 기반 시맨틱 청킹
+- LLM 청크 요약 임베딩
+- 비-md 파일 → 마크다운 변환 (draw.io XML 포함 시 Mermaid 자동 변환)
+- 적재 프리뷰, 데이터 브라우저, 검색 테스트, 이력 관리
+"""
+
+from __future__ import annotations
+
+import asyncio
+import csv
+import hashlib
+import json
+import logging
+import os
+import re
+import time
+import uuid
+
+from codebuff_core.legacy_paths import resolve_jupyter_config
+from datetime import datetime
+from pathlib import Path
+from typing import Any, AsyncGenerator, Dict, List, Optional, Tuple
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+HISTORY_PATH = str(
+    resolve_jupyter_config("codebuff_rag_history.json", "hdsp_rag_history.json")
+)
+
+# 컬렉션 이름
+COLLECTION_ENTERPRISE = "enterprise_tables"
+COLLECTION_BDP = "bdp_tables"
+COLLECTION_GUIDE = "guide_docs"
+COLLECTION_DS_GUIDE = "ds_guide_docs"
+COLLECTION_FAQ = "faq_docs"
+ALL_COLLECTIONS = [
+    COLLECTION_ENTERPRISE,
+    COLLECTION_BDP,
+    COLLECTION_GUIDE,
+    COLLECTION_DS_GUIDE,
+    COLLECTION_FAQ,
+]
+# L2(프로젝트/마트) 테이블 컬렉션 — 벡터 없는 payload-only, 외부 파이프라인이 적재.
+# ALL_COLLECTIONS에 넣지 않는다: ensure_collections(dimension 기반 벡터 생성)와
+# get_collection_stats(admin UI)가 이 리스트를 구동하는데 L2는 벡터도 없고
+# codebuff가 소유하지도 않는다.
+COLLECTION_BDP_L2 = "bdp_tables_l2"
+# 비-테이블 컬렉션 (검색 시 _group_key grouping을 사용하지 않는 그룹)
+GUIDE_COLLECTIONS = {COLLECTION_GUIDE, COLLECTION_DS_GUIDE, COLLECTION_FAQ}
+
+_FQN_RE = re.compile(r"[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)+")
+
+
+def strip_fqn_to_table_name(value: str) -> str:
+    """'db.table' 형태(순수 식별자.식별자)면 마지막 세그먼트(테이블명)만 반환.
+
+    에이전트가 FQN으로 검색하면 db명이 검색 노이즈가 되므로 테이블명만 사용.
+    예: wdp_bdp_db_dlk_l1_unmsk_view.card_pchs → card_pchs
+    """
+    v = value.strip()
+    if _FQN_RE.fullmatch(v):
+        return v.rsplit(".", 1)[-1]
+    return v
+
+
+# 청킹 기본값
+DEFAULT_CHUNKING = {
+    "target_size": 800,
+    "min_size": 150,
+    "max_size": 2000,
+    "overlap": 0,
+}
+
+# ------------------------------------------------------------------
+# 매니저 레지스트리 (chat_service에서 RAG 가용성 체크용)
+# ------------------------------------------------------------------
+_manager_instance: Optional["RAGCollectionManager"] = None
+
+
+def register_manager(mgr: "RAGCollectionManager") -> None:
+    """RAGCollectionManager 싱글톤 등록."""
+    global _manager_instance
+    _manager_instance = mgr
+
+
+def get_manager() -> Optional["RAGCollectionManager"]:
+    """등록된 RAGCollectionManager 반환."""
+    return _manager_instance
+
+
+def is_rag_available() -> bool:
+    """RAG가 사용 가능한지 빠르게 확인. 매니저 등록 여부만 체크."""
+    return _manager_instance is not None
+
+
+class RAGCollectionManager:
+    """3개 RAG 컬렉션의 생성/적재/삭제/검색을 관리."""
+
+    def __init__(
+        self,
+        qdrant_client: Any,
+        embedding_service: Any,
+        llm_config: Optional[Dict[str, Any]] = None,
+    ):
+        self._client = qdrant_client
+        self._embedding = embedding_service
+        self._llm_config = llm_config or self._load_llm_config()
+        self._progress: Dict[str, Any] = {}
+        self._upsert_lock = asyncio.Lock()
+        self._upsert_cancelled = False
+
+    def get_progress(self) -> Dict[str, Any]:
+        """현재 진행 상황 반환."""
+        return dict(self._progress)
+
+    def cancel_upsert(self) -> bool:
+        """진행 중인 적재를 중지 요청."""
+        if self._upsert_lock.locked():
+            self._upsert_cancelled = True
+            return True
+        return False
+
+    # ------------------------------------------------------------------
+    # LLM 설정 로드
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _load_llm_config() -> Dict[str, Any]:
+        """LLM endpoint 로드 — get_config() 가 centri > env > 파일로 해석한 값 (이슈 #113)."""
+        try:
+            from codebuff_core.managers.config_manager import get_config_manager
+
+            cfg = get_config_manager().get_config()
+            vllm = cfg.get("vllm", {})
+            return {
+                "endpoint": vllm.get("endpoint", ""),
+                "api_key": vllm.get("apiKey", ""),
+                "model": vllm.get("model", ""),
+            }
+        except Exception:
+            return {"endpoint": "", "api_key": "", "model": ""}
+
+    # ------------------------------------------------------------------
+    # 컬렉션 관리
+    # ------------------------------------------------------------------
+
+    async def ensure_collections(self, dimension: int) -> None:
+        """3개 컬렉션 생성 (없으면)."""
+        from qdrant_client.models import Distance, VectorParams
+
+        existing = {c.name for c in self._client.get_collections().collections}
+        for name in ALL_COLLECTIONS:
+            if name not in existing:
+                self._client.create_collection(
+                    collection_name=name,
+                    vectors_config=VectorParams(
+                        size=dimension, distance=Distance.COSINE
+                    ),
+                )
+                logger.info("Collection created: %s (dim=%d)", name, dimension)
+
+    async def delete_collection(self, collection_name: str) -> None:
+        """컬렉션 삭제 후 재생성."""
+        if collection_name not in ALL_COLLECTIONS:
+            raise ValueError(f"Unknown collection: {collection_name}")
+        self._client.delete_collection(collection_name)
+        await self.ensure_collections(self._embedding.dimension)
+        logger.info("Collection reset: %s", collection_name)
+
+    async def get_collection_stats(self) -> Dict[str, Any]:
+        """3개 컬렉션 통계."""
+        existing = set()
+        try:
+            existing = {c.name for c in self._client.get_collections().collections}
+        except Exception as e:
+            logger.warning("get_collections failed: %s", e)
+
+        stats = {}
+        for name in ALL_COLLECTIONS:
+            if name not in existing:
+                stats[name] = {"points": 0, "vectors": 0, "status": "not_found"}
+                continue
+            try:
+                info = self._client.get_collection(name)
+                stats[name] = {
+                    "points": info.points_count or 0,
+                    "vectors": getattr(info, "vectors_count", 0) or 0,
+                    "status": str(getattr(info.status, "value", info.status)),
+                }
+            except Exception as e:
+                logger.warning("get_collection(%s) failed: %s", name, e)
+                # count로 포인트 수 직접 카운트
+                try:
+                    count = self._client.count(name).count
+                    stats[name] = {"points": count, "vectors": count, "status": "ok"}
+                except Exception:
+                    stats[name] = {"points": 0, "vectors": 0, "status": "error"}
+        return stats
+
+    # ------------------------------------------------------------------
+    # 테이블 컬렉션 적재 (enterprise_tables / bdp_tables)
+    # ------------------------------------------------------------------
+
+    async def upsert_table_collection(
+        self,
+        collection_name: str,
+        file_path: str,
+        mapping: Dict[str, Any],
+        join_file_path: Optional[str] = None,
+        join_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """CSV → 동적 매핑 → 임베딩 → upsert.
+
+        Args:
+            collection_name: "enterprise_tables" 또는 "bdp_tables"
+            file_path: 메인 CSV 경로
+            mapping: {groupBy, embeddingFields, tableFields, columnFields}
+            join_file_path: 두 번째 CSV (bdp_tables)
+            join_key: 조인 키
+        """
+        if self._upsert_lock.locked():
+            return {
+                "total": 0,
+                "errors": ["적재가 이미 진행 중입니다. 완료 후 다시 시도하세요."],
+            }
+
+        async with self._upsert_lock:
+            return await self._upsert_table_impl(
+                collection_name, file_path, mapping, join_file_path, join_key
+            )
+
+    async def _upsert_table_impl(
+        self,
+        collection_name: str,
+        file_path: str,
+        mapping: Dict[str, Any],
+        join_file_path: Optional[str] = None,
+        join_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        start = time.time()
+        errors: List[str] = []
+        self._progress = {
+            "status": "running",
+            "total": 0,
+            "done": 0,
+            "collection": collection_name,
+        }
+
+        # CSV 파싱
+        rows = self._read_csv(file_path)
+        if join_file_path and join_key:
+            column_rows = self._read_csv(join_file_path)
+            rows = self._join_csvs(rows, column_rows, join_key)
+
+        # 그룹핑 (str 또는 list)
+        group_by = mapping.get("groupBy", [])
+        if not group_by:
+            raise ValueError("mapping.groupBy is required")
+
+        groups = self._group_rows(rows, group_by)
+        logger.info(
+            "Parsed %d groups from %s (rows=%d)", len(groups), file_path, len(rows)
+        )
+
+        # 임베딩 텍스트 생성 + payload 구성
+        embedding_fields = mapping.get("embeddingFields", [])
+        table_fields = mapping.get("tableFields", [])
+        column_fields = mapping.get("columnFields", [])
+        # 임베딩 강조 필드 (헤더+라벨 자리에 박힘). 미지정 시 tableFields[:2]
+        header_fields = mapping.get("headerFields") or table_fields[:2]
+
+        # 컬렉션 확보 (없으면 생성, 있으면 유지)
+        await self.ensure_collections(self._embedding.dimension)
+
+        # indexFields가 있으면 text payload index 생성
+        index_fields = mapping.get("indexFields", [])
+        if index_fields:
+            self._ensure_text_indexes(collection_name, index_fields)
+
+        # type 필터링을 위한 keyword index
+        self._ensure_keyword_index(collection_name, "type")
+
+        # 기존 포인트의 content hash 조회 (변경 감지용)
+        existing_hashes: Dict[str, str] = {}  # pid → _content_hash
+        try:
+            scroll_offset = None
+            while True:
+                pts, scroll_offset = self._client.scroll(
+                    collection_name=collection_name,
+                    offset=scroll_offset,
+                    limit=100,
+                    with_payload=["_content_hash"],
+                    with_vectors=False,
+                )
+                for pt in pts:
+                    h = (pt.payload or {}).get("_content_hash", "")
+                    existing_hashes[str(pt.id)] = h
+                if scroll_offset is None:
+                    break
+        except Exception:
+            pass  # 컬렉션이 비었거나 에러 → 전체 적재
+
+        texts: List[str] = []
+        payloads: List[Dict[str, Any]] = []
+        point_ids: List[str] = []
+        skipped_unchanged = 0
+
+        MAX_COLUMNS_PER_CHUNK = 200
+
+        def _make_table_payload(
+            table_row: Dict[str, str],
+            chunk_rows: List[Dict[str, str]],
+            chunk_marker: str,
+            chunk_type: str,
+            embed_text: str,
+            content_hash: str,
+        ) -> Dict[str, Any]:
+            """type=table / type=columns 공통 payload 생성 (동일 결과 보장).
+
+            table_row: join 이전 원본 main row (table-level 메타). __main_row__
+                보존 키에서 가져오거나, join이 없으면 group_rows[0] 그대로.
+            """
+            payload: Dict[str, Any] = {
+                "_collection": collection_name,
+                "_embed_text": embed_text,
+                "_group_key": group_key,
+                "_content_hash": content_hash,
+                "type": chunk_type,
+            }
+            if chunk_marker:
+                payload["_chunk"] = chunk_marker
+            for tf in table_fields:
+                if tf in table_row:
+                    payload[tf] = table_row[tf]
+            payload["columns"] = [
+                {cf: r[cf] for cf in column_fields if cf in r} for r in chunk_rows
+            ]
+            return payload
+
+        def _enqueue(pid: str, embed_text: str, payload: Dict[str, Any]) -> bool:
+            """해시 비교 후 큐에 추가. skip 시 False."""
+            nonlocal skipped_unchanged
+            ch = payload["_content_hash"]
+            if pid in existing_hashes and existing_hashes[pid] == ch:
+                skipped_unchanged += 1
+                return False
+            texts.append(embed_text)
+            payloads.append(payload)
+            point_ids.append(pid)
+            return True
+
+        for group_key, group_rows in groups.items():
+            first_row = group_rows[0]
+            # join이 있었으면 __main_row__로 table-level 메타 복원
+            # (column row가 description/korean_name 등을 덮어쓴 경우 대비)
+            table_row = first_row.get(self._MAIN_ROW_KEY) or first_row
+            num_columns = len(group_rows)
+            total_col_chunks = (
+                num_columns + MAX_COLUMNS_PER_CHUNK - 1
+            ) // MAX_COLUMNS_PER_CHUNK
+            total_col_chunks = max(total_col_chunks, 1)
+
+            # ── 1) type=table 청크 (테이블당 1개, 모든 컬럼 payload 포함) ──
+            table_text = self._build_table_meta_embed_text(
+                table_row, group_rows, table_fields, embedding_fields, header_fields
+            )
+            if table_text.strip():
+                table_hash = hashlib.sha256(table_text.encode("utf-8")).hexdigest()[:16]
+                table_pid = str(
+                    uuid.uuid5(
+                        uuid.NAMESPACE_DNS,
+                        f"{collection_name}:{group_key}:table",
+                    )
+                )
+                # type=table은 컬럼 청크가 여러 개여도 payload에 전체 컬럼 보존
+                # 단, 너무 많으면 MAX*총_청크수까지만 (Qdrant payload 보호)
+                _table_payload_rows = group_rows[
+                    : MAX_COLUMNS_PER_CHUNK * total_col_chunks
+                ]
+                _chunk_marker = f"1/{total_col_chunks}" if total_col_chunks > 1 else ""
+                table_payload = _make_table_payload(
+                    table_row,
+                    _table_payload_rows,
+                    _chunk_marker,
+                    "table",
+                    table_text,
+                    table_hash,
+                )
+                _enqueue(table_pid, table_text, table_payload)
+
+            # ── 2) type=columns 청크들 (컬럼 수에 따라 1+개) ──
+            for chunk_idx in range(0, num_columns, MAX_COLUMNS_PER_CHUNK):
+                chunk_rows = group_rows[chunk_idx : chunk_idx + MAX_COLUMNS_PER_CHUNK]
+                # 헤더용 테이블명은 table_row에서 (메타 보존), 컬럼 본문은
+                # chunk_rows에서 (column-level description 등 활용)
+                cols_text = self._build_columns_embed_text(
+                    table_row, chunk_rows, table_fields, column_fields, header_fields
+                )
+                if not cols_text.strip():
+                    continue
+                cols_hash = hashlib.sha256(cols_text.encode("utf-8")).hexdigest()[:16]
+                chunk_n = chunk_idx // MAX_COLUMNS_PER_CHUNK + 1
+                cols_pid = str(
+                    uuid.uuid5(
+                        uuid.NAMESPACE_DNS,
+                        f"{collection_name}:{group_key}:columns:{chunk_idx}",
+                    )
+                )
+                _chunk_marker = (
+                    f"{chunk_n}/{total_col_chunks}" if total_col_chunks > 1 else ""
+                )
+                cols_payload = _make_table_payload(
+                    table_row,
+                    chunk_rows,
+                    _chunk_marker,
+                    "columns",
+                    cols_text,
+                    cols_hash,
+                )
+                _enqueue(cols_pid, cols_text, cols_payload)
+
+        if not texts:
+            return {
+                "total": 0,
+                "skipped_unchanged": skipped_unchanged,
+                "errors": [] if skipped_unchanged else ["No valid groups found"],
+            }
+
+        # 배치 임베딩 + upsert (deterministic ID 사용)
+        upserted = await self._batch_upsert(
+            collection_name, texts, payloads, point_ids=point_ids
+        )
+
+        elapsed = round(time.time() - start, 1)
+        self._record_history(collection_name, "upsert", upserted, errors, elapsed)
+        return {
+            "total": upserted,
+            "skipped_unchanged": skipped_unchanged,
+            "groups": len(groups),
+            "elapsed_s": elapsed,
+            "errors": errors,
+        }
+
+    # ------------------------------------------------------------------
+    # 가이드 3단계 파이프라인
+    # ------------------------------------------------------------------
+
+    MAX_FILE_CHARS = 100_000  # 10만자 초과 시 skip
+
+    _STEP1_CONCURRENCY = 3  # 1단계 LLM 동시 호출 수
+
+    async def guide_pipeline_step1(
+        self,
+        source_dir: str,
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """1단계: 원본 파일 → 벡터 임베딩용 MD 재구성 (3개 병렬).
+
+        모든 파일(.md 포함)을 LLM으로 재구성.
+        출력: {source_dir}_mdversion/ 에 .md 파일 저장.
+
+        Yields:
+            {"status": "running", "current": N, "total": M, "file": "name"}
+            {"status": "error", "file": "name", "error": "reason"}
+            {"status": "complete", ...}
+        """
+        p = Path(source_dir)
+        out_dir = Path(f"{source_dir}_mdversion")
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        all_files = sorted(
+            f
+            for f in p.rglob("*")
+            if f.is_file()
+            and not f.name.startswith(".")
+            and not any(part.startswith(".") for part in f.relative_to(p).parts[:-1])
+        )
+
+        total = len(all_files)
+        sem = asyncio.Semaphore(self._STEP1_CONCURRENCY)
+        queue: asyncio.Queue[Dict[str, Any]] = asyncio.Queue()
+        done_count = 0
+        success_count = 0
+        error_count = 0
+
+        async def _process_one(fp: Path) -> None:
+            nonlocal done_count, success_count, error_count
+            async with sem:
+                await queue.put(
+                    {
+                        "status": "running",
+                        "current": done_count + 1,
+                        "total": total,
+                        "file": fp.name,
+                    }
+                )
+                try:
+                    content = fp.read_text(encoding="utf-8")
+
+                    if len(content) > self.MAX_FILE_CHARS:
+                        await queue.put(
+                            {
+                                "status": "error",
+                                "file": fp.name,
+                                "error": f"파일이 너무 큽니다 ({len(content)}자). 수동 분할 필요.",
+                            }
+                        )
+                        error_count += 1
+                        return
+
+                    # source URL 추출 후 LLM 변환 전에 제거
+                    src_url = self._extract_confluence_url(content)
+                    if src_url:
+                        content = re.sub(
+                            r"^\[source:\s*[^\]]*\]\s*\n?",
+                            "",
+                            content,
+                            count=1,
+                        ).lstrip()
+
+                    result = await self._convert_to_markdown(content, fp.name)
+
+                    if not result or not result.strip():
+                        await queue.put(
+                            {"status": "error", "file": fp.name, "error": "LLM 빈 응답"}
+                        )
+                        error_count += 1
+                        return
+
+                    if len(result.strip()) < len(content) * 0.5:
+                        logger.warning(
+                            "MD conversion may be truncated: %s (in=%d, out=%d)",
+                            fp.name,
+                            len(content),
+                            len(result),
+                        )
+
+                    # source URL을 md 첫 줄에 보존
+                    md_content = result.strip()
+                    if src_url:
+                        md_content = f"[source: {src_url}]\n\n{md_content}"
+
+                    out_path = out_dir / f"{fp.stem}.md"
+                    out_path.write_text(md_content, encoding="utf-8")
+                    success_count += 1
+
+                except Exception as e:
+                    await queue.put(
+                        {"status": "error", "file": fp.name, "error": str(e)}
+                    )
+                    error_count += 1
+                finally:
+                    done_count += 1
+
+        # 병렬 태스크 시작
+        tasks = [asyncio.create_task(_process_one(fp)) for fp in all_files]
+
+        # 큐에서 이벤트를 꺼내서 yield (모든 태스크 완료까지)
+        while done_count < total:
+            try:
+                event = await asyncio.wait_for(queue.get(), timeout=1.0)
+                yield event
+            except asyncio.TimeoutError:
+                continue
+
+        # 잔여 이벤트 drain
+        while not queue.empty():
+            yield queue.get_nowait()
+
+        # 모든 태스크 완료 대기
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+        yield {
+            "status": "complete",
+            "total": total,
+            "success": success_count,
+            "errors": error_count,
+            "outputDir": str(out_dir),
+        }
+
+    async def guide_pipeline_step2(
+        self,
+        source_dir: str,
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """2단계: _mdversion/ 파일 → 청킹 + 요약 → _chunked/ 에 개별 파일 저장.
+
+        Yields:
+            {"status": "running", "current": N, "total": M, "file": "name", "phase": "..."}
+            {"status": "complete", "total_files": N, "total_chunks": M, "outputDir": "path"}
+        """
+        md_dir = Path(f"{source_dir}_mdversion")
+        chunk_dir = Path(f"{source_dir}_chunked")
+        chunk_dir.mkdir(parents=True, exist_ok=True)
+
+        # 기존 청크 파일 삭제 (재실행 시 깨끗하게)
+        for old in chunk_dir.glob("*.md"):
+            old.unlink()
+
+        md_files = sorted(md_dir.glob("*.md"))
+        cfg = {**DEFAULT_CHUNKING}
+        total_chunks = 0
+
+        for i, fp in enumerate(md_files):
+            yield {
+                "status": "running",
+                "current": i + 1,
+                "total": len(md_files),
+                "file": fp.name,
+                "phase": "chunking",
+            }
+
+            content = fp.read_text(encoding="utf-8")
+            confluence_url = self._extract_confluence_url(content)
+            if confluence_url:
+                # 첫 줄 source URL을 content에서 제거
+                content = re.sub(
+                    r"^\[source:\s*[^\]]*\]\s*\n?", "", content, count=1
+                ).lstrip()
+            title = self._extract_title(content, fp.name)
+            chunks = self._chunk_markdown(content, cfg)
+
+            if not chunks:
+                continue
+
+            yield {
+                "status": "running",
+                "current": i + 1,
+                "total": len(md_files),
+                "file": fp.name,
+                "phase": "summary",
+            }
+            summaries = await self._generate_chunk_summaries(chunks, title)
+
+            for j, (chunk, summary) in enumerate(zip(chunks, summaries)):
+                section = chunk.get("section", "")
+                # YAML frontmatter에서 따옴표 이스케이프
+                safe_section = section.replace('"', '\\"')
+                safe_summary = summary.replace('"', '\\"')
+
+                frontmatter = (
+                    f"---\n"
+                    f'source: "{fp.name}"\n'
+                    f'section: "{safe_section}"\n'
+                    f'summary: "{safe_summary}"\n'
+                    f"chunk_index: {j + 1}\n"
+                    f"total_chunks: {len(chunks)}\n"
+                    + (
+                        f'confluence_url: "{confluence_url}"\n'
+                        if confluence_url
+                        else ""
+                    )
+                    + "---\n\n"
+                )
+                chunk_path = chunk_dir / f"{fp.stem}_{j + 1:03d}.md"
+                chunk_path.write_text(frontmatter + chunk["content"], encoding="utf-8")
+                total_chunks += 1
+
+        yield {
+            "status": "complete",
+            "total_files": len(md_files),
+            "total_chunks": total_chunks,
+            "outputDir": str(chunk_dir),
+        }
+
+    async def guide_pipeline_step3(
+        self,
+        source_dir: str,
+        collection_name: str = COLLECTION_GUIDE,
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """3단계: _chunked/ 파일 → 임베딩 + Qdrant upsert.
+
+        Yields:
+            {"status": "running", "current": N, "total": M, "file": "name"}
+            {"status": "complete", "total": N, "upserted": M}
+        """
+        chunk_dir = Path(f"{source_dir}_chunked")
+        chunk_files = sorted(chunk_dir.glob("*.md"))
+
+        # 컬렉션 초기화 후 재적재
+        try:
+            self._client.delete_collection(collection_name)
+        except Exception:
+            pass
+        await self.ensure_collections(self._embedding.dimension)
+
+        texts: List[str] = []
+        payloads: List[Dict[str, Any]] = []
+
+        for i, fp in enumerate(chunk_files):
+            yield {
+                "status": "running",
+                "current": i + 1,
+                "total": len(chunk_files),
+                "file": fp.name,
+            }
+
+            raw = fp.read_text(encoding="utf-8")
+            meta, content = self._parse_chunk_file(raw)
+
+            source = meta.get("source", fp.name)
+            section = meta.get("section", "")
+            summary = meta.get("summary", "")
+            title = self._extract_title(content, source)
+
+            prefix = f"[{title}"
+            if section:
+                prefix += f" > {section}"
+            prefix += "]"
+
+            embed_text = f"{prefix}\n{summary}\n\n{content}"
+            texts.append(embed_text)
+            confluence_url = meta.get("confluence_url", "") or meta.get(
+                "source_url", ""
+            )
+            payload_entry: Dict[str, Any] = {
+                "content": content,
+                "summary": summary,
+                "source": source,
+                "title": title,
+                "section": section,
+                "_collection": collection_name,
+                "_embed_text": embed_text,
+            }
+            if confluence_url:
+                payload_entry["confluence_url"] = confluence_url
+            payloads.append(payload_entry)
+
+        # 적재 직전 PII 마스킹 (bdp_guides=guide_docs 컬렉션 한정)
+        if collection_name == COLLECTION_GUIDE:
+            texts, payloads = self._mask_pii_for_ingestion(
+                texts, payloads, collection_name
+            )
+
+        upserted = await self._batch_upsert(collection_name, texts, payloads)
+
+        yield {
+            "status": "complete",
+            "total": len(chunk_files),
+            "upserted": upserted,
+        }
+
+    @staticmethod
+    def _parse_chunk_file(raw: str) -> Tuple[Dict[str, Any], str]:
+        """YAML frontmatter + content 파싱."""
+        if raw.startswith("---"):
+            parts = raw.split("---", 2)
+            if len(parts) >= 3:
+                import yaml
+
+                try:
+                    meta = yaml.safe_load(parts[1]) or {}
+                except Exception:
+                    meta = {}
+                content = parts[2].strip()
+                return meta, content
+        return {}, raw.strip()
+
+    def guide_pipeline_status(self, source_dir: str) -> Dict[str, Any]:
+        """각 단계별 산출물 존재 여부 확인."""
+        md_dir = Path(f"{source_dir}_mdversion")
+        chunk_dir = Path(f"{source_dir}_chunked")
+        return {
+            "mdversion": {
+                "exists": md_dir.is_dir(),
+                "files": len(list(md_dir.glob("*.md"))) if md_dir.is_dir() else 0,
+            },
+            "chunked": {
+                "exists": chunk_dir.is_dir(),
+                "files": len(list(chunk_dir.glob("*.md"))) if chunk_dir.is_dir() else 0,
+            },
+        }
+
+    # ------------------------------------------------------------------
+    # 가이드 문서 적재 (레거시 — 하위 호환)
+    # ------------------------------------------------------------------
+
+    async def upsert_guide_directory(
+        self,
+        dir_path: str,
+        chunking_config: Optional[Dict[str, int]] = None,
+        collection_name: str = COLLECTION_GUIDE,
+    ) -> Dict[str, Any]:
+        """디렉토리 내 모든 파일 순차 처리 → guide 컬렉션 적재."""
+        start = time.time()
+        cfg = {**DEFAULT_CHUNKING, **(chunking_config or {})}
+        p = Path(dir_path)
+        if not p.is_dir():
+            return {"error": f"Not a directory: {dir_path}"}
+
+        # 모든 파일 수집 (숨김 디렉토리 .ipynb_checkpoints 등 제외)
+        all_files = sorted(
+            f
+            for f in p.rglob("*")
+            if f.is_file()
+            and not f.name.startswith(".")
+            and not any(part.startswith(".") for part in f.relative_to(p).parts[:-1])
+        )
+        total_chunks = 0
+        converted = 0
+        errors: List[Dict[str, str]] = []
+
+        # 진행 상황 초기화
+        self._progress = {
+            "status": "running",
+            "total_files": len(all_files),
+            "processed_files": 0,
+            "current_file": "",
+            "total_chunks": 0,
+            "summary_total": 0,
+            "summary_done": 0,
+        }
+
+        # 기존 컬렉션 전체 삭제 후 재적재
+        self._client.delete_collection(collection_name)
+        await self.ensure_collections(self._embedding.dimension)
+
+        for fp in all_files:
+            self._progress["current_file"] = fp.name
+            try:
+                result = await self._process_guide_file(fp, cfg, collection_name)
+                total_chunks += result.get("chunks", 0)
+                self._progress["total_chunks"] = total_chunks
+                if result.get("converted"):
+                    converted += 1
+            except Exception as e:
+                errors.append({"file": str(fp), "error": str(e)})
+                logger.error("Guide file error %s: %s", fp, e)
+            self._progress["processed_files"] += 1
+
+        elapsed = round(time.time() - start, 1)
+        self._progress = {
+            "status": "done",
+            "total_files": len(all_files),
+            "processed_files": len(all_files),
+            "total_chunks": total_chunks,
+            "elapsed_s": elapsed,
+        }
+        self._record_history(
+            collection_name,
+            "upsert_directory",
+            total_chunks,
+            [e["error"] for e in errors],
+            elapsed,
+        )
+        return {
+            "total_files": len(all_files),
+            "total_chunks": total_chunks,
+            "converted_files": converted,
+            "errors": errors,
+            "elapsed_s": elapsed,
+        }
+
+    async def upsert_guide_file(
+        self,
+        file_path: str,
+        chunking_config: Optional[Dict[str, int]] = None,
+        collection_name: str = COLLECTION_GUIDE,
+    ) -> Dict[str, Any]:
+        """guide 컬렉션 파일 1개만 추가/갱신 (해시 비교)."""
+        cfg = {**DEFAULT_CHUNKING, **(chunking_config or {})}
+        fp = Path(file_path)
+        if not fp.is_file():
+            return {"error": f"Not a file: {file_path}"}
+
+        source = fp.name
+        file_hash = self._file_hash(fp)
+
+        # 기존 동일 source 포인트 해시 비교
+        existing = self._scroll_by_source(collection_name, source, limit=1)
+        if existing and existing[0].payload.get("_file_hash") == file_hash:
+            return {"status": "unchanged", "source": source}
+
+        # 기존 포인트 삭제
+        self._delete_by_source(collection_name, source)
+
+        result = await self._process_guide_file(fp, cfg, collection_name)
+        return {"status": "updated", "source": source, **result}
+
+    async def delete_guide_file(
+        self, source: str, collection_name: str = COLLECTION_GUIDE
+    ) -> Dict[str, Any]:
+        """guide 컬렉션에서 특정 source 포인트 삭제."""
+        count = self._delete_by_source(collection_name, source)
+        return {"deleted": count, "source": source}
+
+    def _mask_pii_for_ingestion(
+        self,
+        texts: List[str],
+        payloads: List[Dict[str, Any]],
+        collection_name: str,
+    ) -> Tuple[List[str], List[Dict[str, Any]]]:
+        """RAG 적재 직전 PII 마스킹 후처리.
+
+        임베딩 대상 텍스트와 payload의 텍스트 필드를 마스킹해 원본 PII가
+        벡터/저장값 어디에도 남지 않도록 한다. guide_docs/faq_docs 적재에만 호출.
+        """
+        from codebuff_core.services.pii_guardrail import mask_pii
+
+        mask_fields = (
+            "content",
+            "summary",
+            "title",
+            "section",
+            "question",
+            "answer",
+            "tags",
+        )
+        masked_texts: List[str] = []
+        chunks_with_pii = 0
+        detected: set = set()
+
+        for text, payload in zip(texts, payloads):
+            res = mask_pii(text)
+            masked_texts.append(res.masked_text)
+            if res.has_pii:
+                chunks_with_pii += 1
+                detected.update(res.detected_types)
+            for key in mask_fields:
+                val = payload.get(key)
+                if isinstance(val, str) and val:
+                    field_res = mask_pii(val)
+                    if field_res.has_pii:
+                        payload[key] = field_res.masked_text
+                        detected.update(field_res.detected_types)
+            payload["_embed_text"] = res.masked_text
+
+        if chunks_with_pii:
+            logger.info(
+                "[PII] %s 적재 마스킹: %d/%d chunks, types=%s",
+                collection_name,
+                chunks_with_pii,
+                len(texts),
+                sorted(detected),
+            )
+        return masked_texts, payloads
+
+    async def _process_guide_file(
+        self, fp: Path, cfg: Dict[str, int], collection_name: str = COLLECTION_GUIDE
+    ) -> Dict[str, Any]:
+        """파일 1개 → md 변환 → 청킹 → 요약 → 임베딩 → upsert."""
+        content = fp.read_text(encoding="utf-8")
+        converted = False
+
+        # 비-md 파일 → 마크다운 변환
+        if fp.suffix.lower() != ".md":
+            content = await self._convert_to_markdown(content, fp.name)
+            # 변환 결과 저장
+            md_path = fp.with_suffix(".md")
+            md_path.write_text(content, encoding="utf-8")
+            converted = True
+
+        source = fp.name
+        file_hash = self._file_hash(fp)
+
+        # 제목 추출
+        title = self._extract_title(content, fp.name)
+
+        # 청킹
+        chunks = self._chunk_markdown(content, cfg)
+        if not chunks:
+            return {"chunks": 0, "converted": converted}
+
+        # 요약 생성
+        summaries = await self._generate_chunk_summaries(chunks, title)
+
+        # 임베딩 텍스트 + payload 구성
+        texts: List[str] = []
+        payloads: List[Dict[str, Any]] = []
+
+        for chunk, summary in zip(chunks, summaries):
+            section = chunk.get("section", "")
+            prefix = f"[{title}"
+            if section:
+                prefix += f" > {section}"
+            prefix += "]"
+
+            embed_text = f"{prefix}\n{summary}\n\n{chunk['content']}"
+            texts.append(embed_text)
+            payloads.append(
+                {
+                    "content": chunk["content"],
+                    "summary": summary,
+                    "source": source,
+                    "title": title,
+                    "section": section,
+                    "_collection": collection_name,
+                    "_embed_text": embed_text,
+                    "_file_hash": file_hash,
+                }
+            )
+
+        # 적재 직전 PII 마스킹 (bdp_guides=guide_docs 컬렉션 한정)
+        if collection_name == COLLECTION_GUIDE:
+            texts, payloads = self._mask_pii_for_ingestion(
+                texts, payloads, collection_name
+            )
+
+        upserted = await self._batch_upsert(collection_name, texts, payloads)
+        return {"chunks": upserted, "converted": converted}
+
+    # ------------------------------------------------------------------
+    # FAQ 컬렉션 적재 (faq_docs)
+    # ------------------------------------------------------------------
+
+    async def upsert_faq_collection(self, file_path: str) -> Dict[str, Any]:
+        """CSV(question, answer, tags) → faq_docs 컬렉션 적재.
+
+        - 임베딩 텍스트: question만 사용 (Question-to-Question 정렬로 정확도 ↑)
+        - payload: question, answer, tags, _embed_text, _file_hash
+        - 기존 hash와 동일하면 skip (변경분만 재임베딩)
+        """
+        start = time.time()
+        errors: List[str] = []
+
+        rows = self._read_csv(file_path)
+        if not rows:
+            return {"total": 0, "errors": ["CSV is empty"]}
+
+        # 필수 컬럼 확인
+        first = rows[0]
+        if "question" not in first or "answer" not in first:
+            raise ValueError(
+                "FAQ CSV must contain 'question' and 'answer' columns "
+                f"(got: {list(first.keys())})"
+            )
+
+        await self.ensure_collections(self._embedding.dimension)
+
+        # 기존 포인트의 content hash 조회 (변경 감지)
+        existing_hashes: Dict[str, str] = {}
+        try:
+            scroll_offset = None
+            while True:
+                pts, scroll_offset = self._client.scroll(
+                    collection_name=COLLECTION_FAQ,
+                    offset=scroll_offset,
+                    limit=200,
+                    with_payload=["_content_hash"],
+                    with_vectors=False,
+                )
+                for pt in pts:
+                    h = (pt.payload or {}).get("_content_hash", "")
+                    existing_hashes[str(pt.id)] = h
+                if scroll_offset is None:
+                    break
+        except Exception:
+            pass
+
+        self._progress = {
+            "status": "running",
+            "total": len(rows),
+            "done": 0,
+            "collection": COLLECTION_FAQ,
+        }
+
+        texts: List[str] = []
+        payloads: List[Dict[str, Any]] = []
+        point_ids: List[str] = []
+        skipped_unchanged = 0
+
+        for row in rows:
+            q = str(row.get("question") or "").strip()
+            a = str(row.get("answer") or "").strip()
+            if not q or not a:
+                continue
+            tags = str(row.get("tags") or "").strip()
+
+            # point id는 질문 내용으로 deterministic
+            pid = str(uuid.uuid5(uuid.NAMESPACE_DNS, f"{COLLECTION_FAQ}:{q}"))
+
+            # 임베딩 텍스트 = question만 (Q↔Q 정렬)
+            embed_text = q
+            content_hash = hashlib.sha256(
+                f"{q}\n{a}\n{tags}".encode("utf-8")
+            ).hexdigest()[:16]
+
+            if pid in existing_hashes and existing_hashes[pid] == content_hash:
+                skipped_unchanged += 1
+                continue
+
+            payload: Dict[str, Any] = {
+                "_collection": COLLECTION_FAQ,
+                "_embed_text": embed_text,
+                "_content_hash": content_hash,
+                "question": q,
+                "answer": a,
+            }
+            if tags:
+                payload["tags"] = tags
+
+            texts.append(embed_text)
+            payloads.append(payload)
+            point_ids.append(pid)
+
+        if not texts:
+            return {
+                "total": 0,
+                "skipped_unchanged": skipped_unchanged,
+                "errors": [] if skipped_unchanged else ["No valid rows"],
+            }
+
+        # 적재 직전 PII 마스킹 (faq_docs 컬렉션)
+        texts, payloads = self._mask_pii_for_ingestion(texts, payloads, COLLECTION_FAQ)
+
+        upserted = await self._batch_upsert(
+            COLLECTION_FAQ, texts, payloads, point_ids=point_ids
+        )
+
+        elapsed = round(time.time() - start, 1)
+        self._record_history(COLLECTION_FAQ, "upsert", upserted, errors, elapsed)
+        return {
+            "total": upserted,
+            "skipped_unchanged": skipped_unchanged,
+            "rows": len(rows),
+            "elapsed_s": elapsed,
+            "errors": errors,
+        }
+
+    # ------------------------------------------------------------------
+    # 마크다운 변환
+    # ------------------------------------------------------------------
+
+    async def _convert_to_markdown(self, content: str, filename: str) -> str:
+        """비-md 파일 → 마크다운 구조화 (내용 100% 보존, 포맷만 변경)."""
+        from codebuff_core.managers.config_manager import prompt_value
+
+        # 지시부는 `prompts.guide_ingest_markdown_prompt`, 파일명·원본은 코드가 붙인다 (이슈 #218)
+        prompt = (
+            prompt_value("guide_ingest_markdown_prompt") + "\n\n"
+            f"파일명: {filename}\n\n"
+            f"원본:\n{content}"
+        )
+        result, reason = await self._call_llm(prompt, return_finish_reason=True)
+        print(
+            f"[RAG] MD convert: {filename} finish_reason={reason} "
+            f"in={len(content)} out={len(result or '')}",
+            flush=True,
+        )
+
+        if not result or not result.strip():
+            return content
+
+        # 출력이 잘린 경우 이어쓰기 (최대 3회)
+        max_continuations = 3
+        full_result = result
+        for cont_i in range(max_continuations):
+            if reason != "length":
+                break
+            logger.info(
+                "MD conversion truncated for %s, continuing (%d/%d)",
+                filename,
+                cont_i + 1,
+                max_continuations,
+            )
+            # 이미 변환된 부분에 해당하는 원본 위치를 추정하여 나머지만 전달
+            # 변환 결과의 마지막 5줄에서 키워드를 추출하여 원본에서 위치 탐색
+            last_lines = full_result.strip().splitlines()[-5:]
+            remaining = content
+            for line in last_lines:
+                # 마크다운 포맷 제거 후 원본에서 검색
+                clean = line.strip().lstrip("#").strip().strip("*").strip()
+                if len(clean) > 15:
+                    idx = content.find(clean)
+                    if idx > 0:
+                        # 해당 위치 이후의 원본을 remaining으로
+                        remaining = content[idx + len(clean) :]
+                        break
+
+            last_output = "\n".join(last_lines)
+            cont_prompt = (
+                "이전 마크다운 변환이 출력 한도에 도달하여 중단되었습니다.\n"
+                "아래 규칙을 반드시 지켜주세요:\n"
+                "1. '이전 출력의 마지막 부분' 바로 다음부터 이어서 변환하세요\n"
+                "2. 절대 요약/마무리/결론 섹션을 추가하지 마세요\n"
+                "3. 원본 내용을 축소하지 말고 100% 그대로 마크다운으로 변환하세요\n"
+                "4. 마크다운만 출력하세요 (설명이나 메타 텍스트 없이)\n\n"
+                f"이전 출력의 마지막 부분:\n```\n{last_output}\n```\n\n"
+                f"변환할 나머지 원본:\n{remaining}"
+            )
+            cont_result, reason = await self._call_llm(
+                cont_prompt, return_finish_reason=True
+            )
+            if cont_result and cont_result.strip():
+                full_result += "\n" + cont_result
+
+        return full_result.strip()
+
+    # ------------------------------------------------------------------
+    # 시맨틱 청킹 (마크다운 헤더 기반)
+    # ------------------------------------------------------------------
+
+    def _chunk_markdown(
+        self, content: str, cfg: Optional[Dict[str, int]] = None
+    ) -> List[Dict[str, Any]]:
+        """마크다운 헤더 기반 시맨틱 청킹 + target_size 병합.
+
+        1단계: ## → ### → 빈 줄 → 문장으로 시맨틱 분할
+        2단계: 인접 소형 청크를 target_size까지 병합
+        """
+        c = {**DEFAULT_CHUNKING, **(cfg or {})}
+        target = c["target_size"]
+        min_sz = c["min_size"]
+        max_sz = c["max_size"]
+
+        # 1단계: 시맨틱 분할 (min_size 제한 없이 전부 수집)
+        sections = self._split_by_header(content, level=2)
+        raw_chunks: List[Dict[str, Any]] = []
+
+        for section_header, section_text in sections:
+            if len(section_text) <= max_sz:
+                raw_chunks.append({"content": section_text, "section": section_header})
+                continue
+
+            # ### (h3)로 재분할
+            subsections = self._split_by_header(section_text, level=3)
+            for sub_header, sub_text in subsections:
+                header = (
+                    f"{section_header} > {sub_header}" if sub_header else section_header
+                )
+                if len(sub_text) <= max_sz:
+                    raw_chunks.append({"content": sub_text, "section": header})
+                    continue
+
+                # 빈 줄(문단) 기준 분할
+                para_chunks = self._split_by_paragraphs(sub_text, target, max_sz)
+                for pc in para_chunks:
+                    raw_chunks.append({"content": pc, "section": header})
+
+        # 2단계: 인접 소형 청크를 target_size까지 병합
+        # 제목 전용 청크(section 없고 짧은)는 무조건 다음 청크에 흡수
+        merged: List[Dict[str, Any]] = []
+        for chunk in raw_chunks:
+            clen = len(chunk["content"])
+            prev_is_title_only = (
+                merged
+                and not merged[-1]["section"]
+                and len(merged[-1]["content"]) < min_sz
+            )
+            can_merge = merged and (
+                len(merged[-1]["content"]) + clen + 2 <= target or prev_is_title_only
+            )
+            if can_merge:
+                merged[-1]["content"] += "\n\n" + chunk["content"]
+                if chunk["section"] and not merged[-1]["section"]:
+                    merged[-1]["section"] = chunk["section"]
+            else:
+                merged.append(dict(chunk))
+
+        # min_size 미만 잔여 청크 → 이전 또는 다음 청크에 흡수
+        final: List[Dict[str, Any]] = []
+        for chunk in merged:
+            clen = len(chunk["content"].strip())
+            if clen < min_sz:
+                if final:
+                    # 이전 청크에 흡수
+                    final[-1]["content"] += "\n\n" + chunk["content"]
+                else:
+                    # 첫 번째 청크가 작으면 일단 추가 (다음에 흡수될 수 있음)
+                    final.append(dict(chunk))
+            else:
+                # 이전 청크가 min_size 미만이면 현재에 흡수
+                if final and len(final[-1]["content"].strip()) < min_sz:
+                    chunk["content"] = final[-1]["content"] + "\n\n" + chunk["content"]
+                    if not chunk["section"] and final[-1]["section"]:
+                        chunk["section"] = final[-1]["section"]
+                    final[-1] = chunk
+                else:
+                    final.append(dict(chunk))
+
+        # 마지막 청크가 min_size 미만이면 이전에 흡수
+        if len(final) >= 2 and len(final[-1]["content"].strip()) < min_sz:
+            final[-2]["content"] += "\n\n" + final[-1]["content"]
+            final.pop()
+
+        return final
+
+    @staticmethod
+    def _split_by_header(text: str, level: int) -> List[Tuple[str, str]]:
+        """마크다운 헤더 레벨로 분할. 반환: [(header_text, section_content), ...]"""
+        pattern = r"^(#{" + str(level) + r"})\s+(.+)$"
+        sections: List[Tuple[str, str]] = []
+        current_header = ""
+        current_lines: List[str] = []
+
+        for line in text.split("\n"):
+            m = re.match(pattern, line, re.MULTILINE)
+            if m:
+                # 이전 섹션 저장
+                if current_lines:
+                    sections.append((current_header, "\n".join(current_lines).strip()))
+                current_header = m.group(2).strip()
+                current_lines = [line]
+            else:
+                current_lines.append(line)
+
+        if current_lines:
+            sections.append((current_header, "\n".join(current_lines).strip()))
+
+        return sections if sections else [("", text)]
+
+    @staticmethod
+    def _split_by_paragraphs(text: str, target: int, max_sz: int) -> List[str]:
+        """빈 줄 기준 문단 분할, target_size에 맞게 병합."""
+        paragraphs = re.split(r"\n\s*\n", text)
+        chunks: List[str] = []
+        current = ""
+
+        for para in paragraphs:
+            para = para.strip()
+            if not para:
+                continue
+            if current and len(current) + len(para) + 2 > target:
+                chunks.append(current)
+                current = para
+            else:
+                current = current + "\n\n" + para if current else para
+
+            # max_size 초과 시 문장 단위 분할
+            if len(current) > max_sz:
+                sentences = re.split(r"(?<=[.!?。])\s+", current)
+                buf = ""
+                for s in sentences:
+                    if buf and len(buf) + len(s) + 1 > target:
+                        chunks.append(buf)
+                        buf = s
+                    else:
+                        buf = buf + " " + s if buf else s
+                current = buf
+
+        if current:
+            chunks.append(current)
+        return chunks
+
+    # ------------------------------------------------------------------
+    # LLM 청크 요약 생성
+    # ------------------------------------------------------------------
+
+    async def _generate_chunk_summaries(
+        self,
+        chunks: List[Dict[str, Any]],
+        doc_title: str,
+        concurrency: int = 5,
+    ) -> List[str]:
+        """각 청크에 대해 LLM 요약을 병렬 생성 (semaphore로 동시 요청 제한)."""
+        from codebuff_core.managers.config_manager import prompt_value
+
+        # 지시부는 `prompts.guide_chunk_summary_prompt` 다 (이슈 #218) — 문서 하나에 한 번 읽는다
+        instruction = prompt_value("guide_chunk_summary_prompt")
+        sem = asyncio.Semaphore(concurrency)
+
+        async def _summarize_one(idx: int, chunk: Dict[str, Any]) -> Tuple[int, str]:
+            async with sem:
+                section = chunk.get("section", "")
+                content = chunk["content"]
+                # 너무 짧은 청크는 요약 불필요
+                if len(content.strip()) < 50:
+                    return idx, content.strip()
+                prompt = (
+                    instruction + "\n\n"
+                    f"문서: {doc_title}\n"
+                    f"섹션: {section}\n\n"
+                    "---\n"
+                    f"{content[:3000]}\n"
+                    "---"
+                )
+                try:
+                    summary = await self._call_llm(prompt)
+                    return idx, summary.strip() if summary else ""
+                except Exception as e:
+                    logger.warning("Chunk summary failed [%d]: %s", idx, e)
+                    return idx, ""
+                finally:
+                    self._progress["summary_done"] = (
+                        self._progress.get("summary_done", 0) + 1
+                    )
+
+        self._progress["summary_total"] = self._progress.get("summary_total", 0) + len(
+            chunks
+        )
+
+        tasks = [_summarize_one(i, c) for i, c in enumerate(chunks)]
+        results = await asyncio.gather(*tasks)
+        results_sorted = sorted(results, key=lambda x: x[0])
+        return [r[1] for r in results_sorted]
+
+    # ------------------------------------------------------------------
+    # LLM 호출 (OpenAI 호환 API)
+    # ------------------------------------------------------------------
+
+    async def _call_llm(
+        self, prompt: str, max_retries: int = 5, return_finish_reason: bool = False
+    ) -> "str | Tuple[str, str]":
+        """vllm 엔드포인트로 LLM 호출 (rate limit 재시도 포함).
+
+        Args:
+            return_finish_reason: True면 (content, finish_reason) 튜플 반환.
+        """
+        endpoint = self._llm_config.get("endpoint", "")
+        if not endpoint:
+            raise ValueError("LLM endpoint not configured (summarization or vllm)")
+
+        api_key = self._llm_config.get("api_key", "")
+        model = self._llm_config.get("model", "")
+
+        headers = {"Content-Type": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+        payload = {
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0.1,
+            "max_tokens": 16384,
+        }
+
+        base = endpoint.rstrip("/")
+        url = (
+            f"{base}/v1/chat/completions"
+            if "/v1" not in base
+            else f"{base}/chat/completions"
+        )
+
+        last_error: Optional[Exception] = None
+        for attempt in range(max_retries):
+            try:
+                async with httpx.AsyncClient(timeout=120.0, verify=False) as client:
+                    resp = await client.post(url, json=payload, headers=headers)
+                    resp.raise_for_status()
+                    data = resp.json()
+                    content = data["choices"][0]["message"]["content"]
+                    if return_finish_reason:
+                        reason = data["choices"][0].get("finish_reason", "stop")
+                        return content, reason
+                    return content
+            except httpx.HTTPStatusError as e:
+                last_error = e
+                if e.response.status_code == 429:
+                    # Rate limit: Retry-After 헤더 우선, 없으면 exponential backoff
+                    retry_after = e.response.headers.get("Retry-After")
+                    wait = (
+                        float(retry_after) if retry_after else min(2**attempt * 2, 60)
+                    )
+                    logger.warning(
+                        "Rate limited, waiting %.0fs (attempt %d/%d)",
+                        wait,
+                        attempt + 1,
+                        max_retries,
+                    )
+                    await asyncio.sleep(wait)
+                elif e.response.status_code >= 500:
+                    wait = min(2**attempt, 30)
+                    logger.warning(
+                        "Server error %d, retrying in %ds: %s",
+                        e.response.status_code,
+                        wait,
+                        e,
+                    )
+                    await asyncio.sleep(wait)
+                else:
+                    raise
+            except httpx.RequestError as e:
+                last_error = e
+                wait = min(2**attempt, 30)
+                logger.warning("LLM request error, retrying in %ds: %s", wait, e)
+                await asyncio.sleep(wait)
+
+        raise Exception(
+            f"LLM call failed after {max_retries} retries: {last_error} (url={url})"
+        )
+
+    # ------------------------------------------------------------------
+    # 프리뷰 / 검증
+    # ------------------------------------------------------------------
+
+    async def dry_run_table(
+        self,
+        file_path: str,
+        mapping: Dict[str, Any],
+        join_file_path: Optional[str] = None,
+        join_key: Optional[str] = None,
+        sample_count: int = 3,
+    ) -> Dict[str, Any]:
+        """적재 전 프리뷰 — 파싱 샘플 + 임베딩 텍스트 미리보기."""
+        rows = self._read_csv(file_path)
+        if join_file_path and join_key:
+            column_rows = self._read_csv(join_file_path)
+            rows = self._join_csvs(rows, column_rows, join_key)
+
+        group_by = mapping.get("groupBy", [])
+        groups = self._group_rows(rows, group_by)
+        embedding_fields = mapping.get("embeddingFields", [])
+        table_fields = mapping.get("tableFields", [])
+        column_fields = mapping.get("columnFields", [])
+        header_fields = mapping.get("headerFields") or table_fields[:2]
+
+        samples = []
+        for i, (key, group_rows) in enumerate(groups.items()):
+            if i >= sample_count:
+                break
+            first_row = group_rows[0]
+            table_row = first_row.get(self._MAIN_ROW_KEY) or first_row
+            embed_text = self._build_table_embed_text(
+                table_row,
+                group_rows,
+                table_fields,
+                column_fields,
+                embedding_fields,
+                header_fields,
+            )
+
+            payload = {}
+            for tf in table_fields:
+                if tf in table_row:  # 파일에 존재하는 필드만 포함
+                    payload[tf] = table_row[tf]
+            cols = [{cf: r[cf] for cf in column_fields if cf in r} for r in group_rows]
+
+            samples.append(
+                {
+                    "group_key": key,
+                    "embed_text": embed_text[:800],
+                    "payload_preview": payload,
+                    "columns_count": len(cols),
+                    "columns_sample": cols[:3],
+                }
+            )
+
+        return {
+            "total_groups": len(groups),
+            "total_rows": len(rows),
+            "samples": samples,
+        }
+
+    async def dry_run_guide(
+        self, dir_path: str, chunking_config: Optional[Dict[str, int]] = None
+    ) -> Dict[str, Any]:
+        """guide 컬렉션 청킹 프리뷰."""
+        cfg = {**DEFAULT_CHUNKING, **(chunking_config or {})}
+        p = Path(dir_path)
+        files = sorted(
+            f
+            for f in p.rglob("*")
+            if f.is_file()
+            and not f.name.startswith(".")
+            and not any(part.startswith(".") for part in f.relative_to(p).parts[:-1])
+        )
+        previews = []
+        for fp in files:
+            try:
+                content = fp.read_text(encoding="utf-8")
+                title = self._extract_title(content, fp.name)
+                chunks = self._chunk_markdown(content, cfg)
+                previews.append(
+                    {
+                        "file": fp.name,
+                        "needs_conversion": fp.suffix.lower() != ".md",
+                        "title": title,
+                        "chunk_count": len(chunks),
+                        "chunks_preview": [
+                            {
+                                "section": c.get("section", ""),
+                                "first_100": c["content"][:100],
+                            }
+                            for c in chunks[:5]
+                        ],
+                    }
+                )
+            except Exception as e:
+                previews.append({"file": fp.name, "error": str(e)})
+        return {"total_files": len(files), "previews": previews}
+
+    def validate_csv_mapping(
+        self, file_path: str, mapping: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """CSV 유효성 검증."""
+        rows = self._read_csv(file_path)
+        if not rows:
+            return {"valid": False, "error": "Empty CSV"}
+
+        headers = set(rows[0].keys())
+        group_by = mapping.get("groupBy", [])
+        if isinstance(group_by, str):
+            group_by = [group_by] if group_by else []
+        all_fields = (
+            group_by
+            + mapping.get("embeddingFields", [])
+            + mapping.get("tableFields", [])
+            + mapping.get("columnFields", [])
+        )
+
+        missing = [f for f in all_fields if f and f not in headers]
+        warnings: List[str] = []
+
+        # 빈 값 비율 (각 그룹핑 키별)
+        for gb in group_by:
+            if gb in headers:
+                null_count = sum(1 for r in rows if not r.get(gb))
+                null_pct = round(null_count / len(rows) * 100, 1)
+                if null_pct > 0:
+                    warnings.append(f"groupBy '{gb}': NULL {null_pct}%")
+        if group_by:
+            groups = self._group_rows(rows, group_by)
+            warnings.append(f"Unique groups: {len(groups)}")
+
+        return {
+            "valid": len(missing) == 0,
+            "headers": sorted(headers),
+            "missing_fields": missing,
+            "total_rows": len(rows),
+            "warnings": warnings,
+        }
+
+    def parse_csv_headers(self, file_path: str) -> List[str]:
+        """CSV 헤더 목록 반환."""
+        rows = self._read_csv(file_path, limit=1)
+        if rows:
+            return sorted(rows[0].keys())
+        return []
+
+    def list_directory_files(self, dir_path: str) -> List[Dict[str, Any]]:
+        """디렉토리 내 파일 목록."""
+        p = Path(dir_path)
+        if not p.is_dir():
+            return []
+        files = []
+        for f in sorted(p.rglob("*")):
+            if (
+                f.is_file()
+                and not f.name.startswith(".")
+                and not any(
+                    part.startswith(".") for part in f.relative_to(p).parts[:-1]
+                )
+            ):
+                files.append(
+                    {
+                        "name": f.name,
+                        "path": str(f),
+                        "size": f.stat().st_size,
+                        "ext": f.suffix.lower(),
+                    }
+                )
+        return files
+
+    # ------------------------------------------------------------------
+    # 데이터 브라우저
+    # ------------------------------------------------------------------
+
+    async def browse_collection(
+        self,
+        collection: str,
+        offset: Optional[str] = None,
+        limit: int = 10,
+        filters: Optional[List[Dict[str, str]]] = None,
+    ) -> Dict[str, Any]:
+        """컬렉션 포인트 페이징 조회. offset은 Qdrant scroll의 point ID.
+
+        filters: [{"field": "source", "value": "guide.md"}, ...] — AND 조건.
+        nested 배열 필터는 field에 "columns[].col_name" 형태 사용.
+        """
+        from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+        scroll_filter = None
+        if filters:
+            conditions = [
+                FieldCondition(key=f["field"], match=MatchValue(value=f["value"]))
+                for f in filters
+                if f.get("field") and f.get("value")
+            ]
+            if conditions:
+                scroll_filter = Filter(must=conditions)
+
+        points, next_offset = self._client.scroll(
+            collection_name=collection,
+            scroll_filter=scroll_filter,
+            limit=limit,
+            offset=offset,
+            with_payload=True,
+            with_vectors=False,
+        )
+
+        items = []
+        for pt in points:
+            payload = dict(pt.payload) if pt.payload else {}
+            # _embed_text 는 너무 크므로 축약
+            if "_embed_text" in payload:
+                payload["_embed_text"] = payload["_embed_text"][:200] + "..."
+            items.append({"id": str(pt.id), "payload": payload})
+
+        return {"items": items, "next_offset": next_offset, "count": len(items)}
+
+    async def delete_point(self, collection: str, point_id: str) -> None:
+        """포인트 1개 삭제."""
+        from qdrant_client.models import PointIdsList
+
+        self._client.delete(
+            collection_name=collection,
+            points_selector=PointIdsList(points=[point_id]),
+        )
+
+    # ------------------------------------------------------------------
+    # 검색 테스트
+    # ------------------------------------------------------------------
+
+    async def search_test(
+        self, query: str, collection: Optional[str] = None, top_k: int = 5
+    ) -> List[Dict[str, Any]]:
+        """관리자용 검색 테스트."""
+        query_vec = await self._embedding.embed_query(query)
+        collections = [collection] if collection else ALL_COLLECTIONS
+        results: List[Dict[str, Any]] = []
+
+        for col in collections:
+            try:
+                hits = self._client.query_points(
+                    collection_name=col,
+                    query=query_vec,
+                    limit=top_k,
+                    with_payload=True,
+                )
+                for hit in hits.points:
+                    payload = dict(hit.payload) if hit.payload else {}
+                    if "_embed_text" in payload:
+                        payload["_embed_text"] = payload["_embed_text"][:200] + "..."
+                    results.append(
+                        {
+                            "collection": col,
+                            "score": round(hit.score, 4),
+                            "id": str(hit.id),
+                            "payload": payload,
+                        }
+                    )
+            except Exception as e:
+                logger.warning("Search test failed for %s: %s", col, e)
+
+        results.sort(key=lambda x: x["score"], reverse=True)
+        return results[:top_k]
+
+    async def search_with_filter(
+        self,
+        query: str,
+        collection: Optional[str] = None,
+        filters: Optional[List[Dict[str, str]]] = None,
+        top_k: int = 10,
+        score_threshold: float = 0.5,
+        match_text: Optional[List[str]] = None,
+        chunk_type: Optional[str] = None,
+        exclude_table_names: Optional[List[str]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Qdrant pre-filtering 검색. score_threshold 이상만 반환.
+
+        필터 적용 결과가 0건이면, 필터 값을 쿼리에 합쳐서 필터 없이 자동 재검색.
+        예: filters=[{field: "db_name", value: "ADW"}], query="카드매출"
+            → 0건 시 query="ADW 카드매출" 으로 필터 없이 재검색.
+
+        Args:
+            query: 검색 쿼리 텍스트
+            collection: 특정 컬렉션 또는 None(전체)
+            filters: [{"field": "x", "value": "y"}] AND 조건 리스트
+            top_k: 최대 결과 수 (상한)
+            score_threshold: 최소 유사도 점수 (기본 0.3)
+            match_text: 텍스트 매칭 검색어 리스트 (인덱스 필드 전체에 OR 검색)
+            chunk_type: "table" | "columns" | None.
+                - "table": 테이블명 검색에 최적화된 청크만 (테이블 메타 강조)
+                - "columns": 컬럼 검색에 최적화된 청크만 (컬럼 리스트 강조)
+                - None: 양쪽 모두 검색 후 _group_key로 dedupe (TableConfirmation
+                  후보로 사용)
+        """
+        results = await self._search_qdrant(
+            query=query,
+            collections=[collection] if collection else None,
+            filters=filters,
+            top_k=top_k,
+            score_threshold=score_threshold,
+            match_text=match_text,
+            chunk_type=chunk_type,
+            exclude_table_names=exclude_table_names,
+        )
+
+        # 필터 적용 결과가 0건이면 필터 값을 쿼리에 합쳐서 재검색
+        if not results and filters:
+            filter_values = [f["value"] for f in filters if f.get("value")]
+            if filter_values:
+                enriched_query = " ".join(filter_values) + " " + query
+                logger.info(
+                    "[RAG] filter returned 0 results, retrying without filter: %s",
+                    enriched_query,
+                )
+                results = await self._search_qdrant(
+                    query=enriched_query,
+                    collections=[collection] if collection else None,
+                    filters=None,
+                    top_k=top_k,
+                    score_threshold=score_threshold,
+                    match_text=match_text,
+                    chunk_type=chunk_type,
+                    exclude_table_names=exclude_table_names,
+                )
+
+        return results
+
+    async def _search_qdrant(
+        self,
+        query: str,
+        collections: Optional[List[str]] = None,
+        filters: Optional[List[Dict[str, str]]] = None,
+        top_k: int = 10,
+        score_threshold: float = 0.5,
+        match_text: Optional[List[str]] = None,
+        chunk_type: Optional[str] = None,
+        exclude_table_names: Optional[List[str]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Qdrant 벡터 검색 내부 구현."""
+        from qdrant_client.models import FieldCondition, Filter, MatchText, MatchValue
+
+        # type=table 검색: 임베딩 대상 쿼리에 결정론적으로 라벨을 붙여 정확도 향상.
+        # (테이블명/테이블한글명으로 검색 시 그냥 {값}만 넣으면 dilution으로 정확도 저하)
+        # 한글이 있으면 테이블한글명, 아니면 테이블명. 이미 라벨(":")이 있으면 그대로.
+        _embed_query = query
+        if chunk_type == "table" and ":" not in query:
+            _value = strip_fqn_to_table_name(query)
+            _field = "테이블한글명" if re.search(r"[가-힣]", _value) else "테이블명"
+            _embed_query = f"{_field}:{_value}"
+        query_vec = await self._embedding.embed_query(_embed_query)
+        target_collections = collections or ALL_COLLECTIONS
+
+        # 일반 필터 + type 필터 결합
+        must_conditions: List[Any] = []
+        if filters:
+            must_conditions.extend(
+                FieldCondition(key=f["field"], match=MatchValue(value=f["value"]))
+                for f in filters
+                if f.get("field") and f.get("value")
+            )
+        if chunk_type in ("table", "columns"):
+            must_conditions.append(
+                FieldCondition(key="type", match=MatchValue(value=chunk_type))
+            )
+        # 이미 뽑은 테이블 제외(must_not) — "다른 후보 보여줘"용. 벡터검색은 offset
+        # 페이지네이션이 부적합해서, 이미 본 테이블명을 제외하고 재쿼리해 다음 후보를 얻음.
+        must_not_conditions: List[Any] = []
+        if exclude_table_names:
+            for name in exclude_table_names:
+                if not name or not str(name).strip():
+                    continue
+                for f in ("테이블명", "table_name"):
+                    must_not_conditions.append(
+                        FieldCondition(key=f, match=MatchValue(value=str(name)))
+                    )
+
+        if must_conditions or must_not_conditions:
+            query_filter = Filter(
+                must=must_conditions or None,
+                must_not=must_not_conditions or None,
+            )
+        else:
+            query_filter = None
+
+        results: List[Dict[str, Any]] = []
+        seen_groups: set = set()
+        _match_text_fallback: List[str] = []
+        _MATCH_TEXT_BOOST = 0.15  # match_text 매칭 결과에 score boost
+
+        for col in target_collections:
+            # 테이블 컬렉션은 _group_key로 그룹핑, 가이드 컬렉션은 일반 검색
+            _use_grouping = col not in GUIDE_COLLECTIONS
+            if _use_grouping:
+                self._ensure_keyword_index(col, "_group_key")
+
+            # match_text가 있으면: 1) 필터 검색 + 2) 일반 검색 → 병합
+            mt_filter = None
+            if match_text:
+                try:
+                    col_info = self._client.get_collection(col)
+                    text_fields = [
+                        fname
+                        for fname, schema in (col_info.payload_schema or {}).items()
+                        if "text" in str(getattr(schema, "params", "")).lower()
+                        or getattr(schema, "data_type", "") == "text"
+                    ]
+                    if not text_fields:
+                        text_fields = ["table_name", "korean_name"]
+                    expanded_terms: set = set()
+                    for term in match_text:
+                        if not term or not term.strip():
+                            continue
+                        expanded_terms.add(term.strip())
+                        for sub in term.strip().split("_"):
+                            if sub:
+                                expanded_terms.add(sub)
+                    mt_conditions = [
+                        FieldCondition(key=f, match=MatchText(text=term))
+                        for term in expanded_terms
+                        for f in text_fields
+                    ]
+                    if mt_conditions:
+                        # type 필터를 must로 결합 (chunk_type가 지정된 경우)
+                        if chunk_type in ("table", "columns"):
+                            mt_filter = Filter(
+                                must=[
+                                    FieldCondition(
+                                        key="type",
+                                        match=MatchValue(value=chunk_type),
+                                    )
+                                ],
+                                should=mt_conditions,
+                                must_not=must_not_conditions or None,
+                            )
+                        else:
+                            mt_filter = Filter(
+                                should=mt_conditions,
+                                must_not=must_not_conditions or None,
+                            )
+                except Exception as e:
+                    logger.warning("match_text filter build failed for %s: %s", col, e)
+
+            try:
+                if _use_grouping:
+                    # ── 테이블 컬렉션: query_points_groups ──
+                    if mt_filter:
+                        mt_groups = self._client.query_points_groups(
+                            collection_name=col,
+                            group_by="_group_key",
+                            query=query_vec,
+                            query_filter=mt_filter,
+                            limit=top_k,
+                            group_size=1,
+                            score_threshold=max(score_threshold - 0.2, 0.1),
+                            with_payload=True,
+                        )
+                        if not mt_groups.groups:
+                            mt_terms = ", ".join(match_text or [])
+                            _match_text_fallback.append(
+                                f"[{col}] match_text {mt_terms}에 해당하는 "
+                                f"테이블이 없어 일반 검색 결과입니다. "
+                                f"사용자가 요청한 테이블이 맞는지 확인하세요."
+                            )
+                        for group in mt_groups.groups:
+                            group_id = str(group.id)
+                            if group_id in seen_groups:
+                                continue
+                            seen_groups.add(group_id)
+                            if not group.hits:
+                                continue
+                            hit = group.hits[0]
+                            payload = dict(hit.payload) if hit.payload else {}
+                            payload.pop("_embed_text", None)
+                            payload.pop("_content_hash", None)
+                            self._annotate_chunk_truncation(payload)
+                            results.append(
+                                {
+                                    "collection": col,
+                                    "score": round(
+                                        min(hit.score + _MATCH_TEXT_BOOST, 1.0), 4
+                                    ),
+                                    "id": str(hit.id),
+                                    "payload": payload,
+                                }
+                            )
+
+                    normal_groups = self._client.query_points_groups(
+                        collection_name=col,
+                        group_by="_group_key",
+                        query=query_vec,
+                        query_filter=query_filter,
+                        limit=top_k,
+                        group_size=1,
+                        score_threshold=score_threshold,
+                        with_payload=True,
+                    )
+                    for group in normal_groups.groups:
+                        group_id = str(group.id)
+                        if group_id in seen_groups:
+                            continue
+                        seen_groups.add(group_id)
+                        if not group.hits:
+                            continue
+                        hit = group.hits[0]
+                        payload = dict(hit.payload) if hit.payload else {}
+                        payload.pop("_embed_text", None)
+                        payload.pop("_content_hash", None)
+                        self._annotate_chunk_truncation(payload)
+                        results.append(
+                            {
+                                "collection": col,
+                                "score": round(hit.score, 4),
+                                "id": str(hit.id),
+                                "payload": payload,
+                            }
+                        )
+                else:
+                    # ── 가이드 컬렉션: query_points (그룹핑 없음) ──
+                    seen_ids: set = set()
+                    if mt_filter:
+                        mt_hits = self._client.query_points(
+                            collection_name=col,
+                            query=query_vec,
+                            query_filter=mt_filter,
+                            limit=top_k,
+                            score_threshold=max(score_threshold - 0.2, 0.1),
+                            with_payload=True,
+                        )
+                        for hit in mt_hits.points:
+                            pid = str(hit.id)
+                            if pid in seen_ids:
+                                continue
+                            seen_ids.add(pid)
+                            payload = dict(hit.payload) if hit.payload else {}
+                            payload.pop("_embed_text", None)
+                            payload.pop("_content_hash", None)
+                            results.append(
+                                {
+                                    "collection": col,
+                                    "score": round(
+                                        min(hit.score + _MATCH_TEXT_BOOST, 1.0), 4
+                                    ),
+                                    "id": pid,
+                                    "payload": payload,
+                                }
+                            )
+
+                    normal_hits = self._client.query_points(
+                        collection_name=col,
+                        query=query_vec,
+                        query_filter=query_filter,
+                        limit=top_k,
+                        score_threshold=score_threshold,
+                        with_payload=True,
+                    )
+                    for hit in normal_hits.points:
+                        pid = str(hit.id)
+                        if pid in seen_ids:
+                            continue
+                        seen_ids.add(pid)
+                        payload = dict(hit.payload) if hit.payload else {}
+                        payload.pop("_embed_text", None)
+                        payload.pop("_content_hash", None)
+                        results.append(
+                            {
+                                "collection": col,
+                                "score": round(hit.score, 4),
+                                "id": pid,
+                                "payload": payload,
+                            }
+                        )
+            except Exception as e:
+                logger.warning("search failed for %s: %s", col, e)
+
+        # 테이블명 exact/partial match 리랭킹 (match_text 우선, query fallback)
+        _mt_tokens = set()
+        if match_text:
+            for mt in match_text:
+                if mt and mt.strip():
+                    _mt_tokens.add(mt.strip().lower())
+
+        _query_lower = query.lower()
+
+        for r in results:
+            payload = r.get("payload", {})
+            table_name = (
+                payload.get("table_name")
+                or payload.get("테이블명")
+                or payload.get("table_id")
+                or ""
+            ).lower()
+            if not table_name:
+                continue
+            # 1) match_text exact match (+0.5)
+            if _mt_tokens and table_name in _mt_tokens:
+                r["score"] += 0.5
+            # 2) match_text partial match (+0.1)
+            elif _mt_tokens and any(
+                table_name in t or t in table_name for t in _mt_tokens
+            ):
+                r["score"] += 0.1
+            # 3) query에 테이블명이 포함 (+0.2)
+            elif table_name in _query_lower:
+                r["score"] += 0.2
+
+        results.sort(key=lambda x: x["score"], reverse=True)
+        final = results[:top_k]
+
+        # match_text fallback 메시지가 있으면 결과에 첨부
+        if _match_text_fallback:
+            for r in final:
+                r.setdefault("_warnings", []).extend(_match_text_fallback)
+
+        return final
+
+    def _expand_guide_sections(
+        self, results: List[Dict[str, Any]], collections: List[str]
+    ) -> List[Dict[str, Any]]:
+        """가이드 검색 결과의 chunk를 같은 source+section 전체로 확장.
+
+        검색에서 section의 일부 chunk만 반환되면 LLM이 맥락 부족으로
+        학습 데이터로 보충(할루시네이션)하는 문제를 방지.
+        """
+        from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+        # 가이드 결과만 필터 (테이블 검색은 건너뜀)
+        guide_results = [
+            r for r in results if r.get("collection", "") in GUIDE_COLLECTIONS
+        ]
+        if not guide_results:
+            return results
+
+        # source+section 쌍 수집 (이미 있는 chunk ID 기록)
+        existing_ids: set = set()
+        section_keys: set = set()  # (collection, source, section)
+        for r in results:
+            existing_ids.add(r.get("id", ""))
+            p = r.get("payload", {})
+            col = r.get("collection", "")
+            if col in GUIDE_COLLECTIONS:
+                src = p.get("source", "")
+                sec = p.get("section", "")
+                if src and sec:
+                    section_keys.add((col, src, sec))
+
+        if not section_keys:
+            return results
+
+        # 각 source+section의 누락 chunk를 Qdrant에서 가져오기
+        expanded: List[Dict[str, Any]] = []
+        for col, src, sec in section_keys:
+            try:
+                scroll_filter = Filter(
+                    must=[
+                        FieldCondition(key="source", match=MatchValue(value=src)),
+                        FieldCondition(key="section", match=MatchValue(value=sec)),
+                    ]
+                )
+                pts, _ = self._client.scroll(
+                    collection_name=col,
+                    scroll_filter=scroll_filter,
+                    limit=10,
+                    with_payload=True,
+                    with_vectors=False,
+                )
+                for pt in pts:
+                    pid = str(pt.id)
+                    if pid in existing_ids:
+                        continue
+                    existing_ids.add(pid)
+                    payload = dict(pt.payload) if pt.payload else {}
+                    payload.pop("_embed_text", None)
+                    payload.pop("_content_hash", None)
+                    payload["_expanded"] = True  # 확장된 chunk 표시
+                    expanded.append(
+                        {
+                            "collection": col,
+                            "score": 0.0,  # 검색 매칭이 아닌 확장 chunk
+                            "id": pid,
+                            "payload": payload,
+                        }
+                    )
+            except Exception as e:
+                logger.warning(
+                    "section expand failed for %s/%s/%s: %s", col, src, sec, e
+                )
+
+        if expanded:
+            logger.info(
+                "[RAG] Section expand: %d additional chunks for %d sections",
+                len(expanded),
+                len(section_keys),
+            )
+
+        return results + expanded
+
+    # ------------------------------------------------------------------
+    # 적재 이력
+    # ------------------------------------------------------------------
+
+    def get_history(self) -> List[Dict[str, Any]]:
+        """이력 로그 조회."""
+        try:
+            with open(HISTORY_PATH, encoding="utf-8") as f:
+                return json.load(f)
+        except (FileNotFoundError, json.JSONDecodeError):
+            return []
+
+    def _record_history(
+        self,
+        collection: str,
+        action: str,
+        count: int,
+        errors: List[str],
+        elapsed_s: float = 0,
+    ) -> None:
+        """이력 기록."""
+        history = self.get_history()
+        history.append(
+            {
+                "timestamp": datetime.now().isoformat(),
+                "collection": collection,
+                "action": action,
+                "count": count,
+                "errors": errors[:10],
+                "elapsed_s": elapsed_s,
+            }
+        )
+        # 최근 200건만 유지
+        history = history[-200:]
+        os.makedirs(os.path.dirname(HISTORY_PATH), exist_ok=True)
+        with open(HISTORY_PATH, "w", encoding="utf-8") as f:
+            json.dump(history, f, ensure_ascii=False, indent=2)
+
+    # ------------------------------------------------------------------
+    # 내부 유틸리티
+    # ------------------------------------------------------------------
+
+    def _ensure_text_indexes(self, collection_name: str, fields: List[str]) -> None:
+        """payload 필드에 text index가 없으면 생성. MatchText 검색용."""
+        from qdrant_client.models import TextIndexParams, TokenizerType
+
+        try:
+            info = self._client.get_collection(collection_name)
+            existing = set(info.payload_schema.keys()) if info.payload_schema else set()
+        except Exception:
+            existing = set()
+
+        for field in fields:
+            if field in existing:
+                continue
+            try:
+                self._client.create_payload_index(
+                    collection_name=collection_name,
+                    field_name=field,
+                    field_schema=TextIndexParams(
+                        type="text",
+                        tokenizer=TokenizerType.WORD,
+                        min_token_len=1,
+                        max_token_len=60,
+                        lowercase=True,
+                    ),
+                )
+                logger.info("[RAG] Created text index: %s.%s", collection_name, field)
+            except Exception as e:
+                logger.warning(
+                    "[RAG] Failed to create text index %s.%s: %s",
+                    collection_name,
+                    field,
+                    e,
+                )
+
+    # 이미 keyword index가 생성된 (collection, field) 추적
+    _keyword_index_cache: set = set()
+
+    def _ensure_keyword_index(self, collection_name: str, field: str) -> None:
+        """payload 필드에 keyword index가 없으면 생성. query_points_groups 필수."""
+        cache_key = (collection_name, field)
+        if cache_key in self._keyword_index_cache:
+            return
+        from qdrant_client.models import PayloadSchemaType
+
+        try:
+            info = self._client.get_collection(collection_name)
+            existing = info.payload_schema or {}
+            if field in existing:
+                self._keyword_index_cache.add(cache_key)
+                return
+        except Exception:
+            pass
+
+        try:
+            self._client.create_payload_index(
+                collection_name=collection_name,
+                field_name=field,
+                field_schema=PayloadSchemaType.KEYWORD,
+            )
+            logger.info("[RAG] Created keyword index: %s.%s", collection_name, field)
+        except Exception as e:
+            logger.warning(
+                "[RAG] Failed to create keyword index %s.%s: %s",
+                collection_name,
+                field,
+                e,
+            )
+        self._keyword_index_cache.add(cache_key)
+
+    @staticmethod
+    def _annotate_chunk_truncation(payload: Dict[str, Any]) -> None:
+        """청크 분할된 결과에 컬럼 축약 안내를 추가."""
+        chunk_info = payload.get("_chunk")
+        if not chunk_info:
+            return
+        # _chunk 형식: "1/3" — 총 청크 수가 1보다 크면 축약된 것
+        parts = str(chunk_info).split("/")
+        if len(parts) == 2:
+            try:
+                total_chunks = int(parts[1])
+            except ValueError:
+                total_chunks = 1
+            if total_chunks > 1:
+                payload["_column_truncated"] = (
+                    f"이 테이블은 컬럼이 많아 {total_chunks}개 청크 중 "
+                    f"일부만 표시됩니다. 전체 컬럼이 필요하면 "
+                    f"get_table_columns 도구를 사용하세요."
+                )
+
+    @staticmethod
+    def _build_table_meta_embed_text(
+        first_row: Dict[str, str],
+        group_rows: List[Dict[str, str]],
+        table_fields: List[str],
+        embedding_fields: List[str],
+        header_fields: Optional[List[str]] = None,
+    ) -> str:
+        """type=table 청크용 임베딩 텍스트. 강조 필드(테이블명/한글명) 중심.
+
+        컬럼 이름은 의도적으로 제외 — 테이블명 검색 시 컬럼 토큰에 의한
+        희석(dilution)을 막기 위함. payload의 columns에는 전체 컬럼이
+        들어가므로 결과 셋은 영향 없음.
+
+        header_fields: 강조 자리(헤더+라벨)에 박을 필드 이름 최대 2개.
+            None이면 table_fields[:2] fallback. 매핑의 tableFields 순서와
+            독립적으로 강조 필드를 지정할 수 있음.
+
+        예시 출력 (header_fields=["테이블명","테이블한글명"]):
+            ## dtcn0003 (거래내역)
+            테이블명: dtcn0003
+            테이블한글명: 거래내역
+            - table_id: BDP0031
+            - description: 거래내역 데이터를 daily 주기로 적재하는 BDP Iceberg 테이블
+            - domain: card
+            ...
+        """
+        lines: List[str] = []
+        hf = header_fields if header_fields else table_fields[:2]
+
+        # 제목 + 강조 라벨 (header_fields 사용)
+        title_parts: List[str] = []
+        primary = first_row.get(hf[0], "") if len(hf) > 0 else ""
+        secondary = first_row.get(hf[1], "") if len(hf) > 1 else ""
+        if primary:
+            title_parts.append(primary)
+        if secondary:
+            title_parts.append(f"({secondary})")
+        if title_parts:
+            lines.append(f"## {' '.join(title_parts)}")
+        if primary:
+            lines.append(f"테이블명: {primary}")
+        if secondary:
+            lines.append(f"테이블한글명: {secondary}")
+
+        # 나머지 테이블 메타 (header_fields에 들어간 필드는 제외 — 중복 방지)
+        for tf in table_fields:
+            if tf in hf:
+                continue
+            val = first_row.get(tf, "")
+            if val:
+                lines.append(f"- {tf}: {val}")
+
+        # embeddingFields 중 table fields에 없는 추가 필드
+        extra_fields = [f for f in embedding_fields if f not in table_fields]
+        if extra_fields:
+            extra_vals: set = set()
+            for r in group_rows:
+                for f in extra_fields:
+                    v = r.get(f, "")
+                    if v:
+                        extra_vals.add(str(v))
+            if extra_vals:
+                lines.append("")
+                lines.append(" ".join(extra_vals))
+
+        if group_rows:
+            lines.append(f"- 컬럼 수: {len(group_rows)}")
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def _build_columns_embed_text(
+        first_row: Dict[str, str],
+        group_rows: List[Dict[str, str]],
+        table_fields: List[str],
+        column_fields: List[str],
+        header_fields: Optional[List[str]] = None,
+    ) -> str:
+        """type=columns 청크용 임베딩 텍스트. 컬럼 이름/한글명/설명 위주.
+
+        헤더에 테이블명을 짧게만 포함 — 컬럼 검색 시 컬럼 토큰 비중이
+        지배적이 되도록.
+
+        header_fields: 헤더 식별자에 박을 필드 이름 최대 2개.
+            None이면 table_fields[:2] fallback.
+
+        예시 출력:
+            ## 컬럼 — dtcn0003 (거래내역)
+            - col_name: TRAN_DT, col_korean_name: 거래일자, col_type: VARCHAR, pk: Y
+            - col_name: TRAN_AMT, col_korean_name: 거래금액, col_type: NUMBER, pk: N
+        """
+        lines: List[str] = []
+        hf = header_fields if header_fields else table_fields[:2]
+
+        # 헤더: 강조 X, 식별용으로만 짧게
+        title_parts: List[str] = []
+        primary = first_row.get(hf[0], "") if len(hf) > 0 else ""
+        secondary = first_row.get(hf[1], "") if len(hf) > 1 else ""
+        if primary:
+            title_parts.append(primary)
+        if secondary:
+            title_parts.append(f"({secondary})")
+        if title_parts:
+            lines.append(f"## 컬럼 — {' '.join(title_parts)}")
+
+        # 컬럼 본문
+        if column_fields and group_rows:
+            for r in group_rows:
+                parts: List[str] = []
+                for cf in column_fields:
+                    v = r.get(cf, "")
+                    if v:
+                        parts.append(f"{cf}: {v}")
+                if parts:
+                    lines.append(f"- {', '.join(parts)}")
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def _build_table_embed_text(
+        first_row: Dict[str, str],
+        group_rows: List[Dict[str, str]],
+        table_fields: List[str],
+        column_fields: List[str],
+        embedding_fields: List[str],
+        header_fields: Optional[List[str]] = None,
+    ) -> str:
+        """레거시 호환용 — meta+columns 합쳐서 한 번에 반환.
+
+        preview/dry-run 등 청크 분리가 필요 없는 경로에서 사용.
+        실제 인덱싱 경로에서는 _build_table_meta_embed_text와
+        _build_columns_embed_text를 각각 호출.
+        """
+        meta = RAGCollectionManager._build_table_meta_embed_text(
+            first_row, group_rows, table_fields, embedding_fields, header_fields
+        )
+        cols = RAGCollectionManager._build_columns_embed_text(
+            first_row, group_rows, table_fields, column_fields, header_fields
+        )
+        return f"{meta}\n\n{cols}" if cols else meta
+
+    @staticmethod
+    def _read_csv(file_path: str, limit: int = 0) -> List[Dict[str, str]]:
+        """CSV 또는 Parquet 파일 → dict 리스트. 확장자 또는 magic bytes로 자동 판별."""
+        ext = Path(file_path).suffix.lower()
+        if ext in (".parquet", ".pq"):
+            return RAGCollectionManager._read_parquet(file_path, limit)
+        # 확장자 없거나 불명확 → magic bytes로 parquet 감지
+        if not ext or ext not in (".csv", ".tsv", ".txt"):
+            try:
+                with open(file_path, "rb") as f:
+                    magic = f.read(4)
+                if magic == b"PAR1":
+                    return RAGCollectionManager._read_parquet(file_path, limit)
+            except Exception:
+                pass
+        rows = []
+        with open(file_path, encoding="utf-8-sig") as f:
+            reader = csv.DictReader(f)
+            for i, row in enumerate(reader):
+                rows.append(dict(row))
+                if limit and i + 1 >= limit:
+                    break
+        return rows
+
+    @staticmethod
+    def _read_parquet(file_path: str, limit: int = 0) -> List[Dict[str, str]]:
+        """Parquet 파일 → dict 리스트. 모든 값을 str로 변환."""
+        import pandas as pd
+
+        df = pd.read_parquet(file_path)
+        if limit:
+            df = df.head(limit)
+        # NaN → 빈 문자열, 모든 값 str 변환
+        df = df.fillna("").astype(str)
+        return df.to_dict(orient="records")
+
+    @staticmethod
+    def _group_rows(
+        rows: List[Dict[str, str]], group_by: Any
+    ) -> Dict[str, List[Dict[str, str]]]:
+        """groupBy 키(단일 str 또는 list)로 행 그룹핑."""
+        if isinstance(group_by, str):
+            group_by = [group_by]
+        groups: Dict[str, List[Dict[str, str]]] = {}
+        for row in rows:
+            parts = [row.get(k, "") for k in group_by]
+            if not all(parts):
+                continue
+            key = "||".join(parts)
+            groups.setdefault(key, []).append(row)
+        return groups
+
+    # join 결과 row에 원본 main row를 보존하는 hidden 키
+    _MAIN_ROW_KEY = "__main_row__"
+
+    @staticmethod
+    def _join_csvs(
+        main_rows: List[Dict[str, str]],
+        join_rows: List[Dict[str, str]],
+        join_key: str,
+    ) -> List[Dict[str, str]]:
+        """두 CSV를 조인 키로 병합 (main에 join 정보 추가).
+
+        주의: `{**r, **jr}`에서 column row(jr)가 main row(r)의 동일 필드를
+        덮어쓴다 (예: description, korean_name). column-level 데이터를
+        우선시하는 의도된 동작이지만, table-level 메타에 접근하려면
+        원본 main row가 필요하므로 `__main_row__` 키로 보존한다.
+
+        이후 인덱싱 단계에서 `row.get(_MAIN_ROW_KEY) or row` 로 table-level
+        필드에 접근하고, column-level 필드는 row를 그대로 사용한다.
+        """
+        join_index: Dict[str, List[Dict[str, str]]] = {}
+        for r in join_rows:
+            k = r.get(join_key, "")
+            if k:
+                join_index.setdefault(k, []).append(r)
+
+        merged = []
+        for r in main_rows:
+            k = r.get(join_key, "")
+            matching = join_index.get(k, [])
+            if matching:
+                for jr in matching:
+                    combined = {**r, **jr}
+                    combined[RAGCollectionManager._MAIN_ROW_KEY] = r
+                    merged.append(combined)
+            else:
+                copy = dict(r)
+                copy[RAGCollectionManager._MAIN_ROW_KEY] = r
+                merged.append(copy)
+        return merged
+
+    @staticmethod
+    def _extract_confluence_url(content: str) -> str:
+        """첫 줄의 [source: URL] 패턴에서 URL 추출."""
+        first_line = content.split("\n", 1)[0].strip()
+        m = re.match(r"^\[source:\s*(.+?)\]", first_line, re.IGNORECASE)
+        return m.group(1).strip() if m else ""
+
+    @staticmethod
+    def _extract_title(content: str, fallback: str) -> str:
+        """마크다운 첫 # 제목 추출."""
+        for line in content.split("\n"):
+            m = re.match(r"^#\s+(.+)$", line.strip())
+            if m:
+                return m.group(1).strip()
+        return Path(fallback).stem
+
+    @staticmethod
+    def _file_hash(fp: Path) -> str:
+        """SHA256 해시 (앞 16자)."""
+        return hashlib.sha256(fp.read_bytes()).hexdigest()[:16]
+
+    async def _embed_chunked(
+        self, text: str, chunk_chars: int = 2000
+    ) -> Optional[List[float]]:
+        """긴 텍스트를 청크로 나눠 임베딩 후 평균 벡터 반환."""
+        chunks = [text[i : i + chunk_chars] for i in range(0, len(text), chunk_chars)]
+        try:
+            vecs = await self._embedding.embed_texts(chunks)
+            if not vecs:
+                return None
+            # 평균 벡터
+            dim = len(vecs[0])
+            avg = [0.0] * dim
+            for v in vecs:
+                for j in range(dim):
+                    avg[j] += v[j]
+            n = len(vecs)
+            return [x / n for x in avg]
+        except Exception as e:
+            logger.warning("Chunked embed also failed: %s", e)
+            return None
+
+    async def _batch_upsert(
+        self,
+        collection: str,
+        texts: List[str],
+        payloads: List[Dict[str, Any]],
+        point_ids: Optional[List[str]] = None,
+        batch_size: int = 1,
+        concurrency: int = 64,
+    ) -> int:
+        """배치 임베딩(병렬) + Qdrant upsert."""
+        from qdrant_client.models import PointStruct
+
+        total_items = len(texts)
+        self._progress = {
+            "status": "running",
+            "total": total_items,
+            "done": 0,
+            "collection": collection,
+        }
+
+        # 배치 분할
+        batches = []
+        for i in range(0, total_items, batch_size):
+            batch_ids = point_ids[i : i + batch_size] if point_ids else None
+            batches.append(
+                (texts[i : i + batch_size], payloads[i : i + batch_size], batch_ids)
+            )
+
+        total = 0
+        errors = 0
+
+        # concurrency개씩 병렬 임베딩 → 순차 upsert
+        self._upsert_cancelled = False
+        for group_start in range(0, len(batches), concurrency):
+            if self._upsert_cancelled:
+                self._progress = {
+                    "status": "cancelled",
+                    "done": total,
+                    "total": total_items,
+                }
+                logger.info("Upsert cancelled at %d/%d", total, total_items)
+                break
+
+            group = batches[group_start : group_start + concurrency]
+
+            # 병렬 임베딩
+            embed_tasks = [self._embedding.embed_texts(bt) for bt, _, _ in group]
+            embed_results = await asyncio.gather(*embed_tasks, return_exceptions=True)
+
+            # 순차 upsert (Qdrant 로컬은 동기)
+            for (batch_texts, batch_payloads, batch_ids), embeddings in zip(
+                group, embed_results
+            ):
+                if isinstance(embeddings, Exception):
+                    # 임베딩 에러 → 청크 분할 / 테이블 정보만으로 재시도
+                    logger.warning(
+                        "Embed failed (will retry): %s | text_len=%d",
+                        str(embeddings)[:200],
+                        len(batch_texts[0]) if batch_texts else 0,
+                    )
+                    if batch_texts:
+                        retry_ok = True
+                        retry_embeddings = []
+                        for text in batch_texts:
+                            # 1차: 청크 분할 후 평균 벡터
+                            chunked = await self._embed_chunked(text)
+                            if chunked is not None:
+                                retry_embeddings.append(chunked)
+                                continue
+                            # 2차: 컬럼 제외, 테이블 정보만으로 재시도
+                            table_only = text.split("### 컬럼")[0].strip()
+                            try:
+                                vecs = await self._embedding.embed_texts([table_only])
+                                retry_embeddings.append(vecs[0])
+                                logger.info(
+                                    "Table-only embed OK: %d→%d chars",
+                                    len(text),
+                                    len(table_only),
+                                )
+                            except Exception:
+                                retry_ok = False
+                                break
+                        if retry_ok:
+                            embeddings = retry_embeddings
+                            logger.info(
+                                "Embed retry OK: text_len=%d",
+                                len(batch_texts[0]),
+                            )
+                        else:
+                            embeddings = None  # 아래 에러 처리로
+
+                    if embeddings is None or isinstance(embeddings, Exception):
+                        errors += 1
+                        for pl in batch_payloads:
+                            table_info = {
+                                k: v
+                                for k, v in pl.items()
+                                if k not in ("columns", "_embed_text", "_collection")
+                            }
+                            logger.warning(
+                                "Embed error: %s | table=%s | text_len=%d",
+                                embeddings,
+                                table_info,
+                                len(batch_texts[0]) if batch_texts else 0,
+                            )
+                        self._progress["done"] += len(batch_texts)
+                        continue
+                try:
+                    points = [
+                        PointStruct(
+                            id=pid if pid else str(uuid.uuid4()),
+                            vector=emb,
+                            payload=pl,
+                        )
+                        for pl, emb, pid in zip(
+                            batch_payloads,
+                            embeddings,
+                            batch_ids if batch_ids else [None] * len(batch_payloads),
+                        )
+                    ]
+                    self._client.upsert(collection_name=collection, points=points)
+                    total += len(points)
+                except Exception as e:
+                    errors += 1
+                    logger.warning("Batch upsert error: %s", e)
+                self._progress["done"] = total + (errors * batch_size)
+
+        self._progress = {"status": "done"}
+        return total
+
+    def _scroll_by_source(self, collection: str, source: str, limit: int = 100) -> list:
+        """source 필드로 포인트 검색."""
+        from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+        points, _ = self._client.scroll(
+            collection_name=collection,
+            scroll_filter=Filter(
+                must=[FieldCondition(key="source", match=MatchValue(value=source))]
+            ),
+            limit=limit,
+            with_payload=True,
+            with_vectors=False,
+        )
+        return points
+
+    def _delete_by_source(self, collection: str, source: str) -> int:
+        """source 기준 포인트 삭제."""
+
+        points = self._scroll_by_source(collection, source)
+        if not points:
+            return 0
+        from qdrant_client.models import PointIdsList
+
+        ids = [pt.id for pt in points]
+        self._client.delete(
+            collection_name=collection,
+            points_selector=PointIdsList(points=ids),
+        )
+        return len(ids)