본문으로 건너뛰기

2026-04-22 초안

ADR 0014 — AI 어댑터 레이어 (DRAFT)

상태: Draft — S2 (7~10M) 착수 전 Chair 검토 필요 날짜: 2026-04-22 작성: 자율 세션 (이어지는 회의에서 R1 수집 → R3 결정으로 발행)

배경​

ADR 0004 로드맵 에서 소버린 AI 전환 을 Phase 2 후반 (24~28M) 목표로 설정. 전환 시점에 AI 호출부를 vendor-lock 없이 스위칭하려면 현재 Firebase AI Logic (Gemini 클라이언트 + Vertex AI Search 서버) 직접 호출을 어댑터 인터페이스 뒤로 숨기는 리팩터가 필요.

ADR 0011 S2 (7~10M) 에 "어댑터 레이어 착수" 가 명시되어 있음.

현재 상태 (2026-04-22 기준)​

직접 호출 지점​

  • apps/web/lib/ai/client.ts — Gemini 클라이언트 (generate* 함수들)
  • apps/web/lib/vertex-search/server.ts — Vertex AI Search 서버 (searchDocuments / findSimilar / indexDocument)
  • apps/web/app/(workspace)/**/_actions/*.ts — 위 2개를 직접 import

호출 소비처 (적용 현황 매트릭스)​

기능주 AI보조 AIweight액션 파일
대시보드 브리핑Gemini—0(workspace)/dashboard/_actions/daily-briefing-actions.ts
문서 생성 (HTML)Gemini—1(workspace)/docs/_actions/doc-generate-actions.ts
문서 생성 (docx)——1(workspace)/docs/_actions/generate-docx-action.ts (AI 0, 템플릿 렌더만)
유사 판례·기억 분석GeminiVertex Search1(workspace)/legacy/_actions/legacy-search-actions.ts
전략 보고서Gemini (구조화 JSON)Vertex Search (RAG)3(workspace)/cases/[caseId]/_actions/strategy-report-actions.ts
RelatedMemoriesPanel—Vertex Search0(workspace)/legacy/_actions/related-memories-for-docgen-actions.ts
증거 요약Gemini—1(workspace)/cases/[caseId]/_actions/evidence-summary-actions.ts

대안​

A. Thin wrapper (AiProvider 인터페이스)​

  • packages/core-ai/ 신설 → AiProvider interface 정의 (generateText, generateJson, search, index)
  • 현 Gemini/Vertex 구현을 GeminiVertexProvider 로 감쌈
  • Server Action 은 getAiProvider() 로 의존성 주입
  • 장점: 작은 범위, 소비처 수정 최소
  • 단점: 모델별 특수 기능 (structured output, grounding, safety settings) 이 interface 최저공통분모로 강제됨

B. Feature-level 추상화 (BriefingService, DocGenService, StrategyService 등)​

  • 기능별 전용 서비스 클래스, 내부에 어댑터 포함
  • Server Action 은 service 호출만
  • 장점: 기능 단위 스왑 가능 (브리핑만 타 AI 실험 등)
  • 단점: 서비스 층 보일러플레이트, S2 10주 타임라인에 부담

C. 하이브리드 (권장)​

  • A 의 인터페이스 + B 의 기능 서비스 를 계층화
  • AiProvider (저수준) ← *Service (도메인) ← Server Action
  • AiProvider 는 Firebase AI Logic·Gemini Direct·HyperCLOVA X·Solar 4종 구현 슬롯
  • *Service 는 weight / 폴백 / 텔레메트리 / 엔진버전 관리
  • S2 착수 범위: AiProvider 인터페이스 + GeminiVertexProvider 구현 + BriefingService 1개 파일럿 리팩터

결정 (R3 대기)​

Chair 검토 질문:

  1. C 채택 여부
  2. packages/core-ai 승격 시점 — S2 초반 (7M) vs S2 종반 (10M)
  3. S2 범위에 BriefingService + DocGenService 2개까지 포함 vs 1개 파일럿만
  4. DPIA 기술 작업과의 순서 (어댑터 먼저 / DPIA 먼저 / 병행)

Minority Report 자리 (R1 수집 후 기재)​

  • P5 개발자: "A 만으로 충분. Service 층은 WebPack 5 의 DI 패턴처럼 종종 과잉 엔지니어링."
  • P3 PM: "소버린 AI 전환이 실제 일어날지 미정 — 투자 대비 효과 판단 필요."

후속 과제​

  • Ko-LegalQA eval 프레임워크 (이미 스켈레톤 존재, scripts/eval-citation-precision.ts) 가 어댑터 간 성능 비교 벤치 역할
  • apps/docs/content/architecture/ai-pipeline.md 가 실제 인터페이스 확정 시 재작성 대상

관련 문서​