跳转至

常见问题

这里汇总了使用 zer0data SDK 时的常见问题和解决方案。

🚀 安装相关

Q: 安装时 Git 地址无法访问

问题描述

执行安装命令时出现：ERROR: Repository not found 或 fatal: Could not read from remote repository

解决方案：

  1. SSH 密钥未配置时改用 HTTPS： 

    pip install "git+https://github.com/zer0coldai/zer0data.git@main#subdirectory=sdk"

  2. 检查 SSH 密钥是否已添加到 GitHub： 

    ssh -T git@github.com
    预期输出：Hi <username>! You've successfully authenticated...

  3. 网络受限时使用代理： 

    GIT_SSH_COMMAND="ssh -o ProxyCommand='...'" pip install "git+ssh://..."

Q: 安装后导入失败

问题描述

安装成功但导入时出现：ModuleNotFoundError: No module named 'zer0data'

解决方案：

  1. 确认安装到了当前 Python 环境： 

    python -m pip show zer0data

  2. 确认 pip 和 python 指向同一环境： 

    which python && which pip

  3. 使用虚拟环境时确认已激活： 

    source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows
pip install "git+ssh://..."

Q: 依赖包 dbmodule 安装失败

问题描述

安装 zer0data 时报错：ERROR: Could not find a version that satisfies the requirement dbmodule

解决方案：

dbmodule 是项目内部包，需要同样从仓库安装，通常通过项目根目录的 pyproject.toml 统一管理。在单独安装 SDK 时，请先手动安装 dbmodule：

pip install "git+ssh://git@github.com/zer0coldai/zer0data.git@main#subdirectory=dbmodule"
pip install "git+ssh://git@github.com/zer0coldai/zer0data.git@main#subdirectory=sdk"

🔌 连接相关

Q: get_kline() 抛出连接错误

问题描述

调用 K 线查询时出现连接相关报错，如 ConnectionRefusedError 或 TimeoutError

解决方案：

  1. 确认 DolphinDB 服务已启动： 

    # 如果使用 Docker 部署
docker compose -f docker/clickhouse/compose.yml ps

  2. 检查端口是否可访问： 

    curl -v http://localhost:8123/ping   # ClickHouse HTTP

  3. 检查环境变量配置（如有）： 

    echo $ZER0DATA_DB_HOST
echo $ZER0DATA_DB_PORT

Q: get_symbols() 报 FileNotFoundError

问题描述

调用合约元数据查询时出现：FileNotFoundError: exchangeInfo.json not found

解决方案：

get_symbols() 依赖本地 exchangeInfo.json 快照文件，需要先执行抓取命令：

# 抓取 U 本位永续合约信息
zer0data ingest-source exchange-info --markets um

# 同时抓取 spot / um / cm
zer0data ingest-source exchange-info --markets spot --markets um --markets cm

或者在初始化 Client 时指定已有快照的目录：

client = zd.Client(data_dir="/path/to/exchange_info")

📊 查询相关

Q: get_kline() 传入不支持的 frequency 参数

问题描述

调用时报错：ValueError: invalid frequency: '3h'. Supported values: [...]

解决方案：

frequency 仅支持以下 8 种取值：

取值 含义
"1m" 1 分钟
"5m" 5 分钟
"15m" 15 分钟
"30m" 30 分钟
"1h" 1 小时
"2h" 2 小时
"4h" 4 小时
"1d" 日线

Q: get_kline() 返回空 DataFrame

问题描述

查询成功但返回的 DataFrame 为空，没有数据

可能原因及解决方案：

  1. 该合约在指定时间段内没有数据：确认合约上线时间（通过 get_symbols() 的 onboardDate 字段）早于查询起始日期

  2. 对应周期的数据尚未入库：确认已执行该周期的 ingest 操作： 

    docker compose -f docker/ingestor/compose.yml run --rm ingestor \
  ingest-from-dir --source /data --pattern "**/*-1h-*.zip"

  3. 日期格式错误：日期需为 YYYY-MM-DD 字符串，如 "2024-01-01"，而非 datetime 对象

Q: 查询大量数据时速度慢或内存占用高

问题描述

查询多标的 1m 数据时耗时较长，或程序内存溢出

解决方案：

  1. 使用 fields 仅选择需要的列： 

    df = client.get_kline(
    symbol="BTCUSDT",
    start_date="2024-01-01",
    end_date="2024-12-31",
    frequency="1m",
    fields="datetime,symbol,close,volume",  # 仅取 4 列
)

  2. 使用分页分批处理： 

    PAGE = 100_000
offset = 0
while True:
    chunk = client.get_kline(..., limit=PAGE, offset=offset)
    if chunk.empty:
        break
    # 处理 chunk
    offset += PAGE

  3. 优先使用高周期数据：1m 数据量约为 1h 的 60 倍，非必要不用分钟线

Q: get_symbols() 的 market 参数传入错误

问题描述

调用时报错：ValueError: invalid market: futures

解决方案：

market 仅支持三个取值：

取值 含义
"spot" 现货
"um" U 本位永续合约（默认）
"cm" 币本位永续合约

📦 数据相关

Q: 合约的 onboardDate / deliveryDate 是什么格式？

onboardDate 和 deliveryDate 均为**毫秒级 Unix 时间戳**（int）。如需转换为可读日期：

import pandas as pd

df = client.get_symbols(market="um")
df["onboardDate"] = pd.to_datetime(df["onboardDate"], unit="ms")
df["deliveryDate"] = pd.to_datetime(df["deliveryDate"], unit="ms")
print(df[["symbol", "onboardDate", "deliveryDate"]].head())

Q: 合约元数据已过期，如何更新？

快照不会自动刷新，需手动执行：

zer0data ingest-source exchange-info --markets um

建议将此命令加入定时任务（如每日凌晨执行），以保持合约列表的准确性。

Q: get_symbols() 返回的合约包含已下线合约，如何过滤？

返回数据中 status 列标识合约状态，"TRADING" 表示当前可交易：

df = client.get_symbols(market="um", quote_asset="USDT")
active = df[df["status"] == "TRADING"].reset_index(drop=True)
print(f"当前交易中的合约: {len(active)} 个")

仍未解决？ 请查看 K线数据 API 或 合约元数据 API 中的详细说明。