随着您的 FastAPI 应用用于部署机器学习模型而日益发展,将所有 API 端点都放在一个 Python 文件(例如 main.py)中很快就会变得难以管理。代码将变得更难查找、维护和调试。API 的不同逻辑部分,例如预测端点、状态检查或模型管理路由,会混杂在一起。FastAPI 为此提供了一个整洁的解决方案:APIRouter。您可以将 APIRouter 看作一个迷你 FastAPI 应用。它允许您将相关路径操作(即端点)组合在一起,通常放在独立的 Python 模块中,然后将它们连接回您的主 FastAPI 应用实例。这种模块化方法是构建大型、结构良好的服务的基础。介绍 APIRouter一个 APIRouter 的运作方式与主 FastAPI 应用对象非常相似。您可以在 APIRouter 实例上定义路径操作(使用 @router.get、@router.post 等装饰器),就像在 app 实例上定义一样。让我们看看如何使用它。假设您想将模型预测端点分离到自己的模块中。首先,创建一个新文件,例如 routers/predictions.py。在此文件中,您导入 APIRouter 并创建一个实例:# routers/predictions.py from fastapi import APIRouter from pydantic import BaseModel # 如果需要,定义您的输入/输出 Pydantic 模型 class PredictionInput(BaseModel): feature1: float feature2: str # ... 其他特征 class PredictionOutput(BaseModel): prediction: float probability: float | None = None # 创建路由实例 router = APIRouter() # 在路由实例上定义路径操作 @router.post("/make", response_model=PredictionOutput) async def make_prediction(data: PredictionInput): """ 接收输入数据并返回模型预测结果。 (实际的模型加载和推理逻辑将在此处) """ # 模型推理逻辑的占位符 prediction_value = 1.0 # 替换为实际的 model.predict(...) probability_value = 0.85 # 如果您的模型提供概率,则替换 # 在这里,您通常会: # 1. 预处理输入数据 (data.dict()) # 2. 从您加载的机器学习模型获取预测结果 # 3. 如果有必要,对结果进行后处理 # 4. 返回结构化的输出 return PredictionOutput(prediction=prediction_value, probability=probability_value) @router.get("/info") async def get_model_info(): """ 返回关于预测模型的基本信息。 """ return {"model_name": "ExamplePredictor", "version": "1.0"} # 您可以在此处添加更多与预测相关的端点...请注意,我们使用 @router.post 和 @router.get,而不是 @app.post 和 @app.get。函数签名和 Pydantic 模型的使用方式保持完全一致。在主应用中包含路由现在,您需要让您的主 FastAPI 应用了解这个路由。在 main.py 中(或者主 FastAPI 实例定义的位置),您导入路由对象并使用 app.include_router() 方法。# main.py from fastapi import FastAPI from routers import predictions # 导入包含路由的模块 # 创建主 FastAPI 应用实例 app = FastAPI( title="ML Model Prediction Service", description="API for serving predictions from an ML model.", version="0.1.0" ) # 包含预测路由 app.include_router(predictions.router) @app.get("/") async def read_root(): ```python return {"message": "Prediction API!"}您也可以在此处包含其他路由from routers import monitoringapp.include_router(monitoring.router) 通过这种设置,在 `routers/predictions.py` 中定义的端点(`/make` 和 `/info`)现在是您主应用的一部分。FastAPI 在内部处理路由。当对 `/make` 或 `/info` 的请求到达时,它将被定向到 `predictions` 路由中对应的函数。 ### 使用前缀和标签组织 URL `include_router` 方法提供有用的参数,有助于更好地组织,特别是在 API 文档和 URL 结构方面。 * **`prefix`**: 为路由中定义的所有路由添加路径前缀。这非常适合将端点分组到一个共同的路径段下。 * **`tags`**: 为路由中的所有路由分配标签。这些标签用于在自动生成的 API 文档(如 Swagger UI)中对操作进行分组。 让我们修改 `main.py` 以使用这些参数: ```python # main.py (updated) from fastapi import FastAPI from routers import predictions app = FastAPI( title="ML Model Prediction Service", description="API for serving predictions from an ML model.", version="0.1.0" ) # 包含带前缀和标签的预测路由 app.include_router( predictions.router, prefix="/predict", # predictions.router 中的所有路由现在都以 /predict 开头 tags=["Predictions"] # 在文档中将这些端点分组到“预测”下 ) @app.get("/") async def read_root(): ```python return {"message": "Prediction API!"} 现在,之前在 `/make` 访问的端点将在 `/predict/make` 可用,而 `/info` 将在 `/predict/info` 可用。在您的交互式 API 文档(通常在 `/docs` 找到)中,您将看到这些端点整齐地分组在“预测”标签下。 ```graphviz digraph G { rankdir=LR; graph [bgcolor=transparent, fontname="Arial"]; node [shape=box, style="rounded,filled", fontname="Arial", fontsize=10, color="#495057", fillcolor="#e9ecef", fontcolor="#495057"]; edge [color="#adb5bd", fontname="Arial", fontsize=9]; subgraph cluster_main { label = "main.py"; style="filled,rounded"; color="#dee2e6"; bgcolor="#f8f9fa"; main_app [label="app = FastAPI()"]; include_call [label="app.include_router(\n predictions.router,\n prefix='/predict',\n tags=['Predictions']\n)", shape=invhouse]; main_app -> include_call [label=" 配置 "]; } subgraph cluster_router { label = "routers/predictions.py"; style="filled,rounded"; color="#dee2e6"; bgcolor="#f8f9fa"; router_instance [label="router = APIRouter()"]; predict_endpoint [label="@router.post('/make')", shape=ellipse, fillcolor="#a5d8ff"]; info_endpoint [label="@router.get('/info')", shape=ellipse, fillcolor="#a5d8ff"]; router_instance -> predict_endpoint; router_instance -> info_endpoint; } include_call -> router_instance [label=" 包含 "]; }示意图显示了主应用如何包含预测路由模块。include_router 调用指定了 /predict 前缀并分配了“预测”标签。使用 APIRouter 是构建可维护和可伸缩的 FastAPI 应用的重要一步。它使您能够:关注点分离:将与特定功能(如预测、用户管理、数据预处理)相关的代码保留在独立的模块中。提高可读性:文件更小,更易于理解和查找。促进协作:不同的团队成员可以同时处理不同的路由,减少合并冲突。组织 URL:使用前缀创建逻辑 URL 结构(例如,/api/v1/predict/...)。增强文档:使用标签对自动生成的 API 文档中的相关端点进行分组。随着您的机器学习 API 的发展,尽早采用路由将在长期为您节省大量精力,并构成组织良好的项目结构的支柱。