KonanLLM 세부 설정

1. 문서 목적

이 문서는 KonanLLM 솔루션 스택 파일의 컴포넌트별 세부 설정 을 정리합니다. §4~§10 은 사이트별로 자주 손대게 되는 컴포넌트(license / GPU / host / 모델 파일) 를, §11 은 기본값으로 두는 나머지 컴포넌트를 역할 위주로 요약합니다.

KonanLLM 은 30개가 넘는 컴포넌트로 구성되지만, 설치 시 값을 채워야 하는 것은 §4~§10 의 소수입니다. 나머지는 배포본 기본값 그대로 두면 됩니다.

입력 파일과 솔루션 스택 파일의 관계

일반적인 설치 흐름에서 사용자가 직접 손대는 것은 입력 파일 (inputs/konanllm-input.prop, inputs/konanllm-input.multi.prop) 입니다.

inputs/konanllm-input.prop       ─┐
                                   │  install 단계의 매핑 yaml 기준으로 반영
inputs/konanllm-input.multi.prop ─┤
                                   ▼
                         stacks/Pulumi.my-site.yaml   ← 최종적으로 이 파일이 수정되어 배포에 반영됨
                                   │  Pulumi 가 읽어 실제 배포
                                   ▼
                             컴포넌트 컨테이너들

./instctl.sh install 은 입력 파일의 값을 매핑 yaml 기준으로 솔루션 스택 파일에 자동으로 반영한 뒤 배포까지 이어 갑니다. 따라서 일반적인 설치에서는 이 문서의 stack 키를 직접 편집할 필요가 없습니다 — 입력 파일과 대화식 입력 안내만으로 충분합니다.

언제 이 문서를 보는가

다음 경우에는 입력 파일만으로는 모자라, 이 문서를 기반으로 솔루션 스택 파일을 직접 손봐서 배포 하는 것을 권장합니다.

입력 흐름이 자동으로 채우지 않는 키를 조정해야 할 때
일반적이지 않은 상태로 컴포넌트가 떠 있어 특정 키를 강제로 바꿔야 할 때
문제 해결 / 일시적 우회를 위해 평소엔 안 건드리는 설정을 조정해야 할 때

처음 설치는 single-node 시작를, 단계별 절차는 install 동작 세부 설명를 참고하세요.

2. 솔루션 스택 파일이란

솔루션 스택 파일 은 한 번의 솔루션 설치 단위에 대한 모든 배포 설정을 담은 YAML 파일입니다. 번들의 stacks/ 디렉터리에 위치하며, 보통 stacks/Pulumi.my-site.yaml 같은 형태입니다.

stacks/
└── Pulumi.my-site.yaml      # 예: Pulumi.nhis-konanllm-prd-swarm.yaml

파일명에서 Pulumi. 뒤의 부분이 그 설치를 식별하는 이름이며, init / select / up / status 등 모든 명령이 이 이름을 통해 대상 스택을 찾습니다.

이 파일에 들어가는 주요 내용:

솔루션 / 버전 / 배포 플랫폼 같은 메타 정보 (다음 §3 의 공통 head 참조)
컴포넌트별 runtime 설정 — 이미지 태그, 외부 포트, license, host 배치, GPU UUID, env_overrides 등
비활성화할 컴포넌트 목록 (§12 disable_services)
external_files 매핑

누가 이 파일을 채우는가:

일반 설치 흐름에서는 ./instctl.sh install 이 입력 파일(inputs/konanllm-input.prop, inputs/konanllm-input.multi.prop)의 값을 매핑 yaml 기준으로 이 파일에 자동으로 반영합니다. 사용자가 직접 손댈 일이 없습니다.
자동 매핑 대상이 아닌 키를 조정하거나 일반적이지 않은 상태·문제 해결을 위해 특정 값을 강제로 바꿔야 할 때만, 이 문서 §4 이하의 컴포넌트별 참조를 보고 스택 파일을 직접 편집합니다.

누가 이 파일을 읽는가:

