26Y27a4

QK·2026년 7월 26일

Confluence 문서에 메타데이터가 부족한 상태에서 AIOps RAG 검색 엔진(OpenSearch + Qdrant)을 구축하면, 잘못된 버전의 SOP를 참조하거나 특정 솔루션/환경에 맞지 않는 조치 가이드를 생성하는 심각한 환각(Hallucination) 문제가 발생합니다.

따라서 메타데이터 표준을 정의하고, 기존에 이미 작성된 대량의 문서들에 이를 효율적으로 자동/반자동 반영하는 전략을 제안해 드립니다.

1. AIOps & RAG를 위해 반드시 필요한 핵심 메타데이터 구성안

AIOps 시스템이 정확하게 문서를 필터링(Metadata Filtering)하고 LLM이 문맥을 올바르게 이해하도록 문서 상단(YAML Front-Matter)에 넣어야 할 필수 메타데이터 구조입니다.

메타데이터 필드	설명 및 예시	AIOps / RAG에서의 역할 및 필요성
`doc_type`	`sop`, `incident_report`, `architecture`, `work_plan`, `weekly_report`	LLM 프롬프트 요청에 맞춰 적절한 문서 유형만 필터링 (예: 장애 시 `sop`만 조회)
`target_solutions`	`[k8s, cilium, minio-aistor, keycloak, vault, kyverno]`	질문에 포함된 솔루션 관련 문서만 정확히 타겟팅
`environment`	`prd`, `stg`, `dev`, `shared`	운영(PRD) 환경 전용 스크립트와 개발 환경용 스크립트의 혼선 방지
`status`	`active`, `deprecated`, `draft`	오래되거나 폐기된 SOP/작업계획서를 RAG 검색 대상에서 자동 제외
`tags` / `keywords`	`[bgp, oom, bgppeeringpolicy, secret-rotation]`	OpenSearch 키워드 검색(BM25) 정밀도 대폭 향상
`last_verified_date`	`2026-05-10`	문서의 신뢰성 검증 (오랫동안 업데이트되지 않은 문서 가중치 감소)
`owner` / `author`	`platform-infra-team`, `sre-admin`	조치 가이드 생성 시 담당자 및 담당 팀 명시

최종 반영할 YAML Front-Matter 스키마 예시

---
id: "CONF-10429"
title: "Cilium BGP Control Plane Peering 장애 조치 SOP"
doc_type: "sop"
target_solutions:
  - "cilium"
  - "k8s"
environment: "prd"
status: "active"
tags:
  - "bgp"
  - "network"
  - "peering"
owner: "devops-team"
last_modified: "2026-05-14T10:30:00Z"
last_verified_date: "2026-05-01"
---

2. 기존 문서(Legacy Docs)에 메타데이터를 일괄 반영하는 3단계 전략

이미 Confluence에 존재하는 수백~수천 개의 기존 문서에 사람이 일일이 메타데이터를 추가하는 것은 불가능합니다. 사내 Local LLM을 활용한 자동 추출 파이프라인으로 기존 문서를 한 번 정리(Batch Migration)하는 방식을 추천합니다.

[ 기존 Confluence 문서 ]
          │
          ▼
[ 1단계: Local LLM 기반 Metadata Auto-Extraction ]
 (LLM이 문서 본문을 읽고 doc_type, target_solutions, tags 등을 자동 추론)
          │
          ▼
[ 2단계: Git 저장 시점에 YAML Front-Matter 자동 주입 ]
 (Confluence 원본을 건드리지 않고, Git 변환 단계에서 메타데이터를 결합)
          │
          ▼
[ 3단계: RAG DB (OpenSearch/Qdrant) 인덱싱 & 메타데이터 필터링 ]

1단계: Local LLM을 활용한 메타데이터 자동 추출 코드 (Python)

수집된 HTML/Text 본문을 사내 LLM(vLLM)에 입력하여 메타데이터 JSON을 구조화된 형태(JSON Mode / Function Calling)로 추출합니다.

import requests
import json

LOCAL_LLM_URL = "http://vllm.internal:8000/v1/chat/completions"

METADATA_EXTRACTION_PROMPT = """
너는 Cloud-Native Platform 인프라 문서의 메타데이터를 추출하는 AI 전담 분류기다.
아래 전달되는 Confluence 문서 본문을 읽고, 규격에 맞는 메타데이터 JSON만 반환해라.

[분류 규칙]
1. doc_type: [sop, incident_report, architecture, work_plan, weekly_report, general] 중 하나 선택
2. target_solutions: 본문에 등장하거나 관련된 솔루션 목록 (예: k8s, cilium, minio, keycloak, nexus, harbor, jenkins, argocd, openebs, vault, kyverno, keda)
3. environment: [prd, stg, dev, all] 중 선택
4. tags: 문서의 핵심 키워드 3~5개 추출 (영문 소문자)
5. status: [active, deprecated] 중 선택 (오래되었거나 사용하지 않는다는 언급이 있으면 deprecated)

[문서 본문]
{document_text}

JSON Format:
"""

