FinRobot 数据源与密钥 / AI4Finance-Foundation
FinRobot 数据源与 API Key：7 个数据提供方与市场边界
V2 的数据层是 7 个 provider 共用一套接口，带健康状态与自动故障切换：yfinance、SEC EDGAR、FMP、Finnhub、Adanos（零售情绪）、新闻聚合、FX；V1 只强依赖 FMP + OpenAI。本页把三代的密钥清单、市场覆盖与「钥匙该放哪儿」写清楚，并给出一条实测结论：代码层接受 600519.SS、0700.HK 这类代码，但那不等于数据层真的能取到 A 股数据。
FinRobot V2 的 7 个数据提供方分别提供什么？
它们共用一套接口，每个都带健康状态（可用 / 已保存 / 可选 / 冷却中），一个源停止应答时按状态切换到下一个；数据进入计算层之前还有一层响应校验，畸形载荷会被拒掉。下表把「提供什么、缺了会怎样、本机能不能实测」逐行写清——本机没有配任何数据源 key，所以只有不依赖私有 key 的两项能做源码级核验。
| 提供方 | 提供什么 | 要 key 吗 | 缺了会怎样 | 本机核验到什么程度 |
|---|---|---|---|---|
yfinance | 公开行情与历史价格 | 通常不需要 | 价格与技术面类指标缺失，行情区降级 | 源码核验；未联网取数 |
edgar（SEC EDGAR） | 美股申报文件：10-K / 10-Q / 8-K、Form 4 内部人交易、13F 等 | 通过公开接口访问（仓库用 edgartools） | 申报与治理类章节失去来源 | 源码核验；仓库自带针对 AAPL / MSFT / NVDA / TSLA / JPM / BRK-B 的解析 fixtures |
fmp | 三大报表与倍数相关字段 | 需要 FMP key（可选启用） | 财务字段缺失，对应估值方法行被降级隐藏并留警告 | 未实测（本机无 key） |
finnhub | 公司新闻与部分财务/行情字段 | 需要 Finnhub key | 新闻与情绪类输入缺失 | 未实测（本机无 key） |
adanos | 零售情绪：Reddit / X.com / Polymarket 的结构化快照 | 需要 Adanos key（可选） | 情绪层不出现，不影响估值主干 | 未实测（本机无 key） |
news_aggregator | 新闻聚合 | 视来源而定 | 新闻章节缺内容 | 未实测 |
fx | 汇率，用于跨币种归一 | 视来源而定 | 跨币种标的的估值口径可能无法归一到报价币种（例如报 TWD 或 EUR 的标的） | 源码核验（含 fx_normalize 算子与币种字段） |
FinRobot 的 V0、V1、V2 分别用什么数据源？
「FinRobot 支持哪些数据源」这个问题的答案同样取决于版本，而且三代存放密钥的位置也完全不同：V0 是一堆独立的 utils 模块，V1 只强依赖两个服务，V2 才把它做成带故障切换的数据层。混用两代的配置文件是常见错配来源。
| 版本 | 数据源 | 代码位置 | 密钥配置位置 | 注意点 |
|---|---|---|---|---|
| V0（教学/论文） | Finnhub（finnhub_utils.py）、FMP（fmp_utils.py）、SEC 申报（sec_utils.py + filings_src/ + marker_sec_src/ 的 PDF→Markdown）、yfinance（yfinance_utils.py）、Reddit（reddit_utils.py）、FinNLP（finnlp_utils.py）、财报电话会议（earnings_calls_src/） | finrobot_autogen/finrobot/data_source/ | finrobot_autogen/config_api_keys（字段含 FINNHUB_API_KEY / FMP_API_KEY / SEC_API_KEY / REDDIT_CLIENT_ID / REDDIT_CLIENT_SECRET / TWITTER_BEARER_TOKEN） | FinNLP 是 git submodule，目录空时要 git submodule update --init --recursive；官方明说这一代没有确定性计算层与溯源跟踪 |
| V1（自托管 Web 应用） | 强依赖 FMP（财报、市场指标、同业比较）+ OpenAI（叙述生成）；可选 Adanos（零售情绪） | finrobot_equity/core/src/modules/market_data_api.py、retail_sentiment_client.py | finrobot_equity/core/config/config.ini（fmp_api_key / openai_api_key / adanos_api_key） | 8 个 section writer 以已算好的数字为上下文；填 Adanos 才会多出一层零售情绪 |
| V2（生产） | 上表 7 个 provider，带健康状态与自动故障切换 | finrobot_desktop/finrobot/engine/data/providers/ | 桌面/浏览器界面的 Settings 页，写入系统钥匙串 | 只有这一代有响应校验与「缺数据就留警告」的降级行为 |
pip install finrobot 装到的是 2024 年的 V0，而且一条依赖都没带，所以连 finnhub 模块都 import 不到。V0 要用源码路径（仓库根 pip install -e .），V2 要走 uv sync。这条错配的完整实测记录在安装页。A 股、港股、美股：FinRobot 官方支持到哪一步？
这一节是本页最需要看清的部分。官方数据链路与全部示例都偏美股；中文圈常见的误解是「代码能接受 A 股代码」= 「能分析 A 股」。下面先给矩阵，再给本站实测到的边界证据。
| 市场 | 官方链路支持程度 | 本机实测到的边界 | 要自己补什么 | 主要风险 |
|---|---|---|---|---|
| 美股 | 覆盖较完整：FMP / Finnhub / SEC EDGAR / yfinance，官方示例与仓库测试 fixtures 都是美股 | 标的校验层接受常规美股代码 | 基本只需配 key 与确认档位 | 数据源额度上限与限流 |
| 港股 | 官方未把港股列为主场景 | validate_ticker('0700.HK') 原样通过 | 确认所选 provider 是否真的返回港股字段；核对财报币种与报告期 | 数据覆盖与字段口径不确定，容易「有数字但口径不对」 |
| A 股 | 官方未内置 A 股数据源 | validate_ticker('600519.SS') 与 ('123456.SZ') 都原样通过 | 自行接入 A 股数据源，并处理代码后缀与交易所映射、中文财报与公告解析、人民币/美元币种与单位、季度与年度口径、交易日历与停牌、复权方式、涨跌停与 T+1 制度 | 把美股链路直接套到 A 股上，会得到看起来正常但口径错误的结果 |
| 本机实测输入 | 实际输出 | 说明 |
|---|---|---|
validate_ticker('AAPL') / ('MSFT') | 原样返回 | 常规美股代码通过 |
validate_ticker('aapl') | 'AAPL' | 小写会被归一化成大写 |
validate_ticker('600519.SS') / ('123456.SZ') / ('0700.HK') | 均原样通过 | 代码层不拦 A 股与港股后缀，这不代表数据层能取到 |
validate_ticker('') | ValueError: Invalid ticker ''. Use A-Z/0-9/./- up to 12 chars, e.g. AAPL or BRK.B | 校验层只做格式检查，不做市场可用性检查 |
FinRobot 的密钥该放哪儿？三代三种存法
「key 填了却没生效」多数时候不是 key 的问题，而是填错了地方。这三代的存放位置完全不同，放在一起看能少走很多弯路。
| 属于哪一代 | 放哪里 | 具体位置 | 是否进版本控制 | 注意点 |
|---|---|---|---|---|
| V2（桌面与 CLI） | 系统钥匙串 | 桌面 App 或浏览器界面的 Settings 页填写，不落 .env 文件 | 不进 | 浏览器模式下本地 API 无鉴权，见下方风险提示 |
| V1（Web 应用） | 配置文件 | finrobot_equity/core/config/config.ini | 只有 config.ini.example 进；config.ini 被忽略 | 要从 example 复制，不要直接改 example 文件 |
| V0（LLM 端点） | 配置文件 | finrobot_autogen/OAI_CONFIG_LIST | 只有 OAI_CONFIG_LIST_sample 进 | 它是 AutoGen 配置列表，可以放多组端点，按模型名选用 |
| V0（数据源） | 配置文件 | finrobot_autogen/config_api_keys | 只有 config_api_keys_sample 进 | 用 finrobot.utils.register_keys_from_json("config_api_keys") 载入环境；只填你要用的源 |
| V1（服务参数） | 环境变量 | WEB_HOST / WEB_PORT / DATABASE_URL / GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET / FINROBOT_ADMIN_EMAIL(S) / FINROBOT_ADMIN_PASSWORD / ADANOS_* | 不进 | 初始管理员密码未设置时，首次启动会打印一个随机值 |
:8321，其中包含持有你密钥的 /api/settings。它仍然只绑定本地回环地址，但在共享机器上请优先用桌面 App。三条纪律：①不要提交进仓库；②不要贴进截图、日志或 issue；③排查时只打印「是否存在与长度」，不打印内容。
这些数据源要花多少钱？哪些能免费起步
官方 README 只列 provider 名，不告诉你哪些能免费用、免费档会卡在哪里。下表把「要不要钱、免费档能做什么、低成本怎么起步」摊开；具体价格与额度一律以各家官方定价页为准，本站不转述数字。
| 项目 | 是否必须 | 免费档情况 | 计费形态 | 免费档的典型卡点 | 低成本起步建议 |
|---|---|---|---|---|---|
| 库本体 | 必须 | 开源免费（Apache-2.0） | 不按调用计费 | 无 | 按官方安装说明装好即可 |
| LLM API | 必须（除纯算子实验） | 是否有试用额度以官方定价页为准 | 按用量计费 | 额度用尽时推理环节直接失败 | 先用小样本、短链路跑通再放量；纯算子实验不需要 LLM |
| yfinance | 可选 | 通常无需 key | 无 key 计费 | 公开接口的限流与可用性不受这个库控制 | 拿它做链路验证，正式研报再换稳定源 |
| SEC EDGAR | 按需 | 属公开申报数据，访问要求以 SEC 官方说明为准 | 通常不按调用收费 | 高频访问可能被要求降速 | 只在需要申报原文时调用，并做本地缓存 |
| FMP | 做财报与估值时必填 | 通常提供免费档，字段范围以官方为准 | 免费档 + 付费档 | 部分报表字段或较长历史区间在免费档不可用 | 只取研报真正用到的那几张表 |
| Finnhub | 做新闻/行情时必填 | 通常提供免费档，额度以官方为准 | 免费档 + 付费档 | 免费档容易在调用频率上受限，超限时可能返回空结果 | 先用免费档验证「能不能取到」，再决定是否升级 |
| Adanos | 可选 | 以官方为准 | 以官方为准 | 属情绪类补充数据，不影响估值主干 | 等主干链路稳定后再评估 |
| 商业版产品（finrobot.ai） | 不需要 | — | — | 本机无法验证其条款与价格 | 开源链路够用时不必考虑；如需使用，条款以官方为准 |
FinRobot 的密钥怎么配到位？五步与每步的预期输出
每步都写清「做什么、为什么、预期看到什么」。做完这五步，你应该能明确回答：哪个源真的通、哪个源虽然配了但没生效。
先选版本，再建环境
V2 用
uv（cd finrobot_desktop && uv sync）；V1 用 venv 并pip install -r finrobot_equity/requirements.txt；V0 用 conda 建 Python 3.10 或 3.11 环境后在仓库根pip install -e .。
预期输出：命令提示符出现环境名（或.venv生效）、python -V落在允许区间内。若 V2 提示找不到uv，先装 uv——这是本机实测最先撞到的卡点。按版本把密钥填到正确位置
对照上表：V2 在 Settings 页填写（写入系统钥匙串）；V1 复制
config.ini.example为config.ini填两个必填 key；V0 把两个*_sample文件复制成正式文件并放在finrobot_autogen/。
预期输出：配置文件里没有占位串、没有首尾空格；config.ini与config_api_keys处于被忽略状态（不会出现在 git 待提交列表里）。逐个源做最小验证
用一个官方示例里的美股标的，每次只调用一个 provider，打印返回行数与列名，而不是直接跑完整研报。
预期输出：非空结果 + 你认识的列名。若为空，先按下面的排查表走，再去怀疑标的本身。确认「实际读到的是哪一个 key」
在代码里打印每个源是否读到 key（只打印是否存在与长度，不要打印 key 本身），并记录这次跑通的组合。
预期输出：每个源都能明确回答「有 / 没有」；两处配置冲突时，这一步会立刻暴露。最后才接回完整链路
单源验证通过后再跑端到端流程（例如
finrobot research <ticker>或 V1 的deploy.sh start）。
预期输出：输出里出现估值方法行与数值，且缺少数据的地方带警告而不是静默缺失。看不到警告通道时，说明你走的不是 V2 的降级路径。
密钥填了却没生效？九类原因与确认方法
这类问题最费时间的地方在于「它不报错」。下面按排查顺序排列，从「密钥本身」到「环境与档位」，每类都给出确认方法与判断标准。
| 现象 | 怎么确认 | 处理 | 注意点 |
|---|---|---|---|
| 配置里还是占位符或空串 | 打开配置文件，看是否残留示例占位串或空值 | 换成真实 key，去掉首尾引号与空格 | 复制 key 时最容易带上空格，肉眼很难发现 |
| 填到了另一份配置文件 | 确认运行时代码实际读取的是哪一份文件 | 只保留一处配置；notebook 里注意当前工作目录 | notebook 的工作目录常与项目根不一致 |
| 环境变量与配置文件冲突 | 在代码里打印「实际读到的值是否存在」（不打印内容） | 固定一种配置来源，避免两处并存 | 排查时要防止把 key 打到日志里 |
| key 有效、接口也连得上，但返回空表 | 先用该 provider 的官方文档示例参数单独调一次，再用你自己的参数调一次，比对差异 | 多半是「字段不在当前档位」或「该市场不在覆盖范围」，而不是 key 错 | 「能连通」不等于「字段都能拿到」；空表不会报错 |
| key 有效但被限流 | 隔一段时间或降低调用频率后重试同一请求 | 加本地缓存、减少重复调用 | 限流常表现为「返回空」而不是报错 |
| 该源需要更高档位才有你要的数据 | 用该源的最小样例单独调一次，看返回字段是否齐全 | 确认字段与历史区间是否属于更高档位 | 档位差异以各家官方定价页为准 |
| 标的市场不匹配 | 换一个官方示例里的美股标的再试同一路径 | 先确认标的是否属于该源覆盖的市场 | 官方数据源以美股为主，A 股要自行适配 |
| 本地后端没有起来（V2 浏览器模式） | 看 :8321 是否有响应；浏览器模式要先跑 ./dev.sh，它会先释放 :8321 与 :5173 两个端口 | 按官方说明先起后端、再开前端；被占端口先腾出来 | 桌面 App 开着时也会占用 :8321，需要先退出 |
| 环境和包的问题（密钥其实没问题） | 确认当前解释器或 notebook 内核能导入项目包 | 重新激活环境或修正内核 | 命令行能跑、notebook 不能跑，通常是内核不同 |
按任务配源：六类研究任务要配哪些数据源
与其把所有 key 都申请一遍，不如按任务配最小集合。下表给的是「至少」而不是「最多」，并附上对应的 V2 入口。
| 想做的分析 | 至少要配的源 | V2 入口 | 可选的补充源 | 注意点 |
|---|---|---|---|---|
| 三大报表与财务比率 | FMP | 随研究流水线取数 | SEC EDGAR（核对申报原文） | 免费档字段范围以官方为准 |
| 行情与技术面 | yfinance 或 Finnhub | 随研究流水线取数 | 另一个源做交叉验证 | yfinance 通常无需 key，但稳定性不受这个库控制 |
| 申报文件与公司治理 | SEC EDGAR | 随研究流水线取数 | FMP | 主要覆盖美股申报，非美股市场需自行适配 |
| 新闻与情绪 | 新闻聚合 / Finnhub | 随研究流水线取数 | Adanos（零售情绪） | 情绪类结论建议人工复核后再用 |
| 估值（DCF / DDM / LBO / WACC 等） | FMP（财务） | finrobot dcf <ticker> / finrobot lbo | SEC EDGAR | 估值数字由纯 Python 算子计算，模型只负责叙述 |
| 完整研报 | LLM + FMP + 行情源 | finrobot research <ticker> | SEC EDGAR / Adanos | 缺数据时方法行会被降级隐藏并留警告，产出仍会生成 |
FinRobot 数据源与密钥常见问题
FinRobot 支持 A 股数据吗？
官方数据链路与全部示例都偏美股，没有内置 A 股数据源；要在 A 股上复用这条链路，需要自己接数据源并处理复权、币种、季度口径、停牌与涨跌停等差异。注意一处容易误判的地方：本站实测 validate_ticker 对 600519.SS、123456.SZ 都原样放行，但那只是格式校验通过，不代表数据层取得到数据。判断标准以你接入的数据源实际返回为准。
代码层接受 600519.SS，是不是说明支持 A 股？
不是。校验器只检查「字符是否符合 A-Z/0-9/./- 且不超过 12 位」，不做市场可用性检查；空串才会报错。真正决定能不能分析 A 股的是数据提供方能否返回该标的的行情与财报字段，以及口径是否与你后续的计算一致。V2 的 7 个 provider 里没有 A 股数据源。
yfinance 需要 key 吗？
通常不需要，但它走公开接口，限流与可用性不受这个库控制，适合做链路验证，不适合作为单一数据依赖。它也被列在 V2 的 7 个 provider 之内，带健康状态与故障切换，但切换能力来自框架层，不改变 yfinance 自身的不确定性。以官方仓库的实现为准。
密钥放在哪里最安全？
优先用 V2 的 Settings 页，它写入系统钥匙串而不是 .env。如果用 V0，注意两个 *_sample 文件才在版本控制里，填好的副本应当保持被忽略状态。任何一代都不要把 key 提交进仓库、贴进截图或日志；排查时只打印「是否存在与长度」。
浏览器模式的密钥安全吗？
需要注意。浏览器模式下本地后端的鉴权被降级为空操作（桌面壳有每次启动的能力令牌，纯浏览器读不到），任何本机进程都能访问 :8321，其中包含持有密钥的 /api/settings。它只绑定回环地址，但共享机器上优先用桌面 App。这是官方子目录文档写明的行为。
数据源返回空怎么办？
先分清两类：接口连不上（会报错）与接口连上但返回空（不报错）。后者按「占位符 → 配置文件位置 → 环境变量冲突 → 档位是否覆盖该字段 → 是否被限流 → 标的是否属于该源覆盖市场」的顺序排查。本站实测里最容易被忽略的是倒数第二类：限流常常表现为返回空。
能只配一个数据源吗？
可以，但能力会随之收窄：只有行情源就没有财报字段，只有财报源就缺价格与技术面。V2 的做法是缺哪个就降级隐藏对应方法行并留下警告，所以你拿到的东西会变少，而不是拿到一个错数字。各源覆盖范围以官方 README 与实现为准。
这些数据源要花钱吗？
项目本体是 Apache-2.0 开源、免费；成本来自 LLM 调用与部分 provider 的付费档。免费档的字段范围与调用额度各家不同，本站不转述具体数字，一律以各家官方定价页为准。如果只是想先验证这套系统怎么算数，可以直接跑官方确定性算子，那一步无需任何 key。