LLM & 모델

개요

오케스트레이터는 LLMOperations(컨텍스트 기반 API)와 ToolCapableLLMClient(프롬프트 기반 API)를 모두 구현하여, 플랫폼 전역에서 LLM 모델에 유연하게 접근할 수 있도록 합니다.

직접 사용이 적절한 경우

대부분의 경우 오케스트레이터를 직접 호출할 필요가 없습니다. Pipeline의 LLM_EXECUTION 단계가 자동으로 호출합니다. 다음 상황에서는 직접 사용이 적절합니다:

계층형 모델 아키텍처

오케스트레이터는 티어 인식 모델 선택을 사용합니다. 현재 OSS 런타임의 TieredLLMProperties는 구성된 두 계층(layer1, layer2)을 노출합니다. AnalysisLevel이나 SecurityTaskType의 높은 시맨틱 티어는, 명시적 모델이 요청되지 않는 한 구성된 layer-2 런타임으로 정규화됩니다.

티어 선택 동작 방식

유효 모델은 다음 순서로 해석됩니다:

1. preferredModel 또는 requestedModelId, preferredModel, runtimeModelId, modelId와 같은 실행 메타데이터 — 명시적 모델 ID는 티어 매핑을 완전히 우회합니다
2. analysisLevel — QUICK→1, NORMAL→2, DEEP→3 (런타임에서 구성된 layer 2로 정규화됨)
3. securityTaskType — analysisLevel이 없을 때 보안 작업이 기본 시맨틱 티어로 매핑됩니다
4. tier — 더 높은 우선순위 선택자가 없을 때의 명시적 숫자 티어. 1을 초과하는 값은 layer 2로 정규화됩니다
5. 구성된 모델을 해석할 수 없을 때의 최종 폴백으로서의 기본 ChatModel 빈

AnalysisLevel Enum

ExecutionContext

LLM 요청을 구성하는 주요 방법입니다. @Builder 패턴으로 생성됩니다:

ExecutionContext context = ExecutionContext.builder()
    .prompt(new Prompt("Analyze this for threats"))
    .analysisLevel(ExecutionContext.AnalysisLevel.NORMAL)
    .userId("user-123")
    .requestId(UUID.randomUUID().toString())
    .build();

// Execute
Mono<String> result = orchestrator.execute(context);

// Or stream
Flux<String> chunks = orchestrator.stream(context);

주요 속성

AnalysisLevel 기본 모델 이름

각 AnalysisLevel 값은 getDefaultModelName()을 통해 기본 모델 이름도 노출합니다. 티어 해석이 구성된 layer 모델 없이 폴백될 때 오케스트레이터가 이 기본값을 사용합니다:

팩토리 & 헬퍼 메서드

Tool 호출

오케스트레이터는 에이전트 워크플로우를 위한 Spring AI Tool 호출을 지원합니다. 두 가지 접근 방식이 있습니다:

Tool 프로바이더(어노테이션 메서드)

// Tool provider objects - Spring AI discovers @Tool methods
Prompt prompt = new Prompt("Block suspicious IP 192.168.1.100");

Mono<String> result = orchestrator.callTools(
    prompt, List.of(ipBlockTool, auditTool));

ToolCallback 배열(명시적)

// Explicit ToolCallback array
ToolCallback[] callbacks = new ToolCallback[] {
    myToolCallback1, myToolCallback2
};

Mono<String> result = orchestrator.callToolCallbacks(
    prompt, callbacks);

두 접근 방식 모두 Streaming도 지원합니다: streamTools()와 streamToolCallbacks().

Advisor 시스템

오케스트레이터는 AdvisorRegistry에서 활성화된 어드바이저를 가져와 ExecutionContext에 연결된 요청 범위 어드바이저와 결합합니다. 이 어드바이저들은 오케스트레이터가 선택된 모델에 대한 채팅 호출을 구성할 때 적용됩니다.

커스텀 Advisor 구현

LLM 요청과 응답을 가로채는 어드바이저를 만들려면 BaseAdvisor를 확장합니다:

@Component
public class RequestLoggingAdvisor extends BaseAdvisor {

    public RequestLoggingAdvisor() {
        super("myapp", "request-logging", 100);
        // domain, name, order (lower = runs first)
    }

    @Override
    public ChatClientRequest beforeCall(
            ChatClientRequest request) {
        // Inspect or modify the request before LLM call
        // e.g., log the prompt, add metadata
        return request;
    }

    @Override
    public ChatClientResponse afterCall(
            ChatClientResponse response,
            ChatClientRequest request) {
        // Inspect or modify the response after LLM call
        // e.g., validate response, log metrics
        return response;
    }
}

Advisor는 Spring 빈으로 자동 등록됩니다. AdvisorRegistry는 활성화/비활성화 상태를 관리하고 오케스트레이터에 정렬된 어드바이저 스냅샷을 제공합니다.

설정

API 레퍼런스

관련 문서