[AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현

목표

Server가 Prompt·Provider를 직접 소유하지 않고, 검증한 요청을 AI Runtime에 전달한 뒤 응답을 다시 검증합니다.

AiRun (#24)
→ AiRuntimeClient (#8)
→ POST /internal/v1/analyses (fowoco/ai)

현재 요청 계약

PLAN은 사용자가 작성한 원문만 전달합니다. Client의 빠른 선택 태그나 Intent 코드를 발화문에 덧붙이지 않습니다.

{
  "requestId": "10000000-0000-0000-0000-000000000001",
  "phase": "PLAN",
  "analysisInput": {
    "instruction": "응웬반안 체류연장 준비해줘"
  }
}

requestId: PLAN과 ANALYZE를 같은 실행으로 연결
phase: PLAN 또는 ANALYZE
analysisInput: 실제 분석 데이터
Intent는 Runtime 응답의 detectedIntent를 사용
Workflow는 WF-STY-001 같은 canonical workflowId를 사용
ANALYZE에서는 같은 requestId와 #74가 해결한 Slot 정보만 추가

Server 책임

Bearer service 인증과 request/trace 전달
HTTP/1.1, timeout, bulkhead, circuit breaker, 응답 크기 제한
strict JSON parsing과 requestId·핵심값 검증
Runtime 호출 1회당 Server 내부 AiAttempt 1개
Agent·OCR의 Server DB 직접 접근 금지
API Key, JWT, 비밀번호, Worker Link 원본 token 차단

구현 현황

완료 기준

실제 Runtime을 호출해 다음을 확인하면 이 이슈를 완료합니다.

PLAN 요청이 원문 그대로 전달됨
detectedIntent=EXPIRY_RENEWAL, workflowId=WF-STY-001 형태로 수신
필요한 Slot이 있으면 ANALYZE 재호출까지 성공
timeout·계약 오류가 Server 공통 오류로 안전하게 변환됨

관계

Server 구현 PR: feat: AI Runtime 연동 계약과 안전한 검증 기반 구현 #42, [AI 연동] AI Runtime HTTP 연결과 장애 격리 구현 #56, fix: AI Runtime 통신을 HTTP/1.1로 고정 #93
실행 이력·Candidate: [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24
Slot Resolver: [AI Run][P0] Agent 요청 Slot 조회·재호출 오케스트레이션 구현 #74
Agent 계약: fowoco/ai PR #13, PR #19
OCR 후속: [OCR][P0] Server 소유 문서 OCR 실행·결과 저장 구현 #95, fowoco/ai#20
Parent: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2

2026-08-10 · 실제 Runtime Smoke 결과

로컬에서 실제 Hugging Face Intent 모델을 활성화한 AI Runtime과 Spring Boot Server를 연결해 성공 왕복을 확인했습니다.

POST /api/v1/ai-runs → 202 + aiRunId
AI Runtime PLAN 및 ANALYZE 호출 모두 200
detectedIntent=EXPIRY_RENEWAL
Server가 현재 사업장 DB에서 worker_id, stay_expiry_date 보충
workflowId=WF-STY-001
최종 AiRun SUCCEEDED, analysisOutcome=REVIEW_REQUIRED
실제 모델 confidence 확인

AI 응답의 모델 메타데이터가 stub 기본값으로 표시되는 문제는 Runtime 메타데이터 전달 후속 작업으로 분리하며, Server의 실제 모델 호출과 PLAN→ANALYZE 계약 왕복은 정상임을 확인했습니다.

2026-07-24 · 1단계 구현 시작

Draft PR: #42

AI Runtime의 실제 HTTP API가 준비되기 전에도 독립적으로 검증할 수 있는 계약 기반을 먼저 구현했습니다.

이번 PR에서 완료한 범위

AiRuntimeClient Port와 Provider-neutral 요청·응답 모델
test-only FakeAiRuntimeClient
전송 전 민감정보 차단과 typed outbound allow-list
응답 requestId, contract/Knowledge version 상관관계 검증
요청에 포함된 worker, Workflow, slot 범위 밖의 Candidate 거부
원문을 예외에 남기지 않는 안전한 failure code
계약 fixture, 개인정보·오류 시나리오 테스트와 구현 문서

아직 남은 범위

fowoco/ai가 소유하는 /internal/v1/analyses OpenAPI·Structured Output Schema 확정
RemoteAiRuntimeClient, S2S 인증과 request/trace propagation
timeout, circuit breaker, concurrency bulkhead, body size 제한
strict JSON parsing과 WireMock contract test
날짜·금액·서류명 등 핵심값 보존 검증 확장
[AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24 AiRun에 version·latency·error code 저장

따라서 #8 전체를 닫지는 않고 status:in-progress로 전환합니다. PR #42는 Server가 독립적으로 소유할 수 있는 1단계이며, 실제 Remote 연동은 AI 원본 계약 release 뒤 후속 PR로 진행합니다.

2026-08-03 계약 정리: 별도 intentHint를 제거하고 "발화문, INTENT_TAG" 단일 instruction으로 통일했습니다. #56 코드·테스트와 fowoco/ai#6 요청도 같은 기준으로 갱신했습니다.

2026-08-06 상태 갱신

PR [AI 연동] AI Runtime HTTP 연결과 장애 격리 구현 #56: AI Runtime HTTP Adapter·장애 격리 병합 완료
PR fix: AI Runtime 통신을 HTTP/1.1로 고정 #93: HTTP/1.1 고정 병합 완료
AI PR [Document] 통합 문서함·파일 업로드·문서 준비도 구현 #13·[Q&A] 로컬 실행·환경설정·API 연동 질문 모음 #19: PLAN/ANALYZE와 canonical Workflow ID 계약이 develop에 반영됨
남은 완료 조건: Server ↔ 실제 AI Runtime 성공 응답 Smoke Test

Fake Adapter로 개발 가능한 상태이므로 status:blocked를 해제하고 status:in-progress로 변경합니다. 실제 배포 검증은 #9·#10과 연결합니다.

2026-08-06 실제 Intent 모델 검증 현황

AI develop의 HybridHfIntentAgent와 Hugging Face 모델을 직접 호출해 다음을 확인했습니다.

PLAN 응웬반안 체류연장 준비해줘 → EXPIRY_RENEWAL, confidence 약 0.849
ANALYZE → REVIEW_REQUIRED, candidate workflowId=WF-STY-001
여권 사본을 요청해줘 → DOCUMENT_REQUEST, confidence 약 0.775
Internal Bearer와 /internal/v1/analyses HTTP 계약 정상

남은 blocker는 Server 코드가 아니라 AI 배포 패키징입니다.

배포 환경에서 FOWOCO_INTENT_MODEL_ENABLED=true 필요
현재 AI Dockerfile의 uv sync --frozen --no-dev에는 torch, transformers가 없어 --extra intent 반영 필요
Compose가 모델용 .env를 AI 컨테이너에 전달하도록 설정 필요
응답의 modelProvider, modelName, modelVersion은 실제 모델 실행 중에도 stub 기본값으로 남아 있어 후속 교정 필요

위 AI 배포 설정 반영 후 Server의 PLAN → DB Slot 보충 → ANALYZE → AiCandidate 저장 전체 Smoke Test를 다시 실행하고 #8 완료 여부를 판단합니다.

Navigation Menu

Repository navigation

[AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8

목표

현재 요청 계약

Server 책임

구현 현황

완료 기준

관계

2026-08-10 · 실제 Runtime Smoke 결과

2026-07-24 · 1단계 구현 시작

이번 PR에서 완료한 범위

아직 남은 범위

2026-08-06 상태 갱신

2026-08-06 실제 Intent 모델 검증 현황

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8

Description

목표

현재 요청 계약

Server 책임

구현 현황

완료 기준

관계

2026-08-10 · 실제 Runtime Smoke 결과

Activity

hywznn commented on Jul 24, 2026

2026-07-24 · 1단계 구현 시작

이번 PR에서 완료한 범위

아직 남은 범위

hywznn commented on Aug 3, 2026

hywznn commented on Aug 6, 2026

2026-08-06 상태 갱신

hywznn commented on Aug 6, 2026

2026-08-06 실제 Intent 모델 검증 현황

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions