FinRobot 版本地图 / AI4Finance-Foundation
FinRobot 版本选择：V0 / V1 / V2 / V3 该用哪一个
官方 README 说得很直接：这三套代码不是同一个东西的三个版本在互相竞争，而是给不同用途的。V0 是可读的教学代码，V1 是自托管研报 Web 应用，V2 才是官方认定的生产系统，V3 还在开发中、没有公开代码目录。本页把四代的技术栈、入口命令、有无确定性计算与审计、以及在 Windows 上到底能不能跑摆成一张表，并顺带回答一个中文圈最常踩的坑：pip install finrobot 装到的是什么。
FinRobot 的 V0 / V1 / V2 / V3 分别是什么？
下表按官方 README 的「Where to start」与「Architecture Evolution」两张表整理，并补上「本机能不能跑」这一列——那一列是官方表里没有、但你决定要不要投入时间时最需要的信息。
| 版本 | 目录 | 技术栈 | 官方定位 | 适合谁 | 本机（Windows）能否跑 |
|---|---|---|---|---|---|
| V2 | finrobot_desktop/ | PydanticAI + FastAPI + React 19 + Tauri/Rust | Production（官方当前推荐） | 要真正做研究、要数字可溯源的人 | 桌面安装包不支持；浏览器模式与 CLI 需要先装 uv（本机实测缺 uv） |
| V1 | finrobot_equity/ | OpenAI Agents SDK + FastAPI | Web app（自托管的研报生成服务） | 要一个「输入 ticker 出 HTML/PDF 报告」的内部服务 | 可以，但要 FMP + OpenAI 两个 key；Docker 路径需另装 Docker |
| V0 | finrobot_autogen/ | Microsoft AutoGen | Educational（教学与论文复现） | 想读懂「金融智能体怎么接起来」的人 | 可以（conda + Python 3.10/3.11）；官方明确说它不适合生产 |
| V3 | 无公开目录 | DeepSeek-Harness | In development（开发中） | — | 无法运行：仓库里没有对应代码 |
同一件「出一份研报」，四代分别怎么做？
把四代放在同一件事上对照，差异比读定义更清楚。尤其注意「确定性计算」与「审计」两列——这正是官方把 V2 称为生产系统的原因。
| 环节 | V0（AutoGen） | V1（Web 应用） | V2（生产） |
|---|---|---|---|
| 怎么装 | conda 建 Python 3.10 → 在仓库根 pip install -e .（在子目录里装会失败） | 填 config.ini（FMP + OpenAI）→ ./deploy.sh start | uv sync（CLI 与浏览器模式）或下载桌面安装包 |
| 入口 | notebook（13 个，分 beginner / advanced） | 浏览器表单 127.0.0.1:8001，或两步 CLI 管线 | 桌面 App、浏览器 UI（dev.sh → :5173）、CLI（research / dcf / comps / ic-memo / ask） |
| 数字谁算 | 没有确定性计算层，智能体调工具、LLM 写结果 | 报表、比率、预测、同业倍数由代码先算好，LLM 只写叙述 | 32 个纯 Python 算子（26 估值 + 6 审计），模型不参与计算 |
| 有没有审计 | 无溯源跟踪 | 叙述以已算好的数字为上下文，可 --enable-text-regeneration 重跑 | 6 个审计算子在上线前拿叙述跟数字对账，对不上就报警 |
| 输出形态 | notebook 内的中间结果与 PDF | 可分享的 HTML 报告（示例 NVDA/MSFT/TSLA/META/COP 已入库） | 13 章研报制品 + 目标价区间与置信度 |
| 平台限制 | 官方给的是 macOS/Linux 的 conda 流程 | Docker 路径要求在仓库根构建（镜像以 finrobot_equity.web_app.main 导入） | 桌面安装包仅 macOS Apple Silicon；Windows/Linux 走浏览器模式或 CLI |
| 什么时候选它 | 学习、教学、复现论文 | 要一个能被同事访问的研报服务 | 要产出能拿去用的研究结果 |
pip install finrobot 装到的到底是什么？
这是中文教程里最集中的错配点：很多文章让你 pip install finrobot 然后跑多智能体流程。本机在隔离 venv（Python 3.11.9）里真跑了一遍，结果如下。
| 实测项 | 结果 | 含义 |
|---|---|---|
| 装到哪个版本 | FinRobot 0.1.5，上传时间 2024-06-17（该包共 7 个版本，0.1.0–0.1.5，最新仍是它） | PyPI 上是两年前的 V0 代码，不是 V2 |
| Python 版本约束 | Requires-Python: >=3.10, <3.12 | Python 3.12 及以上直接装不上，必须单独建 3.10/3.11 环境 |
| 许可元数据 | PyPI 写 License: MIT | 与仓库的 Apache-2.0 不一致，以仓库 LICENSE 为准 |
| 装完后带了哪些依赖 | 一条都没带：site-packages 里只有 finrobot 本体，METADATA 里没有任何 Requires-Dist | 「装成功」≠「能用」，见下一行 |
| import 之后会怎样 | import finrobot 成功；from finrobot.agents.workflow import SingleAssistant 报 ModuleNotFoundError: No module named 'finnhub'；finrobot.toolkits 报 No module named 'autogen' | 一用就断，而且报的不是 finrobot 自己的名字 |
| 为什么零依赖 | 根 setup.py 用 open("finrobot_autogen/requirements.txt") 读依赖；0.1.5 的 sdist 里根本没有这个文件（只有 finrobot 旧布局包 + setup.py + LICENSE + README + egg-info），读取失败走了 except 分支，依赖列表被置空 | 属于打包遗漏，不是网络问题；改环境重装也不会变 |
| 正确做法 | 要 V0：克隆仓库后在仓库根 pip install -e .（此时 requirements.txt 存在，依赖才装上） | 或直接按 V2 走 uv sync，不要用 PyPI 那条路 |
pip install -U finrobot 时，讲的是 V0 那条路径；你如果照它去跑 V2 的 CLI 或多智能体研报，方向从一开始就错了。判断该走哪条路的简单办法：先看你要的命令在哪个目录的文档里出现——finrobot research 属于 finrobot_desktop/，notebook 属于 finrobot_autogen/。照着老中文教程做，会失败在哪一步？
下表把「旧教程里写的」与「现在仓库里的实际情况」逐条对照。这些不是猜的，都能在固定 commit 的仓库里核对到。
| 旧教程/常见说法 | 现在的实际情况 | 你会看到的症状 |
|---|---|---|
pip install finrobot 然后直接跑智能体 | PyPI 只有 2024 年的 V0 且零依赖 | ModuleNotFoundError: No module named 'finnhub' 之类，看着像环境坏了 |
在 finrobot/ 目录里 pip install -e . | 该目录已移到 finrobot_autogen/，只有仓库根有 setup.py | 安装命令报找不到 setup.py / 装出来 import 不到 |
notebook 放在仓库根下的 tutorials/ | 现在是 finrobot_autogen/tutorials_beginner/ 与 tutorials_advanced/ | 路径 404；notebook 里的 ../OAI_CONFIG_LIST 也读不到 |
| 配置文件随手放在任意位置 | 两个配置文件要放 finrobot_autogen/（notebook 按相对路径去找） | 跑起来报读不到配置或调用模型失败 |
| 以为有 Smart Scheduler 可以调 | README 仍保留论文期的介绍，但当前仓库没有这套调度器的实现；V2 用类型化流水线 + 注册表选流程 | 在代码里搜不到对应模块 |
| 「装好就能一键出专业研报」 | 那是 V2 的流水线能力（7 条流水线，13 章制品），V0 只有 notebook 级示例 | 跟着 notebook 跑，拿到的不是研报而是一段分析输出 |
| Windows 上找 FinRobot 桌面安装包 | 官方 desktop-v0.1.0 发布物只有 macOS Apple Silicon（M1/M2/M3 及以上） | 发布页没有 Windows 资产可下 |
把 pyautogen 当成当前技术栈 | AutoGen 只对应 V0；V1 是 OpenAI Agents SDK，V2 是 PydanticAI | 在读 V2 代码时找不到期望的 AutoGen 结构，越读越乱 |
OAI_CONFIG_LIST、conda create python=3.10、tutorials_beginner 这些词，它讲的是 V0；如果出现 uv sync、finrobot research、dev.sh，才是 V2。两套命令不要混在一个环境里用。按你的目标，该选哪一版？
先明确目标再选版本，比先选版本再找用途省事。下表的「先做哪一步」都是可以在一小时内完成的验证动作。
| 你的目标 | 选哪一版 | 前置条件 | 先做哪一步验证 | 常见坑 |
|---|---|---|---|---|
| 要一份能追溯数字来源的研报 | V2 | uv + 一个 LLM key | uv sync 后跑 finrobot dcf 看它是否输出 WACC 与算子结果 | 用 PyPI 那条路装 V0，然后抱怨没有算子 |
| 要浏览器界面给同事用 | V1 | FMP + OpenAI 两个 key | ./deploy.sh start 后打开 127.0.0.1:8001 | 忘记 config.ini 是从 example 复制来的，直接改 example 文件 |
| 要读懂金融智能体怎么接起来 | V0 | conda + Python 3.10/3.11 | 在仓库根 pip install -e .，跑一个 beginner notebook | 用 pip install finrobot 代替源码安装，结果依赖全空 |
| 想在 Windows 上跑 V2 图形界面 | V2 浏览器模式 | uv + Node 20+ | 装 uv 后跑 ./dev.sh，看 :5173 是否起来 | 不知道 dev.sh 会先杀掉 :8321/:5173 上的进程；本机实测卡在 uv 缺失 |
| 想用命令行批处理多只股票 | V2 CLI | uv sync + LLM key | finrobot research <ticker> 或 finrobot comps | 把 CLI 当成可以离线跑的工具：取数与推理都要联网 |
| 要读论文与复现它的实验 | V0（配合论文） | 同上 | 对照 arXiv 2405.14767 读 finrobot_autogen/finrobot/agents/ | 把论文里的 Smart Scheduler 当成仓库里现成可调的模块 |
| 要 A 股研究结论 | 都不直接支持 | — | 先确认你有可用的 A 股数据源，再考虑接入 | 看到代码层接受 600519.SS 就以为能取到 A 股数据 |
V0 与 V2 能装在同一个环境里吗？
这个问题在官方文档里没有正面回答，但答案是明确的「不建议」，原因写在两边的包定义里。
| 项 | V0（教学版） | V2（桌面与 CLI） | 放一起会怎样 |
|---|---|---|---|
| 包名 | 发布名 FinRobot，Python 导入名 finrobot | pyproject.toml 里 name = "finrobot"，导入名同样是 finrobot | 两个不同代码库抢同一个导入名，谁后装谁生效 |
| Python 版本 | 官方 conda 流程用 3.10（PyPI 包约束 >=3.10,<3.12） | requires-python = ">=3.11"，CI 跑 3.11/3.12 | 交集只有 3.11，3.10 装不了 V2、3.12 装不了 PyPI 上的 V0 |
| 依赖栈 | AutoGen 系（pyautogen 等） | PydanticAI / FastAPI / yfinance / edgartools 等 | 两套框架与不同版本约束混在一个环境里，冲突难查 |
| 配置文件 | OAI_CONFIG_LIST + config_api_keys（放 finrobot_autogen/） | Settings 页写入系统钥匙串（不落 .env） | 密钥管理方式不同，容易把 V0 的明文 key 文件带进不该带的地方 |
| 建议做法 | 一个版本一个环境：V0 用 conda 环境，V2 用 finrobot_desktop/ 下的 uv 环境 | 身份清晰，出问题也容易定位是哪一代的锅 | |
FinRobot 版本选择常见问题
只想快速试一下，应该装哪一版？
先想清楚你要的是「看懂结构」还是「拿到结果」。看懂结构装 V0（源码安装），拿到结果走 V2。两条路都不要用 pip install finrobot 起步——那条路装到的是 2024 年的 V0 且不带依赖。具体到 V2，本机实测要先装 uv，详见安装页。
V2 是「最新版」吗，还是另一个产品？
是同一个项目里的生产分支，不是独立产品。官方 README 的原话是：三个都是开源项目，V2 是生产系统——确定性计算引擎、溯源保证与智能体编排都在它里面。V0 留着是因为它足够小、可以读，而不是因为它仍是被推荐的运行方式。版本线的正式定义以官方 README 为准。
V3 现在能用吗？
不能。官方把它标为 In development（开发中，DeepSeek-Harness），当前仓库里没有对应的公开代码目录，也没有可运行的入口。任何关于 V3 功能的具体说法都无法在代码里核对，本站不写这类推测。
桌面版到底支持哪些系统？
官方 desktop-v0.1.0 发布物针对 macOS Apple Silicon（M1/M2/M3 及以上）；Intel Mac、Windows、Linux 不在该发行版覆盖范围内，这些平台要走浏览器模式或 CLI。桌面版尚未做 Apple notarize，首次打开可能需要按官方给的命令清一次隔离标记。具体资产与系统要求以官方发布页为准。
为什么 PyPI 包会有零依赖这种问题？
因为打包时漏了依赖清单文件：根 setup.py 去读 finrobot_autogen/requirements.txt，而 0.1.5 的 sdist 里没有这个文件，读取失败后代码把依赖列表置成空。结果是包能装、能 import，但一调用就报缺 finnhub、autogen 这类第三方包。这不是本机环境问题，换机器重装也一样。
我用的是老教程，需要全部推翻重学吗？
不用。老教程讲的多半是 V0 的概念，而 V0 至今仍在维护、仍能跑——它的智能体角色、工作流拓扑、工具注册方式都还有参考价值。你要做的是两件事：确认教程讲的是哪一代（看它有没有 OAI_CONFIG_LIST 这类 V0 特征），以及别把 V0 的命令和 V2 的命令混在同一个环境里。
两代共存会不会互相覆盖？
会。发布名与导入名在两代之间都落在 finrobot 上，同一个环境里装两次，后装的会盖掉先装的。稳妥做法是一个版本一个隔离环境：V0 用 conda 环境，V2 用 finrobot_desktop/ 下的 uv 环境。这样出问题时也容易判断是哪一代引起的。