def extract_metadata_via_llm(doc_title: str, doc_text: str) -> dict:
    prompt = METADATA_EXTRACTION_PROMPT.format(document_text=doc_text[:3000]) # 상위 3000자 분석
    
    payload = {
        "model": "Qwen2.5-Coder-32B",
        "messages": [{"role": "user", "content": prompt}],
        "temperature": 0.1,
        "response_format": {"type": "json_object"}  # JSON 구조 보장
    }
    
    try:
        response = requests.post(LOCAL_LLM_URL, json=payload, timeout=30)
        extracted_meta = json.loads(response.json()["choices"][0]["message"]["content"])
        return extracted_meta
    except Exception as e:
        # LLM 추출 실패 시 기본 Fallback 메타데이터 제공
        return {
            "doc_type": "general",
            "target_solutions": [],
            "environment": "all",
            "tags": [],
            "status": "active"
        }

2단계: 기존 Confluence 원본 수정 vs Git 변환 시 주입 비교

기존 Confluence 문서에 메타데이터를 반영하는 방식은 2가지가 있습니다. "방식 B(Git Pipeline 주입)"를 강력히 권장합니다.

방식 A (Confluence 원본 수정): REST API로 Confluence 페이지 상단에 Label이나 메타데이터 표를 직접 추가.
단점: 원본 문서 이력이 더럽혀지고, 작성자들의 반발 및 Confluence 검색 UX 오염 가능성.

방식 B (Git Markdown 파이프라인에서 주입 - [권장]): Confluence 원본은 그대로 두고, Python Sync Pipeline(2~3단계) 실행 시 LLM이 추론한 메타데이터를 YAML Front-Matter로 조합하여 Git 저장소(.md)에만 반영.
장점: Confluence 원본을 건드리지 않고, Git 저장소 및 검색 엔진(OpenSearch/Qdrant)의 메타데이터 품질을 100% 확보 가능.

3. 신규 작성 문서에 대한 가이드라인 (Confluence 템플릿)

향후 작성될 신규 문서들의 메타데이터 품질을 유지하기 위해 Confluence 전용 Page Template을 구성합니다.

Confluence 템플릿에 "문서 속성(Page Properties) 매크로" 적용

Confluence 상단에 기본 표준 표를 배치하여 엔지니어가 문서 작성 시 선택하도록 유도합니다.

+-------------------------------------------------------+
| [문서 속성]                                            |
| - 문서 유형 (doc_type) : [ SOP / 작업계획서 / 장애보고서 ] |
| - 대상 솔루션          : [ Cilium, K8s, Vault ]         |
| - 적용 환경            : [ PRD / STG ]                |
+-------------------------------------------------------+

Confluence Label 적극 활용

엔지니어들에게 Confluence 우측 하단 Labels 기능에 cilium, sop, prd 등의 태그를 달도록 문화적으로 가이드합니다. (Python Sync API 조회 시 metadata.labels 필드로 즉시 수집 가능)

4. 인덱싱 및 Hybrid Search 시 메타데이터 활용법

이렇게 만들어진 메타데이터는 Qdrant 및 OpenSearch 검색 시 다음과 같이 강력한 Pre-filtering 조건으로 사용됩니다.

# Qdrant 예시: 장애 발생 시 "PRD 환경"의 "Cilium 관련" "Active 상태의 SOP"만 필터링하여 검색
qdrant_cli.search(
    collection_name="ops-knowledge-dense",
    query_vector=query_embedding,
    query_filter=models.Filter(
        must=[
            models.FieldCondition(key="doc_type", match=models.MatchValue(value="sop")),
            models.FieldCondition(key="target_solutions", match=models.MatchValue(value="cilium")),
            models.FieldCondition(key="status", match=models.MatchValue(value="active"))
        ]
    ),
    limit=5
)

요약 결론

기존 문서는 Local LLM을 통해 메타데이터를 자동 추출하여 Git 및 DB 인덱싱 단계에서 YAML Front-Matter로 자동 통합합니다.
메타데이터에는 doc_type, target_solutions, status(active/deprecated)가 가장 핵심이며, 이를 통해 폐기된 문서나 잘못된 솔루션 문서를 검색 단계에서 사전 차단(Pre-filtering)합니다.

engineer

이전 포스트

26Y27a3

다음 포스트