环境准备与 API 密钥：为什么两边都要配

文档摘要

环境准备与 API 密钥：为什么两边都要配难度：动手跑起来之前，系统需要两类「外接能力」：一个会推理的大语言模型，以及能提供行情与财报等材料的金融数据服务。缺一不可——没有模型，人格分析师写不出像样的投资备忘录式理由；没有数据，分析师就没有原材料，流程会在拉数阶段中断或产出空洞结论。本篇从原理、执行逻辑与源码角度，说明如何正确完成环境准备。本文你将学到两类密钥各自负责什么，以及缺失时会出现什么现象环境变量如何准备，以及程序启动时如何加载本地模型路线（Ollama）何时值得尝试，与云端模型有何差异与、相关的配置触点核心原则：模型是「大脑」，数据是「课本」可以把 AI 对冲基金想象成一间讨论室：各位分析师（Agent）是带不同投资风格的学生；

环境准备与 API 密钥：为什么两边都要配

难度：动手

跑起来之前，系统需要两类「外接能力」：一个会推理的大语言模型，以及能提供行情与财报等材料的金融数据服务。缺一不可——没有模型，人格分析师写不出像样的投资备忘录式理由；没有数据，分析师就没有原材料，流程会在拉数阶段中断或产出空洞结论。本篇从原理、执行逻辑与源码角度，说明如何正确完成环境准备。

本文你将学到

两类密钥各自负责什么，以及缺失时会出现什么现象
环境变量如何准备，以及程序启动时如何加载
本地模型路线（Ollama）何时值得尝试，与云端模型有何差异
与 src/cli/input.py、src/main.py 相关的配置触点

核心原则：模型是「大脑」，数据是「课本」

可以把 AI 对冲基金想象成一间讨论室：各位分析师（Agent）是带不同投资风格的学生；大语言模型提供语言理解与推理能力，相当于让学生能组织论证；金融数据 API 提供价格、财报、新闻、内部人交易等事实材料，相当于课本与习题册。只配模型不配数据，学生会「空谈」；只配数据不配模型，材料堆在桌上却无人解读。

环境变量清单（以 .env.example 为模板）

项目根目录的 .env.example 列出了常见提供商的占位符。动手时，复制为 .env 并填入真实密钥（切勿提交到版本库）。下表概括主要变量：

变量名	作用	备注
`OPENAI_API_KEY`	OpenAI 系列模型	常用默认路线
`ANTHROPIC_API_KEY`	Claude 系列	可选
`GROQ_API_KEY`	Groq 托管模型	可选，速度较快
`DEEPSEEK_API_KEY`	DeepSeek	可选
`GOOGLE_API_KEY`	Gemini	可选
`XAI_API_KEY`	Grok	可选
`MOONSHOT_API_KEY`	Kimi / 月之暗面	国内用户可关注 `MOONSHOT_BASE_URL`
`AZURE_OPENAI_*`	Azure OpenAI	需 endpoint 与 deployment
`FINANCIAL_DATASETS_API_KEY`	金融数据集	分析流程必需

最低配置建议：至少一种 LLM 密钥 + 金融数据密钥。.env.example 注释里写明了各提供商的获取方式说明；本教程不复述易变的外部注册细节，你按示例文件操作即可。

程序如何加载环境变量

src/main.py 在文件开头调用：


from dotenv import load_dotenv
load_dotenv()

这意味着：当你用 poetry run python src/main.py ... 启动时，项目根目录下的 .env 会被自动读入进程环境。若密钥「明明填了却仍报认证错误」，优先检查：

.env 是否在项目根目录（与 pyproject.toml 同级），而非误放在子目录。
变量名是否与示例完全一致（大小写、下划线）。
值前后是否有多余空格或引号。
当前 shell 是否另有同名环境变量覆盖了 .env 内容。

金融数据密钥在 Agent 执行时通过 get_api_key_from_state 等工具函数读取，例如 risk_management_agent 拉价格时会用到 FINANCIAL_DATASETS_API_KEY。

建议操作步骤

确认 Python 与 Poetry：项目依赖 Poetry 管理虚拟环境；Web 路线还需 Node，见应用说明。
复制环境文件：将 .env.example 复制为 .env。
填入密钥：至少一个 LLM + 金融数据；保存后勿分享。
安装依赖：在项目根目录执行 poetry install。
验证加载（可选）：启动主程序前，可临时在 Python 里 import os; print(bool(os.getenv("OPENAI_API_KEY"))) 做冒烟检查——注意不要在公开场合打印完整密钥。
进入下一篇：环境就绪后再运行 CLI。

本地模型：Ollama 路线

若希望推理尽量留在本机，可使用 Ollama。CLI 层在 src/cli/input.py 的 add_common_args 中注册了 --ollama 开关；select_model 函数在检测到该开关时，会走 OLLAMA_LLM_ORDER 列表并调用 ensure_ollama_and_model 确认本地服务与模型可用。

概念上的启动方式：


poetry run python src/main.py --ticker AAPL,MSFT --ollama

原理差异：

维度	云端 API	Ollama 本地
数据出境	请求发往云厂商	主要留在本机
成本	按 token 计费	硬件与电费
效果	旗舰模型通常更强	取决于所选本地模型
前置条件	网络 + 密钥	本机资源 + Ollama 服务

对第一次体验的零基础用户，云端较小模型往往更省事——少一层「本地服务是否启动、模型是否 pull 完成」的排查。待跑通主流程后，再尝试 Ollama 做对照实验也不迟。

与 CLI 模型选择的衔接

即使不使用 Ollama，每次运行仍会通过 select_model 交互或 --model 参数指定模型。find_model_by_name 会在 LLM_ORDER 中查找匹配项；选定后，model_name 与 model_provider 写入 AgentState 的 metadata，供各 Agent 调用 LLM 时使用。因此：密钥对应的是提供商，模型名决定具体调用哪一个 checkpoint——二者都配对，才能稳定运行。

安全提示

不要把填好密钥的 .env 发给聊天软件群、公开网盘或截图到社交媒体。
团队协作时，用私密渠道单独传递密钥，或使用各平台提供的「项目级密钥」轮换机制。
若使用学校或公司电脑，确认是否允许将第三方 API 密钥写入本地文件。
教育练习也会产生 API 调用费用；建议先用少量 ticker、少量分析师试跑。

失败现象速查

现象	优先怀疑
AuthenticationError / 401	LLM 密钥无效或未加载
金融数据相关报错	`FINANCIAL_DATASETS_API_KEY` 问题
Ollama 连接失败	本地服务未启动或模型未安装
程序找不到模块	未在项目根目录用 `poetry run` 执行

小结

密钥不是故意设置的「麻烦事」，而是教室的电（模型）与课本（数据）。配齐之后，你才具备进入命令行实战的前提。下一篇将带你用 poetry run 模式完成第一次完整运行。

下一篇请阅读同目录下的《用命令行跑通一次 AI 对冲基金》。