AI Engine Configuration

계층형 LLM 속성

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

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

속성	기본값	설명
`contexa.llm.enabled`	`true`	Contexa LLM 기능 전체 활성화 플래그
`contexa.llm.advisor-enabled`	`true`	Advisor 체인 등록 활성화
`contexa.llm.chat-model-priority`	`ollama,anthropic,openai`	기본 chat model 선택 우선순위
`contexa.llm.embedding-model-priority`	`ollama,openai`	기본 embedding model 선택 우선순위
`contexa.llm.chat.ollama.base-url`	`""`	내장 Ollama chat runtime 활성화 시 필요한 base URL
`contexa.llm.chat.ollama.model`	`""`	명시하지 않으면 자동 구성에서 `qwen3:8b`를 기본 chat model로 사용
`contexa.llm.chat.ollama.keep-alive`	`""`	Ollama chat keep-alive 힌트
`contexa.llm.embedding.ollama.dedicated-runtime-enabled`	`false`	전용 embedding Ollama runtime 사용 여부
`contexa.llm.embedding.ollama.base-url`	`""`	전용 embedding runtime 사용 시 필요한 base URL
`contexa.llm.embedding.ollama.model`	`""`	명시하지 않으면 `mxbai-embed-large` 기본값 사용
`spring.ai.security.layer1.model`	`qwen2.5:14b`	Layer 1 모델
`spring.ai.security.layer1.backup.model`	—	Layer 1 백업 모델
`spring.ai.security.layer2.model`	`exaone3.5:latest`	Layer 2 모델
`spring.ai.security.layer2.backup.model`	—	Layer 2 백업 모델
`spring.ai.security.tiered.layer1.timeout-ms`	`30000`	`TieredLLMProperties`가 사용하는 Layer 1 추론 타임아웃 기본값
`spring.ai.security.tiered.layer2.timeout-ms`	`60000`	`TieredLLMProperties`가 사용하는 Layer 2 추론 타임아웃 기본값

YAML

contexa:
  llm:
    chat-model-priority: ollama,anthropic,openai
    embedding-model-priority: ollama,openai
    chat:
      ollama:
        base-url: http://localhost:11434
        model: qwen2.5:14b
    embedding:
      ollama:
        dedicated-runtime-enabled: true
        base-url: http://localhost:11435
        model: mxbai-embed-large
spring:
  ai:
    security:
      layer1:
        model: qwen2.5:14b
        backup:
          model: llama3.2:latest
      layer2:
        model: exaone3.5:latest
        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 중 우선순위에 따라 선택합니다.

계층형 전략 속성

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

Layer 1 설정

속성	기본값	설명
`spring.ai.security.tiered.layer1.rag.similarity-threshold`	`0.5`	Layer 1 RAG 임계값
`spring.ai.security.tiered.layer1.session.max-recent-actions`	`100`	세션 문맥에 포함할 최대 최근 액션 수
`spring.ai.security.tiered.layer1.cache.max-size`	`1000`	Layer 1 결과 캐시 최대 수
`spring.ai.security.tiered.layer1.cache.ttl-minutes`	`30`	Layer 1 결과 캐시 TTL(분)
`spring.ai.security.tiered.layer1.timeout.total-ms`	`4500000`	Layer 1 전체 파이프라인 타임아웃
`spring.ai.security.tiered.layer1.timeout.llm-ms`	`3000000`	Layer 1 LLM 호출 타임아웃
`spring.ai.security.tiered.layer1.timeout.rag-ms`	`1000000`	Layer 1 RAG 단계 타임아웃
`spring.ai.security.tiered.layer1.vector-search-limit`	`12`	Layer 1 벡터 검색 상한
`spring.ai.security.tiered.layer1.default-budget-profile`	`CORTEX_L1_STANDARD`	기본 예산 프로파일

Layer 1 프롬프트 설정

속성	기본값	설명
`spring.ai.security.tiered.layer1.prompt.max-similar-events`	`3`	프롬프트에 포함할 유사 이벤트 수
`spring.ai.security.tiered.layer1.prompt.max-rag-documents`	`12`	프롬프트에 포함할 RAG 문서 수
`spring.ai.security.tiered.layer1.prompt.include-event-id`	`false`	이벤트 ID 포함 여부
`spring.ai.security.tiered.layer1.prompt.include-raw-timestamp`	`false`	원시 타임스탬프 포함 여부
`spring.ai.security.tiered.layer1.prompt.include-raw-session-id`	`false`	원시 세션 ID 포함 여부
`spring.ai.security.tiered.layer1.prompt.include-full-user-agent`	`false`	전체 User-Agent 포함 여부

Layer 2 설정

