vnpy/vnpy (VeighNa) 딥다이브
— 브로커 접속과 전략을 이벤트 버스 하나로 묶는 퀀트 트레이딩 OS

1프로젝트 한 줄 요약

이 프로젝트는 두 개의 얼굴을 가진다. 하나는 얇은 코어 프레임워크(vnpy/ 패키지) — 이벤트 엔진, 메인 엔진, 게이트웨이·앱 추상 클래스, 주문관리 엔진(OMS)이 전부다. 다른 하나는 수십 개의 vnpy_* 확장 패키지 생태계 — 실제 브로커 접속(vnpy_ctp·vnpy_ib…), 전략 앱(vnpy_ctastrategy…), DB·데이터피드가 전부 별도 pip 패키지로 분리돼 있다. 코어는 "규격"만 정의하고, 실물은 플러그인으로 갈아 끼운다.

# 권장 설치: VeighNa Studio 올인원 인스톨러(윈도우) 또는
pip install vnpy                 # 코어 프레임워크
pip install vnpy_ctp             # CTP 선물 게이트웨이(플러그인)
pip install vnpy_ctastrategy     # CTA 전략 엔진(앱 플러그인)

코드로 시스템을 띄우는 최소 골격은 이렇게 생겼다. 이벤트 엔진 → 메인 엔진 → 게이트웨이/앱 등록 → GUI의 4단 조립이 항상 반복된다:

from vnpy.event import EventEngine
from vnpy.trader.engine import MainEngine
from vnpy.trader.ui import MainWindow, create_qapp
from vnpy_ctp import CtpGateway
from vnpy_ctastrategy import CtaStrategyApp

qapp = create_qapp()
event_engine = EventEngine()               # ① 배전반(이벤트 버스)
main_engine = MainEngine(event_engine)     # ② 오케스트레이터
main_engine.add_gateway(CtpGateway)        # ③ 브로커 접속 플러그인
main_engine.add_app(CtaStrategyApp)        # ③ 전략 앱 플러그인
window = MainWindow(main_engine, event_engine)  # ④ Qt GUI
window.showMaximized()
qapp.exec()

정리하면 VeighNa의 정체는 "백테스트 라이브러리"가 아니라 "라이브 트레이딩 플랫폼"이다. ① 이질적인 브로커들을 게이트웨이 추상화로 통일하고 ② 그 사이를 이벤트 버스로 느슨하게 연결하며 ③ 전략·백테스트·리스크·데이터관리를 플러그인 앱으로 갈아 끼운다. 값(시세·주문 처리)은 브로커의 C++ API가 내지만, 이 레포의 진짜 가치는 그 모든 이질성을 하나의 규격으로 묶은 아키텍처 그 자체에 있다.

2왜 주목받는가

VeighNa가 다시 트렌딩에 오른 건 신생 레포라서가 아니다. 정반대로 2015년부터 10년을 버틴 프로젝트(⭐ 약 43.7k, 포크 12.2k)가 4.0에서 "By Traders, For Traders, AI-Powered"를 내걸고 세대교체했기 때문이다. 그 무게를 떠받치는 사실들은 이렇다.

둘째, 트렌딩을 만든 진짜 방아쇠는 4.0에서 추가된 AI/ML 모듈 vnpy.alpha다. 10주년을 기념해 넣은 이 모듈은 멀티팩터 머신러닝 전략을 개발·연구·실전까지 한 곳에서 돌리게 한다. 설계는 마이크로소프트의 퀀트 프레임워크 Qlib에서 영감을 받았고, Qlib의 유명한 Alpha 158 팩터 세트까지 이식했다.

셋째, 여전히 살아 움직이는 유지보수다. 최신 4.4.0은 numpy 2.x·pandas 2.2·Python 3.13까지 따라가고, QuestDB 데이터베이스 어댑터(vnpy_questdb)와 WeChat(위챗) 알림 엔진을 새로 넣었으며, macOS 지원까지 확장했다. 열린 이슈가 21개뿐일 만큼 촘촘하게 관리된다. 10년 된 코드베이스가 최신 런타임을 이 정도로 바짝 따라가는 건 드문 일이다.

3기술 스택 전체 지도

VeighNa의 스택은 "얇은 코어 + 두꺼운 생태계"다. 코어 이벤트 엔진은 외부 의존성 없이 파이썬 표준 threading·queue만으로 돌아간다. 무거운 것들(GUI·차트·DB·ML)은 전부 선택적 계층으로 얹힌다. 계층별로 훑어보자.

백엔드 · 코어 (이벤트 엔진 = 심장)

프론트엔드 · GUI (Qt6 데스크톱)

VeighNa는 웹앱이 아니라 데스크톱 GUI 애플리케이션이다. 이 계층은 세 조각으로 이뤄진다. ① PySide6 == 6.8.2.1 — Qt6 바인딩. 버전이 정확히 고정된 이유는, C++로 컴파일된 게이트웨이 확장과 ABI(바이너리 호환성)를 맞춰야 하기 때문이다. ② pyqtgraph ≥ 0.13.7 — vnpy/chart가 이걸로 대용량 K라인(캔들) 차트를 실시간 갱신까지 되게 그린다(CandleItem·VolumeItem). ③ qdarkstyle — 트레이더가 밤새 보는 다크 테마. 참고로 vnpy_webtrader 앱을 붙이면 REST + WebSocket 서버가 떠서 웹 UI로도 쓸 수 있지만, 그건 별도 플러그인이다.

데이터 · 인프라 (전부 vnpy_* 플러그인)

4아키텍처 심화 분석

