본문으로 건너뛰기

EVA Agent Release Note

v2.3+a3.0 (Dec 26, 2025)​

Highlights​

  • LangGraph 기반 아키텍처로 대규모 리팩토링: 새로운 app/ 레이어(API/Core/Graph/Node/Provider/Schema) 도입, GraphRegistry/GraphExecutor 추가, 버전 해석 기능이 포함된 YAML ConfigLoader 구현.
  • Visual Agent v1 전면 개편: basic_graph에서 1단계 및 2단계 서브 그래프를 병렬로 실행하여 결과를 통합하며, 선택적으로 번역 및 이미지 설명 생성을 단일 엔드투엔드 파이프라인으로 실행하도록 개선.
  • 강력해진 Feedback ↔ RAG 루프: /api/v1/agents/feedback/record 추가, 벡터 저장소 헬퍼/의존성 주입(DI) 추출, Visual 쿼리 후 벡터 검색을 수행하여 과거 피드백을 기반으로 알림을 교정하는 기능 추가.
  • 설정 시스템 재설계: config/{agent}/{graph}/{node}/{model}/{version}.yaml 구조로 표준화하고, Qwen3-VL (FP8) 설정을 추가했으며 호환성을 위해 기존 별칭(qwen2.5-vl-32b-awq) 유지.
  • 패키징 및 배포 기본값 업데이트: docker-compose의 기본 모델을 Qwen3-VL-8B-Instruct-FP8으로 변경하고 vLLM 성능 플래그 추가; eva-agent 이미지 태그를 2.3-a3.0으로 업데이트.

