把 Python 程序变成一个服务
启动第一个 FastAPI 服务,从浏览器发送请求,观察输入校验和响应。
你在终端运行一个 Python 文件,看到结果后程序结束。网站需要另一种工作方式:程序一直等待,用户发来一次请求,就处理一次并返回结果。这样的程序叫服务。
这组实战会逐步做出一个公司资料问答工具。员工问“出差住宿报销需要哪些材料”,服务先查制度,再把原文和出处返回。资料发生变化时,我们更新数据库;不同团队使用各自的资料。
先把服务入口搭起来。第一步完成后,你会亲自在浏览器提交问题,看到服务返回 JSON。
一次请求怎样到达 Python 函数
FastAPI 帮我们把网址和 Python 函数连接起来,并检查输入。Uvicorn 是接收 HTTP 请求的服务器。浏览器访问 /health 时,Uvicorn把请求交给FastAPI,FastAPI找到对应函数,最后把函数返回的字典转换成JSON。
GET 常用于读取,POST 常用于提交数据。端口像楼里的房间号:同一台电脑可以在不同端口运行不同服务。这里使用 8010。
建立学习目录
这条实战路线使用Python 3.13。在Windows终端运行 python --version,macOS运行 python3 --version,确认输出以 Python 3.13 开头。需要安装时,按 Python官方下载页选择3.13系列;安装后重新打开终端。已安装多个版本时,创建环境的那条命令可用Windows的 py -3.13 或macOS的 python3.13 替换解释器名称,激活后统一使用 python。
打开终端,选择自己使用的系统执行一组命令。后续文件都放在这个 agentdepth-kb 文件夹中。
Windows PowerShell:
mkdir agentdepth-kb
cd agentdepth-kb
python -m venv .venv
.\.venv\Scripts\Activate.ps1如果 PowerShell 提示禁止执行脚本,先运行 Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass,再执行激活命令。这项设置随当前终端关闭而结束。
macOS / Linux:
mkdir -p agentdepth-kb
cd agentdepth-kb
python3 -m venv .venv
source .venv/bin/activate虚拟环境给这个项目准备独立的依赖。激活后,两种系统都使用 python 执行后面的命令。在新终端继续学习时,先进入这个目录,再执行对应的激活命令。
安装与保存程序
在编辑器中新建 requirements.txt,保存下面的内容:
fastapi==0.162.0
uvicorn==0.54.0
httpx==0.28.1
pytest==9.2.0安装这些依赖:
python -m pip install -r requirements.txtFastAPI负责接口,Uvicorn负责启动服务,HTTPX供后面的请求脚本使用,pytest负责测试。第一次安装需要联网。出现 No module named ... 时,在当前已激活的环境重新执行安装命令。
如果报错路径指向另一套Anaconda或Python目录,在对应命令的 python 后加 -E 再执行,例如 python -E -m pip install -r requirements.txt。它会忽略外部Python路径变量,让当前虚拟环境的包生效。
新建 hello.py:
from fastapi import FastAPI
from pydantic import BaseModel, Field
# app 保存本服务的所有接口。
app = FastAPI(title="资料问答入门")
class Question(BaseModel):
# 输入必须有 question 字段,且长度在1到200之间。
question: str = Field(min_length=1, max_length=200)
@app.get("/health")
def health():
# 健康接口帮助我们确认服务已经启动。
return {"status": "ok"}
@app.post("/echo")
def echo(body: Question):
# 去掉首尾空白,把收到的问题返回给浏览器。
return {"received": body.question.strip()}启动服务:
python -m uvicorn hello:app --host 127.0.0.1 --port 8010 --reloadhello:app 表示加载 hello.py 中的 app。--reload 让修改文件后服务自动重新加载。看到终端提示服务已启动后,保持窗口打开。
在浏览器实际发一次请求
在地址栏输入 http://127.0.0.1:8010/health,页面应显示:
{"status":"ok"}再输入 http://127.0.0.1:8010/docs。这是FastAPI根据代码自动生成的接口操作页面。展开 POST /echo,点击 Try it out,把请求体换成:
{"question":"出差住宿报销需要哪些材料?"}点击 Execute。下方响应码为 200,响应体为:
{"received":"出差住宿报销需要哪些材料?"}这次数据已经真正经过HTTP进入Python函数。返回内容现在是原问题,后面我们会让它查资料。
看清输入校验
把请求体换成 {} 再提交,响应码变为 422,错误内容指出缺少 question。把它换成 {"question":""},仍会得到 422,这次原因是长度不足。
这个检查由 Question 完成。body: Question 告诉FastAPI按照这个格式读取请求。只有校验通过,才会进入 echo 函数。排错时先读错误位置和原因,再修改输入。
| 现象 | 可以怎么查 |
|---|---|
| 浏览器提示无法连接 | 看启动窗口是否仍在运行,地址和端口是否为8010 |
| 启动提示找不到hello | 在终端运行Windows的 dir 或macOS的 ls,确认当前目录有hello.py |
| 端口被占用 | 结束自己之前启动的服务,或同时把启动命令与浏览器地址改为8011 |
| 看到404 | 核对路径是 /health、/docs 或 /echo,并在接口页面使用对应请求方法 |
完成后在启动窗口按 Ctrl+C。下一节会在同一个目录搭建知识库服务。
课后练习展开习题收起习题
练习:增加一个服务名称
把健康接口返回值增加 "service": "knowledge-base",重启服务,观察浏览器响应。再提交一个有效问题和一个缺字段请求,确认它们仍分别返回200和422。
参考修改
return {"status": "ok", "service": "knowledge-base"}这项修改只影响健康接口;请求校验仍由 Question 决定。
接口与请求体的详细用法可查阅 FastAPI官方教程。