學習筆記：Qlib 量化投資平臺框架 — FIRST STEPS

Qlib 是微軟亞洲研究院開源的一個面向人工智能的量化投資平臺，旨在實現人工智能技術在量化投資中的潛力，賦能研究，并創造價值，從探索想法到實施生產。Qlib 支持多種機器學習建模范式，包括監督學習、市場動態建模和強化學習。借助 Qlib，用戶可以輕松嘗試他們的想法，以創建更優秀的量化投資策略。

文中內容僅限技術學習與代碼實踐參考，市場存在不確定性，技術分析需謹慎驗證，不構成任何投資建議。

安裝指南

一、環境要求

1. 操作系統
   • 支持 Windows、MacOS 和 Linux，推薦使用 Linux。
2. Python 版本
   • 支持 Python3， Python >=3.8。

二、安裝方法

1. 通過 pip 安裝

pip install pyqlib

2. 通過源碼安裝

步驟說明：

1. 進入 Qlib 根目錄（包含 setup.py 文件）。

2. 依次執行以下命令：

   # 安裝環境依賴
   pip install numpy
   pip install --upgrade cython# 克隆倉庫并安裝
   git clone https://github.com/microsoft/qlib.git && cd qlib
   python setup.py install
   

三、注意事項

1. 環境管理
   • 推薦使用 anaconda 或 miniconda 創建獨立環境。
2. 依賴包安裝

   • 需額外通過 pip 安裝 lightgbm 和 pytorch：

     pip install lightgbm torch torchaudio torchvision
     

四、驗證安裝

執行以下 Python 代碼確認安裝成功：

import qlib
print(qlib.__version__)  # 輸出應為當前安裝版本（如 0.9.6）

關鍵總結

• 優先選擇 Linux 環境，Python 版本需 >=3.8。
• 源碼安裝需按順序處理依賴（numpy → cython → 克隆倉庫）。
• 通過 conda 管理環境可減少依賴沖突風險。
• 必須單獨安裝 lightgbm 和 pytorch 以支持完整功能。

初始化

一、初始化流程

1. 數據準備

   • 執行以下命令下載默認數據集（中國股市數據）：

     python scripts/get_data.py qlib_data --target_dir ~/.qlib/qlib_data/cn_data --region cn
     

   • 數據來源：Yahoo Finance（可能存在缺陷，建議用戶使用高質量自定義數據）。

   • 自定義數據格式要求：詳見 Data Preparation 部分。

2. 初始化 Qlib

   • 在調用其他 API 前，需運行以下 Python 代碼初始化：

     import qlib
     from qlib.constant import REG_CNprovider_uri = "~/.qlib/qlib_data/cn_data"  # 數據存儲路徑
     qlib.init(provider_uri=provider_uri, region=REG_CN)
     

   • 注意：禁止在 Qlib 代碼倉庫目錄內導入 qlib 包，否則可能報錯。

二、關鍵參數解析

qlib.init() 支持以下核心參數配置：

• provider_uri
  類型：str，必填，數據存儲路徑（如 ~/.qlib/qlib_data/cn_data）。

• region
  類型：str，默認值為REG_CN，市場模式：

  • REG_CN（中國股市）
  • REG_US（美國股市）
    不同模式對應交易規則（如最小交易單位、交易限制）。

• redis_host
  類型：str，默認值為"127.0.0.1"，Redis 主機地址（用于緩存與鎖機制）。

• redis_port
  類型：int，默認值為6379，Redis 端口。

• exp_manager
  類型：dict，默認值無，實驗管理器配置（如使用 MLflow）：

  exp_manager={"class": "MLflowExpManager","module_path": "qlib.workflow.expm","kwargs": {"uri": "path/mlruns", "default_exp_name": "Experiment"}
  }
  

• mongo
  類型：dict，默認值無，MongoDB 配置（用于任務管理）：

  mongo={"task_url": "mongodb://localhost:27017/","task_db_name": "rolling_db"
  }
  

• logging_level
  默認值無，系統日志級別（如 DEBUG, INFO）。

• kernels
  類型：int，默認值無，表達式引擎進程數（調試時可設為 1）。

三、注意事項

1. 數據與 region 一致性

   • region 必須與 provider_uri 中數據對應。當前 get_data.py 僅支持中國數據，使用美國數據需用戶自行準備。

2. Redis 依賴

   • 若 Redis 連接失敗（錯誤配置或未啟動），緩存機制將失效。

3. 實驗管理器配置

   • exp_manager 需嚴格按字典格式定義類、模塊路徑及參數（如 MLflowExpManager）。

4. MongoDB 前置條件

   • 使用 mongo 參數前需安裝并啟動 MongoDB，通過 URI 訪問（支持帶認證的 URL）。

5. 調試建議

   • 調試表達式計算時，設置 kernels=1 以簡化問題定位。

四、補充說明

• 區域模式擴展性：region 是預定義配置的快捷方式，用戶可通過手動設置交易單位（trade_unit）、限制閾值（limit_threshold）等覆蓋默認行為。
• 緩存機制文檔：詳見 Cache 部分。

數據檢索功能

一、環境初始化

import qlib
qlib.init(provider_uri='~/.qlib/qlib_data/cn_data')  # 必須初始化后才能獲取數據

