原创内容第2篇，专注AI量化投资、指标信号可视化与策略研发。

写在前面

上一篇文章我们聊了整个AI量化交易系统的全貌，今天我们就开始动手，从最基础的开发环境搭建开始。

说实话，刚开始接触vnpy的时候，我也被各种安装问题搞得头疼。网上的教程要么过时了，要么写得太简单，遇到问题就不知道怎么办。所以这次我决定把整个安装过程完整记录下来，包括可能遇到的坑和解决方案。

项目开源地址：https://github.com/seasonstar/atmquant

我已经将完整的ATMQuant项目代码开源到GitHub上，包含本文提到的所有脚本和配置文件。欢迎大家直接下载使用，项目会持续更新，跟随文章进度不断完善功能。

为什么选择vnpy

在开始安装之前，先简单说说为什么选择vnpy作为我们的开发框架。

vnpy是国内最成熟的开源量化交易框架，已经发展了十年。最新的4.1版本不仅支持传统的CTA策略，还新增了AI量化模块，这正好符合我们的需求。更重要的是，它有完整的中文文档和活跃的社区，遇到问题比较容易找到解决方案。

环境准备

系统要求

首先确认一下系统要求：

• 操作系统：Windows 11以上 / Ubuntu 22.04 LTS以上 / macOS（我用的是macOS）

• Python版本：3.10以上，推荐3.13，我这里用的是3.11.9

让我先检查一下当前的Python环境：

python3 --version
# Python 3.11.9

which python3
# /Library/Frameworks/Python.framework/Versions/3.11/bin/python3

看起来环境符合要求。

下载vnpy源码

vnpy提供了两种安装方式：

1. 直接使用VeighNa Studio（集成环境）

2. 手动安装（我们选择这种方式，更灵活）

我们从GitHub下载最新的4.1.0版本：

# 如果你还没有clone，可以这样做
git clone https://github.com/vnpy/vnpy.git
cd vnpy
git checkout v4.1.0

不过我这里已经有了vnpy的源码，让我看看当前的版本： 好的 ，我这里已经有了vnpy 4.1.0的源码。让我看看项目结构：

ls -la

可以看到有三个安装脚本：

• install.bat - Windows安装脚本

• install.sh - Linux安装脚本

• install_osx.sh - macOS安装脚本

我们用的是macOS，所以看看这个脚本做了什么：

cat install_osx.sh

脚本内容很简洁，主要做了几件事：

1. 升级pip和wheel

2. 安装ta-lib依赖（通过homebrew）

3. 安装numpy和ta-lib的Python包

4. 安装vnpy本身

开始安装

第一步：检查并安装homebrew

在macOS上，ta-lib需要通过homebrew安装。如果你还没有homebrew，先安装它：

# 检查是否已安装homebrew
which brew

如果没有安装，运行：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

第二步：创建虚拟环境（推荐）

虽然可以直接在系统Python环境中安装，但我强烈建议创建一个专门的虚拟环境：

# 创建虚拟环境
python3 -m venv vnpy_env

# 激活虚拟环境
source vnpy_env/bin/activate

# 确认Python版本
python --version

第三步：运行安装脚本

现在开始真正的安装过程：

# 激活虚拟环境
source vnpy_env/bin/activate

# 运行安装脚本
bash install_osx.sh

安装过程中你会看到类似这样的输出：

Looking in indexes: https://pypi.vnpy.com
Requirement already satisfied: pip in ./vnpy_env/lib/python3.11/site-packages (24.0)
Collecting pip
  Downloading https://pypi.vnpy.com/packages/pip-25.2-py3-none-any.whl (1.8 MB)
...
Warning: ta-lib 0.6.4 is already installed and up-to-date.
...
Successfully installed vnpy-4.1.0

整个安装过程大概需要5-10分钟，主要时间花在下载PySide6（Qt界面库）上，这个包比较大。

第四步：验证安装

安装完成后，我们来验证一下是否安装成功：

# 检查vnpy版本
python -c "import vnpy; print(f'vnpy version: {vnpy.__version__}')"
# 输出：vnpy version: 4.1.0