속성	기본값	설명
`spring.ai.security.tiered.layer2.rag.similarity-threshold`	`0.5`	Layer 2 RAG 임계값
`spring.ai.security.tiered.layer2.cache.max-size`	`1000`	Layer 2 캐시 최대 수
`spring.ai.security.tiered.layer2.cache.ttl-minutes`	`30`	Layer 2 캐시 TTL(분)
`spring.ai.security.tiered.layer2.timeout-ms`	`100000`	Layer 2 전체 타임아웃
`spring.ai.security.tiered.layer2.enable-soar`	`false`	Layer 2 SOAR 실행 여부
`spring.ai.security.tiered.layer2.rag-top-k`	`10`	Layer 2 RAG top-k
`spring.ai.security.tiered.layer2.default-budget-profile`	`CORTEX_L2_STANDARD`	Layer 2 기본 예산 프로파일

잘림 설정

속성	기본값	설명
`spring.ai.security.tiered.truncation.layer1.user-agent`	`150`	Layer 1 User-Agent 잘림 길이
`spring.ai.security.tiered.truncation.layer1.payload`	`200`	Layer 1 payload 잘림 길이
`spring.ai.security.tiered.truncation.layer1.rag-document`	`300`	Layer 1 RAG 문서 잘림 길이
`spring.ai.security.tiered.truncation.layer2.user-agent`	`150`	Layer 2 User-Agent 잘림 길이
`spring.ai.security.tiered.truncation.layer2.payload`	`1000`	Layer 2 payload 잘림 길이
`spring.ai.security.tiered.truncation.layer2.rag-document`	`500`	Layer 2 RAG 문서 잘림 길이
`spring.ai.security.tiered.vector-cache.max-size`	`10000`	벡터 캐시 최대 수
`spring.ai.security.tiered.vector-cache.expire-minutes`	`5`	벡터 캐시 TTL(분)
`spring.ai.security.tiered.vector-cache.enabled`	`true`	벡터 캐시 활성화
`spring.ai.security.tiered.vector-cache.record-stats`	`true`	벡터 캐시 통계 기록
`spring.ai.security.tiered.security.trusted-proxies`	`[]`	신뢰 프록시 목록
`spring.ai.security.tiered.security.trusted-proxy-validation-enabled`	`true`	프록시 검증 활성화
`spring.ai.security.tiered.prompt-compression.enabled`	`true`	런타임 프롬프트 압축 활성화

Advisor 속성

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

속성	기본값	설명
`contexa.advisor.chain-profile`	`STANDARD`	Advisor chain profile 이름
`contexa.advisor.security.enabled`	`true`	Security advisor 활성화
`contexa.advisor.security.order`	`50`	Security advisor 실행 순서
`contexa.advisor.security.require-authentication`	`false`	AI 분석 전 인증 필요 여부
`contexa.advisor.soar.approval.enabled`	`true`	SOAR approval advisor 활성화
`contexa.advisor.soar.approval.order`	`100`	SOAR approval advisor 실행 순서
`contexa.advisor.soar.approval.timeout`	`300`	승인 대기 시간(초)

RAG 속성

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

속성	기본값	설명
`contexa.rag.defaults.similarity-threshold`	`0.7`	기본 검색 유사도 임계값
`contexa.rag.defaults.top-k`	`10`	기본 top-k
`contexa.rag.behavior.lookback-days`	`30`	행동 검색 lookback 기간
`contexa.rag.risk.similarity-threshold`	`0.8`	위험 검색 유사도 임계값
`contexa.rag.risk.top-k`	`50`	위험 검색 top-k
`contexa.rag.lab.batch-size`	`50`	AI Lab 배치 크기
`contexa.rag.lab.validation-enabled`	`true`	AI Lab 검증 활성화
`contexa.rag.lab.enrichment-enabled`	`true`	AI Lab 메타데이터 보강 활성화
`contexa.rag.lab.top-k`	`100`	AI Lab top-k
`contexa.rag.lab.similarity-threshold`	`0.75`	AI Lab 유사도 임계값
`contexa.rag.etl.batch-size`	`100`	ETL 배치 크기
`contexa.rag.etl.chunk-size`	`500`	문서 chunk 크기
`contexa.rag.etl.chunk-overlap`	`50`	문서 chunk overlap
`contexa.rag.etl.vector-table-name`	`vector_store`	ETL 논리 테이블 이름
`contexa.rag.etl.behavior.retention-days`	`90`	행동 코퍼스 보관 기간

스트리밍 속성

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

