## 引言：为什么学习量化交易？量化交易（Quantitative Trading）是一种数据驱动的投资方法，利用数学模型、统计分析和算法自动化决策，而不是主观判断。它适合A股市场的高频波动，帮助捕捉Alpha（超额收益）。作为入门实践，我们构建一个完整工具：**后端**用Python + Qlib实现策略回测；**API**用FastAPI桥接；**前端**用React + Tailwind CSS + Recharts可视化仪表盘。这个项目基于Microsoft开源的Qlib框架（AI导向量化平台），聚焦沪深300/个股策略（如Alpha158因子 + LightGBM模型 + TopK）。开发过程从环境搭建到迭代，耗时~~2小时（含调试），最终实现一键回测+曲线显示。案例：分析跃岭股份 (002725.SZ)，年化超额~~7.57%。 **学习目标**： * 理解量化流程：数据 → 模型 → 回测 → 风险评估。 * 实践工具链：Python生态 + Web全栈。 * 风险提醒：历史回测不代表未来，实盘需风控。 ## 1. 环境准备 ### 1.1 Python环境（Conda + Qlib源代码）使用Conda避免pip依赖冲突。Python 3.10兼容Qlib。 ```bash # 创建环境 conda create -n qlib_a股 python=3.10 conda activate qlib_a股 # 克隆Qlib源代码（开发模式，便于修改） git clone https://github.com/microsoft/qlib.git cd qlib # 批量安装依赖（优先conda，避免pip版本错） conda install -c conda-forge numpy pandas pyyaml scipy scikit-learn tqdm tensorboard requests numba fire ruamel.yaml cython setuptools-scm wheel redis black flake8 mypy pre-commit pip install --upgrade cython pip install -e '.[dev]' # 单引号防zsh glob错误 # A股数据（沪深Bin格式，2005-2024） wget https://github.com/chenditc/investment_data/releases/latest/download/qlib_bin.tar.gz mkdir -p ~/.qlib/qlib_data/cn_data tar -zxvf qlib_bin.tar.gz -C ~/.qlib/qlib_data/cn_data --strip-components=1 rm qlib_bin.tar.gz # 初始化Qlib python -c "import qlib; qlib.init(provider_uri='~/.qlib/qlib_data/cn_data', region='cn')" ``` **常见坑 & 修复**： * pip "versions: none"：用conda install + 清华镜像（pip.conf: `index-url = https://pypi.tuna.tsinghua.edu.cn/simple`）。 * zsh glob：pip install -e '.\[dev]'（单引号）。 * setuptools\_scm错：`conda install -c conda-forge setuptools-scm`。 ### 1.2 前端环境（Bun + Vite + React TS） Bun 比 npm 快 10x，Vite 热重载秒级。 ```bash # 创建Vite React TS项目 bun create vite@latest frontend --template react-ts cd frontend # 安装依赖 bun add recharts axios # 图表 + API bun add -d tailwindcss@^3.4.0 postcss autoprefixer # Tailwind v3（避v4坑） # 初始化Tailwind bunx tailwindcss init -p ``` **配置**（postcss.config.cjs用CommonJS避ESM错）： * **tailwind.config.js**： ```js /** @type {import('tailwindcss').Config} */ export default { content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"], theme: { extend: {} }, plugins: [], darkMode: 'class', } ``` * **postcss.config.cjs**（重命名.js为.cjs）： ```js module.exports = { plugins: { tailwindcss: {}, autoprefixer: {}, }, } ``` * **src/index.css**： ```css @tailwind base; @tailwind components; @tailwind utilities; ``` **坑 & 修复**：PostCSS "module is not defined" → 重命名.cjs；content \[]空 → 加src路径。 ## 2. 后端开发：Qlib量化引擎 ### 2.1 核心引擎：quant\_engine.py Qlib 全流程：数据（Alpha158因子）→ 模型（LightGBM）→ 策略（TopK）→ 回测（沪深300基准）。用 workflow 记录实验，风险用risk\_analysis。 **完整代码**（backend/quant\_engine.py）： ```python import qlib from qlib.constant import REG_CN from qlib.data import D from qlib.contrib.model.gbdt import LGBModel from qlib.contrib.strategy import TopkDropoutStrategy from qlib.backtest import backtest, executor from qlib.utils import init_instance_by_config from qlib.workflow import R from qlib.workflow.record_temp import SignalRecord, PortAnaRecord from qlib.contrib.evaluate import risk_analysis import pandas as pd import warnings warnings.filterwarnings('ignore', category=RuntimeWarning) # 忽略数据空slice警告 # 初始化Qlib qlib.init(provider_uri='~/.qlib/qlib_data/cn_data', region=REG_CN) # 配置（沪深300全市场） config = { 'dataset': {'class': 'qlib.data.dataset.DatasetH', 'module_path': 'qlib.data.dataset', 'kwargs': {'handler': {'class': 'Alpha158', 'module_path': 'qlib.contrib.data.handler', 'kwargs': {'start_time': '2010-01-01', 'end_time': '2025-10-16', 'fit_start_time': '2010-01-01', 'fit_end_time': '2017-12-31', 'instruments': 'csi300'}}, 'segments': {'train': ('2010-01-01', '2017-12-31'), 'valid': ('2018-01-01', '2019-12-31'), 'test': ('2020-01-01', '2025-10-16')}}}, 'model': {'class': 'LGBModel', 'module_path': 'qlib.contrib.model.gbdt', 'kwargs': {'loss': 'mse', 'colsample_bytree': 0.8879, 'learning_rate': 0.0421, 'subsample': 0.8789, 'lambda_l1': 205.6999, 'lambda_l2': 34.2895, 'max_depth': 8, 'num_leaves': 210, 'num_threads': 20}}, 'strategy': {'class': 'TopkDropoutStrategy', 'module_path': 'qlib.contrib.strategy', 'kwargs': {'topk': 50, 'n_drop': 5, 'signal': '', 'risk_degree': 0.95}}, 'backtest': {'start_time': '2020-01-01', 'end_time': '2025-10-16', 'account': 100000000, 'benchmark': 'SH000300', 'exchange_kwargs': {'limit_threshold': 0.095, 'deal_price': 'close', 'open_cost': 0.0005, 'close_cost': 0.0015, 'min_cost': 5}}, 'executor': {'class': 'SimulatorExecutor', 'module_path': 'qlib.backtest.executor', 'kwargs': {'time_per_step': 'day', 'generate_portfolio_metrics': True}}, } def run_quant_workflow(): exp_name = "A股_Alpha158_LGB" with R.start(experiment_name=exp_name): model = init_instance_by_config(config['model']) dataset = init_instance_by_config(config['dataset']) model.fit(dataset) R.save_objects(trained_model=model) rec = R.get_recorder() sr = SignalRecord(model, dataset, rec) sr.generate() port_analysis_config = { "backtest": config["backtest"], "strategy": config["strategy"], "executor": config["executor"] } par = PortAnaRecord(rec, port_analysis_config) par.generate() # 加载报告 report_df = rec.load_object('portfolio_analysis/report_normal_1day.pkl') print("报告df列名:", report_df.columns.tolist()) # 调试 # 通用列匹配（避版本差） strategy_col = next((col for col in report_df.columns if 'return' in col.lower() and 'bench' not in col.lower()), 'return') bench_col = next((col for col in report_df.columns if 'bench' in col.lower()), 'bench') cost_col = next((col for col in report_df.columns if 'cost' in col.lower()), None) strategy_return = report_df[strategy_col] bench_return = report_df[bench_col] cost = report_df[cost_col] if cost_col else pd.Series(0, index=report_df.index) daily_excess = strategy_return - bench_return - cost num_days = len(daily_excess) annualized_return = (1 + daily_excess).prod() ** (252 / num_days) - 1 risk_dict = risk_analysis(daily_excess) risk_metrics = { 'sharpe': risk_dict.get('Sharpe') or (daily_excess.mean() / daily_excess.std() * (252 ** 0.5) if daily_excess.std() > 0 else 0), 'volatility': risk_dict.get('Volatility') or (daily_excess.std() * (252 ** 0.5)), 'max_drawdown': risk_dict.get('MaxDD') or ((1 + daily_excess).cumprod().expanding().max() - (1 + daily_excess).cumprod()).max() * -1, 'win_rate': risk_dict.get('WinRate') or (daily_excess > 0).mean() } return { 'excess_return': daily_excess.to_dict(), 'risk_metrics': risk_metrics, 'annualized_return': float(annualized_return) } if __name__ == "__main__": result = run_quant_workflow() print(result) ``` **运行**：`python quant_engine.py`（~~10min首次，输出年化~~7.57%、Sharpe\~1.0）。 **坑 & 修复**： * 导入路径：`from qlib.contrib.strategy import TopkDropoutStrategy`（去.strategy）。 * 基准：'SH000300'（非'CSI300'）。 * Recorder加载：指定exp\_name。 * 报告列：通用匹配'return'/'bench'/'cost'。 * 源代码patch：qlib/backtest/report.py第17行`from qlib.tests.config import CSI300_BENCH`（绝对导入）。 ### 2.2 API桥接：api\_server.py FastAPI暴露/run\_backtest（异步任务 + 进度轮询）。 **完整代码**（backend/api\_server.py）： ```python import sys import os sys.path.append(os.path.dirname(os.path.abspath(__file__))) # 添加backend路径 from fastapi import FastAPI, BackgroundTasks from fastapi.middleware.cors import CORSMiddleware from uuid import uuid4 from collections import defaultdict from typing import Dict, Any import time from quant_engine import run_quant_workflow # 导入引擎 app = FastAPI(title="Qlib A股量化API") # CORS：允许Vite端口 app.add_middleware( CORSMiddleware, allow_origins=["http://localhost:5173", "http://127.0.0.1:5173", "http://localhost:3000"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) # 全局任务状态 tasks: Dict[str, Dict[str, Any]] = defaultdict(dict) def run_quant_async(task_id: str): """异步跑Qlib""" tasks[task_id]['status'] = 'running' tasks[task_id]['progress'] = 0.0 try: # 模拟进度（实际可加Qlib回调） for i in range(100): time.sleep(0.1) tasks[task_id]['progress'] = (i + 1) / 100.0 result = run_quant_workflow() tasks[task_id]['result'] = result tasks[task_id]['status'] = 'completed' tasks[task_id]['progress'] = 1.0 except Exception as e: tasks[task_id]['error'] = str(e) tasks[task_id]['status'] = 'error' tasks[task_id]['progress'] = 0.0 @app.get("/run_backtest") def trigger_backtest(background_tasks: BackgroundTasks): task_id = str(uuid4()) background_tasks.add_task(run_quant_async, task_id) return {"task_id": task_id, "status": "started"} @app.get("/task/{task_id}") def get_task_status(task_id: str): if task_id not in tasks: return {"status": "not_found", "error": "Task not found"} return tasks[task_id] @app.get("/health") def health_check(): return {"status": "Qlib A股系统运行中"} if __name__ == "__main__": import uvicorn uvicorn.run(app, host="127.0.0.1", port=8000) ``` **运行**：`uvicorn api_server:app --reload --host 127.0.0.1 --port 8000`。 **坑 & 修复**：Network Error → 用127.0.0.1绑定；超时 → 异步 + 轮询。 ## 3. 前端开发：React仪表盘 ### 3.1 核心组件：App.tsx 异步拉API数据，进度条 + 卡片 + 曲线。 **完整代码**（frontend/src/App.tsx）： ```tsx import React, { useEffect, useState } from 'react'; import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend, ResponsiveContainer } from 'recharts'; import axios from 'axios'; interface BacktestData { excess_return: { [date: string]: number }; risk_metrics: { sharpe?: number; volatility?: number; max_drawdown?: number; win_rate?: number }; annualized_return: number; } interface TaskStatus { status: 'started' | 'running' | 'completed' | 'error'; progress?: number; result?: BacktestData; error?: string; } function App() { const [data, setData] = useState(null); const [loading, setLoading] = useState(true); const [error, setError] = useState(null); const [taskId, setTaskId] = useState(null); const [progress, setProgress] = useState(0); useEffect(() => { let interval: NodeJS.Timeout; axios.get('http://127.0.0.1:8000/run_backtest') .then(res => { const taskIdRes = res.data.task_id; console.log('任务ID:', taskIdRes); setTaskId(taskIdRes); setLoading(true); interval = setInterval(() => { if (taskIdRes) { axios.get(`http://127.0.0.1:8000/task/${taskIdRes}`) .then(statusRes => { console.log('任务状态:', statusRes.data); const status: TaskStatus = statusRes.data; setProgress(status.progress ? status.progress * 100 : 0); if (status.status === 'completed' && status.result) { setData(status.result); setLoading(false); clearInterval(interval); } else if (status.status === 'error') { setError(status.error || '任务失败'); setLoading(false); clearInterval(interval); } }) .catch(err => { console.error('轮询错误:', err); setError('轮询失败'); setLoading(false); clearInterval(interval); }); } }, 10000); // 10s轮询 return () => clearInterval(interval); }) .catch(err => { console.error('启动任务失败:', err); setError('API启动失败: ' + err.message); setLoading(false); }); return () => { if (interval) clearInterval(interval); }; }, []); if (loading) { return (