./instctl.sh up / preview / status / destroy 등이 실행될 때 Pulumi 가 이 파일을 읽어 실제 배포 / 변경 / 상태 조회를 수행합니다.

이 문서는 KonanLLM에서 실제로 자주 확인하는 설정만 설명합니다. 공통 개념은 본문 앞부분의 설명을 기준으로 읽으면 됩니다.

3. 공통 head 예시

config:
  konan:solution_version: "3.2.1-rc"
  konan:installer_version: "1.0.0"
  konan:deploy_platform: "SWARM"
  konan:solution: "konanllm"
  konan:disable_services: []

위 예시는 솔루션 스택 파일의 공통 head 예시입니다. 실제 운영 환경에서는 버전, 배포 플랫폼, 비활성화 컴포넌트 목록을 환경에 맞게 조정합니다.

이 문서의 이미지 주소에 대하여 — 아래 예시의 image 값은 배포본에 들어 있는 기본값입니다. 설치 시 retag.repo 를 지정해 사이트 내부 레지스트리로 옮긴 경우에는 그 주소로 바뀌므로, 실제 값은 사용 중인 솔루션 스택 파일을 기준으로 확인하세요.

4. `kylin-search`

kylin-search 는 host 고정 배치(deploy_hosts) 와 license 설정이 중요합니다.

konan:kylin_search_config:
  runtime:
    external_port: "10001"
    image: "docker.konantech.com/konanllm/kylin-search:26.05"
    license_server: 10.10.16.143:7580
    license_type: SI8gn
    deploy_hosts:
      - swarm-node-01
  env_overrides: {}

확인 포인트:

deploy_hosts — 검색 서비스를 고정 배치할 노드 목록. 한 노드만 지정하면 단일 노드 배치
license_server, license_type — 검색 라이선스 관련 값

단일 노드만 쓰는 경우 호환을 위해 단수 deploy_host: swarm-node-01 형태도 받지만, 신규 작성 시 deploy_hosts 사용을 권장합니다.

5. `kylin-gaia`

kylin-gaia는 모델 리포지터리 관련 설정을 자주 확인합니다.

konan:kylin_gaia_config:
  runtime:
    external_port: "8880"
    image: "docker.konantech.com/konanllm/kylin-gaia:v2.0.2-alpha.2-61-ge466779"
  env_overrides:
    COMMON_APP_ENV: "prd"
    COMMON_LOG_LEVEL: "DEBUG"
    COMMON_SITE_NAME: "any"
    # 노드별 GPU index 매핑. install 시 metis.init_group_gpus 입력으로 자동 채움.
    # 직접 값을 두려면 "<hostname>:gpu_index,gpu_index <hostname>:gpu_index,gpu_index" 형식으로 작성.
    METIS_INIT_GROUP_GPUS: "worker-a:0,1,2 worker-b:0,1,2"
  external_files:
    - source: model_repo/
      target_ref: MODEL_REPO_PATH

확인 포인트:

external_files로 준비되는 model_repo
METIS_INIT_GROUP_GPUS — 보통 손으로 적지 않고 install 시 metis.init_group_gpus 입력으로 자동 반영됩니다. swarm hostname 으로 정규화된 결과가 스택에 기록됩니다.

6. `kylin-docai-ocr`

OCR는 host와 GPU를 함께 지정하는 경우가 많습니다.

konan:kylin_docai_ocr_config:
  runtime:
    external_port: "10017"
    image: "docker.konantech.com/konanllm/kylin-docai-ocr:1.1.0"
    host: swarm-node-03
    gpu_uuid: GPU-d535ebe7-9371-a3cb-681b-72e92a7e5ef0
  env_overrides: {}
  external_files:
    - source: PP-DocLayoutV2/
      target_ref: LAYOUT_MODELS_PATH/PP-DocLayoutV2

확인 포인트:

host: OCR를 실행할 노드
gpu_uuid: 사용할 GPU
external_files: 레이아웃 모델 준비 여부

