-
Notifications
You must be signed in to change notification settings - Fork 0
04 AI Adapter
- AI Run은 요청 상태·재시도·멱등성·버전·오류를 DB에 보존하는 비동기 실행 resource입니다.
- AI Adapter/Gateway는 Provider 차이를 숨기고 비식별화·호출·Structured Output 검증을 수행합니다.
- Workflow는 AI 결과를 Task로 확정·승인·전달할 수 있는지 판단합니다.
AiRunController
→ AiOrchestrationService
→ AiAdapter
→ PromptContextBuilder
→ AiProviderClient
→ JsonSchemaValidator
→ CoreValuePrivacyValidator
Provider SDK의 Request/Response를 Task·Workflow module에 노출하지 않습니다.
-
POST /ai-runs— 입력과 멱등 key를 저장하고202 Accepted반환 -
GET /ai-runs/{runId}— 상태·후보·검토 사유·버전·오류 조회 -
POST /ai-runs/{runId}/retry— 재시도 가능한 실패만 명시적으로 재실행 -
POST /ai-runs/{runId}/confirm— HR이 선택한 후보만 Task로 정확히 한 번 확정
기존 계획의 /tasks/analyze와 /task-analyses/{analysisId}/confirm은 구현하지 않습니다. 긴 HTTP 연결에서 후보를 즉시 돌려주는 동기식 계약은 서버 재시작·Provider 지연·중복 요청 복구에 불리합니다.
| 환경 | 구현 | 목적 |
|---|---|---|
| 자동 테스트 | Fake Provider | 성공·Timeout·잘못된 JSON을 결정적으로 재현 |
| 개발·실험 | LM Studio compatible Provider | 로컬 모델·Prompt 후보 비교 |
| 데모 배포 | External LLM/Cloud Endpoint Provider | 시연자 PC 없이 서비스 |
| 운영 고도화 | Agent Router + inference server | Blue/Green·자체 model 전환 |
Fake Provider는 테스트 도구입니다. 실제 Provider 장애 때 Fake 결과를 진짜 결과처럼 반환하는 fallback은 금지합니다.
{
"requestId": "uuid",
"traceId": "trace-id",
"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"
}
}Provider에 company_id가 꼭 필요하지 않다면 외부 입력에서 제외합니다. 외국인등록번호·여권번호·전화번호·계좌번호·원본 신분증·계약서 전문은 DTO에 넣지 않습니다.
{
"intents": ["CREATE_TASK"],
"domains": ["EXPIRY", "DOCUMENT"],
"slots": {
"workerId": "uuid",
"documentType": "PASSPORT_COPY"
},
"missingSlots": [],
"ambiguities": [],
"sensitivity": [],
"nextAction": "READY_FOR_REVIEW",
"confidence": 0.94
}후보 배열의 각 항목도 허용된 TaskType·worker ID·slot schema를 만족해야 합니다. 모델이 상태나 다음 행동을 제안해도 서버의 Workflow guard가 최종 상태를 결정합니다.
- Access JWT의 actor와
company_id확인 - 입력 길이·허용 파일 reference·Idempotency-Key 검사
- 민감정보 pattern 탐지·제거 또는 요청 차단
- worker ID를 최소 Context에 매핑
- Prompt·Context Pack·Workflow Catalog version 고정
- timeout·bulkhead가 있는 Provider 호출
- JSON parsing과 JSON Schema 검사
- 허용 intent/domain/enum/date/amount 형식 검사
- 대상자·날짜·금액·문서명 같은 핵심값 보존 검사
- missing slot·ambiguity·sensitivity·confidence 정책 적용
- 결과·검증 오류·version·latency를 AI Run에 저장
- confirm에서 candidate·편집값·Run/Task version·사업장을 재검증
| 상황 | 정책 | 사용자에게 제공할 다음 행동 |
|---|---|---|
| 연결/응답 Timeout | 짧은 timeout, 제한적 retry | 나중 재시도 또는 수동 입력 |
| 429·일시적 5xx | Retry-After/지수 backoff, 최대 횟수 | 대기 후 retry |
| 반복 Provider 장애 | Circuit Breaker open | 즉시 명시적 실패·수동 처리 |
| 동시 AI 요청 급증 | Bulkhead/queue 제한 | 429 또는 queue 정책 |
| 잘못된 JSON/Schema | 자동 retry 남용 금지 | 검토 필요 또는 Provider 오류 |
| 핵심값 손실·PII 발견 | 후보 성공 처리 금지 | HR 검토·입력 수정 |
Resilience4j 정책은 Provider client 경계에 적용합니다. 전체 Controller나 DB transaction을 retry해서 중복 Task·Link를 만들지 않습니다.
QUEUED → RUNNING → VALIDATING → SUCCEEDED | NEEDS_REVIEW | FAILED가 기본 흐름이며, 허용된 일시 오류에서만 RETRYING을 거칩니다.
- 같은
company_id + Idempotency-Key와 같은 payload는 기존 Run을 반환합니다. - 같은 key에 다른 payload가 오면 409 성격의 충돌을 반환합니다.
-
input_hash는 비식별·정규화된 입력과 contract version을 기준으로 계산합니다. - confirm에는 unique constraint와 expected version을 적용합니다.
- 미완료 Run은 durable event를 통해 서버 재시작 뒤 복구합니다.
| 필드 | 이유 |
|---|---|
request_id, trace_id
|
API·event·Provider·audit 연결 |
input_hash, idempotency_key_hash
|
중복 판단과 원문 미저장 |
agent_version |
orchestration 규칙 재현 |
model_provider/name/version |
model 변경 영향 확인 |
prompt/context_pack/workflow_catalog_version |
지식·규칙 회귀 확인 |
latency_ms, retry_count
|
지연·비용·장애 분석 |
validation_status, error_code
|
JSON·업무 검증 실패 분류 |
| 생성·시작·완료 시각 | queue와 처리 시간 분석 |
Provider 요청·응답 전문, Authorization header, API key, 실제 민감식별자는 저장하지 않습니다.
입력 “응웬반A 체류연장 준비하고 여권 사본도 요청해줘”에서 다음을 검증합니다.
-
EXPIRY_RENEWAL,DOCUMENT_REQUEST후보 2개 - worker ID·체류 만료일·
PASSPORT_COPY보존 - 민감정보가 Provider request·품질 log에 없음
- 누락·모호성이 명시됨
- HR confirm 전 실제 Task 없음
- HR approve 전 Worker Link 없음