第 2 章 · 01 Python 与 Poetry 安装

第 2 章 · 01 Python 与 Poetry 安装

本节摘要:本节是「上手篇」的第一步——把 AutoHedge 的运行环境搭起来。项目用 Poetry 管理依赖(pyproject.toml),要求 Python 3.10+。本节先讲清两个版本约束(Python 解释器版本、Poetry 自身版本),再逐行解读 pyproject.toml 里的核心依赖清单(swarms、swarm-models、openai 链路、httpx、loguru、rich、solders、yfinance、python-dotenv、pydantic),说清每个依赖在项目里扮演什么角色。最后给出两条安装路径(Poetry 装与 pip 装),并提醒 Windows/macOS 下 solders 安装的常见坑。读完本节,你能在本机得到一个 import autohedge 不报错的环境。

内容来源:原项目源码 pyproject.toml、requirements.txt,精读并套用体系化模板。

学习目标

阅读完本节,你应当能够:

1. 核对 Python 与 Poetry 的版本要求(Python 3.10+)。
2. 逐行读懂 pyproject.toml 的依赖声明,说出每个依赖的用途。
3. 区分运行依赖与开发(lint)依赖两组。
4. 在本机用 Poetry 或 pip 走通安装。
5. 处理 solders 在 Windows 上的常见安装坑。

一、版本约束:Python 与 Poetry

pyproject.toml 顶部声明了构建后端与 Python 版本下限:

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "autohedge"
version = "0.1.5"
​

逐行解读:

• build-system.requires 声明构建时需要 poetry-core(Poetry 的核心打包库),版本 >=1.0.0。这意味着用 pip install 也能装,因为构建依赖会被 pip 自动拉取。
• [tool.poetry] 是 Poetry 的元信息段。包名 autohedge,版本 0.1.5,许可 MIT,作者 Kye Gomez(The Swarm Corporation)。

关键的 Python 版本约束在依赖段:

[tool.poetry.dependencies]
python = "^3.10"
​

^3.10 是 Poetry 的「脱字符版本」语法,意思是 >=3.10.0,<4.0.0——只允许 3.10 及以上、4.0 以下的 Python。

⚠️ 现实澄清:pyproject.toml 的 classifiers 段却写着 Programming Language :: Python :: 3.9。这是元数据自相矛盾——classifiers 写 3.9,实际依赖要求 3.10+。以 python = "^3.10" 为准:用 3.9 跑会因类型注解(如 Path | None)报错。

Poetry 本身没有版本约束,但建议用 1.5+(支持 poetry-core 与组依赖)。安装 Poetry:

# 官方推荐(Windows PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
# macOS / Linux
curl -sSL https://install.python-poetry.org | python3 -
​

二、核心依赖清单逐行精读

pyproject.toml 的运行依赖段(共 10 项):

[tool.poetry.dependencies]
python = "^3.10"
rich = "*"
swarms = "*"
pydantic = "*"
loguru = "*"
swarm-models = "*"
httpx = "*"
solders = "*"
yfinance = "*"
python-dotenv = "*"
​

注意一个反模式:所有第三方依赖都用 *(任意版本)。这在生产里是危险的——任何一次上游 breaking change 都可能让项目跑不起来。但对教学项目,这样写最省事。下面逐个看用途:

💡 核心心法:看懂这份依赖表,就理解了 AutoHedge 的技术骨架——swarms(编排)+ httpx/yfinance(数据)+ solders(链上)+ rich/loguru(呈现)。其中 solders 是最硬核的一块(第 8 章专讲),其余多是薄封装。

补充:虽然 pyproject.toml 没列 openai,但 swarms 调用 GPT-4.1 时会间接依赖 openai 包(被 swarms 拉进来)。同理,情绪 Agent 用的 exa_search 工具会调 Exa API,需要 EXA_API_KEY(见下节)。

三、开发(lint)依赖

pyproject.toml 还有一组 lint 依赖,与运行无关:

[tool.poetry.group.lint.dependencies]
ruff = ">=0.1.6,<0.15.0"
types-toml = "^0.10.8.1"
types-redis = "^4.3.21.6"
types-pytz = "^2023.3.0.0"
black = "^23.1.0"
types-chardet = "^5.0.4.6"
mypy-protobuf = "^3.0.0"
​

• ruff 是超快的 Python linter([tool.ruff] 段设 line-length = 70)。
• black 是代码格式化器(同样 line-length = 70)。
• 一堆 types-* 是给 mypy 做类型检查用的存根包。

