본문으로 건너뛰기

EVA Agent Dependencies

EVA Agent가 구동되기 위해 꼭 필요한 Dependencies(의존성) 설치 가이드입니다.

EVA Agent를 설치하기 전, 데이터 저장을 위한 Qdrant(벡터 DB)와 모델 추론을 위한 vLLM 인프라를 먼저 구축해야 합니다.

이 가이드는 EVA의 기초가 되는 의존성 패키지 설치 방법을 안내합니다.



설치 구조 이해하기​

성공적인 설치를 위해 각 패키지 간의 선후 관계를 확인해 주세요.

  1. eva-agent-init: 스토리지 클래스(Storage Class)를 정의합니다. (가장 먼저 설치)
  2. qdrant / vllm: 위에서 정의한 스토리지를 사용하여 데이터를 보관합니다.
  3. eva-agent: 위 서비스들이 모두 준비된 후 최종 설치됩니다.


사전 준비 사항​

설치에 필요한 CLI 도구들이 준비되어 있는지 확인해 주세요.



Helm 저장소 등록 및 업데이트​

필요한 모든 오픈소스 레포지토리를 등록하고 최신 상태로 유지합니다. EVA Agent를 설치할 namespace와 service account도 미리 설정해줍니다.

# 1. 각 레포지토리 추가
helm repo add qdrant https://qdrant.github.io/qdrant-helm
helm repo add vllm https://vllm-project.github.io/production-stack
helm repo add eva-agent https://mellerikat.github.io/eva-agent

# 2. 최신 정보 업데이트
helm repo update

# 3. EVA Agent 설치할 namespace 및 service account 설정
kubectl create namespace eva-agent
kubectl create serviceaccount sa-eva-agent -n eva-agent
kubectl -n eva-agent patch serviceaccount sa-eva-agent \
  -p '{"imagePullSecrets":[{"name":"ecr-pull"}]}'


1단계: eva-agent-init 설치​

이 패키지는 이후 설치할 Qdrant와 vLLM이 원활하게 데이터를 저장할 수 있도록 공통 Storage Class를 사전에 정의하는 매우 중요한 단계입니다.

  • 설정 파일 및 버전 참고:
  • values 템플릿: GitHub 저장소에서 환경별 설정 파일을 확인하실 수 있습니다.
  • Chart 버전 확인: 설치에 필요한 버전 정보는 env.tpl 파일을 참조해 주세요.
  • 패키지 역할:
  • eva-agent-vllm 및 eva-agent-qdrant가 데이터를 안전하게 보관할 수 있도록 전용 스토리지 클래스를 구성합니다.
  • 따라서 반드시 다른 패키지들보다 가장 먼저 설치되어야 합니다.

설정 파일(values) 다운로드 (eva-agent-init)​

위의 설정 파일을 GitHub 저장소에서 다운로드 받습니다. 사용하는 환경에 맞는 파일을 선택해 주세요.

EVA Agent의 버전(image tag)별로 values 템플릿이 정리되어 있습니다. Helm 차트와 image는 별개의 버전을 가집니다.

# k3s 환경 values 다운로드 예시
mkdir eva-agent-init
curl -L \
  "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.3-a3.0/1/eva-agent-init/values-k3s.yaml" \
  -o eva-agent-init/values-k3s.yaml

# k3s 환경 설치 예시
helm install eva-agent-init eva-agent/eva-agent-init \
  --version=1.0.0 \
  -n eva-agent \
  -f eva-agent-init/values-k3s.yaml


2단계: eva-agent-qdrant 설치​

벡터 데이터를 저장할 Qdrant DB를 설치합니다.

  • 설정 파일 및 버전 참고:
  • values 템플릿: GitHub 저장소에서 필요한 템플릿을 확인하세요.
  • Chart 버전 확인: 설치 시 필요한 정확한 버전 정보는 env.tpl 파일을 참조해 주시기 바랍니다.
  • 상세 Value 설명: Qdrant Helm 차트의 세부 파라미터는 Artifact Hub Qdrant 페이지에서 자세히 확인할 수 있습니다.
  • 데이터 관리 주의사항:
  • eva-agent-init에서 정의한 Storage Class를 사용하여 PVC와 PV가 동적으로 생성됩니다.
  • 한 번 생성된 PV는 환경을 삭제(uninstall)해도 데이터 보호를 위해 자동으로 삭제되지 않고 남게 됩니다.
  • 스토리지를 완전히 정리하려면 kubectl 명령어를 통해 직접 PVC 및 PV를 지워주셔야 합니다.