7. `kylin-docai-vllm`

vLLM은 backend별로 host와 GPU를 나눠 배치할 수 있습니다.

konan:kylin_docai_vllm_config:
  runtime:
    image: "release.konantech.com:5000/vllm-openai:v0.19.1"
    backends:
      - name: primary
        host: swarm-node-03
        gpu_uuid: GPU-d535ebe7-9371-a3cb-681b-72e92a7e5ef0
  env_overrides: {}
  external_files:
    - source: PaddleOCR-VL-Konan/
      target_ref: MODEL_WEIGHTS_PATH/PaddleOCR-VL-Konan
    - source: PaddleOCR-VL-1.5/
      target_ref: MODEL_WEIGHTS_PATH/PaddleOCR-VL-1.5

확인 포인트:

backends[].host
backends[].gpu_uuid
모델 웨이트 파일 준비 여부

8. `agent-server`

agent-server 는 api / worker 두 개의 service 로 구성되는 composite 컴포넌트입니다. runtime 블록도 세 개 그룹(common, api, worker) 으로 나뉘며, 공용 값은 common 에 두고 service 별로 다른 값만 각 그룹에 둡니다.

konan:agent_server_config:
  runtime:
    common:
      image: "docker.konantech.com/konanllm/agent-server:v1.1.0"
      graphs_path: "components/agent-server/graphs"
      logs_path: "components/agent-server/logs"
      graph_artifacts_path: "components/agent-server/graph_artifacts"
    api:
      external_port: "18001"
    worker: {}
  env_overrides:
    common: {}
    api: {}
    worker: {}

확인 포인트:

common.image — 두 service 가 같은 이미지로 동작
common.graphs_path — host 의 graph 정의 디렉토리 (workspace 기준 상대경로). setup 시 자동 생성. 컨테이너 안 /app/graphs 로 마운트
common.logs_path — 파일 로그 호스트 디렉토리. 컨테이너 안 /app/logs 로 마운트
common.graph_artifacts_path — graph 등록 시 capsule 산출물이 영속되는 호스트 경로. 컨테이너 안 /var/lib/agent-server/graph_artifacts 로 마운트. 멀티 노드 swarm 이면 worker 간 공유를 위해 NFS 같은 공유 저장소 필수
api.external_port — agent-server HTTP API 외부 노출 포트
api / worker 모두 replicas=1 고정. worker 에는 cron scheduler 가 켜져 있음 (CRON_ENABLED=true 기본)
env_overrides 는 role 별 override 도 가능. 공통 env 만 바꾸려면 common: 만 채움

환경변수는 기본값이 내장되어 있어 스택에 아무것도 적지 않아도 동작합니다. 사이트별로 바꿔야 하는 값만 env_overrides 에 채우세요.

9. `opensandbox-server` · `sandbox-workspace`

agent-server worker 가 사용자 코드를 격리 컨테이너에서 실행하기 위해 sandbox 관련 두 개의 컴포넌트가 필요합니다. agent-server 활성화 시 함께 활성화하지 않으면 sandbox 호출이 실패합니다.

konan:opensandbox_server_config:
  runtime:
    image: "release.konantech.com:5000/opensandbox-server:v0.1.8"
    external_port: "8090"
  env_overrides: {}

konan:sandbox_workspace_config:
  runtime:
    image: "release.konantech.com:5000/sandbox-workspace:v1.0.0"
    external_port: "18091"
    workspace_root_path: "components/sandbox-workspace/workspaces"
    staging_root_path: "components/sandbox-workspace/staging"
  env_overrides: {}

확인 포인트:

opensandbox-server.runtime.execd_image — 옵션 키. 별도 명시 안 하면 기본값(release.konantech.com:5000/opensandbox-execd:v1.0.15) 사용
sandbox-workspace.workspace_root_path / staging_root_path — host bind 경로. 멀티 노드 swarm 이면 NFS 등 공유 저장소 필수
추가로 agent-server env_overrides.common 의 OPENSANDBOX_URL / SANDBOX_WORKSPACE_URL 은 두 컴포넌트 service alias 와 일치해야 함 (기본값 사용 시 자동 정렬)

