AI 엔진 구성

계층형 LLM 속성

contexa.llm.*과 spring.ai.security.*를 함께 사용해 런타임 선택과 계층별 모델 할당을 구성합니다. OSS 코어는 Ollama chat runtime을 직접 wiring하며, OpenAI/Anthropic은 Spring AI provider bean이 존재할 때 우선순위에 따라 선택됩니다.

관련 문서: LLM Orchestrator 참조, AI 전략 참조

contexa:
  llm:
    selection:
      chat:
        mode: DYNAMIC_PRIORITY
        priority: ollama,anthropic,openai
      embedding:
        mode: DYNAMIC_PRIORITY
        priority: ollama,openai
    chat:
      ollama:
        base-url: http://localhost:11434
        model: qwen2.5:7b
    embedding:
      ollama:
        dedicated-runtime-enabled: true
        base-url: http://localhost:11435
        model: mxbai-embed-large
spring:
  ai:
    security:
      layer1:
        model: qwen2.5:7b
        backup:
          model: llama3.2:latest
      layer2:
        model: gpt-4o-mini
        backup:
          model: deepseek-r1:14b
      tiered:
        layer1:
          timeout-ms: 30000
        layer2:
          timeout-ms: 60000

OpenAI, Anthropic 자격 증명은 Spring AI의 spring.ai.openai.*, spring.ai.anthropic.*에서 구성하고, Contexa는 등록된 provider bean 중 우선순위에 따라 선택합니다.

권장 선택 구성 (OpenAI + Anthropic + Ollama 페일오버)

관리형 클라우드 제공자와 로컬 Ollama 런타임을 함께 묶으면, API 키가 없거나 클라우드 엔드포인트가 도달 불가능할 때 채팅 호출이 자연스럽게 다음 단계로 떨어집니다. 아래 예제는 OpenAI 를 1차 채팅 제공자, Anthropic 을 2차 페일오버, 로컬 Ollama 런타임을 오프라인 / 키 없음 상태의 최종 폴백으로 사용합니다. 임베딩은 항상 OpenAI 를 사용합니다.

contexa:
  llm:
    selection:
      chat:
        mode: dynamic-priority
        priority: openai,anthropic,ollama
      embedding:
        mode: dynamic-priority
        priority: openai

키별 의미

• mode: dynamic-priority — 오케스트레이터가 콤마로 구분된 priority 목록을 순서대로 평가하여, ChatModel / EmbeddingModel Bean 이 등록되고 호출 가능한 첫 제공자를 선택합니다. dynamic-priority는 Mode.DYNAMIC_PRIORITY enum 의 kebab-case 표기이며, 두 형태 모두 Spring 의 relaxed binding 으로 동일한 값에 바인딩됩니다.
• priority: openai,anthropic,ollama — 채팅 호출은 먼저 OpenAI 를 시도하고, OpenAI 클라이언트의 키가 없거나 복구 불가 오류가 발생하면 오케스트레이터가 Anthropic 으로 페일오버합니다. Anthropic 도 사용 불가일 때는 로컬 Ollama 런타임으로 떨어집니다. 목록 순서가 곧 페일오버 순서이므로, 비용이 낮거나 더 안정적인 제공자를 앞에 둡니다.
• priority: openai (임베딩) — Anthropic 은 Spring AI 에 임베딩 모델을 제공하지 않으며, 플랫폼의 pgvector 스키마는 임베딩 차원을 1536 으로 고정합니다. 이는 OpenAI 의 text-embedding-3-small / text-embedding-ada-002 차원과 일치합니다. 임베딩 목록에 Ollama (보통 768 / 1024 차원) 를 섞으면 같은 컬럼에 폭이 다른 벡터가 기록되어 유사도 검색이 깨집니다. 임베딩은 1536 차원 단일 제공자 로 유지하십시오.

선택 블록과 Spring AI 제공자 속성 짝짓기

contexa.llm.selection.* 블록은 어느 제공자를 호출할지를 결정하지만, 실제 API 키와 모델 식별자는 표준 Spring AI 속성 트리에 둡니다.

spring:
  ai:
    retry:
      max-attempts: 1
    anthropic:
      api-key: ${ANTHROPIC_API_KEY:disabled}
      chat:
        options:
          model: claude-3-sonnet-20240229
    openai:
      api-key: ${OPENAI_API_KEY:disabled}
      base-url: https://api.openai.com
      chat:
        options:
          model: gpt-4o-mini
          temperature: 0.3