Breaking Changes​

  • API 스키마 및 페이로드 변경 (중요)

  • Visual 쿼리가 기존의 단일 vision.schemas.VisualQueryRequest/Response 흐름에서 app.schemas.visual_agent.VisualAgentRequest/Response로 이동 (scenario_list 기반, 통합 meta 모델 사용).

  • 피드백 기록 요청 스키마가 통합 meta를 중심으로 정렬되었으며, 엔드포인트가 /api/v1/agents/feedback/record로 노출됨.

  • 통합 meta 스키마가 app/schemas/common.py에서 Pydantic 모델로 강제 적용됨에 따라 클라이언트의 meta 페이로드 형식이 엄격하게 검증됨.

  • 설정 경로 및 파일 레이아웃 변경 (중요)

  • config/vlm/**, config/enrich_scenario/**, config/llm/prompts/conversational_agent_system_prompt.md와 같은 기존 설정 트리가 제거되거나 교체됨; 서버는 새로운 ConfigLoader 경로 규칙을 따름.

  • 환경 변수 정리

  • 더 이상 사용되지 않는 프로바이더/환경 변수(LLM_PROVIDER, LLM_MODEL, OLLAMA_BASE_URL 등)가 .env.eva-agent.sample에서 제거됨; 배포 시 업데이트된 샘플에 맞춰야 함.

  • 내부 모듈 경로 변경

  • src/messages/** 및 src/vision/detection_scenario/**와 같은 기존 코드가 제거되고 새로운 app 레이어로 교체됨; 내부 임포트 경로가 크게 변경됨.

  • 인프라 엔드포인트 제거

  • 기존의 /infra/models 엔드포인트가 제거됨 (main.py 리팩토링).

Features​

  • API 레이어

  • 라우터 모듈화 및 문서화: app/api/v1/{visual,chat,enrich,feedback} 및 app/api/dependency.py를 통한 RAG 엔진 및 벡터 저장소 설정 매핑 의존성 주입.

  • 422 검증 예외 처리기 추가 및 health/healthz 엔드포인트 제공.

  • Visual Agent

  • 다중 시나리오 요청: scenario_list 입력 및 analysis_list를 통한 시나리오별 결과 반환.

  • 벡터 검색 기반 알림 교정: 피드백 기반 퓨샷(few-shot) 데이터를 검색하여 알림을 조정; Langfuse 스팬(span)에 임베딩/검색/교정 단계를 기록.

  • 번역 파이프라인: 알림이 발생하면 이미지 설명 생성과 병렬로 TranslatorGraph를 통해 후보군만 번역 수행.

  • Enrich Agent

  • Enrich 그래프를 비동기 노드로 리팩토링하고, 출력 스키마/필드를 강화하며 영역(area) 및 메타데이터를 더 일관되게 반영.

  • (실험적) 다중 시나리오 보강: 분류기/분해기 기반의 케이스 분리 기능 추가.

  • 프로바이더 및 모델 카탈로그

  • (내부) 프로바이더별 모델 목록 개선 및 카탈로그 유틸리티 통합.

  • 관측 가능성 (Observability)

  • Visual-Agent/Feedback/Chat-Agent를 위한 강력한 Langfuse 트레이싱: 계층적 스팬, 트레이스 메타데이터 업데이트, 시나리오 컨텍스트 전파.

  • 콘텐츠 인식 이미지 마스킹: base64/데이터 URL뿐만 아니라 알려진 이미지 바이트 시그니처로 디코딩되는 페이로드까지 스크러빙 처리.

  • 문서화

  • README_DEV.md 추가 및 App/Core/Graph/Node 각 레이어별 가이드 제공.

Fixes​

  • Visual Agent 안정성 및 정확성

  • 2단계 인퍼런스 예외 상황, 정렬, 출력 스키마 문제 수정; 시나리오 순서 안정화.

  • None 영역 처리 및 언어 관련 문제 수정 (예: 영역 문자열에 영어 강제 적용).

  • 번역 로직(중복 생성/업데이트 버그) 및 출력 형식 수정.

  • Chat Agent UX 및 일관성

  • 지원되지 않는 요청 흐름 개선 및 시스템 답변에 작업 유형이 유출되는 문제 방지.

  • 감지 간격 단위/메시지 명확화, 오탐지 컷오프 범위 조정, 타겟 추출 및 검증 수정.

  • RAG/Qdrant

  • Qdrant URL/환경 변수 처리 및 관련 유틸리티(예: 베이스 URL 지원) 개선.

Config & Deployment​

  • Docker Compose

  • vLLM 기본 모델을 Qwen3-VL (FP8)로 교체하고 KV 캐시 데이터 타입, 청크 단위 프리필(prefill), 프리픽스 캐싱 등 플래그 추가.

  • eva-agent 이미지 버전을 eva-agent:2.3-a3.0으로 업데이트.

  • Config

  • 새로운 경로 규칙에 따라 Visual/Chat/Enrich/Translation Agent를 위한 대규모 버전별 YAML 설정 추가.

Tests & Quality​

  • Pre-commit 포맷팅 및 스타일 수정 적용 (black/isort, 공백 제거 등).

Upgrade Notes​

  • API 클라이언트

  • Visual 쿼리/피드백/보강/채팅 페이로드가 이제 통합 meta 모델을 기반으로 함; app/schemas/*.py를 기준으로 클라이언트를 업데이트해야 함.

  • Visual 쿼리는 이제 analysis_list를 통해 시나리오별 결과를 반환함; 기존의 단일 시나리오 응답 파싱 로직 업데이트 필요.

  • Config

  • 기존 config/vlm/** 및 config/enrich_scenario/** 설정을 새로운 규칙인 config/{agent}/{graph}/{node}/{model}/{version}.yaml로 마이그레이션 필요.

  • 환경 변수 및 Docker

  • 환경 변수를 .env.eva-agent.sample에 맞추고(지원 중단 변수 제거), docker-compose 기본 모델/옵션 변경에 따른 vLLM/Agent 설정 재검토 필요.

  • 로컬 실행(python main.py) 시 기본 포트는 8888임; 기존 포트나 헬스체크 설정을 확인해야 함.

v2.2+a2.0 (Oct 2, 2025)​

Highlights​

  • Visual, 시나리오 보강, 피드백 흐름 전반에 걸쳐 타입이 지정된 엔벨로프(envelope)와 Langfuse v3 관측 가능성을 적용한 Vision API v2 엔드투엔드 연결.
  • 기존 Ollama 지원과 더불어 새로운 OpenAI 프로바이더 및 팩토리 통합.
  • RAG 레이어 리팩토링: AsyncEmbeddingEngine 및 AsyncVectorStoreEngine 도입; 기존 AsyncSearchEngine 제거; ensure_space() 및 네임드 벡터(named-vectors) 흐름 추가.
  • Conversation Agent를 클래스 기반 작업으로 전면 리팩토링하여 의도/카테고리 라우팅 및 UX 중심의 제안 기능 개선.
  • 감지 시나리오 보강 파이프라인 통합 및 "enrich_scenario"로 명칭 변경; 사전 등록 흐름 지원을 위해 camera_id 처리 완화.
  • 일관되고 재현 가능한 환경을 위해 VLM (Qwen2.5-VL:32B v2.2.0) 및 RAG Visual Agent (v2.2.0)를 위한 새로운 버전별 설정 추가.

Breaking Changes​

  • Vision API 스키마

  • VisualQueryRequest에 vlm_model_name 필수 포함.

  • 퓨샷 템플릿이 이제 VLMScenarioAnalysis에서 파생됨; 필드 접근 방식 업데이트, feedback_content가 feedback_message로 변경됨.

  • ScenarioEnricher 결과가 래핑됨; VisualAgent는 타입이 지정된 엔벨로프(LanguageModelAgentResponse[T], ChainBuiltResult)를 반환함.

  • Feedback API v2: 요청 명칭 변경 및 확장 — camera_id 추가, feedback이 feedback_binary로 변경, 선택적 feedback_message 추가. main.py의 연결 구조 업데이트.

  • RAG/벡터 저장소

  • AsyncVectorStoreEngine 추가 및 AsyncSearchEngine 은퇴; 임베딩 프로토콜 분리 및 이름 변경.

  • 네임드 벡터 매핑 필수; 카메라별 공간을 위해 ensure_space() 호출 필요.

  • Conversation

  • IntentClassifier가 더 이상 RAG 컨텍스트를 가져오지 않음; 프롬프트 구성기 업데이트.

Features​

  • 관측 가능성 (Observability)

  • Langfuse v3 클라이언트 통합; 요청별 트레이스 ID; ainvoke 후 기록되는 프롬프트 미리보기; 이미지 스크러빙 기능.

  • 프로바이더

  • 테스트가 포함된 OpenAI 프로바이더 구현; 프로바이더 및 모델 이름을 추출하는 유틸리티 추가.

  • Conversation 작업

  • 신규 작업: 알림 간격 설정 및 피드백 유사도 임계값 설정 추가.

  • 작업 응답에서 다음 행동 제안: 예) 모니터링 시작, 임계값 조정 등.

  • Vision 및 보강

  • 시나리오 보강 메시지 및 스키마를 vision/detection_scenario 아래로 통합; 새로운 보강 설정 추가.

  • Visual Agent 메시지 빌더 분리; 퓨샷 템플릿 누락에 대한 가드 로직 추가.

  • Configuration

  • VLM qwen2.5vl:32b v2.1.2 및 v2.2.0 추가; RAG 설정 visual_agent v2.2.0 추가; imagePullSecrets 및 환경 패키지 CLI를 포함한 Helm 개선.

Fixes​

  • Conversation 라우팅 및 UX

  • AI 메시지에 대해서만 카테고리 감지 수행; 퀵 버튼 텍스트 정제; 밝기 전략 제거.

  • 타겟 설정 시 영어 타겟 강제 적용; 프롬프트 및 검증 세부 조정.

  • 알림 간격 기본값/단위 명확화; 최소값 및 변환 로직 테스트 포함.

  • Vision/보강 정확성

  • 감지 시나리오 언어를 쿼리와 일치시킴.

  • 렌더링된 프롬프트를 스팬 메타데이터에 보존하고 트레이스 업데이트 오류 수정.

  • 빌드 및 툴링

  • black 언어 버전 정리; pre-commit/스타일 수정.

v2.1+a1.2 (Sep 10, 2025)​

이 버전은 RAG 시스템 강화, 관측 가능성 및 트레이싱 개선, 개발 및 배포 경험 간소화에 중점을 둔 중요한 진전입니다.

Key Features​

  • 네임드 벡터 RAG 및 검색: RAG 시스템이 네임드 벡터를 지원하도록 업그레이드되었습니다. 이를 통해 이미지, 텍스트, 감지 시나리오 등 다양한 모달리티에 가중치를 둔 정교한 멀티모달 검색이 가능해져 더 정확한 결과를 제공합니다.

  • 피드백 인지 알림 교정: 사용자 피드백을 기반으로 알림을 지능적으로 교정하여 스스로 개선되는 피드백 루프를 구축했습니다.

  • LangFuse용 동적 Agent ID: 카메라 정보를 기반으로 동적 agent_id를 사용하여 트레이싱을 수행합니다. 이를 통해 다중 카메라 환경에서 요청 추적 및 디버깅이 훨씬 쉬워졌습니다.

  • 개발 및 배포 강화:

  • Docker 최적화: 빌드 속도 개선 및 로컬 개발을 위한 docker-compose 설정 개선.

  • 로컬 개발 스크립트: 핫 리로딩이 포함된 로컬 실행용 run_agent.sh 추가.

  • Ollama 모델 웜업: 컨테이너 시작 시 모델을 미리 로드하여 첫 요청 지연 시간 단축.

  • EKS 배포: Amazon EKS 배포를 위한 설정 작업 완료.

  • GENERAL_CONVERSATION 작업 제거: 지원되는 작업 목록에서 일반 대화 작업을 삭제했습니다.

v2.1+a1.1 (Aug 29, 2025)​

Summary​

RAG 임베딩 시스템과 Langfuse 트레이싱 통합 전반에 걸친 내부 시스템 최적화 및 정제를 통해 성능, 유지보수성, 일관성을 향상시켰습니다.

Key Changes​

  • RAG 임베딩 시스템 강화: 이미지 임베딩 효율성 개선을 위해 비동기 임베딩 프로바이더 레지스트리 리팩토링.
  • Langfuse 트레이싱 통합 개선: 이미지 데이터 처리 로직을 외부화하여 모듈성을 높이고 오버헤드 감소.
  • 환경 변수 로딩 표준화: 프로젝트 전반에서 예측 가능한 환경 설정을 위해 로딩 방식 표준화.

v2.1.0 (Aug 26, 2025)​

Added​

  • SET_TARGET 작업 로컬라이제이션: 타겟 설정 응답에 대한 다국어 지원.
  • 타겟 관리 작업: 타겟의 추가, 삭제, 설정을 위한 종합 관리 기능 도입.
  • 중앙 집중식 Langfuse 트레이싱: 디버깅을 위한 중앙 트레이싱 시스템 통합.
  • 대화 이력 활용: 문맥 인지를 위해 대화 이력을 Agent 프롬프트에 포함.
  • 동적 LLM 프로바이더: 다양한 LLM 백엔드 간 쉬운 전환 및 관리 메커니즘 추가.
  • 신규 대화 작업: ANSWER_SYSTEM_QUESTION (시스템 질문 답변), HANDLE_UNSUPPORTED_REQUEST (지원되지 않는 요청 처리) 추가.
  • VLM 프롬프트 설정: v2.1.0 등 다양한 VLM 프롬프트 버전 추가 및 관리.

v2.0.0 (Aug 8, 2025)​

대화형 및 Visual AI Agent인 EVA Agent의 첫 번째 공식 릴리즈입니다.

Added​

  • Conversational Agent: 의도 분류 및 동적 프롬프트 구성 기능이 포함된 대화형 Agent 구현.
  • Visual Agent: 구성 가능한 VLM 백엔드를 활용한 이미지 분석용 Agent 도입.
  • RAG 파이프라인: 지식 베이스의 컨텍스트를 활용하여 사용자 쿼리를 보강하는 파이프라인 구축.
  • 벡터 저장소: FAISS 및 Qdrant 통합 지원.
  • FastAPI 애플리케이션: RESTful API를 통해 기능을 서빙하는 견고한 애플리케이션 개발.
  • Docker 기반 배포: Ollama, Qdrant 등 의존성을 포함한 멀티 서비스 환경 구축.