当FastAPI遇上机器学习，一个脚手架工具能省下多少工夫

如果你写过后端接口，大概都经历过这样的场景，新建一个项目，先搭文件夹，配环境，写Dockerfile，配CI，一套流程下来半天就过去了，真正写业务逻辑的时间反而被挤得很少。这就是脚手架工具存在的意义，而今天要聊的这个项目，恰好是为FastAPI和机器学习模型部署量身定做的一套脚手架，叫做cookiecutter-fastapi，作者是Arthur Henrique。

项目是什么，先搞懂Cookiecutter这个词

Cookiecutter字面意思是曲奇饼的模具，用在编程里意思很形象,你有一个模具（模板），往里面填入不同的原料（项目名称、作者信息、描述文字等），就能快速做出一份口味相同但内容各异的曲奇（项目骨架）。技术上它是一个Python命令行工具，底层用Jinja2模板引擎，把文件夹名、文件名、文件内容里的占位符替换成你填入的真实信息。

装这个工具很简单，一行命令搞定：

shell 复制代码

pip install cookiecutter

然后运行下面这行，Cookiecutter会自动去GitHub上拉取这个项目当模板，跑一遍交互式问答，帮你把整个FastAPI项目骨架生成好：

shell 复制代码

cookiecutter gh:arthurhenrique/cookiecutter-fastapi

整个仓库到目前已经积累了706颗星，74次分叉，用MIT协议开源，从2020年立项至今提交了169次，算是一个更新频率不低、社区认可度也还不错的小而美工具。

为什么它特别适合ML模型部署这个场景

市面上FastAPI的脚手架工具不少，但大多数只解决Web接口层的问题。这个项目的独特之处在于，它把机器学习模型的训练、打包、部署也一并纳入了模板设计，等于是把数据科学家和后端工程师两边的工作习惯揉到了一起。

打开生成后的项目目录，能看到一个很清晰的双层结构，一层是标准的FastAPI应用层，另一层是机器学习工作流层：

graph TB A[cookiecutter-fastapi 模板] --> B[FastAPI 应用层] A --> C[机器学习工作流层] B --> B1[api/routes 接口路由] B --> B2[core 配置与日志] B --> B3[models Pydantic模型] B --> B4[services 业务逻辑] B --> B5[main.py 应用入口] C --> C1[data 原始/中间/处理后数据] C --> C2[notebooks Jupyter笔记] C --> C3[ml/data 数据脚本] C --> C4[ml/features 特征工程] C --> C5[ml/model 训练与预测脚本] B --> D[tests pytest测试] C --> D D --> E[GitHub Actions CI/CD] E --> F1[GCP Cloud Run] E --> F2[AWS Lambda]

这套结构设计其实借鉴了数据科学项目常用的Cookiecutter Data Science规范，把data、notebooks、ml这几个文件夹按照原始数据、特征工程、模型训练三个阶段分层管理，逻辑很清楚，即便是刚接触机器学习工程化的新人，照着文件夹名字也能大致猜出每一步该往哪里放代码。

技术栈选型，轻量但不简陋

这个模板对Python版本要求是3.11以上，包管理工具选用的是uv，这是目前Python生态里公认速度最快的包管理器之一，比传统pip和poetry快出一个量级，装依赖基本秒级完成。

除此之外，模板里还内置了这些东西：

Docker与docker-compose，容器化部署一步到位，不用自己再手写Dockerfile
Makefile ，把install、run、test、deploy这些常用命令都封装成简短指令，make run就能跑起本地服务
pytest测试框架，测试目录已经预置好，写业务逻辑的同时顺手写测试
GitHub Actions工作流，代码提交后自动触发CI流程，跑测试、做检查
pylint代码检查配置，保证代码风格统一

生成的项目跑起来之后，默认在本地8080端口提供服务，访问/docs能看到Swagger自动生成的交互式API文档，访问/redoc则是另一种排版风格的文档页面，这两个都是FastAPI框架自带的福利，不需要额外配置。

配置项，填几个空就能定制专属项目

驱动整个生成过程的核心文件是cookiecutter.json，里面预设了几个需要用户填写的变量：