• API 키 자리표시자 — 기본값 disabled 문자열은 운영자가 환경 변수를 주입하지 않은 상태에서 자동 구성이 실제 클라이언트를 등록하지 않도록 막습니다. ANTHROPIC_API_KEY / OPENAI_API_KEY 를 설정하면 해당 제공자가 활성화되고, disabled 그대로 두면 의도적으로 그 분기를 건너뛰어 우선순위의 다음 제공자가 처리합니다.
• spring.ai.retry.max-attempts: 1 — dynamic-priority 로 두 제공자를 연쇄 구성한 환경에서는 Spring AI 내부에서 같은 실패 제공자를 재시도하는 것은 지연만 늘립니다. 1 로 각 호출을 단일 시도로 묶고, CONTEXA 의 페일오버 선택자가 다음 항목을 고르도록 합니다.
• 모델 식별자 — gpt-4o-mini 는 Tier 1 (낮은 지연시간의 Layer 1 컨텍스트 결정) 에, claude-3-sonnet-20240229 는 Tier 2 (포렌식 Layer 2 추론) 에 권장합니다. 새 SKU 가 출시되면 그에 맞게 교체합니다.
• OpenAI 측의 temperature: 0.3 은 의도적입니다. 보안 결정 프롬프트는 낮은 temperature 가 유리하며, 이 값을 높이면 BLOCK / ESCALATE 경계 판단의 편차가 커집니다.

계층형 전략 속성

spring.ai.security.tiered 아래의 속성으로, TieredStrategyProperties에 바인딩됩니다. 프롬프트 예산, 잘림, 벡터 캐시, 프록시 검증, RAG 임계값을 계층별로 제어합니다.

Layer 1 설정

Layer 1 프롬프트 설정

Layer 2 설정

잘림 설정

보안 작업 매핑 속성

spring.ai.security.mapping 아래의 속성으로, SecurityMappingProperties에 바인딩됩니다. 보안 작업(SecurityTaskType)을 LLM 계층(tier)과 분석 수준(QUICK/NORMAL/DEEP)에 매핑합니다.

Advisor 속성

contexa.advisor 접두사 아래의 속성으로, ContexaAdvisorProperties에 바인딩됩니다. advisor chain profile, security advisor, SOAR approval advisor를 구성합니다.

RAG 속성

contexa.rag 접두사 아래의 속성으로, ContexaRagProperties에 바인딩됩니다. 기본 검색, 행동 검색, 위험 검색, AI Lab, ETL 동작을 구성합니다.

스트리밍 속성

contexa.streaming 접두사 아래의 속성으로, StreamingProperties에 바인딩됩니다. 스트리밍 마커, 타임아웃, 재시도 정책, 파서 버퍼를 구성합니다.

LLM 바인딩 속성

contexa.llm.bindings 아래의 속성으로, ContexaLlmBindingProperties에 바인딩됩니다. 사용자 정의 chat·embedding 모델 바인딩을 등록합니다 (Spring AI ChatModel/EmbeddingModel bean → Contexa runtime 카탈로그 매핑).

contexa:
  llm:
    bindings:
      chat:
        primary-ollama:
          bean-name: contexaOllamaChatModel
          provider: ollama
          model-id: qwen2.5:7b
          aliases: [default, fast]
          enabled: true
          primary: true
      embedding:
        primary-ollama:
          bean-name: contexaSharedOllamaEmbeddingModel
          provider: ollama
          model-id: mxbai-embed-large
          enabled: true
          primary: true

PgVector 스토어 속성

spring.ai.vectorstore.pgvector 접두사 아래의 속성으로, PgVectorStoreProperties에 바인딩됩니다. Spring AI 의 CommonVectorStoreProperties를 상속하며, Contexa 코어가 직접 선언한 필드는 인덱스 타입, 거리 함수, 차원, batch/search/store 제한, HNSW/IVFFLAT 세부 설정, 문서 chunking 설정입니다.

spring:
  ai:
    vectorstore:
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: 1024
        batch-size: 100
        parallel-threads: 4
        top-k: 100
        similarity-threshold: 0.5
        search-timeout-ms: 10000
        store-timeout-ms: 10000
        hnsw:
          m: 16
          ef-construction: 64
          ef-search: 100
        document:
          chunk-size: 1000
          chunk-overlap: 200
          enrich-metadata: true
          extract-keywords: true
          generate-summary: false