Model Providers

개요

Contexa는 여러 LLM 런타임을 동시에 지원합니다. 애플리케이션 시작 시 DynamicModelRegistry는 두 가지 경로로 디스크립터 맵을 채웁니다:

1. LlmRuntimeCatalog chat 바인딩 — LlmRuntimeCatalog.getChatBindings()가 반환하는 모든 LlmRuntimeBinding이 등록됩니다. 카탈로그는 Contexa 런타임(예: contexa.llm.chat.ollama.*)과 Spring AI 자동 구성(Anthropic, OpenAI 등)으로 생성된 Spring AI ChatModel 빈으로부터 구성됩니다.
2. TieredLLMProperties 계층 — spring.ai.security.layer1과 spring.ai.security.layer2에 구성된 기본·백업 모델이 해당 티어로 등록됩니다. 레지스트리는 resolveCanonicalModelId(...)를 사용하므로 동일 모델을 runtime ID, bean name, alias 어느 쪽으로도 조회할 수 있습니다.

바인딩이 없을 때 레지스트리는 모델 ID에서 provider 이름을 추론합니다. 인식되는 부분 문자열은 llama, qwen, gemma, mistral, phi, exaone, codellama, deepseek (→ ollama), claude (→ anthropic), gpt·o1·davinci (→ openai), gemini·vertex (→ gemini), bedrock (→ bedrock)입니다. 나머지는 spring으로 분류됩니다.

LlmRuntimeCatalog

탐색된 chat·embedding 런타임을 노출하는 인터페이스입니다. 레지스트리가 바인딩을 찾고 필요할 때 실제 ChatModel 인스턴스를 해석하는 데 사용합니다.

LlmRuntimeBinding

단일 런타임 바인딩에 대한 불변 레코드입니다. 바인딩은 Contexa LLM 자동 구성이 생성하며 카탈로그와 레지스트리 모두가 소비합니다.

헬퍼 메서드

ModelDescriptor

모델의 정체성·기능·기본 옵션·현재 상태를 기술합니다.

ModelCapabilities (nested class)

ModelOptions (nested class)

헬퍼 메서드

DynamicModelRegistry

디스크립터를 관리하고 ChatModel 인스턴스를 캐시하는 중앙 레지스트리입니다. @PostConstruct 초기화 동안 카탈로그와 티어 설정에서 모델을 등록합니다.

생성자 의존성

Public API

ModelSelectionStrategy

모델 선택 로직을 위한 인터페이스입니다. DynamicModelSelectionStrategy가 기본 구현체입니다.

DynamicModelSelectionStrategy

기본 선택 전략은 명시적 모델 우선 폴백 체인을 사용합니다. DynamicModelRegistry, TieredLLMProperties, 기본 ChatModel 빈으로 생성됩니다.

1. 명시적 모델 요청 — 먼저 ExecutionContext.preferredModel을 시도합니다. 없으면 다음 순서로 메타데이터 키를 찾습니다: requestedModelId, preferredModel, runtimeModelId, modelId.
2. 티어 해석 — 명시적 모델이 해석되지 않으면 다음 순서로 티어를 선택합니다: analysisLevel.getDefaultTier() → securityTaskType.getDefaultTier() → ExecutionContext.tier. 1을 초과하는 값은 구성된 layer 2로 정규화됩니다.
3. Primary/backup 조회 — 전략은 TieredLLMProperties.getModelNameForTier(...)로 기본 모델을, getBackupModelNameForTier(...)로 백업 모델을 조회합니다.
4. Primary ChatModel 폴백 — 모든 티어 후보가 실패하면 자동 구성된 기본 ChatModel 빈을 마지막 폴백으로 반환합니다.

해석 메타데이터

전략은 결과를 ExecutionContext.metadata에 기록합니다. 하위 코드와 어드바이저는 다음 키를 확인할 수 있습니다:

추가 메서드

설정

계층형 모델 계층 구조

spring:
  ai:
    security:
      layer1:
        model: qwen2.5:7b
        backup:
          model: qwen2.5:7b
      layer2:
        model: gpt-4o-mini
        backup:
          model: llama3.1:8b
      tiered:
        layer1:
          timeout-ms: 30000
        layer2:
          timeout-ms: 60000

contexa:
  llm:
    chat:
      ollama:
        base-url: http://localhost:11434
        model: qwen2.5:7b

관련 문서