EVA Agent Installation
EVA 서비스의 지능형 추론과 데이터 처리를 담당하는 핵심 컴포넌트입니다. 아래 단계에 따라 설정을 진행해 주세요.
🛠️ 사전 준비 사항
설치를 시작하기 전에 아래의 도구들이 준비되어 있는지 확 인해 주세요.
- Kubernetes 클러스터: EVA가 구동될 클러스터가 필요합니다.
- kubectl 설치: 설치 가이드 바로가기
- Helm 설치: 설치 가이드 바로가기
- AWS CLI 설정: ECR 이미지 접근 권한을 위해 AWS 자격 증명이 필요합니다. 터미널에서 아래 명령어를 입력하여 설정해 주세요.
aws configure
# 안내에 따라 AWS Access Key ID, Secret Access Key 등을 입력합니다.
🚀 EVA Agent 설치하기
1단계: Helm 저장소 등록 및 업데이트
최신 버전의 차트 를 가져오기 위해 레포지토리를 추가하고 업데이트합니다.
helm repo add eva-agent https://mellerikat.github.io/eva-agent
helm repo update
2단계: 설정 파일(values) 템플릿 다운로드
환경에 맞는 설정을 위해 필요한 템플릿 파일들을 다운로드합니다. 사용하는 환경(AWS 또는 K3s)에 맞는 파일을 선택해 주세요.
- 공통 values 템플릿 : https://github.com/mellerikat/eva-agent/blob/chartmuseum/release/2.3-a3.0/1/eva-agent/values.yaml
- 공통 secret values 템플릿 : https://github.com/mellerikat/eva-agent/blob/chartmuseum/release/2.3-a3.0/1/eva-agent/secret-values.yaml.tpl
- k3s specific values 템플릿 : https://github.com/mellerikat/eva-agent/blob/chartmuseum/release/2.3-a3.0/1/eva-agent/values-k3s.yaml
- aws specific values 템플릿 : https://github.com/mellerikat/eva-agent/blob/chartmuseum/release/2.3-a3.0/1/eva-agent/values-aws.yaml
# 1. 공통 기본 설정 및 시크릿 템플릿 다운로드
curl -L "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.3-a3.0/1/eva-agent/values.yaml" -o values.yaml
curl -L "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.3-a3.0/1/eva-agent/secret-values.yaml.tpl" -o values-secret.yaml
# 2. 클라우드(AWS) 환경인 경우
curl -L "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.3-a3.0/1/eva-agent/values-aws.yaml" -o values-aws.yaml
# 3. 온프레미스(K3s) 환경인 경우
curl -L "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.3-a3.0/1/eva-agent/values-k3s.yaml" -o values-k3s.yaml
3단계: 사용자 환경에 맞게 설정 업데이트
values.yaml과 values-secret.yaml 파일을 열어 주요 환경 변수를 수정합니다.
| Category | Name | Description | On-premise(K3s) | Cloud(AWS) |
|---|---|---|---|---|
| 실행환경 | image.tag | image tag | "2.3-a3.0" | "2.3-a3.0" |
| 실행환경 | replicaCount | replica count | 1 | 1 |
| 실행환경 | nodeSelector | node selector | eks.amazonaws.com/nodegroup: ng-an2-eva-agent | |
| 환경변수 | env MODEL_CATALOG_FILE | 사용 가능한 모델 리스트 설정 파일 경로 | config/model_catalog.json | config/model_catalog.json |
| 환경변수 | env VLLM_BASE_URL | vLLM 사용 시 endpoint (미사용 시 공란) | http://eva-agent-vllm-qwen3-vl-8b-fp8-engine-service/v1 | http://eva-agent-vllm-qwen3-vl-8b-fp8-engine-service/v1 |
| 환경변수 | env LLM_PROVIDER | LLM 모델을 서비스하는 제공자를 설정합니다. | vllm | vllm |
| 환경변수 | env LLM_MODEL | 서비스할 로컬 모델을 설정합니다. | qwen3-vl-8b-awq | qwen3-vl-8b-awq |
| 환경변수 | env QDRANT_HOST | Qdrant DB 서버 주소를 지정합니다. | http://eva-agent-qdrant | http://eva-agent-qdrant |
| 환경변수 | env QDRANT_PORT | Qdrant DB 포트 번호를 지정합니다. | "6333" | "6333" |
| 환경변수 | env OPENAI_API_TYPE | OpenAI API 형식 | azure | azure |
| 환경변수 | env OPENAI_API_VERSION | OpenAI API 버전 | 2025-04-01-preview | 2025-04-01-preview |
| 환경변수 | env AZURE_OPENAI_ENDPOINT | Azure OpenAI API endpoint | https://xxxx | https://xxxx |
| 환경변수 | env DEPLOYMENT_NAME | Azure 모델(deployment)명 | gpt-5-chat-2025-08-07 | gpt-5-chat-2025-08-07 |
| 환경변수 | env AZURE_MANAGEMENT_BASE_URL | Azure Management Endpoint (Azure asset 관리) | https://management.azure.com | https://management.azure.com |
| 환경변수(secret) | secretEnv.OPENAI_API_KEY | OpenAI API 키 (미사용 시에도 더미 값 필요 - 주석 처리 X) | ||
| 환경변수(secret) | secretEnv.AZURE_OPENAI_API_KEY | Azure OpenAI API 키 | ||
| 환경변수(secret) | secretEnv.AZURE_CLIENT_SECRET | Azure 등록 앱 자격 증명 (secret) | ||
| 환경변수(secret) | secretEnv.CLOVA_API_KEY | 네이버 Hyper Clova API 키 |
⚠️ 주의:
OPENAI_API_KEY등 Secret 항목은 미사용 시에도 더미 값을 넣어두어야 에러가 발생하지 않습니다. (주석 처리 금지)
4단계: EVA Agent 설치 실행
설정 파일을 모두 준비했다면 아래 명령어로 설치를 진행합니다. ECR 로그인 후 Helm 설치가 시작됩니다.
# 1. AWS ECR 로그인 (이미지 Pull 권한 확보)
NS=eva-agent
ACCOUNT_ID=339713051385
AWS_ECR_REGION=ap-northeast-2
AWS_ECR_HOST=${ACCOUNT_ID}.dkr.ecr.${AWS_ECR_REGION}.amazonaws.com
aws ecr get-login-password --profile default | docker login --username AWS --password-stdin $AWS_ECR_HOST
# 2. Helm Install 실행 (환경에 맞는 yaml 파일을 매칭하세요)
docker_config_file="$HOME/.docker/config.json"
values_file="$docker_config_file-values.yaml"
cat > "$values_file" << EOF
dockerConfig:
json: $(cat "$docker_config_file" | base64 -w0)
EOF
# --version은 Chart version임 (image 버전(tag) X)
helm install eva-agent eva-agent/eva-agent --version=2.1.2 -n eva-agent \
-f values.yaml \
-f values-k3s.yaml \
-f values-secret.yaml \
-f $values_file
rm -f "$values_file"
(참고: aws 환경이라면 values-k3s.yaml 대신 values-aws.yaml을 사용하세요.)
5단계: 설치 상태 확인
설치가 완료된 후 모든 서비스가 정상적으로 올라왔는지 확인합니다.
kubectl get all -n eva-agent