用命令行跑通一次 AI 对冲基金

文档摘要

用命令行跑通一次 AI 对冲基金难度：动手命令行适合想快速看到结果、或以后希望写脚本自动化的读者。本篇用最少步骤带你完成「输入股票 → 选择分析师与模型 → 等待 LangGraph 工作流 → 看到决策表格」的第一次成功体验，并结合、、说明背后执行逻辑。本文你将学到模式为何是项目推荐启动方式主程序与回测程序在参数上的异同 ticker、日期、分析师、Ollama、初始资金等关键概念第一次失败时优先检查什么为什么用 poetry run Poetry 为项目创建隔离的 Python 虚拟环境，并锁定依赖版本。直接调用系统可能找不到、等包。推荐模式始终是：这样可确保解释器与依赖树与一致。

用命令行跑通一次 AI 对冲基金

难度：动手

命令行适合想快速看到结果、或以后希望写脚本自动化的读者。本篇用最少步骤带你完成「输入股票 → 选择分析师与模型 → 等待 LangGraph 工作流 → 看到决策表格」的第一次成功体验，并结合 src/main.py、src/cli/input.py、src/backtester.py 说明背后执行逻辑。

本文你将学到

poetry run 模式为何是项目推荐启动方式
主程序与回测程序在参数上的异同
ticker、日期、分析师、Ollama、初始资金等关键概念
第一次失败时优先检查什么

为什么用 poetry run

Poetry 为项目创建隔离的 Python 虚拟环境，并锁定依赖版本。直接调用系统 python 可能找不到 langgraph、questionary 等包。推荐模式始终是：


poetry run python <模块路径> [参数...]

这样可确保解释器与依赖树与 pyproject.toml 一致。主程序入口对应 src/main.py，回测入口对应 src/backtester.py——二者共用 parse_cli_inputs，但默认行为略有不同（下文详述）。

运行前检查清单

.env 中已有至少一种 LLM 密钥与 FINANCIAL_DATASETS_API_KEY
已执行 poetry install
准备好 1–3 个股票代码（美股常用字母代码，如 AAPL、MSFT、NVDA）
心理预期：首次运行可能需数分钟，取决于分析师数量与模型速度

主程序：单次决策分析

基本命令形态


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

--ticker 与 --tickers 等价（dest="tickers"）。多个代码用英文逗号分隔，内部由 parse_tickers 拆成列表。

执行链路（源码级）

run_hedge_fund（src/main.py）向图传入：

data.tickers、start_date、end_date
data.portfolio：现金、保证金、各 ticker 多空仓位占位
metadata：show_reasoning、model_name、model_provider

工作流编译后 invoke，最终消息由 portfolio_manager 以 JSON 形式输出，parse_hedge_fund_response 解析为 Python 字典。

初始 portfolio 的构造

主程序在 __main__ 块中组装 portfolio，结构如下（伪代码）：


portfolio = {
    "cash": inputs.initial_cash,           # 默认 100000.0
    "margin_requirement": inputs.margin_requirement,
    "margin_used": 0.0,
    "positions": {ticker: {"long": 0, "short": 0, ...} for ticker in tickers},
    "realized_gains": {...},
}

这意味着：第一次运行时你通常是「空仓 + 现金」，组合管理会在限额内建议买入、卖出或持有；不会出现「未告知系统你却已有真实持仓」的情况——除非你在后续扩展中自行修改 portfolio 初始状态。

交互式参数：分析师与模型

若命令行未指定 --analysts 或 --analysts-all，select_analysts 会弹出 questionary 复选框，列出 ANALYST_ORDER 中的全部分析师。第一次建议：

2 个人格：如 ben_graham + cathie_wood（价值 vs 成长对照）
1–2 个专题：如 valuation_analyst + fundamentals_analyst
不要一次全开：更慢、更贵、终端表格更长

也可非交互指定：


poetry run python src/main.py --ticker AAPL --analysts ben_graham,valuation_analyst

--analysts-all 会覆盖 --analysts，启用全部节点。