사용자 환경에 맞게 설정값 업데이트​

CategoryNameDescriptionOn-premise(K3s)Cloud(AWS)
스토리지persistence.sizeQdrant에 할당할 PVC 용량10Gi10Gi
스토리지persistence.annotationsPVC/PV 관련 annotation(필요 시 추가)
스토리지persistence.storageVolumeName(환경 구성에 따라) 사용할 PV/볼륨 식별용 이름eva-agent-qdrant-storageeva-agent-qdrant-storage
스케줄링nodeSelector특정 노드에만 스케줄링되도록 노드 라벨 선택자eks.amazonaws.com/nodegroup: ng-an2-eva-agent-db

설정 파일 다운로드 (eva-agent-qdrant)​

Qdrant에 적용할 values 및 post-renderer 파일 템플릿을 다운로드 합니다.

# k3s Qdrant 설치 예시
mkdir eva-agent-qdrant
curl -L \
  "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.3-a3.0/1/eva-agent-qdrant/values.yaml" \
  -o eva-agent-qdrant/values.yaml
curl -L \
  "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.3-a3.0/1/eva-agent-qdrant/values-aws.yaml" \
  -o eva-agent-qdrant/values-aws.yaml
curl -L \
  "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.3-a3.0/1/eva-agent-qdrant/post-renderer.sh" \
  -o eva-agent-qdrant/post-renderer.sh
chmod +x eva-agent-qdrant/post-renderer.sh

# AWS 환경인 경우 "-f eva-agent-qdrant/values-aws.yaml" 추가
helm install eva-agent-qdrant qdrant/qdrant \
  --version=1.15.0 \
  -n eva-agent \
  -f eva-agent-qdrant/values.yaml \
  --post-renderer eva-agent-qdrant/post-renderer.sh


3단계: eva-agent-vllm 설치​

모델 추론 서버인 vLLM을 설치합니다. (Agent 이미지 버전 2.2-a2.0 이상 필수)

  • 설정 파일 및 버전 참고:
  • values 템플릿: GitHub 저장소에서 확인 가능합니다.
  • Chart 버전 확인: 정확한 버전 값은 env.tpl 파일을 참조해 주세요.
  • 상세 Value 설명: 더 자세한 설정 옵션은 Artifact Hub vLLM-stack에서 보실 수 있습니다.
  • 핵심 설정: PVC/PV의 원활한 동적 할당을 위해 nodeSelector 설정이 올바른지 반드시 확인해 주세요.

💡 참고: eva-agent-init에서 정의한 Storage Class를 사용하여 PVC/PV를 생성합니다. 한 번 생성된 PV는 재설치 시에도 유지되지만, 완전히 삭제하려면 kubectl delete로 수동 정리해야 합니다.


사용자 환경에 맞게 설정값 업데이트​

아래의 표는 Nvidia L40s GPU 1장 서버를 기준으로 합니다.

