contexa-core

AI Strategy

AI Strategy 시스템은 DiagnosisType을 기반으로 AI 요청을 적절한 처리 Lab으로 라우팅합니다. AIStrategyRegistry는 모든 Strategy 구현체를 자동 탐색하며, AINativeProcessor는 분산 락 및 감사 로깅이 포함된 고수준 AICoreOperations 인터페이스를 제공합니다.

개요

Strategy 레이어는 API/Streaming 레이어와 AI Lab 사이에 위치합니다. 각 AIStrategy 구현체는 하나의 DiagnosisType을 처리하고 연관된 Lab에 처리를 위임합니다. 전체 실행 흐름은 다음과 같습니다:

AICoreOperations
AINativeProcessor
DistributedStrategyExecutor
AIStrategyRegistry
AIStrategy → AILab

AIStrategy<T, R>

도메인별 AI 처리 Strategy의 핵심 인터페이스입니다. 각 구현체는 하나의 DiagnosisType을 처리합니다.

public interface AIStrategy<T extends DomainContext, R extends AIResponse>
getSupportedType() DiagnosisType
이 Strategy가 처리하는 DiagnosisType을 반환합니다. 레지스트리에서 라우팅에 사용됩니다.
getPriority() int
이 Strategy의 우선순위를 반환합니다. 동일한 타입을 처리하는 여러 Strategy가 있을 경우 가장 낮은 우선순위가 선택됩니다.
execute(AIRequest<T> request, Class<R> responseType) R
동기 실행. 실패 시 DiagnosisException을 던집니다.
executeAsync(AIRequest<T> request, Class<R> responseType) Mono<R>
리액티브 Mono를 반환하는 비동기 실행.
executeStream(AIRequest<T> request, Class<R> responseType) Flux<String>
Streaming 실행. supportsStreaming()이 true를 반환할 때만 사용 가능합니다.
supportsStreaming() boolean
이 Strategy가 Streaming을 지원하는지 여부를 반환합니다. 기본값: false.

AbstractAIStrategy<T, R>

Strategy에서 Lab으로의 위임 패턴을 구현하는 기본 클래스입니다. AILabFactory를 사용하여 런타임에 Lab을 해석합니다.

public abstract class AbstractAIStrategy<T extends DomainContext, R extends AIResponse>
    implements AIStrategy<T, R>

템플릿 메서드 흐름

  1. validateRequest(request) — 수신된 요청을 검증합니다.
  2. getRequiredLab() — getLabType()을 사용하여 AILabFactory를 통해 Lab을 해석합니다.
  3. convertLabRequest(request) — AIRequest를 Lab의 요청 형식으로 변환합니다.
  4. processLabExecution(lab, labRequest, request) — Lab을 실행하고 응답을 반환합니다.

추상 메서드 (구현 필수)

getLabType() Class<?>
이 Strategy가 위임하는 AILab 클래스 타입을 반환합니다.
validateRequest(AIRequest<T> request) void
요청을 검증합니다. 유효하지 않은 요청의 경우 DiagnosisException을 던지세요.
convertLabRequest(AIRequest<T> request) Object
범용 AIRequest를 Lab의 특정 요청 타입으로 변환합니다.
processLabExecution(Object lab, Object labRequest, AIRequest<T> request) R
변환된 요청으로 Lab을 실행하고 타입이 지정된 응답을 반환합니다.
processLabExecutionAsync(Object lab, Object labRequest, AIRequest<T> request) Mono<R>
비동기 Lab 실행. 리액티브 Lab 구현을 위해 오버라이드하세요.

AIStrategyRegistry

모든 AIStrategy 빈을 자동 탐색하고 DiagnosisType별로 요청을 라우팅합니다. 동일한 타입을 처리하는 여러 Strategy가 있을 경우 가장 낮은 우선순위가 선택됩니다.

public class AIStrategyRegistry
getStrategy(DiagnosisType diagnosisType) AIStrategy<T, R>
주어진 진단 타입에 대한 Strategy를 반환합니다. 등록된 Strategy가 없으면 DiagnosisException을 던집니다.
executeStrategyAsync(AIRequest<T> request, Class<R> responseType) Mono<R>
request.getDiagnosisType()으로 Strategy를 조회하고 비동기로 실행합니다.
executeStrategyStream(AIRequest<T> request, Class<R> responseType) Flux<String>
Strategy를 조회하고 Streaming 모드로 실행합니다.

AICoreOperations<T>

AI 처리를 위한 고수준 인터페이스입니다. StandardStreamingService와 컨트롤러에서 사용됩니다.

public interface AICoreOperations<T extends DomainContext>
process(AIRequest<T> request, Class<R> responseType) Mono<R>
요청을 처리하고 타입이 지정된 응답을 반환합니다.
processStream(AIRequest<T> request) Flux<String>
요청을 Streaming 모드로 처리합니다.

AINativeProcessor<T>

주요 AICoreOperations 구현체입니다. Strategy 실행 전후에 분산 락 및 감사 로깅을 추가합니다.

public final class AINativeProcessor<T extends DomainContext>
    implements AICoreOperations<T>

