旧环境与新环境（v6）

由bq1fuwkt创建，最终由bq1fuwkt更新于2026-11-09 05:58 被浏览 2 用户

适用对象：准备将旧环境中的数据查询、Notebook 和交易策略迁移到 BigQuant v6 的用户，以及开始使用 v6 的新用户。本文把旧 dai、M.bigtrader 和 bigtraderv1 用法与新 bigquant.dai、bigquant.bigtrader 对照。环境名称为 v6 不代表已切换到计划中的纯新栈镜像；具体功能以当前 Studio 或任务的实际环境和运行结果为准。

1. 准备环境

在平台提供的 v6 AIStudio 中，先检查当前 Python 环境：

python -c "import bigquant; from bigquant import dai, bigtrader; print(bigquant.__version__)"
bq doctor

在本地使用 SDK 时，需安装 bigquant 并登录平台 API Key：

uv pip install bigquant
bq auth login --apikey bq_xxx
bq doctor

API Key 可在网站的设置页创建。不要把它写进 Notebook、策略文件或分享代码。平台 AIStudio 通常由当前会话提供身份，无需在代码中登录。若 bq doctor 报告引擎不可用，先确认 Python 版本与操作系统是否有对应的 BigTrader 引擎 wheel；数据查询仍可单独使用。参见 SDK 环境配置说明。

2. 查找并读取数据

先用目录命令确认数据源名称、字段和可用日期：

bq dai search 股票日线 --size=20
bq dai info cn_stock_bar1d
bq dai fields cn_stock_bar1d -q close

下面的查询读取限定日期和股票的日线，并转成 pandas DataFrame：

from bigquant import dai

result = dai.query(
    """SELECT date, instrument, close
       FROM cn_stock_bar1d
       ORDER BY date, instrument""",
    filters={
        "date": ["2024-01-02", "2024-01-31"],
        "instrument": ["000001.SZ"],
    },
)
df = result.df()
print(df.head())
print("行数:", len(df))
if not df.empty:
    print("日期范围:", df["date"].min(), df["date"].max())

filters 用来裁剪历史数据分区；查询多张表时也会作用于计划中的相关表。结果是否符合预期，还要检查行数、日期、股票代码和空值。需要滚动均值或横截面排名时，在 SQL 中使用 m_*、c_* 运算符，并为滚动窗口多取一段历史；不要先用逐行 WHERE 删掉窗口所需的记录。数据源检索、查询方式和 SQL 示例见数据指南与 SQL 指南。

3. 编写并运行回测

把下面内容保存为 strategy.py，在有新 BigTrader 引擎的环境中运行：

from bigquant import bigtrader

\
def initialize(context):
    context.target_weight = 0.8

\
def handle_data(context, data):
    instrument = "000001.SZ"
    if context.get_position(instrument).current_qty == 0:
        context.order_target_percent(instrument, context.target_weight)

\
perf = bigtrader.run(
    instruments=["000001.SZ"],
    start_date="2024-01-02",
    end_date="2024-06-28",
    capital_base=1_000_000,
    initialize=initialize,
    handle_data=handle_data,
)
print(perf.diagnostics)
print(perf.metrics["annualized_return"].value)
print(perf.result.trades.tail())

python strategy.py

initialize 设置策略状态，handle_data 逐个交易时点处理行情和订单；bigtrader.run() 返回回测结果。先看 perf.diagnostics 和成交表，再看收益率：零成交、订单被拒或数据缺失都可能让回测正常结束，却得不到预期交易。真实策略还应明确可交易标的、交易成本、信号日期与资金约束。完整示例见策略编写、结果解读和常见隐性错误。

4. 从旧环境迁移：按用法对照

先复制原 Notebook 或策略，保留旧环境中同一日期范围的查询结果、订单、成交、持仓和收益作为基线。以下对照针对常见旧写法；旧 M.bigtrader、直接调用 bigtraderv1 和新版 SDK 是不同接口，不能通过全局替换包名完成迁移。

