Full-Stack AI Agent Template：像搭乐高一样快速构建 AI 应用

想象这样的场景：你刚刚想出一个 AI 产品的点子——比如做一个带知识库问答功能的 SaaS 平台。按照传统流程，你需要手写 FastAPI 后端、配置 Next.js 前端、集成 LangChain 或 PydanticAI、设计 RAG 向量数据库、搞定认证和权限……光是项目架子就要折腾好几天。

Full-Stack AI Agent Template 告诉你：这套流程，一个命令就能生成。

这个开源项目是一款交互式 CLI 代码生成器，基于 Cookiecutter 模板引擎 + Jinja2 条件渲染，通过一行命令生成完整的 FastAPI + Next.js 全栈 AI 应用骨架，内置 5 大 AI Agent 框架、RAG 管道、20+ 企业级集成，以及 JWT 认证、WebSocket 流式输出、管理后台、Stripe 计费、Celery 异步任务等一整套生产级功能。

图1：生成的 AI Chat 界面，支持实时任务规划与流式输出

背景故事：一个开发者的"不想重复造轮子"

这个项目由独立开发者 Kacper（@Kacper95682155） 创建和维护，他在 GitHub 上创建了完整的 Vstorm OSS 生态，包括 pydantic-deepagents（模块化 Agent 运行时）、pydantic-ai-shields（Pydantic AI Agent 护栏）、pydantic-ai-subagents（声明式多 Agent 编排）等多个互补项目。

这个模板的诞生源于他在多个 AI 项目中反复搭建相同的基础设施：认证系统、数据库连接、WebSocket 管道、任务队列……每一个新项目都在重复同样的脚手架工作。他的解决方案是用一个 CLI 工具把这些基础设施代码全部模板化，通过交互式问答选择所需组件，5 分钟生成一个可以直接跑的生产级项目。

项目使用 MIT 许可证，Python 3.11+ 环境，推荐使用 uv 作为包管理工具，在 GitHub 上已获得 OpenSSF Best Practices 认证，测试覆盖率达到 100%，持续集成由 GitHub Actions 驱动。

核心功能：5 分钟生成全栈 AI 应用

5 大 AI Agent 框架支持

项目支持在生成项目时选择不同的 AI Agent 运行时框架：

框架	特点	适用场景
PydanticAI	Pydantic 官方 Agent 框架，结构化输出强	需要严格数据类型约束的 AI 应用
PydanticDeep	Vstorm 自研，Claude Code 风格 CLI + Docker 沙箱	多 Agent 团队协作、浏览器自动化
LangChain	生态最成熟，文档丰富	快速原型、多数据源集成
LangGraph	有向无环图工作流，状态管理强	复杂多步骤推理链路
DeepAgents	即插即用的 Agent 组件库	模块化组合不同 Agent 能力

开发者可以在初始化项目时通过 --ai-framework 参数指定框架，或者使用交互式向导（默认模式）选择：

# 交互式向导（默认）
fastapi-fullstack

# 直接指定参数
fastapi-fullstack create my_ai_app \
  --ai-framework pydantic_ai \
  --rag \
  --database postgresql \
  --task-queue celery

RAG 检索增强生成管道

项目内置完整的 RAG 管道，支持对接多种向量数据库：

• Milvus（大规模生产级向量检索）
• Qdrant（Rust 编写，高性能）
• pgvector（PostgreSQL 扩展，现有 SQL 基础设施友好）
• ChromaDB（轻量级，本地开发首选）

生成的 RAG 管道包含文档上传、分块策略、嵌入生成、向量索引、混合检索、重新排序（reranker）等完整流程，并支持配置知识库来源（上传文档、URL、Notion 等）。

图2：RAG 知识库问答演示，支持多源文档接入

企业级功能集成（20+）

生成的脚手架不是简单的 Hello World，而是一个可以真正上生产的系统：

• 认证授权：JWT + OAuth2、邮件验证码登录、社交账号登录（Google/GitHub）
• 数据库：PostgreSQL（SQLAlchemy/SQLModel）、MongoDB、Redis
• 异步任务：Celery + Redis、Taskiq、Arq、Prefect（带可视化 Dashboard）
• 实时通信：WebSocket 流式输出，AI 回答一个字一个字蹦出来的体验
• 计费系统：Stripe 集成，支持订阅制、按量计费、免费额度、积分体系
• 可观测性：Logfire（Pydantic 官方观测平台）、LangSmith 集成
• 容器化：生成的项目包含 Dockerfile 和 docker-compose，支持 K8s 部署
• CI/CD：可选 GitHub Actions 或 GitLab CI 配置

