一直以为只有我有这种毛病每次新开一个 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 只调 servicesservices 只依赖 models 和 providers不会出现循环引用。2.2 内置能力清单把脚手架内置的功能整理成一张表方便对照自己的需求查漏能力实现方式解决什么问题配置管理Pydantic Settings .env环境差异、密钥管理数据库SQLAlchemy 2.0 异步引擎 Alembic异步会话、迁移统一响应体自定义response工具 全局异常处理前端统一解析、错误规范JWT 鉴权OAuth2PasswordBearer 依赖注入接口身份认证CORSCORSMiddleware 环境配置前端跨域联调日志轮转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_encodingutf-8, case_sensitiveTrue, extraignore, ) 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 sqliteaiosqlite:///./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_sensitiveTrue会让.env里的变量名必须和代码里完全一致比如写DATABASE_URL而不是database_url。这样看似繁琐但避免了和系统环境变量里一堆小写变量混淆尤其在部署时调试更清爽。extraignore也很关键。.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, echosettings.DEBUG) SessionLocal async_sessionmaker(engine, expire_on_commitFalse) async def get_db() - AsyncSession: async with SessionLocal() as session: yield session一个常被忽略的细节是expire_on_commitFalse。SQLAlchemy 默认在 commit 后会把 session 里对象的属性全部过期下次访问时重新发起查询。在异步环境里如果在 response 序列化时触发了这种懒加载查询而且当前请求的 session 已经关闭就会报MissingGreenlet这种让人一头雾水的错误。把这个参数设成Falsecommit 后对象属性保留序列化就不会意外触发懒加载。数据库这块我还配了 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_codeexc.status_code, contenterror_response(codeexc.code, messageexc.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(minutesexpires_minutes or settings.ACCESS_TOKEN_EXPIRE_MINUTES), } return jwt.encode(payload, settings.SECRET_KEY, algorithmsettings.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(code40001, message无效或过期的 token, status_code401) 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(messagesrequest.messages) return StreamingResponse( source, media_typetext/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.13team 成员就不会踩版本坑了。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 流式解析在某些模型下会断流。这些反馈直接驱动了脚手架质量的提升比自己闭门造车高效太多。做开源的真正收获从来不只是代码本身是你发现世界上另一群人也在解决同样的问题并且愿意帮你的方案变得更好。这才是这个脚手架项目至今让我最有成就感的地方。
基于FastAPI的AI应用后端脚手架：开箱即用与流式输出实践
一直以为只有我有这种毛病每次新开一个 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 只调 servicesservices 只依赖 models 和 providers不会出现循环引用。2.2 内置能力清单把脚手架内置的功能整理成一张表方便对照自己的需求查漏能力实现方式解决什么问题配置管理Pydantic Settings .env环境差异、密钥管理数据库SQLAlchemy 2.0 异步引擎 Alembic异步会话、迁移统一响应体自定义response工具 全局异常处理前端统一解析、错误规范JWT 鉴权OAuth2PasswordBearer 依赖注入接口身份认证CORSCORSMiddleware 环境配置前端跨域联调日志轮转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_encodingutf-8, case_sensitiveTrue, extraignore, ) 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 sqliteaiosqlite:///./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_sensitiveTrue会让.env里的变量名必须和代码里完全一致比如写DATABASE_URL而不是database_url。这样看似繁琐但避免了和系统环境变量里一堆小写变量混淆尤其在部署时调试更清爽。extraignore也很关键。.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, echosettings.DEBUG) SessionLocal async_sessionmaker(engine, expire_on_commitFalse) async def get_db() - AsyncSession: async with SessionLocal() as session: yield session一个常被忽略的细节是expire_on_commitFalse。SQLAlchemy 默认在 commit 后会把 session 里对象的属性全部过期下次访问时重新发起查询。在异步环境里如果在 response 序列化时触发了这种懒加载查询而且当前请求的 session 已经关闭就会报MissingGreenlet这种让人一头雾水的错误。把这个参数设成Falsecommit 后对象属性保留序列化就不会意外触发懒加载。数据库这块我还配了 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_codeexc.status_code, contenterror_response(codeexc.code, messageexc.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(minutesexpires_minutes or settings.ACCESS_TOKEN_EXPIRE_MINUTES), } return jwt.encode(payload, settings.SECRET_KEY, algorithmsettings.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(code40001, message无效或过期的 token, status_code401) 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(messagesrequest.messages) return StreamingResponse( source, media_typetext/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.13team 成员就不会踩版本坑了。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 流式解析在某些模型下会断流。这些反馈直接驱动了脚手架质量的提升比自己闭门造车高效太多。做开源的真正收获从来不只是代码本身是你发现世界上另一群人也在解决同样的问题并且愿意帮你的方案变得更好。这才是这个脚手架项目至今让我最有成就感的地方。