속성	기본값	설명
`contexa.streaming.final-response-marker`	`###FINAL_RESPONSE###`	최종 구조화 응답 앞에 붙는 마커
`contexa.streaming.streaming-marker`	`###STREAMING###`	스트리밍 청크 마커
`contexa.streaming.json-start-marker`	`===JSON_START===`	JSON 시작 마커
`contexa.streaming.json-end-marker`	`===JSON_END===`	JSON 종료 마커
`contexa.streaming.timeout`	`PT5M`	전체 스트리밍 타임아웃
`contexa.streaming.max-retries`	`3`	스트림 재시도 횟수
`contexa.streaming.retry-delay`	`PT1S`	초기 재시도 지연
`contexa.streaming.retry-multiplier`	`1.5`	재시도 backoff 배율
`contexa.streaming.marker-buffer-size`	`100`	마커 감지 버퍼 크기
`contexa.streaming.sentence-buffering-enabled`	`true`	문장 단위 버퍼링 활성화

PgVector 스토어 속성

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

YAML

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

튜닝 시나리오

실제 코드 기준으로 바로 적용할 수 있는 대표 조정 예시입니다.

응답이 느린 경우

YAML

contexa:
  llm:
    chat:
      ollama:
        model: qwen2.5:7b
spring:
  ai:
    security:
      layer1:
        model: qwen2.5:7b
      tiered:
        layer1:
          timeout:
            total-ms: 5400000
            llm-ms: 3600000
            rag-ms: 1200000

RAG 결과가 부정확한 경우

YAML

contexa:
  rag:
    defaults:
      similarity-threshold: 0.85
      top-k: 3
spring:
  ai:
    security:
      tiered:
        layer1:
          rag:
            similarity-threshold: 0.7
          vector-search-limit: 6

토큰 사용량을 줄이고 싶은 경우

YAML

spring:
  ai:
    security:
      tiered:
        layer1:
          prompt:
            max-rag-documents: 2
            max-similar-events: 1
          vector-search-limit: 3
        truncation:
          layer1:
            payload: 100
            rag-document: 150

운영 배포 권장 예시

YAML

contexa:
  llm:
    chat-model-priority: ollama,anthropic,openai
    embedding-model-priority: ollama,openai
    embedding:
      ollama:
        dedicated-runtime-enabled: true
        base-url: http://localhost:11435
  advisor:
    security:
      enabled: true
      require-authentication: true
spring:
  ai:
    security:
      layer1:
        model: qwen2.5:14b
      layer2:
        model: exaone3.5:latest
      tiered:
        vector-cache:
          max-size: 50000
          expire-minutes: 10
          enabled: true
          record-stats: true
        security:
          trusted-proxy-validation-enabled: true

상세 속성 참조

TieredStrategyProperties — Layer 1

속성	기본값	설명
`.rag.similarity-threshold`	`0.5`	Layer 1 RAG 임계값
`.session.max-recent-actions`	`100`	최근 액션 포함 수
`.cache.max-size`	`1000`	Layer 1 캐시 크기
`.cache.ttl-minutes`	`30`	Layer 1 캐시 TTL
`.timeout.total-ms`	`4500000`	Layer 1 전체 예산
`.timeout.llm-ms`	`3000000`	Layer 1 LLM 예산
`.timeout.rag-ms`	`1000000`	Layer 1 RAG 예산
`.vector-search-limit`	`12`	벡터 검색 상한
`.default-budget-profile`	`CORTEX_L1_STANDARD`	기본 예산 프로파일
`.prompt.max-similar-events`	`3`	유사 이벤트 포함 수
`.prompt.max-rag-documents`	`12`	RAG 문서 포함 수

TieredStrategyProperties — Layer 2 및 공통

속성	기본값	설명
`.layer2.rag.similarity-threshold`	`0.5`	Layer 2 RAG 임계값
`.layer2.cache.max-size`	`1000`	Layer 2 캐시 크기
`.layer2.cache.ttl-minutes`	`30`	Layer 2 캐시 TTL
`.layer2.timeout-ms`	`100000`	Layer 2 타임아웃
`.layer2.enable-soar`	`false`	SOAR 활성화
`.layer2.rag-top-k`	`10`	Layer 2 RAG top-k
`.vector-cache.max-size`	`10000`	벡터 캐시 크기
`.vector-cache.expire-minutes`	`5`	벡터 캐시 TTL
`.security.trusted-proxies`	`[]`	신뢰 프록시 목록
`.security.trusted-proxy-validation-enabled`	`true`	프록시 검증 활성화
`.prompt-compression.enabled`	`true`	프롬프트 압축 활성화

AI 엔진 구성

계층형 LLM 속성

계층형 전략 속성

Layer 1 설정

Layer 1 프롬프트 설정

Layer 2 설정

잘림 설정

Advisor 속성

RAG 속성

스트리밍 속성

PgVector 스토어 속성

튜닝 시나리오

응답이 느린 경우

RAG 결과가 부정확한 경우

토큰 사용량을 줄이고 싶은 경우

운영 배포 권장 예시

상세 속성 참조