10. `dcgm-exporter`

GPU 모니터링을 위한 Application 으로 실제 GPU 가 존재하는 cluster node 의 host 이름을 정확히 등록해야 해당 host 에 배포됩니다.

konan:dcgm_exporter_config:
  runtime:
    image: "docker.konantech.com/konanllm/dcgm-exporter:4.2.3-4.1.3-ubuntu22.04"
    gpu_hosts:
      - swarm-node-01
      - swarm-node-02
      - swarm-node-03

11. 기본값으로 두는 컴포넌트

§4~§10 외 컴포넌트는 보통 스택 default 그대로 두고 image (이미지 태그 올림 정도) 만 만집니다. 역할과 자주 만지는 키를 그룹별로 묶어두니, 변경 전에 어떤 컴포넌트가 어떤 역할을 하는지 빠르게 확인할 때 보세요.

11.1 데이터 저장

컴포넌트	역할	자주 만지는 키
`postgresql`	application 들의 메타데이터 / 세션 DB. agent-server, kylin-service, gaia 가 모두 사용	`image`, `external_port`, `env_overrides.POSTGRES_PASSWORD`
`redis`	캐시 / pub-sub. agent-server, kylin-service 등이 사용	`image`, `external_port`
`lakefs`	로컬 object store + version control. konanllm 의 데이터 / 인덱스 자산 저장	`image`, `external_port`
`clickhouse`	OTel telemetry / 로그 저장. grafana datasource	`image`, `external_port`
`seaweedfs`	S3 호환 object store. langfuse 가 저장하는 미디어 파일 보관	`image`, `external_port`

11.2 Kylin 응용

컴포넌트	역할	자주 만지는 키
`kylin-service`	Kylin 솔루션 백엔드 API. studio / gateway 가 호출	`image`, `external_port`
`kylin-gateway`	외부 진입점 / proxy. 사용자 트래픽이 여기로 진입	`image`, `external_port`
`kylin-studio`	사용자 / 운영자 web UI	`image`, `external_port`
`kylin-batch`	정기 배치 작업 (인덱싱·정리 작업)	`image`, `external_port`
`kylin-docai`	DocAI 진입점 (DRM·파일 처리). docai-ocr / docai-vllm 을 묶어 호출	`image`, `external_port`
`kylin-crawler`	웹 / 소스 크롤러 (수집)	`image`, `external_port`, `env_overrides.MAX_PAGES`
`ks-chunker`	`kylin-search` 의 문서 청킹 담당. search 와 같은 노드에 자동 배치	`image`, `external_port`

11.3 관측·로깅

컴포넌트	역할	자주 만지는 키
`fluentd`	로그 수집·포워딩. kylin-gateway 로그를 clickhouse / otel 로 전달	`image`, `external_port`
`otel-collector`	OTel pipeline (gRPC 4317). 각 service 가 trace / metric 송신	`image`
`otel-file-collector`	파일 로그 수집 (ksearchd 같이 OTel SDK 미적용 service 용)	`image`
`prometheus`	메트릭 시계열 DB. node-exporter / dcgm-exporter 스크랩	`image`, `external_port`
`grafana`	observability 대시보드. clickhouse / prometheus 를 datasource 로 묶음	`image`, `external_port`, `env_overrides.GF_SECURITY_ADMIN_PASSWORD`
`node-exporter`	노드 host 메트릭 exporter (global mode, 모든 노드 1 개씩)	`image`
`langfuse`	LLM 호출 트레이싱 / 평가 UI. web + worker 2 service 로 구성	`image`, `external_port`, `public_host`

11.4 인프라 보조

컴포넌트	역할	자주 만지는 키
`node-id-init`	swarm 노드에 node-id label 부여 (1회 init job)	`image`
`docker-socket-proxy`	opensandbox-server 등이 호스트 docker 소켓에 안전하게 접근하도록 proxy	`image`
`litellm`	LLM 호출 프록시	`image`, `external_port`

