Python FastAPI

FastAPI 的核心是用 Python 快速创建 AI 服务接口，让 Java 后端可以通过 HTTP 调用 Python 里的模型、RAG 或 Agent 能力。

• Python FastAPI
  • FastAPI 是什么
  • 创建 FastAPI 服务
  • 定义请求响应
  • 完整 main.py
  • Java 调用 Python
  • 接口异常处理
  • 统一响应格式
  • Java 调用异常处理
  • 目录建议
  • requirements.txt
  • 常见问题
    • 为什么要 Java 调 Python
    • FastAPI 的 docs 页面有什么用
    • GET 请求能不能带请求体
    • Java 调 Python 要不要加超时
  • 练习清单
  • 小结
  • 参考资料

FastAPI 是什么

FastAPI，中文可以理解为“快速 API Web 框架”。

它是 Python 生态里常用的 Web API 框架。

在 AI Agent 学习路线里，FastAPI 主要用来承接 Python AI 生态能力。

比如：

LangChain
LangGraph
RAG 实验
Embedding
Agent 工作流
评测脚本

Java 和 Python 的分工可以先这样理解：

Java：业务系统、权限、数据库、接口网关
Python：AI 编排、模型生态、Agent 实验
FastAPI：把 Python AI 能力暴露成 HTTP 接口

创建 FastAPI 服务

安装依赖：

python -m pip install fastapi uvicorn pydantic

Uvicorn，中文可以理解为“Python ASGI 服务器”。

ASGI，全称是 Asynchronous Server Gateway Interface，中文一般翻译为“异步服务器网关接口”。

创建 main.py：

from fastapi import FastAPI

app = FastAPI(title="AI Service")


@app.get("/")
def health():
    return {
        "status": "ok"
    }

启动：

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

访问：

http://127.0.0.1:8000

接口文档：

http://127.0.0.1:8000/docs

定义请求响应

FastAPI 通常用 Pydantic 定义请求和响应。

Pydantic，中文可以理解为“Python 数据校验库”。

示例：

from pydantic import BaseModel, Field


class ChatRequest(BaseModel):
    message: str = Field(min_length=1)


class ChatResponse(BaseModel):
    answer: str

接口：

from fastapi import FastAPI

app = FastAPI(title="AI Service")


@app.post("/chat", response_model=ChatResponse)
def chat(request: ChatRequest):
    return ChatResponse(
        answer=f"收到问题：{request.message}"
    )

FastAPI 会自动完成：

读取 JSON 请求体
转换为 Pydantic 对象
校验字段类型
生成接口文档
校验响应结构

完整 main.py

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI(title="AI Service")


class ChatRequest(BaseModel):
    message: str = Field(min_length=1)


class ChatResponse(BaseModel):
    answer: str


@app.get("/")
def health():
    return {
        "status": "ok"
    }


@app.post("/chat", response_model=ChatResponse)
def chat(request: ChatRequest):
    return ChatResponse(
        answer=f"收到问题：{request.message}"
    )

测试：

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"什么是 FastAPI？"}'

返回：

{
  "answer": "收到问题：什么是 FastAPI？"
}

Java 调用 Python

Java 后端可以用 HTTP 调用 FastAPI。

先定义 Java 请求响应对象：

public record PythonChatRequest(String message) {
}

public record PythonChatResponse(String answer) {
}

使用 RestClient 调用：

import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;

@Service
public class PythonAiClient {

    private final RestClient restClient;

    public PythonAiClient(RestClient.Builder builder) {
        this.restClient = builder
                .baseUrl("http://127.0.0.1:8000")
                .build();
    }

    public String chat(String message) {
        PythonChatResponse response = restClient.post()
                .uri("/chat")
                .body(new PythonChatRequest(message))
                .retrieve()
                .body(PythonChatResponse.class);

        if (response == null) {
            throw new IllegalStateException("Python AI 服务无响应");
        }

        return response.answer();
    }
}

Controller 可以继续由 Java 对外提供：

@PostMapping("/api/python-chat")
public ChatResponse chat(@RequestBody ChatRequest request) {
    String answer = pythonAiClient.chat(request.message());
    return new ChatResponse(answer);
}

链路：

前端
  -> Java Spring Boot
  -> Python FastAPI
  -> Python AI 能力
  -> Java 返回前端

接口异常处理

FastAPI 可以用 HTTPException 返回明确错误。

HTTPException，中文可以理解为“HTTP 异常”。

示例：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI(title="AI Service")


class ChatRequest(BaseModel):
    message: str = Field(min_length=1)


class ChatResponse(BaseModel):
    answer: str


