feat: 解决 aarch64 上 Qlib 安装（源码 git 固化依赖）并记录下载代理规则
- backend/pyproject.toml + uv.lock: pyqlib 以 git+https 固定 commit 79633dd 注册为核心依赖， 替代无法在 Linux aarch64 安装的 PyPI wheel（ROADMAP §2 旧备注） - engine.py: 更正占位说明（Qlib 现已可安装，工作流实现待 Phase 2 补齐） - AGENT.md §0: 网络下载困难时使用 HTTP 代理 192.168.1.160:3128 - README / ROADMAP: 同步 Qlib 安装方式与代理说明
This commit is contained in:
Simon
@@ -10,6 +10,38 @@
|
||||
|
||||
---
|
||||
|
||||
# 0. 网络下载与代理规则
|
||||
|
||||
当网络下载（git clone、pip / uv 安装、wget、数据下载、Docker pull 等）出现**困难或超时**时，
|
||||
统一使用本机局域网 HTTP 代理：
|
||||
|
||||
```text
|
||||
192.168.1.160:3128
|
||||
```
|
||||
|
||||
示例（仅在下载失败 / 超时时启用，不把代理写入代码或 Git）：
|
||||
|
||||
```bash
|
||||
# git clone（仅对 GitHub 等外网 https 目标使用）
|
||||
git -c http.proxy=http://192.168.1.160:3128 -c https.proxy=http://192.168.1.160:3128 clone <url>
|
||||
|
||||
# pip / uv 安装
|
||||
export http_proxy=http://192.168.1.160:3128
|
||||
export https_proxy=http://192.168.1.160:3128
|
||||
uv pip install <pkg>
|
||||
|
||||
# wget / curl
|
||||
wget -e use_proxy=yes -e http_proxy=http://192.168.1.160:3128 <url>
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 代理只用于**外网**下载；内网资源（如 ssh git@192.168.1.10、局域网服务）不要走代理。
|
||||
- 代理 IP 属于局域网配置，不写入 `.env` / `config.yaml` / 任何提交进 Git 的文件。
|
||||
- 直接下载成功时不要多此一举走代理。
|
||||
|
||||
---
|
||||
|
||||
# 1. 项目定位
|
||||
|
||||
这是一个：
|
||||
|
||||
@@ -60,7 +60,7 @@ cp .env.example .env
|
||||
|
||||
# 2. 安装依赖（自动使用 Python 3.12，见 backend/.python-version）
|
||||
cd backend
|
||||
uv sync
|
||||
uv sync # 含 pyqlib（GitHub 源码依赖，固定 commit）。若网络下载困难/超时，按 AGENT.md §0 设置代理 192.168.1.160:3128 后重试
|
||||
|
||||
# 3. 运行测试
|
||||
uv run pytest
|
||||
|
||||
@@ -1,15 +1,14 @@
|
||||
"""Qlib 后端引擎（桥接占位）。
|
||||
|
||||
当前开发平台为 Linux aarch64 + CPython 3.12：pyqlib 官方仅提供 x86_64 /
|
||||
macOS / Windows 且最高 Python 3.8 的 wheel（实测 uv 解析不可满足），因此
|
||||
Qlib 实现在此平台无法安装运行。
|
||||
本模块是 Qlib 引擎的桥接边界（AGENT.md §14 / §15：Qlib 只允许在
|
||||
quant/qlib_adapter/ 内被引用）。Qlib（pyqlib）已通过「源码 git 安装」成功
|
||||
部署到本机（Linux aarch64 + CPython 3.12，backend/.venv，uv 管理；
|
||||
backend/pyproject.toml 固定 commit，细节见 docs/ROADMAP.md §2 备注）。
|
||||
|
||||
受支持平台（如 x86_64 Linux + Python 3.11）启用方式：
|
||||
cd backend && uv pip install pyqlib==0.9.7
|
||||
将本模块替换为真实实现：Parquet/本地行情 → QlibDataset → Alpha158 →
|
||||
LightGBM 训练/预测 → 回测，并归一化为 domain.entities.research 输出。
|
||||
|
||||
业务层经 app.quant.engine.QuantEngine Protocol 注入引擎，切换无需改业务代码。
|
||||
基于 Qlib 的因子 / 回测工作流（Parquet/本地行情 → QlibDataset → Alpha158 →
|
||||
LightGBM 训练/预测 → 回测，并归一化为 domain.entities.research 输出）属
|
||||
Phase 2 后续实现；当前默认研究引擎仍为 LocalEngine（纯 pandas，见
|
||||
app/quant/engine.py），业务层经 QuantEngine Protocol 注入，切换无需改业务代码。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -20,8 +19,8 @@ from app.domain.entities.research import BacktestResult, FactorTestReport, Resea
|
||||
from app.quant.engine import QuantEngine
|
||||
|
||||
_MSG = (
|
||||
"Qlib 引擎需要 pyqlib，当前平台（Linux aarch64 + Python 3.12）无可用 wheel。"
|
||||
"请改用 LocalEngine 或在受支持平台安装 pyqlib 后实现（见本模块 docstring）。"
|
||||
"Qlib 引擎工作流尚未实现：pyqlib 现已可在本机安装使用（见 docs/ROADMAP.md §2），"
|
||||
"但 QlibDataset → LightGBM 的实现待 Phase 2 补齐。当前请使用默认 LocalEngine。"
|
||||
)
|
||||
|
||||
|
||||
|
||||
@@ -11,6 +11,9 @@ dependencies = [
|
||||
"alembic>=1.13",
|
||||
"pyyaml>=6.0",
|
||||
"httpx>=0.28.1",
|
||||
# Qlib 研究引擎：PyPI 无 aarch64 wheel（见 docs/ROADMAP.md §2 备注），故从源码 git 安装并固定 commit。
|
||||
# 网络下载困难时使用 HTTP 代理（见根目录 AGENT.md §0：192.168.1.160:3128）。
|
||||
"pyqlib @ git+https://github.com/microsoft/qlib.git@79633dd",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
|
||||
Generated
+3297
File diff suppressed because it is too large
Load Diff
+8
-4
@@ -68,10 +68,14 @@
|
||||
|
||||
## 2. Phase 2 —— 研究引擎（M2）
|
||||
|
||||
> 实施备注（2026）：pyqlib 官方 wheel 仅支持 x86_64 / macOS / Windows 且最高 Python 3.8 构建；
|
||||
> 本项目开发机为 Linux aarch64 + Python 3.12，无法安装 Qlib（已实测 pip 解析不可满足）。
|
||||
> 依据 AGENT.md §40「更简单、可替换优先」与 Qlib 经 Adapter 隔离的约束，M2 交付**引擎接口 + 默认自研轻量引擎**（pandas 实现因子/评估/低频回测，完整可测）；
|
||||
> `quant/qlib_adapter/` 保留桥接边界，在支持平台安装 pyqlib 后填充 Qlib Dataset / LightGBM 工作流实现，业务层不感知切换。
|
||||
> 实施备注（2026-09 更新）：PyPI `pyqlib` 官方 wheel 仅支持 x86_64 / macOS / Windows，在 Linux aarch64 上 pip 解析不可满足（旧备注）；
|
||||
> 现已改用 **microsoft/qlib 源码 git 安装**并验证成功：开发机 Linux aarch64 + CPython 3.12（backend/.venv，uv 管理），
|
||||
> 依赖已注册进 `backend/pyproject.toml`（`pyqlib @ git+https://github.com/microsoft/qlib.git@79633dd`，固定 commit，随 uv.lock 固化）；
|
||||
> numpy/pandas/scipy/lightgbm/pyarrow 等使用 aarch64 PyPI wheel，qlib 的两个 Cython 扩展（rolling/expanding）源码构建通过，
|
||||
> 已验证 `import qlib` / `qlib.init()` / LightGBM 训练预测正常。源码 checkout 保留在项目外 `/home/pi/project/qlib-src`（供查阅/二次开发）；
|
||||
> 网络下载困难时按 AGENT.md §0 使用 HTTP 代理（192.168.1.160:3128）。
|
||||
> M2 依据 AGENT.md §40「更简单、可替换优先」与 Qlib 经 Adapter 隔离的约束，交付**引擎接口 + 默认自研轻量引擎**（pandas 实现因子/评估/低频回测，完整可测）；
|
||||
> `quant/qlib_adapter/` 为桥接边界，现可在本机填充 Qlib Dataset / LightGBM 工作流实现（Phase 2 后续），业务层不感知切换。
|
||||
|
||||
> 目标：用 Research Specification 驱动「因子 → 评估 → 低频选股回测」闭环，产出标准化结果。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user