QTEASY 快速上手指南
安装与导入
使用 pip 安装（要求 Python >= 3.9, <3.13）：部分功能（如全部内置策略、数据库存储等）需要可选依赖，详见 FAQ 与安装说明。
pip install qteasy
启动后即可导入 qteasy 并查看版本号：
>>> import qteasy as qt
>>> print(qt.__version__)
输出如下：
2.5.2
qteasy发布历史 — 各版本变更说明，升级前可查阅
一分钟跑通
本节将带您完成：配置 tushare Token → 下载沪深 300 十年指数数据 → 查看数据与 K 线 → 使用内置 DMA 策略对 000300.SH 做择时回测，并得到一份可用的回测结果。
2. 下载 000300.SH 十年指数数据
配置好 tushare Token 后，下载沪深 300 指数（000300.SH）的日线数据。建议先下载交易日历与指数基础信息，再下载指数日线（约十年）：
使用qteasy.refill_data_source()函数，qteasy会自动从配置好的数据下载渠道下载数据，当数据量太大时，会自动分块下载数据、完成数据检查和清洗并存储到数据库中。
>>> # 下载交易日历与指数基础信息
>>> qt.refill_data_source(tables=['trade_calendar', 'index_basics'])
>>> # 下载 000300.SH 近十年日线数据
>>> qt.refill_data_source(
... tables=['index_daily'],
... start_date='20140101',
... end_date='20241231',
... symbols=['000300.SH'],
... )
输出如下：
Filling data source file://csv@qt_root/data/ ...
into 1 table(s) (parallely): {'trade_calendar'}
<trade_calendar> 35000 wrn: 100%|████████████████████████████████████████████████████████████████████████████████████| 8/8 [00:05<00:00, 1.58task/s]
Data refill completed! 35000 rows written into 1/1 table(s)!
Filling data source file://csv@qt_root/data/ ...
into 2 table(s) (parallely): {'index_daily', 'index_basic'}
<index_daily> 152760 wrn: 100%|██████████████████████████████████████████████████████████████████████████████████████| 2/2 [00:05<00:00, 2.51s/task]
<index_basic> 1327 wrn: 100%|████████████████████████████████████████████████████████████████████████████████████████| 8/8 [00:05<00:00, 1.58task/s]
Data refill completed! 154087 rows written into 2/2 table(s)!
3. 查看数据与 K 线图
数据落地后，可用 get_history_data 取数、用 HistoryPanel.plot 和 qt.candle 画 K 线，确认数据与行情是否正常：
>>> # 获取近一年日线，直接返回 HistoryPanel
>>> hp = qt.get_history_data(
... htypes='open, high, low, close', # 需要获取的数据类型分别为开盘价、最高价、最低价、收盘价
... shares='000300.SH', # 资产类型为沪深300指数
... start='20230101', # 数据起始日期
... end='20231231', # 数据结束日期
... )
>>> print(hp) # 查看数据结构与范围
>>> # 在 HistoryPanel 上绘制静态 K 线 + 成交量
>>> hp.plot(interactive=False)
>>> # 或者使用 qt.candle 快速绘制 K 线（内部同样基于 HistoryPanel）
>>> qt.candle('000300.SH', start='2023-06-01', end='2023-12-01', asset_type='IDX')
3.1 交互式图表（Plotly）与依赖
如果你希望在 Notebook 里缩放、平移并查看每根 K 线/指标对应的具体数值，可以使用交互式绘图：
>>> hp.plot(interactive=True)
交互式图表依赖 Plotly。建议按你的使用环境选择安装：
基础交互（Plotly Figure）：
pip install plotly
Notebook 更完整交互（FigureWidget + 回调）：
pip install ipywidgets anywidget
在 Notebook 中，qteasy 会优先尝试提供更完整的 FigureWidget 体验；如果当前内核/依赖不满足，则会回退到 HTML 方式展示。若未安装 Plotly，interactive=True 会直接抛出英文错误提示（通常包含 “requires plotly”）。
3.2 最常用的交互参数
plotly_backend_app='auto'|'FigureWidget'|'html'：在 Notebook 中选择输出方式（默认'auto'）。layout='auto'|'overlay'|'stack'：多标的布局。'overlay'仅对 两标的叠加对比最常用；'auto'会在“两标的 → overlay，其余 → stack”间自动选择。highlight='max'|'min'：高亮最大/最小值点（静态与交互均可用）。
输出如下：
{'000300.SH':
open high low close
2023-01-03 3864.84 3893.99 3831.25 3887.90
2023-01-04 3886.25 3905.90 3873.65 3892.95
2023-01-05 3913.49 3974.88 3912.26 3968.58
... ... ... ... ...
2023-10-10 3696.25 3701.26 3655.59 3657.13
2023-10-11 3674.75 3689.53 3658.35 3667.55
2023-10-12 3697.93 3711.50 3682.84 3702.38
[186 rows x 4 columns]
}
3.5 操作历史数据（HistoryPanel）
在实际研究中，很多时候我们不仅需要“看 K 线”，还需要在代码里对历史数据做统计、生成因子。
get_history_data() 除了可以返回 DataFrame 外，还可以直接返回一个三维的 HistoryPanel，便于对多标的、多指标做统一计算：
>>> # 获取 000300.SH 的 OHLCV 历史数据，并返回 HistoryPanel
>>> hp = qt.get_history_data(
... htypes='open, high, low, close, vol',
... shares='000300.SH',
... start='20230101',
... end='20231231',
... as_data_frame=False, # 关键：返回 HistoryPanel
... )
>>> print(hp.shape, hp.shares, hp.htypes)
>>> # 1) 计算简单收益率矩阵（时间 × 股票）
>>> ret = hp.returns(price_htype='close', method='simple')
>>> print(ret.head())
>>> # 2) 计算 20 日滚动波动率
>>> vol = hp.volatility(window=20, price_htype='close', annualize=True)
>>> print(vol.tail())
>>> # 3) 生成 K 线技术指标（如 20 日均线、MACD）
>>> hp_ma = hp.kline.sma(window=20) # 在 htypes 中新增 'sma_20'
>>> hp_ma_macd = hp_ma.kline.macd() # 再追加 MACD 指标
>>> print(hp_ma_macd.htypes)
>>> # 4) 识别蜡烛形态（如锤头线）
>>> hammer = hp.candle_pattern('cdlhammer') # 返回 DataFrame，非 0 代表出现形态
>>> print(hammer[hammer['000300.SH'] != 0].head())
>>> # 5) 单只股票切片成 DataFrame，方便与 pandas / sklearn 等联动
>>> df_300 = hp_ma_macd.to_share_frame('000300.SH')
>>> print(df_300.tail())
上面的例子演示了从 get_history_data(..., as_data_frame=False) 得到 HistoryPanel 之后，如何在一两行代码内完成收益率、波动率、技术指标与形态信号的计算，并随时切回熟悉的 DataFrame 做进一步分析。
更系统的 HistoryPanel 用法可以参考「使用教程」中“历史数据的操作和分析”一章，以及 HistoryPanel API 参考。
4. 使用 DMA 策略做择时回测
使用内置 DMA 均线择时策略，以 000300.SH 为交易标的，在已下载的十年数据上做回测。下面使用一组常用且表现较稳的参数（短均线 20、长均线 60、DMA 周期 10），直接得到回测结果与图表：
>>> # 设置qteasy的运行配置参数
>>> qt.configure(
... asset_pool='000300.SH', # 交易资产池包括沪深300指数
... asset_type='IDX', # 投资资产类型为IDX-指数
... invest_cash_amounts=[100000], # 回测初始投资金额为十万元
... invest_start='20150101', # 回测投资初始日期
... invest_end='20241231', # 回测投资结束日期
... cost_rate_buy=0.0003, # 交易费率：买入手续费万分之三
... cost_rate_sell=0.0001, # 交易费率：卖出手续费万分之一
... visual=True, # 是否输出回测结果可视化图表：是
... trade_log=True, # 是否输出回测记录：是
... )
>>> op = qt.Operator(strategies='dma') # 创建一个交易员对象，执行一个DMA交易策略
>>> op.set_parameter('dma', par_values=(20, 60, 10)) # 设置交易策略的参数
>>> res = qt.run(op, mode=1) # 启动交易，运行模式为1（回测交易）
输出如下：
====================================
| |
| BACKTEST REPORT |
| |
====================================
qteasy running mode: 1 - History back testing
time consumption for operate signal creation: 81.3 ms
time consumption for operation back testing: 4.9 ms
investment starts on 2015-01-05 15:00:00
ends on 2024-12-30 15:00:00
Total looped periods: 10.0 years.
-------------operation summary:------------
Only non-empty shares are displayed, call
"loop_result["oper_count"]" for complete operation summary
Sell Cnt Buy Cnt Total Long pct Short pct Empty pct
000300.SH 340 41 381 44.7% -0.0% 55.3%
Total operation fee: ¥ 3,261.19
total investment amount: ¥ 100,000.00
final value: ¥ 115,601.73
Total return: 15.60%
Avg Yearly return: 1.46%
Skewness: -1.16
Kurtosis: 16.95
Benchmark return: 1.67%
Benchmark Yearly return: 0.17%
------strategy loop_results indicators------
alpha: 0.006
Beta: 0.975
Sharp ratio: 0.113
Info ratio: 0.001
250 day volatility: 0.130
Max drawdown: 36.85%
peak / valley: 2015-04-27 / 2018-11-27
recovered on: Not recovered!
==================END OF REPORT===================
运行后将得到收益曲线、最大回撤、夏普比等评价指标及可视化图表。若要尝试其他参数或优化区间，可参考下一节「qteasy 能做什么」中的参数优化与 回测文档。
qteasy 能做什么
获取并管理金融历史数据:
方便地从多渠道获取大量金融历史数据，进行数据清洗后以统一格式进行本地存储
通过
DataType对象结构化管理金融数据中的可用信息，即便是复权价格、指数成份等复杂信息，也只需要一行代码即可获取基于
DataType对象的金融数据可视化、统计分析以及分析结果可视化数据本地存储、按需取用，为回测与实盘提供一致的数据基础，便于复现
以简单、安全的方式创建交易策略
通过
BaseStrategy类，交易策略定义方法直观、逻辑清晰内置超过70种策略开箱即用，独特的策略混合和组机制，复杂策略可以通过简单策略拼装而来，过程如同搭积木
交易策略的数据输入和使用方法完全封装且安全，完全避免无意中导致未来函数、数据泄露等问题，保证策略运行结果的真实性和可靠性
同一套策略逻辑既用于回测也用于实盘，减少「回测漂亮、实盘走样」的落差
交易策略的回测评价、优化和模拟自动化交易
通过
Operator交易员类管理策略运行，按照真实市场交易节奏回测策略，对交易结果进行多维度全方位评价，生成交易报告和结果图表提供多种优化算法，包括模拟退火、遗传算法、贝叶斯优化等在大参数空间中优化策略性能
获取实时市场数据，运行策略模拟自动化交易，跟踪记录交易日志、股票持仓、账户资金变化等信息
回测、优化与实盘使用同一套运行机制，写一次策略即可全模式运行，配置清晰，便于复现与排查
未来将通过QMT接口接入券商提供的实盘交易接口，实现自动化交易
端到端路线图 / 教程
若希望按完整流程走通「从配置到回测、优化、模拟/实盘」，可依下列顺序阅读教程与文档，每步均有对应章节与示例：
下载数据 → 教程：获取数据、下载并管理金融历史数据
参数优化 → 教程：交易策略的优化、优化交易策略
模拟/实盘运行 → 教程：交易策略的部署及运行、模拟实盘运行概览
上述教程已覆盖从配置到回测、优化与模拟/实盘的完整链路；遇到问题时可在 FAQ 中查找「如何跑通」「为何慢」「防未来函数」等常见说明。