@app.post("/chat", response_model=ChatResponse)
def chat(request: ChatRequest):
    if "error" in request.message:
        raise HTTPException(status_code=500, detail="模拟 Python AI 服务异常")

    return ChatResponse(answer=f"收到问题：{request.message}")

非法请求体会由 FastAPI 自动返回校验错误。

比如：

{
  "message": ""
}

会触发字段校验。

统一响应格式

学习阶段可以先保持简单响应。

后面 Java 和 Python 联调时，建议统一格式。

示例：

from typing import Generic, TypeVar

from pydantic import BaseModel

T = TypeVar("T")


class ApiResponse(BaseModel, Generic[T]):
    code: str
    message: str
    data: T | None = None

聊天数据：

class ChatData(BaseModel):
    answer: str

返回：

@app.post("/chat")
def chat(request: ChatRequest) -> ApiResponse[ChatData]:
    return ApiResponse(
        code="OK",
        message="success",
        data=ChatData(answer=f"收到问题：{request.message}")
    )

统一响应格式的好处：

Java 端更好解析
错误码更清楚
日志更容易统一
后面联调更稳定

Java 调用异常处理

Java 调 Python 服务时要考虑：

Python 服务没启动
连接超时
读取超时
返回 4xx
返回 5xx
响应结构不符合预期

可以先做基础兜底：

public String chat(String message) {
    try {
        PythonChatResponse response = restClient.post()
                .uri("/chat")
                .body(new PythonChatRequest(message))
                .retrieve()
                .body(PythonChatResponse.class);

        if (response == null) {
            return "Python AI 服务无响应";
        }

        return response.answer();
    } catch (Exception e) {
        return "Python AI 服务暂时不可用";
    }
}

正式项目里不要直接吞异常。

至少要记录：

requestId
请求路径
请求耗时
错误类型
Python 服务地址

目录建议

python-fastapi-demo
├── main.py
├── requirements.txt
├── README.md
└── app
    ├── __init__.py
    ├── schemas.py
    ├── routers
    │   └── chat.py
    └── services
        └── ai_service.py

简单项目可以先只有 main.py。

后面接口多了，再拆成：

schemas：请求响应模型
routers：接口路由
services：业务逻辑
config：配置

requirements.txt

requirements.txt 用来记录 Python 依赖。

示例：

fastapi
uvicorn
pydantic
python-dotenv

安装：

python -m pip install -r requirements.txt

后面接大模型 API 时，再加入：

openai  # 通过 DashScope OpenAI 兼容接口调用 qwen3.5-flash
langchain
langgraph

常见问题

为什么要 Java 调 Python

Java 适合做稳定业务系统。

Python 适合接 AI 生态。

通过 HTTP 拆分后，两边可以各自使用适合的技术栈。

FastAPI 的 docs 页面有什么用

/docs 是自动生成的接口调试页面。

可以直接查看接口路径、请求体、响应结构，并发起测试请求。

这对 Java 调 Python 前的联调很有用。

GET 请求能不能带请求体

不建议。

FastAPI 官方也更推荐使用 POST、PUT、PATCH、DELETE 等方法发送请求体。

聊天、分类、RAG 查询这类接口一般用 POST。

Java 调 Python 要不要加超时

要加。

大模型接口可能比较慢。

Java 侧不能无限等待。

后面需要补：

连接超时
读取超时
重试
熔断
降级
调用日志

本节先把最小 HTTP 调用跑通。

练习清单

完成几件事情：

能创建 FastAPI 服务
能启动 uvicorn
能访问 /docs
能用 Pydantic 定义请求和响应
能写 /chat 接口
能用 curl 调用 FastAPI
能用 Java RestClient 调用 Python 接口
知道 Java 调 Python 要处理超时和异常

建议目录：

ai-agent-study
├── python
│   └── fastapi-ai-service
│       ├── main.py
│       ├── requirements.txt
│       └── README.md
├── java
│   └── spring-ai-chat-demo
│       └── PythonAiClient.java
└── docs
    └── python-fastapi.md

小结

本节的结论：

FastAPI 是 Java 后端接入 Python AI 能力的 HTTP 服务层，先跑通请求、响应、校验和异常处理。

最小链路：

Java Spring Boot
  -> HTTP
  -> Python FastAPI
  -> 返回 JSON
  -> Java 解析并返回前端

这一步完成后，后面 LangChain、LangGraph、RAG、Agent 都可以先放在 Python 服务里，再由 Java 调用。

参考资料

• FastAPI Tutorial
• FastAPI Request Body
• FastAPI Handling Errors
• VS Code FastAPI Tutorial