QuantZone 安装与使用教程:从 SDK 安装到因子查询

如果你做 A 股量化研究，最怕的往往不是模型没想法，而是数据接入链路太长：先找数据源，再整理合约代码，再处理交易日历，最后还要把数据拼成能进策略或回测框架的形状。

QuantZone 的定位很直接：把常用的 A 股因子数据、指数行情、股票合约信息、交易日历和因子回测能力，用一个 Python SDK 暴露出来。本文按“能跑起来”的顺序，带你完成安装、获取凭证、查询数据和常见排错。

本文参考 QuantZone 官方文档：https://quantzone.tech/docs

示例仅用于 SDK 接入演示，不构成任何投资建议。

1. 准备环境

QuantZone SDK 当前文档对应版本为 quantzone 0.8.1。使用前需要准备三样东西：

• Python 3.9 或更高版本
• QuantZone 平台账号（免费注册）
• 控制台里创建的 API 凭证：access_key、sign_secret 和 base_url

官方 wheel 覆盖 Python 3.9 到 3.14，支持 Windows、macOS 和 Linux。日常研究环境里，用虚拟环境安装会更干净：

python -m venv .venv.venv\Scripts\activate

如果你在 macOS 或 Linux：

python3 -m venv .venvsource .venv/bin/activate

2. 安装 QuantZone

全新安装：

pip install quantzone

如果你之前装过旧版本，建议直接升级：

pip install -U quantzone

安装后可以检查版本：

python -c "import quantzone; print(quantzone.__version__)"

如果后续遇到 SDKVersionError 或 HTTP 426，优先执行 pip install -U quantzone。

3. 获取 API 凭证

登录 QuantZone 后，进入控制台的 API Key 页面，点击创建密钥。你会拿到三项配置：

• base_url
  ：云端 API 地址，控制台 API Key 页可见
• access_key
  ：公开标识符，可在控制台查看
• sign_secret
  ：签名密钥，只在创建或重置时展示一次
  

这里最重要的是 sign_secret。它用于 SDK 在本地生成请求签名，不要提交到 Git 仓库，也不要写进前端代码、日志或截图里。如果泄露或遗失，可以在控制台重置密钥，旧凭证会立即失效。

4. 第一次连通测试

先用 get_quota() 查一下自己的配额，这是最适合作为连通性测试的接口：

from quantzone import QuantZoneclient = QuantZone(    access_key="你的_access_key",    sign_secret="你的_sign_secret",    base_url="https://api.quantzone.tech",)quota = client.get_quota()print(quota)client.close()

能正常打印配额信息，就说明 SDK 安装、网络连接和鉴权都通过了。

{'daily_quota_bytes': 268435456, 'daily_used_bytes': 0, 'extra_quota_bytes': 0, 'available_bytes': 268435456, 'remaining_days': None, 'license_type': '免费版'}

更推荐的写法是用 with 自动关闭连接：

from quantzone import QuantZonewith QuantZone(    access_key="你的_access_key",    sign_secret="你的_sign_secret",    base_url="https://your-cloud-api.example.com",) as client:    print(client.get_quota())

5. 查询因子数据

QuantZone 最核心的接口是 get_factors()。它返回的是窄表 DataFrame，固定四列：

• date
  ：数据日期
• order_book_id
  ：股票代码
• value
  ：因子值
• factor
  ：因子名

查询两个股票在一段时间内的某个因子：

from quantzone import QuantZonewith QuantZone(    access_key="你的_access_key",    sign_secret="你的_sign_secret",    base_url="https://your-cloud-api.example.com",) as client:    df = client.get_factors(        ukey=["000001.XSHE", "600519.XSHG"],        factor="trend_dominance_factor",        start_date="2024-01-02",        end_date="2024-01-31",    )print(df.head())

如果省略 ukey，表示查询全市场。需要注意几个边界：

• factor
   必填，支持单个因子或因子列表
• 单次最多查询 20 个因子
• ukey
   单次最多 100 个
• 日期区间跨度不超过 365 天
• 大查询建议按月份或按因子分批

如果你的策略或回测框架更喜欢宽表，可以自己透视：

wide = df.pivot_table(    index=["date", "ukey"],    columns="factor",    values="value",)

6. 查看可用因子和股票列表