⚠️ 现实澄清:这组 lint 依赖里有 types-redis、mypy-protobuf,但项目源码没有任何 redis 或 protobuf 引用。这是作者从别的项目模板复制过来的痕迹——再次印证第 1 章说的「营销先行、模板残留」。普通学习者可以完全忽略这组依赖。

四、两条安装路径

路径 A:Poetry(推荐,贴合项目原意)

# 1. 进入项目根目录
cd K:\Project\ht-teach\writing\AutoHedge-main

# 2. 用 Poetry 解析并安装依赖(创建虚拟环境)
poetry install

# 3. 进入虚拟环境
poetry shell

# 4. 验证
python -c "import autohedge; print('ok')"
​

poetry install 会读 pyproject.toml,生成 poetry.lock(锁定版本),并在虚拟环境里装齐所有依赖。如果只想要运行依赖、不要 lint 组:

poetry install --without lint
​

路径 B:pip(不装 Poetry 的备选)

项目根目录有 requirements.txt(仅 8 行,内容比 pyproject.toml 还少):

# 1. 建议先建虚拟环境
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS/Linux

# 2. 用 pip 装(注意要先 pip install -e . 让 autohedge 包可被 import)
pip install -e .
# 或只装 requirements.txt(但这样不会注册 autohedge 包本身)
pip install -r requirements.txt
​

注意 requirements.txt 比正式依赖少了 rich、yfinance、python-dotenv,只列了 swarms、pydantic、loguru、swarm-models、fastapi、uvicorn、requests、httpx、solders——还多了 fastapi、uvicorn、requests 这些 pyproject.toml 里没有的。两份依赖清单不一致,这是项目的又一处粗糙。

💡 选择建议:优先用 Poetry——它读的是 pyproject.toml,依赖更全、更贴合作者意图。requirements.txt 像是早期残留,不完整。

五、solders 在 Windows 上的常见坑

solders 是 Rust 编译的 Python 扩展,装不上多半是缺预编译 wheel。排查顺序:

1. 确认 Python 版本:必须是 3.10~3.12(3.13 可能暂无 wheel)。
2. 确认位数:必须是 64 位 Python(32 位无 wheel)。
3. 升级 pip:旧版 pip 不会优先取 wheel,会尝试源码编译(需 Rust 工具链)。python -m pip install -U pip。
4. 若仍失败:去 PyPI solders 页面 看是否有对应 cp310-cp310-win_amd64.whl。没有就只能装 Rust 自己编译。

⚠️ 现实澄清:solders 装失败是新手放弃 AutoHedge 的第一大原因。如果只是想学多 Agent 编排(第 3~7 章),可以暂时不碰链上部分——但 pip install -e . 仍会尝试装 solders。变通办法:先注释掉 pyproject.toml 里的 solders = "*" 再装,等到第 8 章再补上。

六、入口脚本:poetry.scripts

pyproject.toml 还注册了一个命令行入口:

[tool.poetry.scripts]
autohedge = "autohedge.cli:main"
​

意思是:用 Poetry 装完后,终端敲 autohedge 等价于执行 autohedge.cli 模块里的 main() 函数。这就是第 5 章那个 REPL 的入口。用 pip 装也会自动注册这个入口(pip install -e . 后即可 autohedge 直接运行)。

本节要点回顾

1. 版本约束:Python ^3.10(即 3.10~3.x);Poetry 1.5+;classifiers 写 3.9 是元数据 bug,以依赖声明为准。
2. 核心依赖 10 项:swarms/swarm-models(编排)、pydantic(校验)、loguru(日志)、rich(终端)、httpx(HTTP)、solders(Solana 签名)、yfinance(行情)、python-dotenv(.env)。
3. 依赖全用 *:教学项目省事但生产危险;requirements.txt 与 pyproject.toml 不一致,以后者为准。
4. 安装路径:推荐 Poetry(poetry install);备选 pip install -e .;可 --without lint 跳过无关的 lint 组。
5. solders 坑:需 64 位 Python 3.10~3.12 + 新 pip;装不上是放弃首因,学编排可暂注释掉。
6. 入口脚本:autohedge = "autohedge.cli:main",装完即可终端敲 autohedge。

下一节,我们配 .env——把 OpenAI key、Jupiter key、Solana 私钥等环境变量填好,AutoHedge 才能真正调通 LLM 与链上接口。