____                  _   _ ______ _______ 
 |  _ \                | | | |  ____|__   __|
 | | | | ___  ___ _ __ | |_| | |__     | |   
 | | | |/ _ \/ _ \ '_ \|  _  |  __|    | |   
 | |_| |  __/  __/ |_) | | | | |       | |   
 |____/ \___|\___| .__/|_| |_|_|       |_|   
                 | |                         
                 |_|                         

开放的 HFT 引擎。从 L2 数据清洗、Alpha 挖掘、模型蒸馏到 FPGA 部署的全流程工业级解决方案。

先决条件

• Xilinx UltraScale+ (Alveo U50/U200/U250) 或 Virtex-7。
• Vivado Design Suite 2020.2+ (必须带 HLS)。
• Linux (Ubuntu 20.04/CentOS 7)。
• Python 3.8+

数据流水线

DeepHFT 不处理原始 PCAP/Binary 数据。请使用 C++ 预处理引擎将数据清洗并对齐为 Parquet 格式。

输入规范:

• 格式: Apache Parquet (Snappy 压缩)
• Schema:
  • feature_[000-127]: float32 (标准化后的因子)
  • target_ret: float32 (未来 N 个 Tick 的收益率)

配置: 编辑 config/config.yaml 指定数据路径与硬件参数。

---

模型构建

1. 训练 Teacher 模型

Teacher 模型用于捕捉非线性市场微观结构。采用 Transformer 架构。

python train.py --config config/config.yaml --device cuda:0

• Output: checkpoints/teacher_best.pth
• Log: logs/experiment_id/

2. 知识蒸馏

将 Teacher 映射为 FPGA 友好的 1D-CNN。此步骤移除 Softmax/Attention 等高延迟算子。

python distill.py --teacher_ckpt checkpoints/teacher_best.pth

• Output: export/student_cnn.onnx
• Opset: 13 (必须严格匹配 HLS 编译器支持版本)

---

硬件综合

使用 hls4ml 将 ONNX 转换为 C++ HLS 工程，并生成 IP Core。

# 自动量化为 ap_fixed<16,6> 并生成 Vivado HLS 工程
python build_fpga.py --onnx export/student_cnn.onnx --part xcu250-figd2104-2L-e

构建产物:

• hls_project/alpha_cnn/: HLS 工程源码
• hls_project/alpha_cnn/solution1/impl/ip/xilinx_com_hls_alpha_cnn_1_0.zip: 最终 IP Core

---

FPGA 部署与连线

本节指导如何在 Vivado 中手动集成生成的 IP Core。由于每个交易团队的 Shell (PCIe/Network Stack) 不同，此处需根据实际硬件架构进行连线。

1. 导入 IP Core

1. 启动 Vivado 并打开你的 FPGA 工程 (包含 Shell/DMA 的工程)。
2. 点击 Project Manager -> Settings -> IP -> Repository。
3. 点击 + 号，选择路径：hls_project/alpha_cnn/solution1/impl/ip。
4. 点击 OK，确认识别到 Alpha_CNN_IP。

2. 实例化与连线

1. 打开 IP Integrator -> Open Block Design

2. 右键空白处 -> Add IP，搜索 alpha_cnn 并双击添加。

3. 时钟与复位

   • 连接 ap_clk 到系统主时钟 (推荐 200MHz - 300MHz)。
   • 连接 ap_rst_n 到系统复位信号 (低电平有效)。
   • 注意: 必须与数据源 (DMA/NIC) 处于同一时钟域，否则您需要添加 AXI Interconnect 或 FIFO 进行跨时钟域处理。

4. 数据输入

   • 找到 input_features 接口 (通常是 AXI4-Stream 或 ap_memory)。
   • 若为 AXI-Stream: 直接连接到网卡 IP (如 Xilinx CMAC / 10G Ethernet Subsystem) 的 RX_AXIS 接口。
   • 若为 AXI-Lite/Memory: 连接到 PCIe DMA (XDMA/QDMA) 的 M_AXI 接口。

5. 信号输出

   • 找到 alpha_score 接口。
   • 连接到你的下单逻辑。
   • 或者连接到 ILA (Integrated Logic Analyzer) 进行在线调试。

3. 综合与生成比特流

1. 在 Sources 窗口右键 Block Design -> Create HDL Wrapper。
2. 点击 Run Synthesis。
   • 检查 Timing Summary，确保 WNS (Worst Negative Slack) > 0。
3. 点击 Run Implementation
4. 点击 Generate Bitstream
5. 导出 .bit 或 .xclbin 文件。

---

运行时集成

在 Host 端或 Soft-Core (MicroBlaze) 中加载模型参数（如果未使用完全烘焙的权重）。

// 示例: 通过 PCIe/AXI 写入输入数据
#include "xrt/xrt_device.h"
#include "xrt/xrt_kernel.h"

void run_inference(std::vector<float>& market_data) {
    auto input_buffer = prepare_buffer(market_data);
    // 写入 FPGA 寄存器/HBM
    input_bo.write(input_buffer.data());
    input_bo.sync(XCL_BO_SYNC_BO_TO_DEVICE);
    // 触发 Kernel (如果是 AXI-Stream 直连，此步由网卡触发)
    auto run = kernel(input_bo, output_bo);
    run.wait();
    // 读取 Alpha
    output_bo.sync(XCL_BO_SYNC_BO_FROM_DEVICE);
    float alpha = output_buffer[0];
    if (alpha > THRESHOLD) execute_order();
}

---

常见 Q&A

• Timing Violation (WNS < 0):
  • 原因：CNN 层数过深或时钟频率过高 (300MHz+)。
  • 解决：在 build_hls.py 中增加 Strategy='Resource' 或降低 ReuseFactor 以换取面积。或者在 Vivado 中降低时钟频率至 200MHz。
• HLS Synthesis 失败:
  • 原因：ONNX Opset 版本不兼容。
  • 解决：确保 torch.onnx.export 使用 opset_version=13。
• 精度异常:
  • 原因：ap_fixed 溢出。
  • 解决：检查 hls4ml 报告中的 Min/Max 值，调整整数位宽 (例如从 <16,6> 调整为 <18,8>)。