04 AI Adapter

AI Adapter

역할

AI Adapter는 모델 자체가 아니라 Spring Boot와 모델 Provider 사이의 안전한 연결 계층입니다.

TaskService
  → AiTaskAnalyzer 인터페이스
    → 개인정보 제거
    → Context와 버전 주입
    → 모델 호출
    → JSON Schema 검증
    → 핵심값 보존 검증
    → 안전한 결과 또는 검토 필요 반환

TaskService는 OpenAI, Gemini, HyperCLOVA 같은 특정 업체의 Request/Response를 알지 않습니다.

외부 API의 두 단계

1. POST /tasks/analyze: HR 원문을 분석하고 저장된 후보를 반환합니다.
2. POST /task-analyses/{analysisId}/confirm: HR이 선택한 후보만 실제 Task로 만듭니다.

분석 응답의 후보와 실제 Task를 분리하면 복합 요청에서 일부 후보만 선택할 수 있고, 같은 confirm 재시도에 대한 중복 생성도 서버가 통제할 수 있습니다.

환경별 Provider

환경	구현	목적
자동 테스트	FakeTaskAnalyzer	성공·오류를 결정적으로 재현
개발·실험	LmStudioTaskAnalyzer	로컬 모델과 Prompt 후보 비교
데모 배포	ExternalLlmTaskAnalyzer	외부 LLM API 또는 Cloud Endpoint
운영 고도화	Agent Router	Blue/Green과 자체 Inference Server

LM Studio는 최종 데모 의존성이 아닙니다.

권장 내부 계약

public interface AiTaskAnalyzer {
    TaskAnalysisResult analyze(TaskAnalysisCommand command);
}

Command에는 업무에 필요한 최소 정보만 포함합니다.

{
  "requestId": "uuid",
  "companyId": "uuid",
  "inputText": "응웬반A 체류연장 준비하고 여권 사본도 요청해줘",
  "workers": [
    {
      "workerId": "uuid",
      "displayName": "응웬반A",
      "language": "vi",
      "expiryDate": "2026-09-30"
    }
  ],
  "versions": {
    "agent": "task-agent-v1",
    "prompt": "task-analysis-v1",
    "contextPack": "context-v0.2",
    "workflowCatalog": "workflow-v1"
  }
}

여권번호, 외국인등록번호, 전화번호, 계좌번호는 DTO에 넣지 않습니다.

모델 응답 예시

{
  "tasks": [
    {
      "taskType": "EXPIRY_RENEWAL",
      "workerId": "uuid",
      "title": "체류기간 연장 준비",
      "requiredInformation": [],
      "missingFields": [],
      "confidence": 0.94
    },
    {
      "taskType": "DOCUMENT_REQUEST",
      "workerId": "uuid",
      "title": "여권 사본 요청",
      "documentType": "PASSPORT_COPY",
      "missingFields": [],
      "confidence": 0.97
    }
  ]
}

모델이 상태를 반환해도 서버가 최종 상태를 결정합니다. AI 후보는 HR 승인 이전 상태만 가질 수 있습니다.

검증 순서

1. 인증 사용자와 사업장 Context 확인
2. 민감정보 패턴 제거·거부
3. Prompt·Context Pack·Workflow 버전 주입
4. Timeout이 있는 Provider 호출
5. JSON 파싱
6. JSON Schema 자료형·필수 필드 검사
7. 허용 TaskType과 worker_id 검사
8. 날짜·금액·서류명·대상자 보존 검사
9. 누락정보와 신뢰도 정책 적용
10. TaskAnalysisCandidate와 AiInvocation을 같은 요청 ID로 저장
11. HR confirm 요청에서 선택 후보·편집 값·사업장·분석 버전을 다시 검증
12. Idempotency를 적용해 실제 Task를 한 번만 생성

실패 처리표

상황	서버 처리	자동 발송
JSON 파싱 실패	오류 저장, REVIEW_REQUIRED 성격의 안전 결과	금지
Schema 위반	validation_errors 저장	금지
필수정보 누락	Task를 NEEDS_INFO로 저장	금지
낮은 신뢰도	HR 재확인 요청	금지
Provider Timeout	제한적 Retry 후 안전한 오류	금지
worker_id 불일치	후보 생성 거부	금지
날짜·금액 손실	후보 생성 거부 또는 NEEDS_INFO	금지
민감정보 탐지	모델 호출 전 제거·차단 기록	금지

Provider 오류를 일반 서버 장애로 숨기지 않되, 외부 응답 전문이나 Secret을 사용자에게 노출하지 않습니다.

AiInvocation 기록

필드	이유
request_id	API·Task·AI 로그를 함께 추적
agent_version	Agent 동작 버전 재현
model_provider/name/version	모델 변경 영향 확인
prompt_version	Prompt 회귀 확인
context_pack_version	업무 지식 버전 확인
workflow_catalog_version	상태·필수정보 기준 확인
latency_ms	지연과 Timeout 분석
parsing_error	JSON 안정성 분석
validation_errors	핵심값·Schema 실패 분석
created_at	배포·장애 시점 비교

품질개선 로그에는 비식별 입력 요약과 검증 결과만 저장합니다. 원본 민감정보, 전체 Authorization 헤더, API Key는 저장하지 않습니다.

버전 교체 원칙

MVP에서도 버전 필드를 저장하면 나중에 다음 흐름으로 확장할 수 있습니다.

Spring Boot → Agent Router → Blue Agent
                           → Green Agent

Green은 staging Smoke Evaluation 후 0% → 10% → 50% → 100%로 이동하고, 문제 시 Blue로 되돌립니다. 실제 Router와 트래픽 분할은 MVP 범위 밖입니다.

관련 이슈

• #8 AI Adapter
• #9 데모 배포
• #10 E2E
• LLM Provider RFC