57 lines
2.5 KiB
Markdown
57 lines
2.5 KiB
Markdown
# OpenBB 集成指南
|
||
|
||
本指南帮助你在本项目中启用并使用 OpenBB v4 作为市场数据源，同时保证在未安装 OpenBB 的情况下，应用可平稳回退到演示/合成数据。
|
||
|
||
## 1. 为什么选择 OpenBB v4
|
||
- 统一的路由接口：`from openbb import obb`
|
||
- 多数据提供商聚合（如 yfinance、polygon、fmp 等）
|
||
- 返回对象支持 `.results` 或 `.to_df()`，便于统一处理
|
||
|
||
## 2. 安装与环境准备
|
||
默认未安装 OpenBB（requirements.txt 中为可选依赖）。如需启用：
|
||
|
||
```bash
|
||
pip install "openbb>=4.1.0"
|
||
```
|
||
|
||
若你使用的是国内网络，建议配置合适的 PyPI 镜像或使用代理。
|
||
|
||
## 3. 配置说明
|
||
无需额外配置即可使用 `provider='yfinance'` 的公共数据。若你有付费数据源（如 polygon），可通过环境变量或 OpenBB 的 provider 配置进行设置。
|
||
|
||
## 4. 代码结构与调用方式
|
||
- Streamlit UI: `app/tabs/openbb_tab.py`
|
||
- 自动检测 OpenBB 是否可用；若不可用则使用演示数据或合成数据
|
||
- 优先路由：`obb.equity.price.historical`，ETF 回退至 `obb.etf.price.historical`
|
||
- 引擎模块: `src/jixia/engines/openbb_engine.py`
|
||
- 延迟导入 OpenBB：首次调用时 `from openbb import obb`
|
||
- 对 `.results` / `.to_df()` / `.to_dataframe()` 做兼容处理
|
||
- 辅助脚本: `src/jixia/engines/openbb_stock_data.py`
|
||
- 延迟导入 `obb`
|
||
- ETF 历史数据路径更新为 `obb.etf.price.historical`
|
||
|
||
## 5. 回退机制
|
||
- UI 层（OpenBB Tab）
|
||
- 未安装 OpenBB 或请求失败：读取 `examples/data/*.json` 的演示数据；仍失败则生成合成数据
|
||
- 引擎层
|
||
- 若未安装 OpenBB：返回 `success=False`，带错误消息，不影响其他功能
|
||
|
||
## 6. 开发与测试
|
||
- 单元测试建议：
|
||
- 未安装 OpenBB 时，`_load_price_data` 能返回演示/合成数据
|
||
- 已安装 OpenBB 时，能通过 `obb.equity.price.historical` 获取 DataFrame
|
||
- 在本仓库中新增了占位测试：`tests/test_openbb_fallback.py`
|
||
|
||
## 7. 典型问题排查
|
||
- ImportError: No module named 'openbb'
|
||
- 未安装 OpenBB；按第2节安装。
|
||
- 返回空数据
|
||
- 检查 symbol 是否正确；尝试更换 provider 或缩短时间窗口。
|
||
- 列名/索引不匹配
|
||
- UI 中已对常见列/索引做了规范化处理；如仍异常，可打印原始 DataFrame 排查。
|
||
|
||
## 8. 后续计划
|
||
- 接入更多 OpenBB 路由（基本面、新闻、财报、因子）
|
||
- 与辩论系统结果联动，生成投资洞察卡片
|
||
- 支持用户自定义 provider 优先级与兜底策略
|