FastAPI本地部署时请求失败的常见原因与解决方案

fastapi应用启动时报“连接被拒绝”错误，通常是因为在服务器尚未启动时就执行了客户端请求代码，导致请求无法建立连接。本文将详细解释该问题的根本原因，并提供正确的部署与测试方法。

在您提供的 FastAPI 示例中，问题核心在于服务端代码与客户端调用逻辑混写在同一文件中。具体来看：

# ... FastAPI 路由定义 ... @app.post("/predict") def predict_route(data: List[float]):     prediction = predict(data)     return {"prediction": prediction}  # ❌ 错误：此处立即发起 http 请求 import requests f = open('test_data.json') data = json.load(f)  response = requests.post("http://localhost:8000/predict", json=data)  # ← 此行在 uvicorn 启动前就执行！ print(response.json())

当您运行 uvicorn main:app –reload 时，python 会自上而下执行整个 main.py 文件。这意味着：

• requests.post(…) 会在 FastAPI 应用监听 http://localhost:8000 之前就被触发；
• 此时端口 8000 尚未被占用，系统返回 [winError 10061]（windows）或 ConnectionRefusedError（linux/macOS），即“目标机器主动拒绝连接”。

✅ 正确做法是：分离服务端与客户端逻辑。

✅ 推荐方案：拆分为两个独立文件

1. app.py（纯服务端）

from fastapi import FastAPI import pickle import numpy as np from typing import List  app = FastAPI()  def predict(data: List[float]):     with open("model.pkl", "rb") as f:         model = pickle.load(f)     data = np.array(data).reshape(1, -1)     prediction = model.predict(data).tolist()  # .tolist() 确保 JSON 可序列化     return prediction  @app.post("/predict") def predict_route(data: List[float]):     return {"prediction": predict(data)}

启动服务：

uvicorn app:app --reload --host 127.0.0.1 --port 8000

2. test_client.py（独立客户端）

import requests import json  # 确保服务已启动后再运行此脚本 with open("test_data.json") as f:     test_data = json.load(f)  response = requests.post(     "http://127.0.0.1:8000/predict",     json=test_data,     timeout=10 )  if response.status_code == 200:     print("✅ 预测成功：", response.json()) else:     print("❌ 请求失败，状态码：", response.status_code)     print("响应内容：", response.text)

运行测试：

python test_client.py

⚠️ 注意事项

• ✅ 始终先启动服务（uvicorn），再运行客户端脚本；
• ✅ 使用 127.0.0.1 替代 localhost 可避免部分 DNS 解析延迟（尤其在 Windows 上）；
• ✅ model.pkl 必须与 app.py 在同一目录，或使用绝对路径加载；
• ✅ 返回值需为 JSON 可序列化类型（如 np.ndarray 需 .tolist() 转换）；
• ? 若仍报错，请检查：端口是否被占用（netstat -ano | findstr :8000）、防火墙设置、或模型文件是否存在。

通过清晰分离关注点，不仅能解决当前连接错误，也为后续集成测试、CI/CD 和 API 文档（Swagger ui 自动可用）打下坚实基础。