数据查询与数据源

普通 SQL 查询的结构相近，首先换入口，再核对查询结果：

# 旧环境
import dai
old_df = dai.query(
    "SELECT date, instrument, close FROM cn_stock_bar1d",
    filters={"date": ["2024-01-02", "2024-01-31"]},
).df()

# 新环境
from bigquant import dai
new_df = dai.query(
    "SELECT date, instrument, close FROM cn_stock_bar1d",
    filters={"date": ["2024-01-02", "2024-01-31"]},
).df()

同名 dai 不是同一个包，SQL 引擎和依赖版本也可能不同。对比行数、date/instrument 键、列类型、空值与关键数值，不能只看查询是否成功。旧代码使用 udf_list、compression、auto_load_udf 等专有参数时，应重新查新 help(dai.query)，不要原样传入。

旧 DataSource.read() 常把日期、股票和字段直接作为参数，返回 DataFrame；新 read_bdb() 使用分区过滤，默认返回 Arrow Table，要 DataFrame 时显式指定：

# 旧环境：读取 BDB 表
import dai
df = dai.DataSource("cn_stock_bar1d").read(
    start_date="2024-01-02",
    end_date="2024-01-31",
    instruments=["000001.SZ"],
    fields="date,instrument,close",
)

# 新环境：读取同一 BDB 表
import pandas as pd
from bigquant import dai

df = dai.DataSource("cn_stock_bar1d").read_bdb(
    as_type=pd.DataFrame,
    partition_filter={
        "date": ("2024-01-02", "2024-01-31"),
        "instrument": {"000001.SZ"},
    },
    columns=["date", "instrument", "close"],
)

partition_filter 中元组表示闭区间，集合表示指定值。旧 DataSource 和新 bigquant.dai.DataSource 是不同 Python 类；把新类对象直接传给旧 M.bigtrader.v30(data=...) 可能报“不支持的标的类型”。自有数据源的写入、追加、去重和读取请按新数据源指南重新检查。

交易策略：模块先保持原样；需要时再改用 SDK

旧环境和当前兼容 v6 中，from bigmodule import M、M.xxx.vN(...) 的调用方式相同，先保持原样运行。只有具体模块报输入或依赖错误时才处理该处，例如旧 M.bigtrader.v30 可能不接受新 bigquant.dai.DataSource。若你主动选择改用新 SDK 交易接口，才将模块策略改为 bigtrader.run(...)。下面是两种写法的结构对照，并非必须迁移步骤或收益相同的证明。

# 旧模块代码骨架
from bigmodule import M
import dai

signal_df = dai.query(
    "SELECT date, instrument FROM cn_stock_bar1d",
    filters={"date": ["2024-01-02", "2024-06-28"], "instrument": ["000001.SZ"]},
).df()

\
def handle_data(context, data):
    today = data.current_dt.strftime("%Y-%m-%d")
    rows = context.data[context.data["date"] == today]
    if not rows.empty:
        context.order_target_percent("000001.SZ", 0.8)

\
module_result = M.bigtrader.v30(
    data=signal_df,
    start_date="2024-01-02",
    end_date="2024-06-28",
    frequency="daily",
    product_type="股票",
    handle_data=handle_data,
)

# 新 SDK 代码骨架
from bigquant import bigtrader, dai

\
def initialize(context: bigtrader.Context):
    context.df = dai.query(
        "SELECT date, instrument FROM cn_stock_bar1d",
        filters={"date": [context.start_date, context.end_date], "instrument": context.instruments},
    ).df()

\
def handle_data(context: bigtrader.Context, data: bigtrader.DataReader):
    rows = context.df[context.df["date"] == context.trading_day]
    if not rows.empty:
        context.order_target_percent("000001.SZ", 0.8)

