FAQ

如何搭建不同python版本的安裝環境

在qteasy Tutorial中，我們介紹了使用venv創建虛擬環境安裝qteasy的方法。但是，有時候用戶可能需要在不同的python版本下安裝qteasy，例如在python3.9、python3.10、python3.11、python3.12等等版本下安裝qteasy。這裏我們介紹一種方法，可以在不同的python版本下安裝qteasy。

使用Anaconda創建不同python版本的環境：

Anaconda是一個科學計算的Python發行版，它包含了conda、Python等180多個科學包及其依賴項。因此，我們可以使用Anaconda創建不同python版本的環境，然後在不同的環境下安裝qteasy。

Anaconda可以在其官網下載，下載地址爲：Anaconda。針對不同操作系統，下載對應的版本，然後安裝。

安裝Anaconda後，我們可以使用conda命令創建不同的python版本的環境，並在其中安裝python包。例如：

$ conda create -n py39 python=3.9  # 创建python3.9环境
$ conda activate py39  # 激活python3.9环境
$ pip install qteasy  # 在python3.9环境下安装qteasy

在conda環境中，使用pip安裝的軟件包也能被正確地識別和管理。

下面有一些常用的conda命令：

$ conda env list  # 查看所有的环境
$ conda activate py39  # 激活python3.9环境
$ conda deactivate  # 退出当前环境
$ conda remove -n py39 --all  # 删除python3.9环境
$ conda list  # 查看当前环境下安装的包
$ conda list -n py39  # 查看python3.9环境下安装的包

使用國內的pip鏡像源

在國內，由於網絡環境的原因，有時候使用pip安裝python包會很慢，甚至失敗。這時候，我們可以使用國內的pip鏡像源，例如清華大學的pip鏡像源。

在使用pip安裝python包時，可以使用-i參數指定pip鏡像源，例如：

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

如何升級qteasy到最新版本

在使用qteasy時，我們可能需要升級到最新版本。升級前建議查閱發佈歷史瞭解各版本的用戶可見變更。升級 qteasy 到最新版本的方法如下：

$ pip install qteasy --upgrade

或者使用下面的命令：

$ pip isntall qteasy -U

如果要使用國內的清華鏡像源，可以使用下面的命令：

$ pip install -i https://pypi.tuna.tsinghua.edu.cn/simple qteasy --upgrade

如何安裝TA-Lib

完整的TA-Lib包無法通過pip安裝，因爲通過pip install ta-lib安裝的只是TA-Lib包的一個python wrapper, 用戶必須首先安裝C語言的TA-Lib才能在python中使用它。

有些用戶可以用下面的方法安裝C語言的TA-Lib包： conda install -c conda-forge libta-lib

在不同的系統下安裝C語言的TA-Lib包的方法：

Windows

下載 ta-lib-0.4.0-msvc.zip 並解壓至 C:\ta-lib.
下載並安裝 Visual Studio Community (2015 或更新版本)，選擇 [Visual C++] 功能
Windows 開始菜單, 啓動 [VS2015 x64 Native Tools Command Prompt]
移動至 C:\ta-lib\c\make\cdr\win32\msvc
nmake

Mac OS

首先安裝homebrew，然後通過homebrew安裝C語言TA-LIB包：

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

如果使用Apple Silicon芯片，可以使用：

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

Linux

下載 ta-lib-0.4.0-src.tar.gz ，然後:

$ tar -xzf ta-lib-0.4.0-src.tar.gz
$ cd ta-lib/
$ ./configure --prefix=/usr
$ make
$ sudo make install

C語言TA-LIB包安裝完成後，即可以通過pip安裝python的TA-Lib包：

$ pip install ta-lib

如果需要在arm64架構的Mac上安裝TA-Lib，可以使用下面的命令：

$ arch -arm64 python -m pip install --no-cache-dir ta-lib

如果您使用Arm64架構的電腦，但是安裝ta-lib後出現導入錯誤ImportError:，可能是因爲環境的問題，請參考這篇文章解決您的問題。

在較高版本python環境中安裝qteasy

解決方案是升級到最新的qteasy版本。較新版本的qteasy已經在python3.7 ~ 3.12環境中進行了測試，可以在這些環境中正常運行。

$ pip install qteasy --upgrade

較早版本的qteasy沒有在高版本的python環境中進行充分測試，因此存在一些兼容性問題。這樣的問題主要存在於v1.1.4及以前的qteasy分發版中。

同時，較早版本的qteasy在也使用了一些在高版本的pandas、numpy中即將被棄用的API，這也可能導致對高版本pandas、numpy的兼容性問題，在v1.1.7及以後版本的qteasy中，已經對這些問題進行了修復。

在qteasy.cfg中添加配置資訊後，提示數據庫連接失敗

有用戶反饋，在qteasy.cfg文件中配置好數據庫連接資訊後，仍然提示數據庫連接失敗。並得到下面類似的錯誤資訊：

