QTEASY 快速上手指南
安裝與導入
使用 pip 安装（要求 Python >= 3.9, <3.13）：部分功能（如全部内置策略、数据库存储等）需要可选依赖，详见 FAQ 与安装说明。
pip install qteasy
啓動後即可導入 qteasy 並查看版本號：
>>> import qteasy as qt
>>> print(qt.__version__)
輸出如下：
2.6.0
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 中查找「如何跑通」「爲何慢」「防未來函數」等常見說明。