전체 구조의 한 문장 요약: MainEngine이 오케스트레이터, EventEngine이 신경망, 나머지(게이트웨이·엔진·앱)는 그 위에 등록되는 참여자다. 핵심은 참여자들이 서로를 직접 호출하지 않는다는 것 — 오직 이벤트 큐를 통해서만 대화한다.

핵심 설계 패턴 ① — 이벤트 드리븐 디커플링

이벤트 엔진의 심장은 30줄 남짓이다. 큐에서 사건을 꺼내(_run), 타입별 핸들러와 범용 핸들러에게 뿌린다(_process). 게이트웨이가 시세를 받으면 전략을 직접 부르는 게 아니라, 그냥 큐에 put할 뿐이다. 누가 그 시세를 받을지는 register한 쪽이 결정한다 — 발신자와 수신자가 서로를 모른다.

# vnpy/event/engine.py — 이벤트 루프의 핵심
def _run(self):
    while self._active:
        try:
            event = self._queue.get(block=True, timeout=1)
            self._process(event)
        except Empty:
            pass

def _process(self, event):
    if event.type in self._handlers:
        [handler(event) for handler in self._handlers[event.type]]
    if self._general_handlers:
        [handler(event) for handler in self._general_handlers]

핵심 설계 패턴 ② — 게이트웨이 추상화 + 이중 이벤트 발행

BaseGateway는 모든 브로커가 지켜야 할 계약이다. connect·subscribe·send_order·cancel_order·query_account·query_position은 반드시 구현하고, 데이터가 들어오면 on_tick·on_order·on_trade 같은 콜백으로 이벤트 엔진에 "밀어 넣는다". 영리한 부분은 같은 데이터를 두 번 발행한다는 것: 범용 이벤트(EVENT_TICK)와, vt_symbol이 붙은 종목별 이벤트(EVENT_TICK + "IF2312.CFFEX")를 함께 던진다.

# vnpy/trader/gateway.py — 왜 두 번 발행하나?
def on_tick(self, tick):
    self.on_event(EVENT_TICK, tick)                    # ① 모두에게(OMS·모니터)
    self.on_event(EVENT_TICK + tick.vt_symbol, tick)   # ② 이 종목 구독자에게만

def on_event(self, type, data=None):
    event = Event(type, data)
    self.event_engine.put(event)                       # 큐에 던지고 끝

이 이중 발행 덕분에, 특정 종목만 매매하는 전략은 EVENT_TICK + vt_symbol만 구독해 자기 종목 틱만 받는다. 수천 종목의 시세가 흘러도 매번 필터링(O(n))할 필요 없이, 이벤트 이름으로 O(1) 라우팅이 된다.

핵심 설계 패턴 ③ — OMS는 "모든 데이터 이벤트를 구독하는 상황판"

OmsEngine은 초기화 때 모든 데이터 이벤트의 핸들러로 자기를 등록한다. 그래서 시스템에 흐르는 틱·주문·체결·포지션·잔고·계약정보가 전부 OMS의 메모리 딕셔너리에 최신 상태로 쌓인다. 그리고 MainEngine은 OMS의 조회 메서드(get_tick·get_contract·get_all_active_orders…)를 자기 몸에 바인딩해, 외부에선 main_engine.get_tick(...)처럼 투명하게 쓰게 한다.

# vnpy/trader/engine.py — OMS가 모든 데이터 이벤트를 구독
def register_event(self):
    self.event_engine.register(EVENT_TICK, self.process_tick_event)
    self.event_engine.register(EVENT_ORDER, self.process_order_event)
    self.event_engine.register(EVENT_TRADE, self.process_trade_event)
    self.event_engine.register(EVENT_POSITION, self.process_position_event)
    self.event_engine.register(EVENT_ACCOUNT, self.process_account_event)
    self.event_engine.register(EVENT_CONTRACT, self.process_contract_event)

def process_tick_event(self, event):
    tick = event.data
    self.ticks[tick.vt_symbol] = tick   # 최신 틱을 상황판에 갱신

데이터 흐름 — 틱 하나의 왕복

핵심은 모든 화살표가 이벤트 큐를 통과한다는 것이다. 게이트웨이는 전략의 존재를 모르고, 전략은 게이트웨이의 종류를 모른다. 이 완전한 디커플링이 "백테스트 코드 = 실전 코드"를 가능하게 하는 근본 이유다 — 백테스트 엔진도 그저 또 하나의 이벤트 소스일 뿐이다.

5디렉토리 구조 해부

구조가 말해 주는 것: 책임이 칼같이 나뉘어 있다. event/는 순수 메시징(트레이딩을 전혀 모름), trader/는 트레이딩 도메인(주문·포지션·거래소), alpha/는 ML, rpc/는 분산, chart/는 시각화. 이렇게 한 패키지 = 한 관심사로 쪼갠 덕에, 이벤트 엔진만 떼어다 다른 프로젝트에 써도 될 만큼 독립적이다. 그리고 앞서 강조했듯 게이트웨이·앱·DB·데이터피드는 이 트리에 없다 — 전부 별도 vnpy_* 패키지로, datafeed.py의 동적 로더가 런타임에 import_module("vnpy_" + 이름)으로 불러온다(없으면 pip install vnpy_xxx 안내를 띄우고 우아하게 실패).

6학습 포인트

실습 아이디어 (짧게)

vnpy/event/engine.py를 처음부터 끝까지 읽어라(200줄 미만). 그 다음 trader/gateway.py의 on_tick/on_order 이중 발행과, trader/engine.py의 OmsEngine.register_event가 어떻게 짝을 이루는지 따라가 보라. 이 둘만 연결해서 봐도 "이벤트를 던지는 쪽 ↔ 구독하는 쪽"의 전체 그림이 완성된다.

7시스템 / 실행 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크