C:\Users\yuewe\Documents\GitHub\qteasy-1.0.26\qteasy\database.py:2504: RuntimeWarning: (1045, "Access denied for user 'yuewe'@'localhost' (using password: NO)"), Can not set data source type to "db", will fall back to default type
warnings.warn(f'{str(e)}, Can not set data source type to "db",'

如果您第一次遇到這樣的問題，可能應該首先檢查您的qteasy.cfg文件。主要檢查下面兩方面：

配置的key是否錯誤，qteasy穩定版本使用的數據庫連接資訊配置key是local_db_host / local_db_port … 等等，而不是database_host，以前在官方文檔中曾經存在一些錯誤，這些錯誤已經在最新的文檔中修正了。
在文件中給出配置資訊的時候，請不要加其他字符，如", <和>等等，否則，這些字符也會被認爲是token或者數據庫名的一部份。從而導致連接數據庫失敗。

qteasy在解析配置文件的時候，會根據配置的類型，自動轉換爲正確的格式，例如，數據庫端口3306應該是int變量，直接使用：

local_db_port = 3306

即可。qteasy會將字符串3306轉換爲int型3306。·

下面這個配置文件的例子是正確的：

tushare_token = 2dff3f034aa966479c81e4b4b0736fb081b740abb2xxxxxxxxxxxxxxxxxxxxx

local_data_source = database

local_db_host = localhost
local_db_port = 3306
local_db_user = user_name
local_db_password = pass_word
local_db_name = ts_db

從數據庫中讀取數據時，提示建議安裝`sqlalchemy`

有時候，在使用數據庫作爲數據源，並從數據庫中讀取數據時，您可能會看到以下提示資訊：

UserWarning: pandas only supports SQLAlchemy connectable (engine/connection) or database string URI or sqlite3 DBAPI2 connection. Other DBAPI2 objects are not tested. Please consider using SQLAlchemy.

以上提示資訊建議用戶使用sqlalchemy.

總的來說，這是一條UserWarning。其實並沒有錯誤發生，數據讀取是成功的。出現這條警告資訊的原因跟您安裝的pandas的版本有關。您不需要安裝sqlalchemy，qteasy已經移除了對sqlalchemy的依賴. 爲了確認爲何會出現這條警告，請檢查一下您的pandas版本.

import pandas as pd
pd.__version__

如果您使用的pandas版本爲1.1以上，有可能會出現這條UserWarning，但一般來說應該不會影響使用：這是因爲qteasy使用pymysql作爲數據庫連接API，但pandas從1.1版本以後，逐步開始將pymysql的支持去掉了，儘管經過測試，在pandas的1.5版本下qteasy仍然能夠正確讀取數據，但是會收到警告資訊。

以上問題已經進入了我的修改清單，在接下來的小升級中，會去掉對pandas的sql API依賴，直接使用pymysql讀取數據庫，這樣就不會出現這條警告資訊了。如果您不希望看到這條警告資訊，也可以降級pandas的版本到1.1.0。qteasy在開發初期一致固定使用較低版本的pandas，絕大部分的穩定性測試基於pandas的1.1版本，如果使用1.1版本的pandas就不會出現這個提示資訊，其他所有功能也都正常。

從tushare下載數據時提示下載頻率過高而失敗

某些tushare數據存在每分鐘讀取頻率限制，如果積分不夠，下載頻率是會被限制的，從而導致某些數據下載不完整，例如下面的情況：

運行腳本：

>>> qt.refill_data_source(tables='events', start_date='20230101', end_date='20240403',reversed_par_seq=True)

出現下列報錯：

[##############--------------------------]6000/16923-35.5% <fund_share:016407.OF>37107wrtn/about 19 minleftC:\ProgramData\anaconda3\envs\qteasy-env-p311\Lib\site-packages\qteasy*database.py:5134*: UserWarning:
抱歉，您每分钟最多访问该接口600次，权限的具体详情访问：https://tushare.pro/document/1?doc_id=108。:
download process interrupted at [fund_share]:<F180003.OF>-<016408.OF>
37107 rows downloaded, will proceed with next table!
warnings.warn(msg)
[#######################-----------------]10000/16923-59.1% <fund_manager:012277.OF>1264483wrtn/about 15 minleftC:\ProgramData\anaconda3\envs\qteasy-env-p311\Lib\site-packages\qteasy\database.py:5134: UserWarning:
抱歉，您每分钟最多访问该接口500次，权限的具体详情访问：https://tushare.pro/document/1?doc_id=108。:
download process interrupted at [fund_manager]:<F180003.OF>-<012278.OF>
1264483 rows downloaded, will proceed with next table!
warnings.warn(msg)

爲此，qteasy設計了專門的重試機制來規避或緩解這個問題。

您可以嘗試修改qteasy的下面幾個配置，調整下載數據時的重試次數和延時設置，這幾個配置參數是專門爲了應對tushare的讀取頻率限制設置的：

QT_CONFIG.hist_dnld_retry_cnt - 下載數據時失敗重試的次數，默認爲7次 QT_CONFIG.hist_dnld_retry_wait - 第一次下載失敗時的等待時長，單位爲秒，默認爲1秒 QT_CONFIG.hist_dnld_backoff - 等待後仍然失敗時等待時間的倍增乘數，默認爲2倍

qteasy在調用所有的tushare函數時，會自動retry，每兩次retry之間會逐漸延長間隔。比如，第一次下載不成功時，會暫停一秒重試，如果重試仍然有問題，會等待2秒重試，下一次等待4秒、再等待8秒。。。依此類推，一直到重試次數用光，這時纔會raise。

正常來講，重試7次後的延時會倍增到32秒，加上前面延時的長度，已經超過1分鐘了，正常是不會觸發頻率錯誤的，但如果網速過快，或者同時啓用的線程太多，可能會有上面的問題。

這時可以嘗試將重試次數改成10次或更多（這樣會顯著延長下載時間），或者增加等待初始時長：

>>> qt.configure(hist_dnld_retry_cnt=10, hist_dnld_retry_wait=2.)
>>> qt.refill_data_source(tables='events', start_date='20230101', end_date='20240403',reversed_par_seq=True)

從`tushare`分批下載數據

某些時候我們需要分批下載數據，在每批次之間暫停一定時間，例如tushare的某些數據表設置了頻率限制，限定每分鐘最多下載的次數，如果超過這個次數，會導致下載失敗。這時，我們可以通過下面兩個配置參數來實現這樣的分批下載和停頓：

QT_CONFIG.hist_dnld_delay: 默認值爲0，如果設置爲一個大於0的整數，表示分批下載時每批的下載數量
QT_CONFIG.hist_dnld_delay_evy』: 默認值爲0，如果設置爲一個大於0的整數，表示兩個下載批次之間等待的秒數以下配置可以使得每下載600組數據就等待一分鐘：

>>> qt.configure(hist_dnld_delay=60, hist_dnld_delay_evy=600)
>>> qt.configure(hist_dnld_retry_cnt=3)  # 同时减少重试的次数以缩短报错前等待的时间，这个配置并不是必要的

按照上述方法設置後，每次下載數據時，即使使用並行下載的方式，qteasy也不會將所有任務同時提交給進程池，而是分批提交，等待一段時間後，再次提交下一批。

上述功能是在qteasy的v1.1.11版本中新增的，如果您的qteasy版本較低，請升級至最新版本。

如何跑通從數據到回測/優化的最小流程？

建議按《快速上手指南》中的「一分鐘跑通」完成：配置 tushare Token → 下載數據 → 使用內置策略做一次回測。完整鏈路（配置數據源 → 下載數據 → 定義策略並回測 → 參數優化 → 模擬/實盤運行）及對應教程跳轉見快速上手指南 - 端到端路線圖 / 教程。按該路線圖中的順序閱讀各教程即可從零走通全流程。

回測/優化爲什麼慢？

可能原因包括：

數據量與窗口長度：回測區間越長、資產池越大、策略的 window_length 越大，單次回測需要準備與計算的數據越多。
參數組數：優化模式（mode=2）下，參數組合越多，需要執行的單次回測次數越多；已通過多進程並行緩解，但仍與機器核心數及任務規模相關。
首次 Numba 編譯：核心回測函數（如 backtest_step、backtest_batch_steps）使用 Numba JIT，首次運行或參數類型變化時會觸發編譯，產生一次性延遲；後續同類型回測會複用緩存，速度會明顯提升。
數據準備：若 DataSource 中數據未提前準備好，回測前會觸發數據拉取與窗口裝配，也會增加首次運行時間。

若需進一步瞭解回測引擎與性能設計，可參閱回測引擎與性能與《架構與設計》中的回測引擎與性能（設計視角）。

如何理解「防未來函數」？

qteasy 從機制上避免策略在回測中“看到”未來數據：每個時間步運行時，引擎僅向策略注入該步當時可見的歷史數據窗口，策略在 realize() 中通過 get_data(dtype_id) 取到的只是該窗口內的數據；在此窗口上計算指標（如 EMA）與實盤“當時僅能看到的歷史”一致，因此不會無意中使用未來數據。詳細設計理由（爲何不做全時間軸向量化、數據窗口如何按步注入等）見《架構與設計》中的設計初衷與獨特優勢。

use_latest_data_cycle 是什麼，如何設置？

use_latest_data_cycle（常簡寫爲 ulc）控制策略所用數據窗口是否包含當根 K 線（當前時刻的最新數據）：設爲 True 時，窗口可含當前 bar（如收盤價），對應“交易時是否允許用當時最新價”；設爲 False 時，窗口嚴格爲“過去已收盤”的數據。該選擇在長期回測中會對收益產生顯著影響，qteasy 將其作爲可配置項在策略聲明與運行配置中暴露。含義與影響見設計初衷與獨特優勢 - use_latest_data_cycle；具體設置方式見策略類的 data_types / window_length 聲明及策略如何聲明與使用數據，以及當前版本文檔與 API 中的配置說明。