# 测试核心模块导入
python -c "from vnpy.trader.engine import MainEngine; print('MainEngine imported successfully')"
# 输出：MainEngine imported successfully

如果这两个命令都能正常运行，说明vnpy安装成功了！

可能遇到的问题和解决方案

在安装过程中，我遇到了一些小问题，这里分享一下解决方案：

问题1：ta-lib安装失败

如果你看到类似这样的错误：

error: Microsoft Visual C++ 14.0 is required

解决方案：

• Windows：安装Visual Studio Build Tools

• macOS：确保安装了Xcode Command Line Tools：xcode-select --install

• Linux：安装build-essential：sudo apt-get install build-essential

问题2：PySide6下载慢

PySide6包比较大（几百MB），如果下载慢可以：

1. 使用国内镜像源：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ pyside6

1. 或者手动下载wheel文件后本地安装

问题3：权限问题

如果遇到权限错误，不要使用sudo，而是：

1. 确保使用虚拟环境

2. 检查目录权限

3. 使用--user参数安装到用户目录

创建第一个测试脚本

安装完成后，我们创建一个完整的测试脚本来验证环境。

test_vnpy.py完整代码：（也可以直接从GitHub项目中下载：https://github.com/seasonstar/atmquant）

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
vnpy环境测试脚本
测试vnpy核心功能是否正常工作
"""

import sys
from datetime import datetime

def test_vnpy_import():
    """测试vnpy核心模块导入"""
    print("=" * 50)
    print("测试vnpy模块导入...")
    
    try:
        import vnpy
        print(f"✓ vnpy版本: {vnpy.__version__}")
    except ImportError as e:
        print(f"✗ vnpy导入失败: {e}")
        returnFalse
    
    try:
        from vnpy.trader.engine import MainEngine
        print("✓ MainEngine导入成功")
    except ImportError as e:
        print(f"✗ MainEngine导入失败: {e}")
        returnFalse
    
    try:
        from vnpy.event import EventEngine
        print("✓ EventEngine导入成功")
    except ImportError as e:
        print(f"✗ EventEngine导入失败: {e}")
        returnFalse
    
    try:
        from vnpy.trader.object import TickData, BarData
        print("✓ 数据对象导入成功")
    except ImportError as e:
        print(f"✗ 数据对象导入失败: {e}")
        returnFalse
    
    returnTrue

def test_dependencies():
    """测试关键依赖库"""
    print("\n" + "=" * 50)
    print("测试关键依赖库...")
    
    dependencies = [
        ("numpy", "数值计算库"),
        ("pandas", "数据分析库"),
        ("talib", "技术分析库"),
        ("PySide6", "GUI界面库"),
        ("pyqtgraph", "图表库"),
        ("plotly", "可视化库")
    ]
    
    success_count = 0
    for lib_name, description in dependencies:
        try:
            if lib_name == "talib":
                import talib
            elif lib_name == "PySide6":
                import PySide6
            else:
                __import__(lib_name)
            print(f"✓ {lib_name}: {description}")
            success_count += 1
        except ImportError as e:
            print(f"✗ {lib_name}: {description} - 导入失败: {e}")
    
    print(f"\n依赖库测试结果: {success_count}/{len(dependencies)} 成功")
    return success_count == len(dependencies)

def test_basic_functionality():
    """测试基本功能"""
    print("\n" + "=" * 50)
    print("测试基本功能...")
    
    try:
        from vnpy.event import EventEngine
        from vnpy.trader.engine import MainEngine
        
        # 创建事件引擎
        event_engine = EventEngine()
        print("✓ 事件引擎创建成功")
        
        # 创建主引擎
        main_engine = MainEngine(event_engine)
        print("✓ 主引擎创建成功")
        
        # 测试数据对象创建
        from vnpy.trader.object import TickData
        from vnpy.trader.constant import Exchange
        
        tick = TickData(
            symbol="rb2501",
            exchange=Exchange.SHFE,
            datetime=datetime.now(),
            gateway_name="test"
        )
        print("✓ 数据对象创建成功")
        
        # 清理资源
        main_engine.close()
        event_engine.stop()
        print("✓ 资源清理成功")
        
        returnTrue
        
    except Exception as e:
        print(f"✗ 基本功能测试失败: {e}")
        returnFalse

def main():
    """主测试函数"""
    print("vnpy环境测试开始...")
    print(f"Python版本: {sys.version}")
    print(f"测试时间: {datetime.now()}")
    
    # 运行所有测试
    tests = [
        ("模块导入测试", test_vnpy_import),
        ("依赖库测试", test_dependencies),
        ("基本功能测试", test_basic_functionality)
    ]
    
    passed_tests = 0
    for test_name, test_func in tests:
        try:
            if test_func():
                passed_tests += 1
                print(f"\n{test_name}: ✓ 通过")
            else:
                print(f"\n{test_name}: ✗ 失败")
        except Exception as e:
            print(f"\n{test_name}: ✗ 异常 - {e}")
    
    print("\n" + "=" * 50)
    print(f"测试总结: {passed_tests}/{len(tests)} 项测试通过")
    
    if passed_tests == len(tests):
        print("🎉 恭喜！vnpy环境配置完全正确！")
        returnTrue
    else:
        print("⚠️  部分测试失败，请检查安装配置")
        returnFalse

if __name__ == "__main__":
    success = main()
    sys.exit(0if success else1)

运行测试：

python test_vnpy.py

如果看到这样的输出，说明一切正常：

vnpy环境测试开始...
Python版本: 3.11.9
测试时间: 2025-08-15 15:36:19.050890
==================================================
测试vnpy模块导入...
✓ vnpy版本: 4.1.0
✓ MainEngine导入成功
✓ EventEngine导入成功
✓ 数据对象导入成功

模块导入测试: ✓ 通过
...
🎉 恭喜！vnpy环境配置完全正确！

启动vnpy图形界面

环境验证通过后，我们可以启动vnpy的图形界面看看效果：

python main.py

如果一切正常，你会看到类似这样的输出：

============================================================
ATMQuant - AI量化交易系统
基于vnpy 4.1框架
============================================================
✓ vnpy核心模块导入成功
✓ 事件引擎创建成功
✓ 主引擎创建成功
✓ 图形界面启动成功

🎉 ATMQuant启动完成！

然后会弹出vnpy的主界面：

vnpy主界面

这个界面包含了：

• 菜单栏：系统、功能、帮助等主要菜单

• 工具栏：常用功能的快捷按钮

• 状态栏：显示系统运行状态

• 主工作区：后续会显示账户、持仓、日志等内容

虽然现在界面比较空，但这说明vnpy已经成功运行了。后续我们会逐步添加CTP接口、策略引擎等功能，界面会变得更加丰富。

vnpy源码整合与项目重构

安装验证完成后，我们需要进行一个重要的步骤：将vnpy源码整合到我们的项目中。这样做的目的是为了后续的二次开发和定制化需求。

为什么要整合vnpy源码

在实际的量化交易开发中，我们经常需要：

• 修改vnpy的核心功能以适应特定需求

• 添加自定义的图表组件和指标

• 优化交易执行逻辑

• 集成第三方数据源和AI分析模块

如果只是通过pip安装vnpy，我们就无法进行这些深度定制。因此，我们需要将vnpy源码纳入项目管理。

项目重构过程

第一步：清理vnpy安装包中的非核心文件

vnpy的GitHub仓库包含很多我们不需要的文件，比如：

• 安装脚本（install_*.sh, install.bat）

• 项目配置文件（pyproject.toml, setup.py）

• GitHub相关文件（.github/目录）

• 文档文件（docs/目录，我们有自己的文档体系）

• 示例文件（examples/目录，我们会创建自己的示例）

我手动清理了这些文件，只保留了vnpy的核心源码目录。

第二步：保留vnpy核心模块

保留的vnpy核心目录结构：

vnpy/                              # vnpy核心框架
├── vnpy/                          # 主要源码包
│   ├── __init__.py
│   ├── alpha/                     # AI量化模块
│   ├── chart/                     # 图表模块
│   ├── event/                     # 事件引擎
│   ├── rpc/                       # RPC通信
│   └── trader/                    # 交易核心
├── LICENSE                        # 开源协议
└── README.md                      # 基本说明

第三步：为vnpy插件预留空间

未来我们可能需要安装各种vnpy插件，比如：

• vnpy_ctp/ - CTP接口插件

• vnpy_ctastrategy/ - CTA策略引擎

• vnpy_ctabacktester/ - CTA回测引擎

• vnpy_rqdata/ - RQData数据插件

• vnpy_tqsdk/ - 天勤数据插件

这些插件都会以vnpy_*的形式存在于项目根目录中。

建立基础工程规范

完成vnpy源码整合后，我们需要建立一套标准化的工程规范。这不仅是为了代码的可维护性，也是为了后续的教学和内容创作。

项目目录结构

基于实际的量化交易开发需求，我们设计了以下目录结构：

atmquant/                          # 项目根目录
├── 📁 core/                        # 核心业务模块
│   ├── 📁 charts/                  # 图表相关(定制化图表)
│   │   ├── chart_manager.py
│   │   ├── kx_chart.py
│   │   ├── chart_items.py
│   │   └── smart_money_channels.py
│   ├── 📁 data/                    # 数据处理核心
│   │   ├── future_data/            # 期货数据
│   │   └── processors/             # 数据处理器
│   └── 📁 strategies/              # 策略相关
│       └── base/                   # 基础策略类
├── 📁 config/                      # 统一配置管理
│   ├── strategies.json             # 策略配置
│   ├── accounts.py                 # 账户配置
│   ├── symbols.py                  # 品种配置
│   └── settings.py                 # 系统设置
├── 📁 scripts/                     # 运行脚本
│   ├── run_trader.py               # 交易主程序
│   ├── run_download.py             # 数据下载
│   └── maintenance/                # 维护脚本
├── 📁 backtests/                   # 回测相关
│   ├── results/                    # 回测结果
│   ├── strategies/                 # 批量回测脚本
│   └── reports/                    # 回测报告
├── 📁 utils/                       # 工具模块
├── 📁 tests/                       # 测试文件
│   ├── unit/                       # 单元测试
│   ├── integration/                # 集成测试
│   └── backtest/                   # 回测测试
├── 📁 docs/                        # 文档目录
├── 📁 articles/                    # 公众号文章
├── 📁 logs/                        # 日志文件
├── 📁 vnpy/                        # VeighNa框架源码
│   └── vnpy/                       # vnpy核心包
│       ├── alpha/                  # AI量化模块
│       ├── chart/                  # 图表模块
│       ├── event/                  # 事件引擎
│       ├── rpc/                    # RPC通信
│       └── trader/                 # 交易核心
├── 📁 vnpy_*/                      # vnpy插件(按需安装)
│   ├── vnpy_ctp/                   # CTP接口插件
│   ├── vnpy_ctastrategy/           # CTA策略引擎
│   └── vnpy_ctabacktester/         # CTA回测引擎
├── 📄 main.py                      # 主入口文件
├── 📄 requirements.txt             # 依赖包
└── 📄 README.md                    # 项目说明

目录结构说明

数据存储策略：

• 我们使用MySQL数据库进行数据存储，不需要本地data目录

• 所有市场数据、tick数据等都存储在数据库中

• 这样可以更好地管理数据的一致性和并发访问

vnpy源码管理：

• vnpy/ - 包含vnpy框架的完整源码，便于二次开发和定制

• vnpy_*/ - vnpy生态的各种插件，根据需要安装和配置

• 这种结构让我们既能使用vnpy的强大功能，又能进行深度定制

测试管理：

• tests/ - 统一管理所有测试文件

• 按测试类型分类：单元测试、集成测试、回测测试

• 便于持续集成和质量保证

代码规范

为了保证代码质量和一致性，我们制定以下规范：

1. 命名规范

• 文件名：使用小写字母和下划线，如ma_strategy.py

• 类名：使用驼峰命名，如MovingAverageStrategy

• 函数名：使用小写字母和下划线，如calculate_ma

• 常量：使用大写字母和下划线，如DEFAULT_PERIOD

2. 注释规范

class MovingAverageStrategy:
    """
    移动平均线策略
    
    基于双均线交叉的经典策略实现
    当短期均线上穿长期均线时买入，下穿时卖出
    
    参数:
        fast_period: 快速均线周期，默认10
        slow_period: 慢速均线周期，默认20
    """
    
    def __init__(self, fast_period: int = 10, slow_period: int = 20):
        """初始化策略参数"""
        self.fast_period = fast_period
        self.slow_period = slow_period

3. 类型注解

from typing import Dict, List, Optional
from vnpy.trader.object import BarData, TickData

def calculate_indicators(bars: List[BarData]) -> Dict[str, float]:
    """
    计算技术指标
    
    Args:
        bars: K线数据列表
        
    Returns:
        包含各种指标值的字典
    """
    pass

版本控制规范

Git提交规范

• feat: 新功能

• fix: 修复bug

• docs: 文档更新

• style: 代码格式调整

• refactor: 代码重构

• test: 测试相关

示例：

git commit -m "feat: 添加双均线策略实现"
git commit -m "fix: 修复K线数据缺失问题"
git commit -m "docs: 更新策略使用文档"

测试规范

• 所有核心功能都要有对应的测试

• 使用Python标准的unittest框架

• 测试文件统一放在tests目录下

• 按功能模块组织测试文件

实际开发建议

基于我的实际使用经验，给大家几个建议：

1. 从简单开始

不要一开始就想着做复杂的AI策略。先从简单的均线策略开始，熟悉vnpy的基本流程。

2. 重视回测

vnpy的回测功能很强大，但要注意：

• 数据质量很重要

• 考虑滑点和手续费

• 避免过度拟合

3. 做好风控

实盘和回测差别很大，风控是保命的：

• 设置止损

• 控制仓位

• 监控异常

4. vnpy源码管理

将vnpy源码纳入项目管理有几个好处：

• 版本控制：可以追踪对vnpy的修改历史

• 定制开发：可以根据需要修改vnpy的核心功能

• 插件管理：统一管理各种vnpy插件

• 部署便利：整个项目可以作为一个整体进行部署

5. 记录一切

把开发过程、遇到的问题、解决方案都记录下来。这不仅对自己有用，也是很好的教学素材。

下一步计划

环境搭建和项目结构确定后，下一篇文章我们将：

1. vnpy插件安装：安装CTP接口和策略引擎等必要插件

2. 数据获取与管理：配置数据源，获取历史数据

3. 第一个策略：实现一个简单但完整的双均线策略

项目重构总结

通过这次环境搭建和项目重构，我们完成了几个重要的工作：

✅ 完成的工作

1. vnpy环境验证：确保vnpy 4.1.0正确安装和运行

2. 图形界面启动：成功启动vnpy主界面，验证系统完整性

3. 源码整合：将vnpy源码纳入项目管理，便于二次开发

4. 目录规范化：建立了清晰的项目目录结构

5. 开发规范：制定了代码、配置、版本控制等规范

6. 工具脚本：创建了测试脚本和主程序入口

🎯 项目优势

• 可定制性：拥有vnpy完整源码，可以进行深度定制

• 可扩展性：预留了插件空间，支持vnpy生态

• 可维护性：清晰的目录结构和开发规范

• 教学价值：完整的文档和示例，适合学习

🔄 持续改进

这个项目结构不是一成不变的，随着功能的增加和需求的变化，我们会持续优化：

• 根据实际使用情况调整目录结构

• 完善开发规范和最佳实践

• 增加更多的工具脚本和自动化流程

写在最后

搭建开发环境看起来简单，但细节很多。我把这个过程完整记录下来，希望能帮你避开一些坑。

特别是vnpy源码的整合，这个步骤很多教程都没有提到，但对于serious的量化开发来说非常重要。有了源码，我们就有了无限的可能性。

记住，工具只是手段，重要的是思路和方法。vnpy给我们提供了一个很好的框架，但真正的价值在于我们如何使用它来实现自己的交易想法。

项目资源

• GitHub项目：https://github.com/seasonstar/atmquant

• 完整代码：包含本文所有脚本和配置文件

• 持续更新：跟随文章进度不断完善功能

如果觉得项目对你有帮助，欢迎给个Star支持一下！

下一篇文章我们就开始动手写代码，敬请期待！

#AI量化 #交易系统

---

本文内容仅供学习交流，不构成任何投资建议。交易有风险，投资需谨慎。