CategoryNameDescriptionOn-premise(K3s)Cloud(AWS)
Serving EngineservingEngineSpec.runtimeClassName런타임 클래스 지정(예: GPU runtime)""""
Serving EngineservingEngineSpec.modelSpec서빙할 모델(엔진) 목록[][]
ModelservingEngineSpec.modelSpec.name모델 식별자(차트 내부에서 참조)"qwen3-vl-8b-fp8""qwen3-vl-8b-fp8"
ModelservingEngineSpec.modelSpec.modelURLHF 모델 경로"Qwen/Qwen3-VL-8B-Instruct-FP8""Qwen/Qwen3-VL-8B-Instruct-FP8"
ModelservingEngineSpec.modelSpec.repository사용할 vLLM 이미지 repo"vllm/vllm-openai""vllm/vllm-openai"
ModelservingEngineSpec.modelSpec.tagvLLM 이미지 tag"v0.11.0""v0.11.0"
AuthservingEngineSpec.modelSpec.serviceAccountName엔진 파드가 사용할 ServiceAccountsa-eva-agentsa-eva-agent
ScaleservingEngineSpec.modelSpec.replicaCount엔진 replica 수11
ResourcesservingEngineSpec.modelSpec.requestCPUCPU request44
ResourcesservingEngineSpec.modelSpec.requestMemoryMemory request"32Gi""28Gi"
ResourcesservingEngineSpec.modelSpec.requestGPUGPU request11
StorageservingEngineSpec.modelSpec.pvcStoragePVC 용량"30Gi""30Gi"
StorageservingEngineSpec.modelSpec.storageClassStorageClass 이름"eva-agent-sc-fs""eva-agent-sc-fs"
StorageservingEngineSpec.modelSpec.pvcAccessModePVC 접근 모드["ReadWriteMany"]["ReadWriteMany"]
vLLMservingEngineSpec.modelSpec.vllmConfig.hostvLLM 호스트 주소"0.0.0.0""0.0.0.0"
vLLMservingEngineSpec.modelSpec.vllmConfig.tensorParallelSize단일 모델이 사용할 GPU 갯수11
vLLMservingEngineSpec.modelSpec.vllmConfig.gpuMemoryUtilizationGPU 메모리 사용 비율0.70.7
vLLMservingEngineSpec.modelSpec.vllmConfig.maxModelLen최대 컨텍스트 길이1228812288
vLLMservingEngineSpec.modelSpec.vllmConfig.dtype모델 dtype 설정"auto""auto"
vLLMservingEngineSpec.modelSpec.vllmConfig.enableChunkedPrefillChunked prefill 활성화truetrue
vLLMservingEngineSpec.modelSpec.vllmConfig.enablePrefixCachingPrefix caching 활성화truetrue
vLLMservingEngineSpec.modelSpec.vllmConfig.extraArgsvllm serve 추가 인자• --served-model-name
• qwen3-vl-8b-fp8
• --kv-cache-dtype
• fp8
• --max-num-batched-tokens
• 4096		• --served-model-name
• qwen3-vl-8b-fp8
• --kv-cache-dtype
• fp8
• --max-num-batched-tokens
• 4096
SchedulingservingEngineSpec.modelSpec.nodeSelectorTerms엔진 파드 스케줄링 제약-matchExpressions: kubernetes.io/os In [linux] (AWS: eks nodegroup In [ng-an2-eva-agent-gpu])

⚠️ 주의: vllmConfig.extraArgs의 kv-cache-dtype은 Nvidia GPU의 아키텍쳐에 의존성이 있는 값으로 Ada 이전 아키텍쳐의 경우 반드시 "auto"로 설정 해야 합니다.

설정 파일 다운로드 (eva-agent-vllm)​

vLLM에 적용할 values 및 post-renderer 파일 템플릿을 다운로드 합니다. 아래 템플릿 중 공통 values.yaml와 values-k3s.yml 파일은 Nvidia A6000 GPU, values-aws.yaml 파일은 Nvidia L40s GPU 1장을 가진 서버를 기준으로 합니다. vLLM 관련 설정 값은 위의 표를 보고 GPU 서버의 스펙에 따라 변경해주셔야 합니다.

# k3s & vLLM
mkdir eva-agent-vllm
curl -L \
  "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.3-a3.0/1/eva-agent-vllm/values.yaml" \
  -o eva-agent-vllm/values.yaml
curl -L \
  "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.3-a3.0/1/eva-agent-vllm/values-k3s.yaml" \
  -o eva-agent-vllm/values-k3s.yaml
curl -L \
  "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.3-a3.0/1/eva-agent-vllm/post-renderer.sh" \
  -o eva-agent-vllm/post-renderer.sh
chmod +x eva-agent-vllm/post-renderer.sh

# AWS 환경인 경우 "-f eva-agent-qdrant/values-aws.yaml"로 변경
helm install eva-agent-vllm vllm/vllm-stack \
  --version=0.1.7 \
  -n eva-agent \
  -f eva-agent-vllm/values.yaml \
  -f eva-agent-vllm/values-k3s.yaml \
  --post-renderer eva-agent-vllm/post-renderer.sh