模型选择由 select_model 处理：加 --ollama 走本地 Ollama 列表；加 --model gpt-4o 等可跳过部分交互（若 find_model_by_name 命中）。

风控与组合管理无需手动选择——create_workflow 在分析师节点之后固定追加 risk_management_agent 与 portfolio_manager。

日期区间

主程序调用 parse_cli_inputs(..., default_months_back=None)，因此：

若未传 --start-date / --end-date，resolve_dates 默认取最近三个月至今天。
格式必须为 YYYY-MM-DD，否则抛出 ValueError。

示例：


poetry run python src/main.py --ticker AAPL --start-date 2024-01-01 --end-date 2024-06-30

日期会传入各 Agent，用于拉取该区间内的价格与基本面数据。区间越长，数据量越大，但单次分析仍只产出一组当前决策，不会像回测那样按日推进。

可选调试开关

主程序额外支持（见 parse_cli_inputs 的 include_*_flag）：

--show-reasoning：展示各 Agent 更详细的推理过程（若 Agent 实现支持）
--show-agent-graph：可视化 LangGraph 结构（便于理解节点连接）

回测入口默认不包含这两项，以减少输出噪音。

回测程序：历史纸上练兵


poetry run python src/backtester.py --ticker AAPL,MSFT,NVDA

src/backtester.py 同样调用 parse_cli_inputs，但：

require_tickers=False（ticker 可空，具体行为以实现为准）
default_months_back=1（默认回测最近一个月）
不包含 graph / reasoning 标志

核心是将 run_hedge_fund 作为 agent 回调传入 BacktestEngine：


backtester = BacktestEngine(
    agent=run_hedge_fund,
    tickers=inputs.tickers,
    start_date=inputs.start_date,
    end_date=inputs.end_date,
    initial_capital=inputs.initial_cash,
    ...
)
performance_metrics = backtester.run_backtest()

BacktestEngine（src/backtesting/engine.py）按工作日循环：每个交易日调用同一 Agent 图，在模拟账户中执行建议，累计组合价值与绩效指标。回测含义详见延伸章《回测是什么》；切勿把回测曲线当作未来收益承诺。

回测相关 CLI 参数

与主程序共享的参数包括：--initial-cash（别名 --initial-capital）、--margin-requirement、--ollama、--model、--analysts*、日期参数。保证金比例影响做空时的资金占用规则，默认 0.0 表示教育场景下的简化设定。

第一次建议的完整示例（概念）


# 1. 单次分析：两只股票，指定分析师，显示推理
poetry run python src/main.py \
  --ticker AAPL,MSFT \
  --analysts warren_buffett,fundamentals_analyst \
  --show-reasoning

# 2. 本地模型路线
poetry run python src/main.py --ticker NVDA --ollama

# 3. 短回测
poetry run python src/backtester.py --ticker AAPL --start-date 2024-01-01 --end-date 2024-01-31

Windows PowerShell 中换行可用反引号 `，或写成一行。

成功的标志

终端应出现彩色表格，结构由 print_trading_output（src/utils/display.py）渲染：

AGENT ANALYSIS：每位分析师的 Signal（BULLISH/BEARISH/NEUTRAL）、Confidence、Reasoning
TRADING DECISION：Action、Quantity、Confidence、Reasoning
PORTFOLIO SUMMARY：多 ticker 汇总及看多/看空/中性计数

若看到 No trading decisions available，说明 JSON 解析失败或组合管理未返回有效结构——检查模型输出格式或密钥额度。

失败时优先排查

现象	优先怀疑
立刻认证错误	`.env` 未加载或密钥错误
拉数失败	金融数据密钥或网络
模型调用失败	额度、模型名、地区限制
极慢	Agent 过多、模型过大
中断后无输出	Ctrl+C 退出；回测程序会尝试打印部分结果

小结

先求跑通，再求跑全。一次「两只股票 + 少数分析师」的成功，远胜于「全部 Agent + 旗舰模型」的超时失败。跑通后，下一篇教你按三层结构阅读输出。

下一篇请阅读同目录下的《如何读懂输出结果：信号、限额与最终决策》。