• 需預先完成數據下載并設置正確的provider_uri路徑

二、交易日歷操作

from qlib.data import D
calendar = D.calendar(start_time='2010-01-01', end_time='2017-12-31', freq='day')
print(calendar[:2])  # 輸出前兩個交易日

• 支持時間范圍過濾
• 可指定頻率參數(freq)

三、股票池管理

1. 基礎配置

D.instruments(market='all')  # 全市場配置
D.instruments(market='csi300')  # 滬深300成分股

2. 動態篩選器

(1) 正則篩選器

from qlib.data.filter import NameDFilter
name_filter = NameDFilter(name_rule_re='SH[0-9]{4}55')  # 匹配SHxxxx55格式

(2) 表達式篩選器

from qlib.data.filter import ExpressionDFilter
expr_filter = ExpressionDFilter(rule_expression='$close>2000')  # 收盤價大于2000

(3) 組合使用

instruments = D.instruments(market='csi300', filter_pipe=[name_filter, expr_filter])

四、特征數據加載

1. 基礎特征獲取

fields = ['$close', '$volume', 'Ref($close, 1)', 'Mean($close, 3)', '$high-$low']
data = D.features(['SH600000'], fields, start_time='2010-01-01', freq='day')

完整Features參考詳見官方文檔：Feature API Reference

2. 帶緩存的加載

D.features(..., disk_cache=1)  # 啟用緩存
D.features(..., disk_cache=0)  # 禁用緩存（客戶端默認）
D.features(..., disk_cache=2)  # 服務端更新緩存

3. 高級表達式構建

方法一：字符串表達式

"(($high / $close) + ($open / $close)) * ..."

方法二：代碼對象構建

from qlib.data.ops import *
f1 = Feature("high") / Feature("close")
f2 = Feature("open") / Feature("close")
f3 = (f1 + f2) * (f1 + f2) / (f1 + f2)

五、注意事項

1. 首次請求數據時因緩存初始化可能較慢
2. 相同股票池和字段的后續請求會利用緩存加速
3. 復雜表達式建議分步構建以提高可讀性
4. 時間范圍參數需遵循格式規范

完整API參考詳見官方文檔：Data API Reference

自定義模型集成

一、核心流程

1. 定義模型類：繼承 qlib.model.base.Model
2. 編寫配置文件：描述模型路徑和參數
3. 模型測試：通過命令行或代碼驗證

二、自定義模型類實現規范

2.1 必須重寫方法

(1) __init__ 方法

• 接收來自配置文件的初始化參數
• 必須與配置文件參數命名嚴格一致
• 示例邏輯：

def __init__(self, loss='mse', **kwargs):# 參數校驗if loss not in {'mse', 'binary'}:raise NotImplementedError# 參數存儲self._params.update(objective=loss, **kwargs)

(2) fit 方法

• 輸入必須包含 dataset: DatasetH
• 支持可選參數默認值（如 num_boost_round=1000）
• 典型處理流程：

def fit(self, dataset, num_boost_round=1000):# 數據準備df_train, df_valid = dataset.prepare(...)# 特征/標簽分離x_train, y_train = df_train["feature"], df_train["label"]# 模型訓練self.model = lgb.train(...)

(3) predict 方法

• 必須返回 pd.Series 格式預測結果
• 示例實現：

def predict(self, dataset):x_test = dataset.prepare(...)return pd.Series(self.model.predict(x_test.values), index=x_test.index)

2.2 可選方法

finetune 方法

• 需繼承 ModelFT 基類
• 實現微調邏輯：

def finetune(self, dataset, num_boost_round=10):dtrain = self._prepare_data(dataset)self.model = lgb.train(..., init_model=self.model)

三、配置文件規范

model:class: LGBModel                  # 類名module_path: qlib.contrib.model  # 模塊路徑args:loss: mse                    # __init__參數learning_rate: 0.0421        # 模型超參數max_depth: 8# ...其他參數

注意要點：

1. args 內參數通過 **kwargs 傳遞給 __init__
2. 基準配置參考路徑：examples/benchmarks/<MODEL_NAME>/

四、模型測試方法

4.1 命令行測試

cd examples
qrun benchmarks/LightGBM/workflow_config_lightgbm.yaml

4.2 代碼測試

參考示例：examples/workflow_by_code.ipynb

五、關鍵注意事項

1. 參數一致性：配置參數必須與__init__定義完全匹配
2. 數據維度：
   • LightGBM 要求標簽為 1D 數組
   • 需處理 y_train.values.ndim == 2 的情況
3. 錯誤處理：
   • 必須校驗 self.model is not None 后才執行預測
4. 微調要求：
   • 需顯式繼承 ModelFT 基類

六、擴展參考

1. 預測模型文檔：Forecast Model: Model Training & Prediction
2. API 文檔：Model API
3. 基準模型實現：examples/benchmarks/ 目錄下的各模型實現

風險提示與免責聲明
本文內容基于公開信息研究整理，不構成任何形式的投資建議。歷史表現不應作為未來收益保證，市場存在不可預見的波動風險。投資者需結合自身財務狀況及風險承受能力獨立決策，并自行承擔交易結果。作者及發布方不對任何依據本文操作導致的損失承擔法律責任。市場有風險，投資須謹慎。