一直以为只有我有这种毛病：每次新开一个 AI 项目，前三天都在干同一件事——搭 FastAPI、配跨域、写健康检查、接日志、把大模型 SDK 封装一层，再调一晚上的流式响应。业务代码一行没写，时间倒是烧掉不少。后来实在忍不了，我把这套东西抽成了一个后端脚手架，陆陆续续用了一年多，最近整理干净后开源了出去。这篇文章就把脚手架的设计思路、核心模块的实操细节和踩过的坑都写清楚，给同样写 AI 应用的人一个可以直接抄作业的起点。
这套脚手架解决的是“AI 应用后端最无聊的那部分”：从零启动一个 FastAPI 项目的繁琐配置、大模型厂商 SDK 的反复适配、鉴权日志这些非业务但要命的基础设施。目标是开箱即用，clone 下来装完依赖就能跑通一个带流式聊天接口的最小可用服务。适合正在做 AI Agent、大模型应用后端，或者想从 FastAPI 入门又不想被配置劝退的开发者参考。
1. 为什么非要自己做一个 FastAPI 脚手架
1.1 重复的轮子到底长什么样
先说说那些让我抓狂的重复工作。做 AI 应用，后端接口十有八九是这几类：对话聊天、文本生成、知识库检索、Agent 任务编排。不管业务怎么变，底座几乎一样——HTTP 服务要配跨域，接口要鉴权，日志要轮转，参数要校验，大模型要接 SDK，输出要流式返回给前端。
具体到代码层面更是离谱。每次我都得重新写一遍CORSMiddleware的配置，重新写一个全局异常处理器把报错包成统一的{code, message, data}结构，重新封装一个StreamingResponse去转发大模型 token，重新搭一套日志配置让开发环境和生产环境长不一样。这些代码和业务没半点关系，但缺了任何一个，项目都跑不顺。
更麻烦的是大模型 SDK。今天接 OpenAI 的接口格式，明天换国产模型，后天用户要接私有化部署的 Ollama。每家 SDK 的调用方式大同小异，但参数名、流式返回格式、错误处理完全不一样。如果每个项目都从零写适配层，光切换模型供应商就够写一周。
1.2 为什么底座选了 FastAPI 而不是 Flask 或 Django
做 Python 后端，绕不开 Flask、Django、FastAPI 这几个选择。我并不是说他们不好，但放 AI 应用这个场景里，FastAPI 有天然优势。
首先，FastAPI 原生支持async/await。AI 应用的后端大量时间花在等大模型返回、等外部 API 响应上，这种 IO 密集型场景用异步能极大提升并发吞吐。Flask 虽然也能配异步，但原生写起来很别扭；Django 的异步支持是后加的，成熟度和生态相比 FastAPI 的异步范式还是有距离。
其次，FastAPI 基于 Pydantic 做数据校验和序列化，类型定义一套，校验、文档、自动补全全都能吃到红利。写请求体和响应体，就等于写了一个带类型的接口契约。前端拿到手，直接看/docs页面就能对着格式联调，省去大量口头传参和文档维护时间。
还有一个被很多人忽略的点：FastAPI 自动生成 OpenAPI 文档。AI 应用经常要跟前端、测试、算法同学协作，Swagger UI 直接打开/docs就能看一眼接口定义、试一下请求，沟通成本降了一个量级。Django REST Framework 也有类似能力，但整套框架的重量对 AI 应用后端来说还是偏重了。
1.3 脚手架的定位和边界
做脚手架最容易犯的毛病是想什么都往里塞。我一开始也犯过这个错，数据库、消息队列、定时任务、多租户、权限系统全塞进去，结果每个项目 git log 一大半是在删代码。
所以这个脚手架的定位很明确：只做“AI 应用后端的基础设施”，不碰业务。具体来说，它提供的是配置管理、异步数据库会话、统一响应与异常处理、JWT 鉴权、日志轮转、CORS 配置、健康检查、大模型 Provider 适配层、流式输出封装。这些是无论做什么 AI 应用都用得上的东西。
业务相关的部分，比如知识库、用户体系、订单、聊天历史存储，我刻意没有封装进去，留给每个项目的开发者自己写。这样脚手架才能保持小而稳定，不会因为某个业务需求爆炸而被迫大改。
2. 脚手架的功能设计与工程结构
2.1 目录结构总览
先放一个项目目录结构，让心里有个地图：
fastapi_ai_scaffold/ ├── app/ │ ├── api/ │ │ ├── v1/ │ │ │ ├── endpoints/ │ │ │ │ ├── chat.py # 聊天接口 │ │ │ │ ├── health.py # 健康检查 │ │ │ │ └── auth.py # 登录/刷新 token │ │ │ └── router.py # 路由汇总注册 │ │ └── deps.py # 依赖注入（当前用户、数据库会话等） │ ├── core/ │ │ ├── config.py # Pydantic Settings 配置管理 │ │ ├── security.py # JWT 生成与校验 │ │ └── logging.py # 日志配置 │ ├── models/ # SQLAlchemy ORM 模型 │ ├── schemas/ # Pydantic 请求/响应模型 │ ├── services/ # 业务服务层 │ ├── providers/ │ │ ├── base.py # LLM Provider 抽象基类 │ │ ├── openai_provider.py │ │ └── ollama_provider.py │ ├── utils/ │ │ └── response.py # 统一响应体封装 │ └── main.py # 应用入口 ├── alembic/ # 数据库迁移 ├── tests/ # pytest 测试 ├── .env.example ├── pyproject.toml ├── alembic.ini └── README.md一眼看过去，这个结构遵循的还是模块分层：api层管路由和 HTTP 细节，services层管业务逻辑，providers管外部模型接入，models和schemas分别管 ORM 和数据校验模型。这样分的好处是依赖方向始终是单向的——api 只调 services，services 只依赖 models 和 providers，不会出现循环引用。
2.2 内置能力清单
把脚手架内置的功能整理成一张表，方便对照自己的需求查漏：
| 能力 | 实现方式 | 解决什么问题 |
|---|---|---|
| 配置管理 | Pydantic Settings + .env | 环境差异、密钥管理 |
| 数据库 | SQLAlchemy 2.0 异步引擎 + Alembic | 异步会话、迁移 |
| 统一响应体 | 自定义response工具 + 全局异常处理 | 前端统一解析、错误规范 |
| JWT 鉴权 | OAuth2PasswordBearer + 依赖注入 | 接口身份认证 |
| CORS | CORSMiddleware + 环境配置 | 前端跨域联调 |
| 日志轮转 | logging.handlers.RotatingFileHandler | 日志不爆盘 |
| 大模型接入 | Provider 抽象 + 统一接口 | 快速切换模型供应商 |
| 流式输出 | StreamingResponse 封装 | 打字机效果 |
| 健康检查 | /health 接口 + 数据库 ping | 容器编排、监控 |
这几项每一类都是 AI 应用后端的高频需求。比如健康检查，部署到云服务上要被负载均衡器请求验证存活，没有这个接口服务注册都过不了；日志轮转更不用说，跑一晚上流式接口，日志能涨到几个 G，不轮转迟早磁盘爆掉。
2.3 设计原则：配置驱动和 Provider 抽象
脚手架里的两个核心设计原则值得展开讲。
一是配置驱动。所有需要根据不同环境变化的东西，统一从配置中心读取，不允许在代码里写死。数据库地址、Redis 地址、JWT 密钥、日志级别、允许跨域的域名、默认模型名，全部通过.env注入。这样同一个项目从本地开发环境切到测试环境、生产环境，只需要改.env文件，代码一行都不用动。
二是 Provider 抽象。所有大模型供应商都实现同一个基类，暴露统一接口。外部逻辑只依赖抽象层，不依赖具体的 OpenAI 或 Ollama 实现。好处很明显——换供应商改一行配置，加供应商写一个新类，不影响其他代码。这个设计在做 AI 应用时几乎必备，因为今天用 GPT，明天换国产模型，用户环境里跑的可能还是本地部署的 Llama，不抽象好根本活不下去。
3. 核心模块拆解与实操要点
3.1 配置管理：Pydantic Settings 的分层玩法
配置这块我用了pydantic-settings，它支持从默认值、.env文件、环境变量、命令行参数多个源头读取配置，并提供类型校验和 IDE 提示。
核心代码长这样：
# app/core/config.py from pydantic_settings import BaseSettings, SettingsConfigDict class Settings(BaseSettings): model_config = SettingsConfigDict( env_file=".env", env_file_encoding="utf-8", case_sensitive=True, extra="ignore", ) APP_NAME: str = "FastAPI AI Scaffold" DEBUG: bool = False SECRET_KEY: str = "change-me" JWT_ALGORITHM: str = "HS256" ACCESS_TOKEN_EXPIRE_MINUTES: int = 30 DATABASE_URL: str = "sqlite+aiosqlite:///./app.db" REDIS_URL: str = "redis://localhost:6379/0" LLM_PROVIDER: str = "ollama" OLLAMA_BASE_URL: str = "http://localhost:11434" OPENAI_API_KEY: str = "" OPENAI_BASE_URL: str = "" settings = Settings()这里有个细节很多人容易踩坑：case_sensitive=True会让.env里的变量名必须和代码里完全一致，比如写DATABASE_URL而不是database_url。这样看似繁琐，但避免了和系统环境变量里一堆小写变量混淆，尤其在部署时调试更清爽。
extra="ignore"也很关键。.env文件里写多了解析不了的自定义变量，不会直接报错，只会忽略。不然前端同学部署的时候多写一个变量，服务直接起不来，排查半天还以为是他们的问题。
3.2 异步数据库会话的正确打开方式
AI 应用后端虽然不常做复杂事务，但对话记录、用户数据这些总得有地方存。我用的是 SQLAlchemy 2.0 的异步引擎，搭配async_sessionmaker创建会话。
# app/core/database.py from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession from app.core.config import settings engine = create_async_engine(settings.DATABASE_URL, echo=settings.DEBUG) SessionLocal = async_sessionmaker(engine, expire_on_commit=False) async def get_db() -> AsyncSession: async with SessionLocal() as session: yield session一个常被忽略的细节是expire_on_commit=False。SQLAlchemy 默认在 commit 后会把 session 里对象的属性全部过期，下次访问时重新发起查询。在异步环境里，如果在 response 序列化时触发了这种懒加载查询，而且当前请求的 session 已经关闭，就会报MissingGreenlet这种让人一头雾水的错误。把这个参数设成False，commit 后对象属性保留，序列化就不会意外触发懒加载。
数据库这块我还配了 Alembic 迁移。每次修改模型后执行alembic revision --autogenerate生成迁移脚本，执行alembic upgrade head更新表结构。开发期还能用alembic downgrade回滚，避免手改表结构的那种心惊胆战。
3.3 统一响应体和全局异常处理
前端接后端接口最烦的就是每个接口返回结构都不一样，调试的时候要读一堆文档。脚手架里统一了响应格式和异常格式。
正常响应长这样：
{ "code": 0, "message": "success", "data": { ... } }业务异常长这样：
{ "code": 40001, "message": "token 已过期", "data": null }实现上靠两个东西配合。一是utils/response.py里定义了success_response和error_response两个函数，所有接口都通过它们返回；二是在main.py里注册了全局异常处理器，把HTTPException、RequestValidationError、未捕获异常、自定义业务异常分别处理成统一结构。
# app/main.py @app.exception_handler(AppException) async def app_exception_handler(request, exc: AppException): return JSONResponse( status_code=exc.status_code, content=error_response(code=exc.code, message=exc.message), )这样设计的好处是，前端拿到的永远是同一个格式，哪怕后端半夜抛了个空指针异常，前端也能解析出code和message，不会把堆栈暴露给用户。
3.4 JWT 鉴权：不要自己再造轮子
鉴权这块最容易犯的错是自己去写加密逻辑。别这样，直接用现成库。
脚手架里用python-jose生成和校验 JWT，配合 FastAPI 的依赖注入做统一鉴权。
# app/core/security.py from jose import jwt, JWTError from datetime import datetime, timedelta, timezone def create_access_token(sub: str, expires_minutes: int | None = None): payload = { "sub": sub, "exp": datetime.now(timezone.utc) + timedelta(minutes=expires_minutes or settings.ACCESS_TOKEN_EXPIRE_MINUTES), } return jwt.encode(payload, settings.SECRET_KEY, algorithm=settings.JWT_ALGORITHM)在api/deps.py里用 FastAPI 的Depends机制做当前用户解析：
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login") async def get_current_user(token: str = Depends(oauth2_scheme)) -> User: credentials_exception = AppException(code=40001, message="无效或过期的 token", status_code=401) try: payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.JWT_ALGORITHM]) except JWTError: raise credentials_exception ...用Depends而不是写中间件做鉴权，是因为依赖注入可以精确控制哪些接口需要鉴权、哪些不需要。健康检查、登录接口就走公开路由，聊天接口挂上Depends(get_current_user)就行。中间件反而容易搞成一刀切，后面想放行某个接口还得写一堆排除逻辑。
3.5 大模型流式输出：把“打字机”效果往上提一层
做 AI 应用，流式响应十有八九躲不开。前端想要的效果是模型输出一个字，界面一个字一个字蹦出来，而不是等几十秒一口气渲染一整段。
这个功能在 FastAPI 里可以基于StreamingResponse实现：
# app/api/v1/endpoints/chat.py from fastapi.responses import StreamingResponse @app.post("/api/v1/chat/stream") async def chat_stream(request: ChatRequest): provider = get_provider(settings.LLM_PROVIDER) source = provider.stream_chat(messages=request.messages) return StreamingResponse( source, media_type="text/event-stream", headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}, )注意StreamingResponse的迭代器必须是异步生成器，并在media_type里指定text/event-stream。X-Accel-Buffering: no这个 header 是给 Nginx 这类反向代理看的，告诉它别帮我把响应缓冲完再返回，必须边收边转发。这个问题曾经坑了我一晚上，后面单独讲。
4. 从零到一：快速跑通脚手架的正确姿势
4.1 环境准备与依赖安装
Python 版本建议 3.11 及以上，我用的是 3.12。依赖管理用的uv，这工具比pip快很多，而且能直接创建虚拟环境，一条命令搞定：
git clone https://github.com/yourname/fastapi-ai-scaffold.git cd fastapi-ai-scaffold uv venv source .venv/bin/activate # Windows 下是 .venv\Scripts\activate uv pip install -r requirements.txt不建议直接在系统 Python 里裸装依赖，尤其你机器上同时有多个 Python 项目的时候，依赖冲突能把人逼疯。uv venv会在项目目录下创建独立的虚拟环境，隔离干净也方便删除。
4.2 配置文件初始化
复制.env.example为.env，然后按需修改：
cp .env.example .env最关键的两个配置先改掉：SECRET_KEY换成一段随机字符串，DATABASE_URL改成你本地的数据库地址。脚手架默认支持 SQLite，开箱即用不需要额外装数据库，但部署到生产环境建议换 PostgreSQL，异步 SQLAlchemy 的拼音对 PostgreSQL 的异步驱动支持更完善。
然后初始化数据库：
alembic upgrade head没有迁移也能跑，但有迁移会让后续改表结构变得无比轻松。万一后面你加了一个字段想同步到数据库，执行alembic revision --autogenerate -m "add field"就完事了。
4.3 启动服务并验证核心链路
uvicorn app.main:app --reload --port 8000看到日志输出Uvicorn running on http://0.0.0.0:8000后，打开浏览器访问http://localhost:8000/docs，应该能看到 Swagger UI。里面至少有一个健康检查接口和一个聊天接口可以试。
先调健康检查：
GET /api/v1/health正常会返回：
{ "code": 0, "message": "success", "data": { "status": "ok" } }这说明配置加载、路由注册、统一响应体都正常。然后试试聊天接口，脚手架默认的LLM_PROVIDER接的是 Ollama，如果你本地装了 Ollama 并拉了一个模型，可以直接体验流式打字机效果。
4.4 快速新增一个业务模块的四个步骤
很多人拿到脚手架想加自己的业务，不知道怎么下手。其实套路是固定的，按顺序走就行。
第一步，建模型。在app/models/下新建note.py，定义 SQLAlchemy 模型，字段按业务需求定。
第二步，迁移。执行alembic revision --autogenerate -m "add note table"，检查生成脚本没问题后执行alembic upgrade head，数据库表就建好了。
第三步，写 Pydantic schema。定义创建请求和返回响应需要的字段，关系到接口的参数校验和文档显示。
第四步，写接口。在app/api/v1/endpoints/下新建note.py，挂一个 CRUD 接口，然后在router.py里注册即可。有鉴权需求就在接口上挂Depends(get_current_user)，没有就不挂。
这个流程熟练了以后，一个 CRUD 模块从无到有大概十分钟，而且全程不需要手动建表，不需要重启服务（--reload会热加载），效率比零散拼代码高很多。
5. 常见问题与排查技巧实录
5.1 Pydantic 和 FastAPI 版本冲突导致启动失败
有段时间pydantic-settings和 FastAPI 依赖的pydantic版本不兼容，启动时会报类似ModuleNotFoundError: No module named 'pydantic_settings'或者莫名其妙的校验错误。
排查思路很简单：先pip list | grep pydantic看版本，如果 pydantic 是 1.x，那pydantic-settings根本装不上；如果是 2.x，但pydantic-settings版本太老，也会有问题。最好的办法是直接在干净虚拟环境里按 requirements 安装，别在已有大量依赖的环境里升级，容易连锁反应。
5.2 CORS 配了还是跨域
前端联调最常见的报错是浏览器的No 'Access-Control-Allow-Origin' header is present。很多人以为是 CORS 代码没生效，但实际原因往往是：
- 前端请求带了
Authorization头，而后端CORSMiddleware没允许这个头。需要在allow_headers里加Authorization。 - 前端开了
withCredentials携带 Cookie，而后端allow_origins=["*"]跟携带凭证是冲突的，必须改成具体的域名。 - 前端请求的是一次带
OPTIONS方法的预检请求，如果路由没有处理OPTIONS方法，中间件没有正确拦截，也会导致失败。
我在脚手架里把 CORS 配置拆成了环境变量可选项，开发环境用宽泛配置，生产环境显式指定允许域名，两种场景分开，省得来回改。
5.3 流式接口不流式，收到一次性返回
这是做流式输出最容易踩的坑。本地调试一切正常，部署到服务器后，前端迟迟拿不到第一帧输出，非要等模型全部生成完毕才一次性返回。
这个问题九成出在反向代理层。Nginx 默认对上游响应做缓冲，只有收到完整的响应体才会转发给客户端，所以流式直接失效。解决办法是在 Nginx 配置里关掉对该路径的缓冲：
proxy_buffering off;同时在响应头里带上Cache-Control: no-cache和X-Accel-Buffering: no，提醒网关层不要缓存、不要聚合。不同云厂商的负载均衡规则不一样，有的需要额外配置“流式”或“SSE”开关，部署前记得查一下文档。
5.4 uv 安装依赖慢或直接卡死
uv 虽然快，但在某些网络环境下默认源拉包也可能不稳定。解决办法是配置国内镜像源：
uv pip install -r requirements.txt --index-url https://mirrors.aliyun.com/pypi/simple/也可以在项目根目录下创建uv.toml，把默认源固定下来，后面团队其他人 clone 项目就不用每人再配一遍。
如果出现某个包编译报错，大概率是 Python 版本不匹配。比如一些老包对 3.12 支持不好，就切回 3.11 创建虚拟环境。这种问题多半是项目没有锁 Python 版本导致的，可以在pyproject.toml里声明requires-python = ">=3.11, <3.13"，team 成员就不会踩版本坑了。
6. 脚手架使用过程中的真实体会与后续计划
6.1 我在这套结构里省下的时间
用了几个月后，最直观的感受是：新项目从“开始搭”到“能调模型接口”的时间从两三天压缩到了半小时。之前每次换项目切供应商要重新看一遍 SDK 文档，现在统一走 Provider 抽象层，接新供应商只需要写一个类实现统一的stream_chat和chat方法，不会影响到任何业务代码。
印象最深的一次，一个项目需要从 OpenAI 切换到本地私有化部署的模型，业务代码完全没有改动，只改了.env里的LLM_PROVIDER和OLLAMA_BASE_URL，重启服务重新调接口，一切照常。那一刻真的觉得当初做抽象层的时间太值了。
6.2 后续想加的东西和方向
脚手架目前处于“好用但还有很多扩展空间”的状态。接下来有几个想做的方向：一是多租户支持，方便做成 SaaS 给不同客户用；二是加入更多 Provider，比如各家国产大模型的官方 SDK，毕竟不同项目对接的模型差异很大；三是完善 Docker 部署能力和 CI/CD 模板，让前端同学也能一键拉起后端环境做联调；四是把监控和 metrics 加上，对接 Prometheus，跑一段时间能看到请求量、延迟、token 消耗这些关键指标。
6.3 给想自己做脚手架的人一个建议
如果你也在考虑做一套自己的脚手架，或者想给开源项目做贡献，我的建议是记住一句话：千万不要什么都往里塞。脚手架是“基础架构的沉淀”，不是“业务代码的仓库”。一个需求进脚手架的判断标准应该是——你是不是至少有三个不同项目都会用到它，而不是“这个项目刚需要，先扔进去看看”。
另一个建议是保持开源心态。把脚手架开源出去，不是显摆代码写得多好，而是让更多人帮忙发现问题、提出建议。项目刚开源的时候，我自己觉得已经挺稳了，结果 issue 里有人反馈 Windows 下目录命令不兼容、有人提了 Redis 缓存开关的 PR、有人发现 Ollama 流式解析在某些模型下会断流。这些反馈直接驱动了脚手架质量的提升，比自己闭门造车高效太多。
做开源的真正收获从来不只是代码本身，是你发现世界上另一群人也在解决同样的问题，并且愿意帮你的方案变得更好。这才是这个脚手架项目至今让我最有成就感的地方。
