前言

        在Python后端开发领域，Web框架层出不穷，老牌的Django功能大而全，适合重型管理系统；轻量化的Flask极简灵活，适合小型项目。但在当下AI爆发、微服务普及、高并发接口需求激增的时代，一款兼顾高性能、易开发、自带类型校验、自动生成接口文档的现代化Web框架，成为了开发者的首选，它就是 FastAPI。

        现如今绝大多数AI知识库、对话机器人、大模型中转接口、代码Agent后端，底层全部基于FastAPI开发。本文将从零开始，由浅入深带你全方位掌握FastAPI，零基础也能看懂，文末附带AI项目专属的流式SSE实战案例，直接适配你的知识库项目。

一、FastAPI 是什么？

1.1 核心概念

        FastAPI 是一款基于 Python 3.8+ 开发的现代化、高性能、异步Web框架，专门用于快速构建API接口服务，由Sebastián Ramírez于2018年底发布。简单说，它的目标就是：让开发者用最少代码写出高性能、自动生成文档的API。

        它底层依托两大核心库：

  • Starlette：负责底层Web服务运行，主打异步高性能；

  • Pydantic：负责数据校验与类型解析，依托Python类型注解实现自动参数校验。

1.2 FastAPI 核心优势（为什么选它？）

1）极致高性能

原生支持 async/await 异步编程，非阻塞IO模型，能够以极少的资源支撑高并发请求。性能直追Go、Node.js，远超传统同步框架Flask、Django，非常适合AI长连接、流式响应、高并发接口场景。

2）开发效率极高

开发者只需要编写基础路由与类型注解，无需手写冗余的数据校验、参数解析代码。官方数据统计，使用FastAPI可将接口开发效率提升 200%~300%。

3）自动生成接口文档

框架内置交互式接口文档，无需额外集成第三方工具。项目启动后，直接访问指定地址即可查看、调试所有接口，完美适配前后端协作、项目对接、招投标交付。

  • Swagger UI：/docs，可视化调试接口；

  • ReDoc：/redoc，格式化离线文档。

4）自带强类型校验

依托Pydantic实现全自动参数校验、类型转换、异常提示。前端传参格式错误、类型错误、参数缺失时，框架自动返回标准化报错，无需开发者手动判断。

5）低学习成本

语法简洁，兼容同步/异步两种写法，新手可以先用同步模式快速上手，进阶后再使用异步优化性能，适配所有层级开发者。

1.3 适用业务场景

  • AI相关：大模型对话接口、知识库问答、流式SSE响应、Agent任务调度；

  • 微服务：轻量化后端微服务、内部接口网关；

  • 常规开发：小程序/APP后端、管理系统接口、第三方API转发；

  • 长连接业务：消息推送、实时日志、数据同步。

二、环境搭建

2.1 依赖安装

创建虚拟环境后，安装FastAPI与运行服务器uvicorn：

pip install fastapi uvicorn

简单说明：

  • fastapi：框架本体，用于编写接口；

  • uvicorn：ASGI高性能异步服务器，用于启动项目（类比Flask的werkzeug）。

2.2 第一个Hello World项目

新建 main.py，编写最简代码：

# 导入核心类 
from fastapi import FastAPI 
# 实例化应用对象 
app = FastAPI(title="FastAPI入门项目", version="1.0") 
# 注册根路由 
@app.get("/") 
def root(): 
    return {"msg": "Hello FastAPI！"}

2.3 启动项目

终端执行启动命令：

uvicorn main:app --reload --host 0.0.0.0 --port 8000

参数详解：

  • main：对应文件名 main.py；

  • app：文件内实例化的FastAPI对象；

  • --reload：热重载，代码修改自动重启（仅开发环境使用）；

  • --host 0.0.0.0：允许局域网所有设备访问；

  • --port 8000：指定运行端口。

2.4 访问地址

  • 项目首页：http://127.0.0.1:8000

  • 交互式接口文档：http://127.0.0.1:8000/docs

  • 离线格式化文档：http://127.0.0.1:8000/redoc

三、基础路由与请求方式

路由的本质：将客户端的URL请求，绑定到对应的处理函数上，不同请求方式对应不同业务场景。

3.1 常见请求方式

  • GET：查询数据，参数拼接在URL中，无请求体；

  • POST：提交数据，用于新增、复杂查询、AI对话；

  • PUT/DELETE：分别用于更新、删除资源。

3.2 同步/异步路由写法

FastAPI同时支持同步、异步两种接口写法，开发者可自由选择：

from fastapi import FastAPI
import asyncio

app = FastAPI()

# 同步接口（适合简单业务）
@app.get("/sync/info")
def get_sync_info():
    return {"data": "同步普通接口"}

# 异步接口（适合AI、IO阻塞、高并发业务）
@app.get("/async/info")
async def get_async_info():
    await asyncio.sleep(0.1)
    return {"data": "异步高性能接口"}

建议：AI、文件读写、数据库、网络请求类IO密集型业务，统一使用异步写法。

四、参数接收（核心重点）

FastAPI将参数分为三类，也是后端开发最核心的知识点：

  • 路径参数：参数写在URL路由地址中；

  • 查询参数：URL后缀拼接的键值对；

  • 请求体参数：POST专用，JSON格式，用于传递复杂数据。

4.1 路径参数

适用于定位唯一资源，参数直接嵌入路由地址：

# 路径参数：item_id 直接写在路由内
@app.get("/item/{item_id}")
async def get_item(item_id: int):
    # 自动校验：如果传入非数字，直接返回报错
    return {"item_id": item_id}

4.2 查询参数

