大模型学习应用 5: Vercel 部署 Python FastAPI 项目完整指南

Vercel 部署 Python FastAPI 项目完整指南

本文将详细介绍如何在 Vercel 平台上部署 Python FastAPI 项目，包括项目结构、代码实现、部署流程以及常见问题的解决方案。这是一个前置的测试项目，验证在vercel部署python项目的可行性，后续会部署更加复杂的服务，并且与coze结合

大模型落地开发实战指南！请关注微信公众号：「AGI启程号」 深入浅出，助你轻松入门！
数据分析、深度学习、大模型与算法的综合进阶，尽在CSDN博客主页

本项目源代码github链接，可自行克隆到自己的代码仓库完成vercel部署

一、项目代码结构介绍

1.1 项目目录结构

velcel项目部署测试/
├── api/
│   ├── hello.py          # 基础 Python API 函数
│   └── app.py           # FastAPI 应用（主应用）
├── Pipfile              # Python 环境配置
├── requirements.txt      # Python 依赖
├── vercel.json          # Vercel 路由配置
├── .gitignore           # Git 忽略文件
└── README.md            # 项目说明

1.2 核心文件代码解析

1.2.1 FastAPI 主应用 (api/app.py)

from fastapi import FastAPI
from datetime import datetime

# 创建 FastAPI 应用实例
app = FastAPI(title="Vercel FastAPI 测试", version="1.0.0")

@app.get("/")
def read_root():
    return {
        "message": "Hello from FastAPI on Vercel!",
        "timestamp": datetime.now().isoformat(),
        "status": "running"
    }

@app.get("/info")
def get_info():
    return {
        "app": "FastAPI on Vercel",
        "version": "1.0.0",
        "python_version": "3.10",
        "timestamp": datetime.now().isoformat()
    }

@app.get("/health")
def health_check():
    return {"status": "healthy", "timestamp": datetime.now().isoformat()}

@app.post("/echo")
def echo_data(data: dict):
    return {
        "message": "Data received successfully",
        "received_data": data,
        "timestamp": datetime.now().isoformat()
    }

代码关键点：

• 直接导出 app 变量，无需额外的 handler 函数
• Vercel 会自动检测 FastAPI 应用并作为 ASGI 应用运行
• 提供了多个端点用于测试不同功能

1.2.2 基础 Python 函数 (api/hello.py)

from http.server import BaseHTTPRequestHandler