图3：Prefect 可视化任务编排 Dashboard，监控异步任务执行

技术架构：Cookiecutter 模板 + 模块化设计

生成器架构（fastapi_gen/）

CLI 工具本身代码结构清晰，仅 5 个核心模块：

fastapi_gen/
├── cli.py        # Click CLI：new / create / templates 三个入口
├── config.py     # Pydantic 模型定义配置项，120+ 变量
├── prompts.py    # Questionary 交互式提问
├── generator.py  # Cookiecutter 调用执行
└── prompts.py   # AI Agent 生成提示词模板

生成产物架构

生成的项目遵循统一的分层架构：

backend/
├── app/
│   ├── main.py         # FastAPI 入口 + lifespan 管理
│   ├── api/            # 路由、依赖注入、异常处理
│   ├── core/           # 配置、安全、中间件
│   ├── db/             # ORM 模型、会话管理
│   └── schema/         # Pydantic 请求/响应模型
frontend/
├── app/                # Next.js 15 App Router
├── components/          # React 组件库
└── lib/                # 工具函数

图4：生成的 Next.js 15 Dashboard，支持亮色/暗色主题

Web UI 特性

生成的前端包含完整的 React 组件体系：AI Chat 界面（支持 Markdown 渲染、代码高亮、图片上传）、知识库管理后台、用户管理面板、计费管理、组织架构设置等。

图5：Chat 界面支持多 Agent 协作，子 Agent 分工处理不同子任务

落地体验：谁在用？怎么用？

典型使用场景

1. AI SaaS 平台快速启动：开发者想做一个 AI 客服/文档问答产品，选框架 → 选 RAG 方案 → 一键生成，30 分钟拿到完整后端 + 前端。
2. 企业内部 AI 工具搭建：公司需要一个带认证、带计费的内部 AI 助手平台，基于此模板生成后接入自有 LLM API 即可。
3. AI Agent 原型验证：想快速验证某个 AI Agent 方案（选 PydanticAI 或 LangGraph），用模板生成项目而不是从零搭建。

上手门槛

门槛非常低。只要本地装了 Python 3.11+ 和 uv，执行 pip install fastapi-fullstack 或 uv pip install fastapi-fullstack，然后运行 fastapi-fullstack 即可进入交互式配置向导。不需要懂 Docker、不需要懂 AI 框架，体验相当友好。

生成的代码质量较高：完整的类型注解、Pydantic 验证、pytest 测试、ruff 代码规范，生成后直接 docker-compose up 就能跑起来。

图6：生成项目包含完整的 Landing Page，支持暗色主题

局限与不足

项目并非完美，以下几点需要纳入评估：

1. 非零运维：这是一个代码生成器，不是托管服务。生成的代码需要自己部署、维护和升级，cookiecutter 模板更新后需要手动同步到已有项目。
2. Next.js 前端复杂度：生成的前端是一个完整 SaaS 界面，包含大量页面（计费、管理后台、多语言等），对于只需要简单 AI 界面的场景显得过于庞大。
3. Python 3.11+ 要求：部分企业环境可能还在使用 3.9 或 3.10，升级 Python 版本本身就有一定成本。
4. AI 模型需要自备：模板生成的是应用框架，LLM API（OpenAI/Anthropic/Azure）需要自行申请并配置 key，没有内置的模型调用能力。
5. PostgreSQL 强依赖：虽然支持多种数据库，但 RAG 功能最佳体验依赖 pgvector，生产环境推荐 PostgreSQL，SQLite 用户需要额外适配。

行业意义：降低 AI 应用开发的第一道门槛

2024-2025 年是 AI 应用爆发的年份，但"从想法到可运行的代码"这道坎难住了大量非 AI 原生的开发者。LangChain 的崛起解决了"怎么调用 LLM"的问题，而这个项目解决的是"怎么搭建一个包含 AI 的完整产品"的问题——认证、数据库、异步任务、前端 UI、计费系统，这些和 AI 无关但产品必须的基础设施，正是阻碍独立开发者快速验证想法的真正瓶颈。

项目在 GitHub 拥有 1539 颗星（持续增长中），pypi 月下载量可观，且作者保持着高频的版本迭代（2024-2025 年持续更新）。结合 Vstorm OSS 生态中的 pydantic-deepagents（Agent 运行时）、pydantic-ai-shields（安全护栏）等工具，整个生态正在构建一个从"想法"到"生产 AI 应用"的完整工具链。

如果你正在构建 AI 应用但不想从零搭建基础设施，这个项目值得花 5 分钟试用一下。