\
perf = bigtrader.run(
    instruments=["000001.SZ"],
    start_date="2024-01-02",
    end_date="2024-06-28",
    frequency="1d",
    initialize=initialize,
    handle_data=handle_data,
)
print(perf.diagnostics)
print(perf.result.trades.tail())

需要核对信号表的 date 类型与运行日是否能正确匹配；滚动信号还需在 filters 中为窗口多取历史。可按策略数据示例在 initialize 中按本次运行日期加载。旧模块通常给回调传入字符串代码和模块端口；新 run() 接受 Python callable。新 instruments 必须覆盖所有可能下单的标的，data 参数是行情读取器，不是旧模块的信号输入。

旧用法	新 `bigquant` 用法	需要人工核对
`import dai`	`from bigquant import dai`	简单查询可沿用 SQL 形态；旧 DAI 专有参数、UDF 和读写方法需逐个迁移。
`DataSource.read(start_date=..., instruments=..., fields=...)`	`DataSource.read_bdb(as_type=pd.DataFrame, partition_filter=..., columns=...)`	新默认结果是 Arrow Table；自定义或非 BDB 数据源需按实际格式选读取方法。
`from bigmodule import M`、`M.bigtrader.v30(...)`	先保持原调用；只有主动切新 SDK 时才用 `bigtrader.run(...)`	模块语法未统一变化；若遇到新 DataSource 类型错误，先核对模块输入。新 SDK 的 `context.data` 不自动出现。
`frequency="daily"`、`product_type="股票"`	`frequency="1d"`、默认股票市场；其他品种显式设 `market`	分钟/tick 订阅、账户类型和交易日历须重验。
`context.rebalance_period`、`backtest_engine_mode`	在策略中表达调仓规则；新 `run()` 由新引擎执行	没有同名参数的直接映射，不能把旧调仓周期或引擎模式静默丢掉。
`bigtrader.IContext`、`bigtraderv1.IContext`	`bigquant.bigtrader.Context`	改类型注解只是第一步；回调方法、数据和结果对象也须核对。
旧 `raw_perf`/模块输出	`perf.diagnostics`、`perf.metrics`、`perf.result`	指标定义、订单、成交、持仓和日期要对拍。

若原策略直接 import bigtraderv1 as bigtrader 或 import bigtrader，并决定使用新 SDK，仍需按上表逐项迁移；这两个旧包的类和参数不等于 bigquant.bigtrader。目标环境若缺少所用模块或模块内部依赖，先确认可用版本和处理办法，不要自行猜测替代接口。复制自社区、模板、知识库或课程的代码，也要检查实际取得的代码版本；页面能打开、代码能复制，不代表能在当前环境运行。

迁移后至少用同一输入比较数据行数和字段、交易日期、订单、成交、持仓及主要指标，并解释成本、撮合或引擎造成的差异。模拟和实盘策略先在回测中验证，再按平台流程部署。不要直接改写仍在运行的任务或已发布版本来试错。

5. 遇到问题时

导入失败：查看 python -c "import bigquant; print(bigquant.__version__)" 与 bq doctor；核实当前 Studio 或任务实际使用的环境。旧 dai、bigtrader 包在纯新栈候选中不提供。
查询为空或结果不对：运行 bq dai info <数据源名>，核对分区字段、filters、日期范围、股票代码和空值。分钟数据的日期包含时分秒，日期范围终点要覆盖所需交易日。
回测结束却没有交易：检查 perf.diagnostics、perf.result.orders 与 perf.result.trades，确认 instruments 覆盖下单标的，订单未被拒绝，信号日期能与交易日匹配。
旧策略或分享内容无法运行：保留原代码及报错信息，记录 Studio 环境或任务运行信息，通过平台原有支持渠道反馈；在确认新接口和结果前不要把旧任务直接投入实盘。

更详细的接口与示例可在已安装 SDK 的环境运行 bq docs、bq examples，或查看 help(bigtrader.run)、help(dai.query)。