生成回测中... 进度: {progress.toFixed(0)}%

预计10min（首次训练）

); } if (error) { return (

{error}

); } const chartData = Object.entries(data?.excess_return || {}).slice(-100).map(([date, val]) => ({ date, return: val })); return (

Qlib A股量化仪表盘

年化收益

{(data?.annualized_return * 100).toFixed(2)}%

夏普比率

{data?.risk_metrics.sharpe?.toFixed(2) || 'N/A'}

最大回撤

{data?.risk_metrics.max_drawdown?.toFixed(2) || 'N/A'}

胜率

{data?.risk_metrics.win_rate ? (data.risk_metrics.win_rate * 100).toFixed(1) + '%' : 'N/A'}

回测收益曲线

[`${(value * 100).toFixed(2)}%`, '超额收益']} />

); } export default App; ``` **运行**：`bun run dev`（localhost:5173）。 ![](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/b6602498497444a0805509fc08bdf39c~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5Y-25qKF5qCR:q75.awebp?rk3s=f64ab15b&x-expires=1761832373&x-signature=Ba4qGixLraaukhpPliVsIHvrpns%3D) **坑 & 修复**：Network Error → 127.0.0.1:8000；超时 → 异步轮询10s；样式无 → postcss.config.cjs + content路径。 ## 4. 集成测试 & 迭代 ### 4.1 全链路测试 * 后端：`python quant_engine.py` → dict输出（年化7.57%）。 * API：`uvicorn api_server:app --reload --host 127.0.0.1 --port 8000` → /run\_backtest返回task\_id，/task/{id}进度→数据。 * 前端：刷新 → 进度条→卡片+曲线（hover%）。 ### 4.2 迭代示例：跃岭股份 (002725.SZ) 个股策略 **分析**：当前15.26元，低估（P/E 15x），短期观望，中期持有（目标18元）。风险：汽车周期，机会：出口订单。 **Qlib迭代**：单股RSI均值回归（RSI<30买>70卖 + Alpha158）。更新quant\_engine.py config（instruments='002725'，topk=1），exp\_name="跃岭股份\_RSI\_Alpha158"，end\_time='2025-10-16'。运行：年化~~12%、Sharpe~~1.1。 **扩展**：加MACD handler（qlib.contrib.data.handler.MACD），或多股池（instruments='auto\_parts'）。 ## 结语：量化入门心得这个项目让我从0到1掌握量化全链路：Qlib的松耦合组件让策略迭代简单，前端可视化让结果直观。年化7.57%是起点，实盘需调参+风控。继续迭代：加Tushare实时数据、RL执行优化。量化是工具，不是魔法——数据+纪律=Alpha！ **资源**：Qlib GitHub、[Investopedia量化指南](https://www.investopedia.com/terms/q/quantitative-trading.asp)。欢迎反馈迭代！（记录日期：2025-10-16）