주요 동작

  • 분산 락 — Strategy 실행 전 DistributedLockService를 통해 락을 획득합니다. 분산 배포에서는 Redis 구현이 사용될 수 있고, 단일 JVM 환경에서는 메모리 기반 구현이 사용됩니다. 기본 락 타임아웃은 30분입니다.
  • 감사 로깅 — 실행 전 감사 추적 항목을 생성하고 실행 후 결과 또는 오류로 완료합니다.
  • 노드 식별 — 각 노드는 락 소유권을 위한 고유 ID를 생성합니다.

DistributedStrategyExecutor<T>

AINativeProcessor와 AIStrategyRegistry를 연결합니다. 오류 래핑 및 결과 검증을 처리합니다.

public class DistributedStrategyExecutor<T extends DomainContext>
executeDistributedStrategyAsync(AIRequest<T> request, Class<R> responseType) Mono<R>
결과 검증과 함께 AIStrategyRegistry.executeStrategyAsync()에 위임합니다.
executeDistributedStrategyStream(AIRequest<T> request, Class<R> responseType, String auditId) Flux<String>
오류 처리와 함께 AIStrategyRegistry.executeStrategyStream()에 위임합니다.

LabExecutionStrategy

다단계 워크플로우, 폴백 동작, 품질 게이트를 포함하여 Lab이 어떻게 실행되어야 하는지 정의하는 설정 객체입니다.

public class LabExecutionStrategy
속성타입설명
strategyIdString고유 Strategy 식별자.
operationTypeString실행되는 작업의 유형.
executionStepsList<LabExecutionStep>종속성과 타임아웃이 포함된 정렬된 Lab 실행 단계 목록.
fallbackStrategyFallbackStrategy폴백 동작을 정의합니다 (IMMEDIATE, GRADUAL, FULL_RECOVERY, EMERGENCY).
qualityGateQualityGate정확도, 응답 시간, 신뢰도에 대한 품질 임계값.

QualityGate

passesQualityGate(double accuracy, double responseTime, double confidence) boolean
세 가지 지표가 모두 각각의 임계값을 충족하면 true를 반환합니다.

FallbackStrategy.FallbackType Enum

값설명
IMMEDIATE즉시 폴백 Lab으로 전환.
GRADUAL더 단순한 처리로 점진적 성능 저하.
FULL_RECOVERY폴백 전 전체 복구 시도.
EMERGENCY최소 처리로 긴급 폴백.

코드 예제

커스텀 Strategy 구현

Java 
@Component
public class ProductRecommendationStrategy
        extends AbstractAIStrategy<ProductContext,
                                    ProductRecommendationResponse> {

    public ProductRecommendationStrategy(AILabFactory labFactory) {
        super(labFactory);
    }

    @Override
    public DiagnosisType getSupportedType() {
        return new DiagnosisType("PRODUCT_RECOMMENDATION");
    }

    @Override
    public int getPriority() {
        return 100;
    }

    @Override
    protected Class<?> getLabType() {
        return ProductRecommendationLab.class;
    }

    @Override
    protected void validateRequest(
            AIRequest<ProductContext> request)
            throws DiagnosisException {
        if (request.getContext() == null) {
            throw new DiagnosisException(
                    getSupportedType().name(),
                    "INVALID_REQUEST",
                    "ProductContext is required");
        }
        if (request.getContext().getCategory() == null) {
            throw new DiagnosisException(
                    getSupportedType().name(),
                    "INVALID_REQUEST",
                    "Product category is required");
        }
    }

    @Override
    protected Object convertLabRequest(
            AIRequest<ProductContext> request)
            throws DiagnosisException {
        ProductContext ctx = request.getContext();
        return new ProductRecommendationRequest(
                ctx.getProductId(),
                ctx.getCategory(),
                ctx.getUserPreferences());
    }

    @Override
    protected ProductRecommendationResponse processLabExecution(
            Object lab, Object labRequest,
            AIRequest<ProductContext> request) throws Exception {
        ProductRecommendationLab productLab =
                (ProductRecommendationLab) lab;
        return productLab.process(
                (ProductRecommendationRequest) labRequest);
    }
}

AICoreOperations 사용

Java 
@RestController
public class ProductController {

    private final AICoreOperations<ProductContext> aiProcessor;

    @PostMapping("/api/products/recommend")
    public Mono<ProductRecommendationResponse> recommend(
            @RequestBody ProductRequest body) {

        ProductContext context = body.toProductContext();
        AIRequest<ProductContext> request = new AIRequest<>(
                context,
                new TemplateType("PRODUCT_RECOMMENDATION"),
                new DiagnosisType("PRODUCT_RECOMMENDATION"));
        request.setNaturalLanguageQuery(
                "Recommend products for this request");

        return aiProcessor.process(
                request, ProductRecommendationResponse.class);
    }
}

AI Engine Overview

AI 엔진 아키텍처 및 진단 프로세스 개요.

Streaming

StandardStreamingService는 Strategy/Lab Streaming 경로에 AICoreOperations를 사용합니다.

AI Pipeline

Strategy 레이어를 우회하는 대안 실행 경로.
설정 레퍼런스
AI Strategy가 사용하는 모델 계층, 폴백, 스트리밍 관련 속성은 AI 설정을 참조하세요. 현재 OSS 코어에서는 TieredLLMProperties, ContexaProperties, StreamingProperties가 주요 구성 축입니다.