DeepAgent Filesystem 기반 세만틱 레이어 (Filesystem-as-Semantic-Layer)
전통적인 데이터베이스 중심의 메타데이터 관리 대신, 에이전트가 직접 탐색하고 읽을 수 있는 구조화된 파일 시스템을 세만틱 레이어로 활용하는 방안입니다. 이는 에이전트의 컨텍스트 윈도우 활용을 최적화하고 지식 관리의 유연성을 극대화합니다.
📂 디렉토리 구조 및 역할
DeepAgent가 접근 가능한 전용 디렉토리(semantic_layer/)를 정의하고, 각 지식의 유형별로 파티셔닝합니다.
semantic_layer/
├── domains/ # 도메인별 비즈니스 컨텍스트 (예: sales, finance)
│ └── sales.yaml # 판매 도메인 용어 정의 및 주요 KPI 설명
├── entities/ # 물리적 테이블과 매핑되는 논리적 엔티티
│ ├── orders.json # 주문 테이블의 컬럼 설명, 타입, 제약조건
│ └── customers.json
├── metrics/ # 계산 로직 (SQL Snippets)
│ ├── revenue.sql # "매출" 계산 공식 (SUM(price * quantity))
│ └── churn_rate.sql # "이탈률" 계산 로직
├── relationships/ # 엔티티 간의 관계 (Graph Info)
│ └── er_diagram.yaml # PK-FK 관계 및 Join 경로 가이드
└── rules/ # SQL 작성 가이드라인
└── formatting.md # SQL 스타일, Alias 규칙, 방언(Dialect) 특이사항🛠 주요 구현 구성 요소
1. 엔티티 정의 (Schema-as-Code)
에이전트가 read_file을 통해 즉시 이해할 수 있도록 JSON/YAML 포맷으로 작성합니다.
{
"entity": "orders",
"physical_name": "FACT_SALES_ORDERS",
"description": "고객의 최종 주문 정보가 저장되는 팩트 테이블",
"columns": [
{
"name": "order_id",
"description": "주문 고유 식별자 (PK)",
"is_key": true
},
{
"name": "total_amt",
"description": "할인이 적용된 최종 결제 금액",
"calculation_hint": "price * qty - discount"
}
]
}2. 메트릭 캡슐화 (SQL Snippets)
복잡한 비즈니스 로직을 SQL 조각으로 파일화하여 에이전트가 이를 참조하여 조합하게 합니다.
- 파일명:
metrics/monthly_active_users.sql - 내용:
COUNT(DISTINCT user_id) FILTER (WHERE last_login >= current_date - interval '30 days')
3. 지능형 스키마 프루닝 (Filesystem-as-Metadata-RAG)
수천 개의 파일 중 질문에 필요한 파일만 선택하는 프로세스로, Metadata RAG 기술의 핵심입니다.
- Keyword/Semantic Search: 질문(예: “지난달 매출 얼마야?”)과 관련성이 높은
metrics/revenue.sql,entities/orders.json식별. - Deterministic Pruning: 식별된 테이블의 ERD 정보를 참조하여 Join 경로상에 있는 필수 파일(
entities/customers.json등)을 규칙 기반으로 자동 포함. - Context Assembly: 선택된 파일의 내용만 에이전트의 프롬프트에 동적으로 삽입하여 컨텍스트 최적화.
🔄 에이전트 워크플로우
- 지식 탐색 (Explore): 사용자의 질문을 분석하고
semantic_layer/내의 관련 디렉토리를 탐색(ls)하고 필요한 파일을 읽음(read). - 논리적 조립 (Compose): 읽어온 메트릭 정의와 엔티티 정보를 결합하여 논리적 쿼리 계획 수립.
- 물리적 변환 (Generate):
rules/의 가이드라인에 맞춰 타겟 DB(PostgreSQL, BigQuery 등)에 최적화된 SQL 생성. - 검증 및 피드백 (Validate): 생성된 SQL이 세만틱 레이어의 정의와 일치하는지 재검토.
🌟 기대 효과
- 추적 가능성 (Traceability): 모든 세만틱 정의가 파일로 관리되므로 Git을 통한 버전 관리 및 변경 이력 추적이 용이함.
- 에이전트 친화성: 데이터베이스 카탈로그 조회보다 텍스트 기반 파일 읽기가 에이전트의 추론 속도와 정확도 면에서 유리함.
- 확장성: 새로운 도메인이나 메트릭 추가 시 DB 스키마 변경 없이 파일 추가만으로 대응 가능.