用 Makefile 收拢 Python AI 项目的常用命令

用 Makefile 收拢 Python AI 项目的常用命令
一个 AI 小工具做起来，命令很快就会散落各处：建虚拟环境、装依赖、跑测试、启动服务、打包产物、清理缓存。这些命令有的写在 README 里，有的藏在终端历史里，时间一长自己都要翻半天。Makefile 的价值不在“构建”，而在给项目提供一个统一的命令入口：make test、make run、make clean，谁接手都看得懂。Linux 上 make 基本是现成的，不需要额外安装。

一个最小可用的 Makefile 长这样：

makefile
PY := .venv/bin/python
PIP := .venv/bin/pip

.PHONY: setup test run clean

setup:
python3 -m venv .venv
$(PIP) install -r requirements.txt

test:
$(PY) -m pytest tests

run:
$(PY) -m uvicorn app:app --host 127.0.0.1 --port 8000

clean:
rm -rf .pytest_cache pycache dist
几个细节值得展开。第一，命令前的缩进必须是 Tab，不是空格。这是 make 最经典的坑，复制粘贴时很容易被编辑器自动转成空格，报错信息又很隐晦，排查时先看这里。第二，.PHONY 声明那些不对应真实文件的目标，避免目录里恰好有个叫 test 的文件时 make 误判“已是最新”而不执行。第三，把 Python 和 pip 的路径抽成变量，统一指向虚拟环境，比每个目标里写一长串路径清楚，也避免了“忘记激活虚拟环境”这类问题——make 里的命令不依赖当前 shell 是否 activate。第四，默认目标取第一个，一般放 help 或 setup，方便新人直接 make 看提示。

如果项目用 Docker，Makefile 同样能收拢：

makefile
image:
docker build -t sentiment-api .

up:
docker run --rm -p 8000:8000 sentiment-api
这样团队里有人习惯本地 venv、有人习惯容器，命令入口仍然是同一套。再加一个 fmt 目标调用格式化工具、一个 lint 目标做检查，放进 CI 里也很顺。需要提醒的是，make 的并行选项 -j 适合互不依赖的目标，但 setup 和 test 之间有先后关系，不能简单并行，写规则时要心里有数。

对入门者来说，Makefile 不需要写得多复杂，覆盖“装环境、跑测试、启动、清理”四件事就够。把命令集中之后，README 只需要一句话：先 make setup，再 make run。项目再小，这个习惯也能省下不少来回解释的时间。