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