11.5 RAGOps

ragops-server · ragops-collector · ragops-taskserver · ragops-gateway · ragops-client · ragops-taskserver-client 6개 컴포넌트가 KonanLLM 과 함께 설치됩니다. RAG 파이프라인 운영 도구로, 설정과 사용법은 RAGOps 매뉴얼을 참고하세요.

설치 관점에서 알아둘 것은 두 가지입니다.

문서 데이터를 kylin-search · ks-chunker · kylin-docai 와 공유 디렉터리로 주고받습니다. 기본값은 workspace 하위 경로라 별도 준비가 필요 없지만, multi-node 설치에서는 HOST_WORKSPACE_PATH 가 공유 저장소여야 합니다.
RAGOps 를 쓰지 않는 사이트는 §12 disable_services 에 위 6개를 추가해 제외합니다.

비고:

위 컴포넌트는 default 환경변수가 코드 안에 기본값으로 정의되어 있어 스택 파일이 비어 있어도 동작합니다. site 별 override 가 필요하면 env_overrides 만 채우면 됩니다.
컴포넌트 전체에서 빠뜨리고 싶은 항목은 §12 disable_services 로 처리합니다.

12. `disable_services`

일부 컴포넌트를 제외해야 할 때 사용합니다.

konanllm은 포함되는 컴포넌트가 많기 때문에, 아래 같은 경우 disable_services를 자주 사용합니다.

사이트별로 제외해야 하는 컴포넌트가 있을 때
특이 상황에서 특정 확장 기능을 이번 배포에서 제외하고 싶을 때
GPU나 외부 파일 준비가 끝나기 전 OCR/VLLM 계층을 잠시 제외하고 싶을 때

config:
  konan:disable_services:
    - grafana
    - kylin-crawler

위 예시는 grafana, kylin-crawler를 현재 배포에서 제외하는 경우입니다.

RAGOps 를 쓰지 않는 사이트는 6개를 함께 제외합니다.

config:
  konan:disable_services:
    - ragops-server
    - ragops-collector
    - ragops-taskserver
    - ragops-gateway
    - ragops-client
    - ragops-taskserver-client

13. `external_files` 준비 위치 예시

external_files/
├── kylin-gaia/
│   └── model_repo/
├── kylin-docai-ocr/
│   └── PP-DocLayoutV2/
└── kylin-docai-vllm/
    ├── PaddleOCR-VL-Konan/
    └── PaddleOCR-VL-1.5/

14. 자주 조정하는 항목

이미지 주소
외부 포트
disable_services
search host / license
OCR / vLLM GPU
agent-server worker replica·sandbox bind 경로
external_files 경로

15. 다음 문서

install 동작 세부 설명: 단계별 설치 절차
운영 포인트: 운영 명령 모음
install 입력 세부 설명: 입력 파일과 매핑 위치

KonanLLM 세부 설정

1. 문서 목적

입력 파일과 솔루션 스택 파일의 관계

언제 이 문서를 보는가

2. 솔루션 스택 파일이란

3. 공통 head 예시

4. kylin-search

5. kylin-gaia

6. kylin-docai-ocr

7. kylin-docai-vllm

8. agent-server

9. opensandbox-server · sandbox-workspace

10. dcgm-exporter

11. 기본값으로 두는 컴포넌트

11.1 데이터 저장

11.2 Kylin 응용

11.3 관측·로깅

11.4 인프라 보조

11.5 RAGOps

12. disable_services

13. external_files 준비 위치 예시

14. 자주 조정하는 항목

15. 다음 문서

4. `kylin-search`

5. `kylin-gaia`

6. `kylin-docai-ocr`

7. `kylin-docai-vllm`

8. `agent-server`

9. `opensandbox-server` · `sandbox-workspace`

10. `dcgm-exporter`

12. `disable_services`

13. `external_files` 준비 위치 예시