不知道有哪些因子时，用 list_factors()：

factors = client.list_factors()print(factors[:5])

返回结果里包含因子名和该因子的数据起止日期。

查看股票合约信息，用 list_stocks()：

stocks = client.list_stocks()print(stocks.head())

返回 DataFrame 包含：

• order_book_id
  ：股票代码
• industry_name
  ：行业名称
• symbol
  ：股票简称

7. 查询指数行情

指数日线接口是 get_index_daily()。和因子数据不同，指数代码必须带交易所后缀：

df = client.get_index_daily(    ukey=["000001.XSHG", "399001.XSHE"],    fields=["open", "close", "daily_return"],    start_date="2024-01-02",    end_date="2024-01-31",)print(df.head())

fields 可选字段包括：

• open
• close
• high
• low
• prev_close
• daily_return
• volume
• total_turnover

如果省略 fields，默认返回全部字段。

8. 使用交易日历

量化研究里，日期处理很容易埋坑。QuantZone 提供了几个交易日历接口：

dates = client.get_trading_dates("2024-01-01", "2024-01-31")print(dates[:3])prev_day = client.get_previous_trading_date("2024-01-15")next_day = client.get_next_trading_date("2024-01-15", n=5)print(client.is_trading_date("2024-01-02"))print(client.is_trading_date("2024-01-06"))

日期参数支持几种常见写法，例如：

• 20240131
• "2024-01-31"
• "20240131"
• "2024/01/31"
• datetime.date
• datetime.datetime
• pandas.Timestamp

不建议传 "today"、"now" 或带时区后缀的字符串，SDK 会拒绝不在白名单内的日期格式。

9. 因子回测的基本流程

如果要使用 SDK 内置因子回测，流程是三步：

client.prepare_backtest_data()data = client.load_backtest_data()

然后准备宽表因子，调用 backtest()：

df = client.get_factors(    factor="trend_dominance_factor",    start_date="2023-01-01",    end_date="2023-12-31",)wide = df.pivot(index="date", columns="order_book_id", values="value")result = client.backtest(    wide,    data,    "2023-01-01",    "2023-12-31",    "./output",    "trend_dominance_factor",    group_num=10,)print(result.summary())print(result.best_group)print(result.plot_paths)

首次执行 prepare_backtest_data() 会下载基准数据，后续会增量更新。回测结果里包含分组收益、累计收益、Rank IC、超额指标和图片路径。

10. 常见问题

鉴权失败怎么办？

先检查三件事：本机系统时间是否准确，sign_secret 是否复制完整，SDK 是否为最新版。如果不确定，先升级：

pip install -U quantzone

大查询超时怎么办？

timeout 默认 60 秒，官方文档说明上限也是 60 秒，不能靠无限调大超时解决。正确方式是分批查询：

import pandas as pdmonths = pd.date_range("2024-01-01", "2024-12-31", freq="MS")for start in months:    end = start + pd.offsets.MonthEnd(0)    df = client.get_factors(        factor="trend_dominance_factor",        start_date=start,        end_date=end,    )    # 在这里处理或保存 df

查询结果会自动保存到本地吗？

不会。get_factors() 和 get_index_daily() 只返回内存里的 DataFrame。需要落盘时自己保存：

df.to_parquet("factor.parquet")df.to_csv("factor.csv", index=False)

接口失败要不要自动重试？

只建议对 NetworkError 这类瞬时网络问题做有限重试。不要重试 AuthError、QuotaExceededError、SDKVersionError 这类确定性失败，否则只是浪费时间和配额。

结语

如果只是想把 QuantZone 接到自己的研究脚本里，最短路径其实很清晰：

1. pip install -U quantzone
2. 在控制台创建 API Key，保存 base_url、access_key、sign_secret
3. 用 get_quota() 做连通性测试
4. 用 list_factors() 找因子，用 get_factors() 拉数据
5. 按需把窄表 DataFrame 透视成宽表，接入自己的研究或回测流程

数据接口稳定之后，研究节奏会顺很多。把重复的数据准备工作交给 SDK，自己把注意力留给因子逻辑、组合构建和风险控制。

参考资料：

• QuantZone 官方文档：https://quantzone.tech/docs
• PyPI quantzone：当前最新版本 0.8.1