变量名	含义	默认值/说明
project_name	项目名称	用户自定义
project_slug	项目文件夹名	自动由project_name转小写并替换空格为短横线
project_short_description	项目简短描述	用户自定义
machine_learn_model_path	模型文件存放路径	./ml/model/
machine_learn_model_name	模型文件名	model.pkl
input_example_path	预测接口示例输入路径	./ml/model/examples/example.json
full_name	作者姓名	用户自定义
email	联系邮箱	用户自定义
version	项目初始版本号	0.1.0

这些变量在你运行cookiecutter命令时会逐一以问答形式出现，回车确认或者输入自定义值，几分钟内一个完整的、带着你个人信息和描述的项目就生成好了，省去了手动改一堆占位符的麻烦。

云部署这块也考虑得比较周全

很多模板生成完项目就完事了，剩下的部署工作全靠开发者自己摸索，但这个项目连主流云平台的部署脚本也一并准备好了，涵盖了国外最常用的两大云服务商。

Google Cloud Platform方向，走的是Cloud Run无服务器容器部署路线，流程大致是先装gcloud命令行工具，登录认证，设置好项目ID，开启Cloud Run、Cloud Build和IAM这三个必要的API权限，最后跑一下项目自带的gcp-deploy.sh脚本就能把服务发布出去。

AWS方向，走的是Lambda无服务器函数路线，需要装awscli和sam-cli两个工具，用aws configure做认证，然后依次执行sam build和sam deploy两条命令完成部署，项目里甚至专门准备了一个main-aws-lambda.py入口文件，用来适配Lambda运行环境的特殊调用方式，这一点比很多同类模板考虑得更细致。

有个活生生的示例项目可以参考

光看模板文件难免有点抽象，仓库里还专门放了一个叫pregnancy-model的示例项目，作者自己描述这是拿来在GitHub上做直播演示用的。这个示例基本就是用模板生成后的实际样子，连uv.lock依赖锁定文件、compare.sh对比脚本都一起提交进去了，等于是把模板从抽象骨架变成了一份可以直接跑起来的活体标本，对着这个示例项目一步步看，比单纯读文档理解起来快得多。

适合谁用，又有哪些局限

这套模板最契合的场景，是那种既要写Web接口，又要把训练好的机器学习模型（比如用scikit-learn、XGBoost训练出的pkl文件）包装成在线预测服务的场景。数据科学家训练完模型，后端同学拿这个模板搭好FastAPI外壳，模型往ml/model文件夹一放，改改predictor.py里的加载逻辑，一个可以对外提供预测能力的API服务就成型了。

当然它也有自己的边界，如果你的项目根本不涉及机器学习，只是想快速搭一个纯粹的Web后端，这个模板里那些data、notebooks、ml文件夹反而显得多余，这时候选一个更轻量、专注Web层的FastAPI模板可能更合适。另外目前仓库的活跃度处于中等水平，星标数不算爆款级别，社区生态相对小众，遇到问题多半得靠自己啃源码或者提issue，不像一些大型框架那样能随手搜到海量教程。

写在最后

这类脚手架工具的价值，从来不在于它有多少炫技的设计，而在于它能不能真正帮你省下重复劳动的时间，把精力留给真正有创造性的部分，无论是调模型参数还是设计业务逻辑。cookiecutter-fastapi做的事情不复杂，说白了就是把FastAPI的Web开发习惯和机器学习工程化的目录规范糅合在一起，配上uv这种新一代包管理工具，再加上现成的CI流程和云部署脚本，整体拼出了一条从模型训练到线上服务的完整链路。如果你正好需要快速把一个机器学习模型包装成可用的API，这个模板值得直接拿来试试手，运行一条cookiecutter命令，剩下的交给它就好。

参考资料

arthurhenrique/cookiecutter-fastapi GitHub仓库主页, github.com/arthurhenri...

cookiecutter.json 配置文件, github.com/arthurhenri...

项目模板目录结构与README, github.com/arthurhenri...

pregnancy-model 示例项目, github.com/arthurhenri...