class handler(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header('Content-type', 'text/plain')
        self.end_headers()
        self.wfile.write("Hello from Python on Vercel!".encode('utf-8'))
        return

代码关键点：

• 使用传统的 BaseHTTPRequestHandler 方式
• 提供简单的文本响应
• 适合简单的 API 端点

1.2.3 依赖配置 (requirements.txt)

fastapi==0.104.1

说明：

• 只包含必要的依赖
• Vercel 会自动安装指定版本的包

1.2.4 Python 环境配置 (Pipfile)

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[requires]
python_version = "3.10"

[packages]
fastapi = "*"
uvicorn = "*"

[dev-packages]

说明：

• 指定 Python 版本为 3.10
• uvicorn 用于本地开发测试

1.2.5 路由配置 (vercel.json)

{
  "routes": [
    { "src": "/(.*)", "dest": "api/app.py" }
  ]
}

说明：

• 所有请求都路由到 FastAPI 应用
• 无需 builds 配置，避免警告
• FastAPI 负责内部路由分发

二、部署流程

2.1 GitHub 部署准备

步骤1：创建 GitHub 仓库

# 初始化 Git 仓库
git init

# 添加文件
git add .

# 提交代码
git commit -m "Initial commit: Vercel FastAPI project"

# 关联远程仓库
git remote add origin https://github.com/your-username/your-repo.git

# 推送代码
git push -u origin main

步骤2：确保项目结构正确

• 确认所有必要文件都已提交
• 检查 .gitignore 文件排除不必要的文件
• 验证依赖文件格式正确

2.2 Vercel 部署流程

步骤1：安装 Vercel CLI

# 全局安装 Vercel CLI
npm install -g vercel

步骤2：登录 Vercel

# 登录 Vercel 账户
vercel login

步骤3：部署项目

# 在项目根目录执行
vercel

# 或直接部署到生产环境
vercel --prod

步骤4：配置部署设置

在部署过程中，Vercel 会询问：

• 项目名称（可自定义）
• 是否关联 GitHub 仓库
• 部署设置确认

步骤5：验证部署

部署完成后会得到访问 URL，测试以下端点：

• https://your-project.vercel.app/ - FastAPI 主页
• https://your-project.vercel.app/health - 健康检查
• https://your-project.vercel.app/info - 应用信息
• https://your-project.vercel.app/api/hello - 基础函数

2.3 本地开发测试

# 启动本地开发服务器
vercel dev

# 访问本地地址
http://localhost:3000

三、注意事项及问题处理

3.1 常见问题及解决方案

问题1：ModuleNotFoundError: No module named ‘fastapi’

错误信息：

File "/var/task/api/app.py", line 1, in 
from fastapi import FastAPI
ModuleNotFoundError: No module named 'fastapi'

解决方案：

1. 确保 requirements.txt 包含正确的依赖
2. 检查依赖版本格式：fastapi==0.104.1
3. 避免依赖冲突，优先使用 requirements.txt

问题2：issubclass() arg 1 must be a class

错误信息：

TypeError: issubclass() arg 1 must be a class
Python process exited with exit status: 1

原因：
使用了 handler = Mangum(app) 导致 Vercel 检查 handler 时出错

解决方案：

1. 删除 Mangum 相关代码
2. 直接导出 FastAPI 应用：

# ❌ 错误方式
from mangum import Mangum
handler = Mangum(app)

# ✅ 正确方式
app = FastAPI()
# 直接导出 app，无需额外 handler

问题3：cannot import name ‘Adapter’ from ‘mangum’

错误信息：

ImportError: cannot import name 'Adapter' from 'mangum'

原因：
Mangum 库版本更新，API 发生变化

解决方案：
完全移除 Mangum 依赖，让 Vercel 自动处理 ASGI：

# 删除这些导入和代码
from mangum import Adapter  # 删除
handler = Adapter(app)      # 删除

问题4：Vercel 构建警告

警告信息：

WARN! Due to `builds` existing in your configuration file, 
the Build and Development Settings defined in your Project Settings will not apply.

解决方案：
简化 vercel.json 配置：

// ❌ 导致警告的配置
{
  "version": 2,
  "builds": [
    {
      "src": "api/*.py",
      "use": "@vercel/python"
    }
  ],
  "routes": [...]
}

// ✅ 简化后的配置
{
  "routes": [
    { "src": "/(.*)", "dest": "api/app.py" }
  ]
}

3.2 最佳实践

1. 依赖管理

• 使用 requirements.txt 指定明确的版本号
• 保持依赖最小化，只安装必要的包
• 定期更新依赖版本

2. 代码结构

• FastAPI 应用直接导出，无需额外适配器
• 保持代码简洁，避免不必要的复杂性
• 合理组织 API 端点

3. 配置优化

• 使用最简化的 vercel.json 配置
• 让 Vercel 自动检测项目类型
• 避免过度配置

4. 调试技巧

# 查看部署日志
vercel logs

# 查看项目列表
vercel ls

# 查看项目详情
vercel inspect [deployment-url]

# 强制重新部署
vercel --force

3.3 性能优化建议

1. 冷启动优化

   • 减少依赖数量
   • 优化代码加载时间
   • 使用合适的 Python 版本

2. 响应时间优化

   • 实现适当的缓存策略
   • 优化数据库查询（如果使用）
   • 减少不必要的计算

3. 监控和日志

   • 使用 Vercel Analytics
   • 实现健康检查端点
   • 添加适当的错误处理

总结

通过本文的详细介绍，我们成功实现了：

1. 简洁的项目结构 - 最小化配置，最大化功能
2. 稳定的部署流程 - 避免常见陷阱，确保部署成功
3. 完善的问题解决方案 - 覆盖开发过程中的各种问题

这个项目展示了如何在 Vercel 上正确部署 Python FastAPI 应用，避免了传统部署中的复杂配置，充分利用了 Vercel 的自动检测和 Serverless 特性。

关键成功要素：

• ✅ 直接导出 FastAPI 应用，无需 Mangum
• ✅ 使用简化的 vercel.json 配置
• ✅ 明确指定依赖版本
• ✅ 合理的路由设计

该方案特别适合：

• 快速原型开发
• API 服务部署
• 无服务器架构实践
• 现代 Web 应用后端

希望本文能帮助您顺利完成 Vercel Python 项目的部署！