路由固定，参数通过 ?key=value&key2=value2 拼接，GET请求专用：

@app.get("/search")
async def search(keyword: str, page: int = 1, size: int = 10):
    """
    keyword：必传参数
    page/size：可选参数，设置默认值
    """
    return {
        "keyword": keyword,
        "page": page,
        "size": size
    }

4.3 请求体参数（POST核心）

日常开发、AI接口开发使用最多，用于接收前端JSON数据。FastAPI通过Pydantic模型规范化管理请求体，自动校验字段类型：

from pydantic import BaseModel

# 定义数据模型，自动校验参数
class ChatRequest(BaseModel):
    prompt: str
    temperature: float = 0.7
    max_tokens: int = 2048

# POST接收JSON请求体
@app.post("/chat")
async def chat(req: ChatRequest):
    return {
        "prompt": req.prompt,
        "temperature": req.temperature
    }

五、静态文件与跨域配置

5.1 挂载静态文件

前后端分离项目中，用于托管图片、js、css、静态HTML页面：

from fastapi.staticfiles import StaticFiles

# 挂载static文件夹，外部可直接访问
app.mount("/static", StaticFiles(directory="static"), name="static")

5.2 跨域CORS配置

前端页面调用后端接口会触发跨域报错，一行配置即可解决：

from fastapi.middleware.cors import CORSMiddleware

# 允许跨域
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],       # 允许所有域名
    allow_credentials=True,
    allow_methods=["*"],       # 允许所有请求方式
    allow_headers=["*"],       # 允许所有请求头
)

六、全局异常处理

FastAPI默认报错格式繁琐，我们可以自定义全局异常处理器，统一返回标准化JSON报错，适配前后端项目：

from fastapi import HTTPException, Request
from fastapi.responses import JSONResponse

# 自定义全局异常
@app.exception_handler(HTTPException)
async def http_exception_handler(request: Request, exc: HTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "code": exc.status_code,
            "msg": exc.detail,
            "data": None
        }
    )

七、高阶实战：AI流式SSE响应（重点）

7.1 什么是SSE？

SSE（Server-Sent Events）服务器推送事件，基于HTTP长连接，专门用于服务端向客户端单向持续推送数据，无需额外引入WebSocket，是AI流式输出的行业标准方案。

7.2 完整流式接口代码

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
import httpx
import logging
from typing import Dict

app = FastAPI()
logger = logging.getLogger(__name__)
API_URL = "你的大模型接口地址"

class StreamRequest(BaseModel):
    prompt: str
    temperature: float = 0.6

# 核心流式接口
@app.post("/api/stream/chat")
async def stream_chat(req: StreamRequest):
    payload = {
        "prompt": req.prompt,
        "temperature": req.temperature
    }
    headers = {"Content-Type": "application/json"}

    # 异步生成器
    async def generate_stream():
        async with httpx.AsyncClient(timeout=1800.0) as client:
            async with client.stream("POST", API_URL, json=payload, headers=headers) as response:
                if response.status_code != 200:
                    error_text = await response.aread()
                    logger.error(f"模型调用异常: {error_text}")
                    yield f'data: {{"error": "接口调用失败"}}\n\n'
                    return
                # 逐段推送数据
                async for chunk in response.aiter_text():
                    for line in chunk.split("\n"):
                        if line.strip():
                            yield f"{line}\n"

    # 返回SSE流式响应
    return StreamingResponse(
        generate_stream(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "Connection": "keep-alive",
            "X-Accel-Buffering": "no" # 禁止Nginx缓存，解决流卡顿
        }
    )

7.3 代码核心知识点复盘

  • StreamingResponse：FastAPI专属流式响应对象，用于返回SSE长连接；

  • async with：自动管理异步HTTP连接，请求结束自动关闭，防止连接泄露；

  • yield：异步生成器核心，分段输出内容、不关闭连接，实现打字机效果；

  • X-Accel-Buffering: no：生产环境必备，解决Nginx缓冲导致流式卡顿问题。

八、项目目录规范（企业级）

小型项目直接单文件开发，中型AI知识库项目推荐以下分层结构，适配软著申报、团队协作：

Langchain-Project/
├── main.py               # 项目入口
├── config.py             # 全局配置
├── api/                  # 所有路由接口
│   ├── __init__.py
│   ├── chat.py           # 对话接口
│   └── kb.py             # 知识库接口
├── core/                 # 核心组件
│   ├── exceptions.py     # 异常处理
│   └── stream.py         # 流式工具
├── static/               # 静态资源
└── .venv/                # 虚拟环境

九、总结

FastAPI之所以成为AI时代的首选Python后端框架，本质原因可以总结为三点：

  1. 异步高性能：完美适配AI长连接、流式输出、高并发问答场景；

  2. 开箱即用：自动接口文档、参数校验、异常捕获，大幅降低开发成本；

  3. 生态完善：兼容所有Python第三方库，和Langchain、向量数据库、大模型无缝集成。

若你正在做知识库、AI Agent、智能问答项目，FastAPI是必备底层技术，掌握路由、参数接收、SSE流式响应三大知识点，足以支撑99%的AI后端开发需求。

# fastapi # web app
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

AtomGit 首发开源｜光轮智能发布全球首个十万小时级全模态人类行为开源数据集 EgoSuite-Open100K

avatar AtomGit开源社区
cover

AtomCode 全新上线万亿代码模型 LongCat-2.0。限时 7 天免费体验！

avatar AtomGit开源社区
cover

构筑赋能金融行业应用 Agent｜20 强决战北京，一场金融 Agent 的硬核答卷

avatar AtomGit开源社区