看到有朋友留言说想了解下 FastAPI 开发 AI Agent 相关的话题，之前有玩过一段时间，奈何本机电脑配置一般，跑起来不流畅，便作罢了，但该走的路，该踩的坑也是一样没落下，最近整理了下，把代码也再跑了下，后续会逐渐分享给各位参考，今天先开个头。
你是不是也有过这种憋屈的时刻：兴致勃勃在本地跑了个大模型，问他"今天天气咋样"都能回得有模有样，可一旦想把它接进自己的 App、小程序，或者让同事调一下------整个人就卡住了？
这事儿其实可以特别简单：一个 FastAPI 服务 + 一个本地 Ollama，就能跑通一个完整的 AI Agent 接口，还能自动给你生成漂亮的 Swagger 文档。今天我就把这条捷径画出来，你跟着走一遍，差不多晚饭前就能跑起来。
🎯 本文能帮你解决的
把"本地大模型"变成"标准 HTTP API"，顺便搞清楚 Agent 最核心的骨架------ Agent = LLM + 工具 + 编排逻辑 ，而不是一上来就啃那些重框架。
你会得到一个带请求/响应校验、环境变量管理、自动生成接口文档的最小可行 Agent 后端。
🧭 内容速览
· 一个让本地 LLM"开口接客"的痛点场景
· 用餐厅点餐比喻，拆解 Agent 到底是个啥
· FastAPI + Ollama + Pydantic 的最小实战代码
· 请求生命周期：从你的问题到 Agent 那句回答
· 几个一偷懒就翻车的坑，帮你提前绕开
🔑 第一部分：那把"钥匙"到底在哪儿？
看个案例：小媛说他在本地把 Llama3 跑起来了，想给自己的客服系统加个自动回复接口。
需求不复杂：前端扔一段用户问题过来，后端问 Ollama，然后把答案送回去。她觉得这应该半小时搞定。
结果呢？她先是卡在"怎么把每次的提问包装成 API"，然后又纠结"返回的结果该用啥格式"，最后看着一堆手动拼的 JSON schema 叹了口气。
这就是典型的手里有发动机，却没给车架和轮胎。FastAPI 正好就是那套车架，帮我们把发动机（LLM）稳稳地装上去，还顺带送个仪表盘（Swagger）。
🍔 第二部分：Agent 这套"套餐"到底怎么理解
先别急着敲代码，咱们聊聊 Agent 的本质。我特别喜欢用 快餐店点餐来打比方：
👩🍳 LLM------ 就是后厨那个万能大厨，你提啥要求他都能给整出个菜。
🧰 工具 ------ 是大厨手边的锅铲、烤箱、菜刀。没有工具，他只能干聊；有了工具，他才能查天气、调数据库、执行函数。
📋 编排逻辑 ------ 是前台那张点餐流程单：先确认需求，再选择合适的工具，最后让大厨出餐，错了还要打回重做。
所以一个最简化的 Agent 接口，不是直接把用户的话丢给 Ollama 完事，而是要在代码里体现这三层。今天我们先把基础路走通，让"大厨"先能出餐，后面再加"工具"就容易了。
⚡ 第三部分：动手！从零搭一个 /chat 端点
先晒一下我们的目标------一个跑在本地、用 Swagger 就能聊天的接口。你发一段话，它回一段话，背后调的是 Ollama。
咱们的项目目录就简简单单几个文件：
├── main.py # 主服务入口
├── models.py # 请求/响应模型
├── config.py # 环境变量配置
└── pyproject.toml好，咱们先来搞定环境。 我默认你已经装好了 Ollama 并且拉取了模型，比如 llama3。然后一行命令把依赖装齐：
uv add fastapi[standard] httpx对，你没看错，连 httpx都得装，一会儿我们要用它去异步调 Ollama 的 API，这时候就别用 requests 同步请求了，一上量接口直接卡成 PPT。
接下来重点来了，定义请求和响应模型。 打开 models.py，用 Pydantic来管住进出。
我喜欢把这事儿交给 Pydantic，比手写字典强一万倍------自动校验，还能直接喂给 Swagger。
from pydantic import BaseModel
class ChatRequest(BaseModel):
message: str
class ChatResponse(BaseModel):
reply: str这里再说个容易翻车的点：模型里字段如果写成 msg 这种简写，回头对接前端的人会恨你一辈子。老老实实把可读性拉满。
然后是 config.py，咱们用 pydantic-settings 管理环境变量。这样不用把地址硬编码在代码里，随时可以通过 .env 或环境变量覆盖。
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
ollama_base_url: str = "http://localhost:11434"
model_name: str = "llama3"
class Config:
env_file = ".env"
settings = Settings()官方文档虽然默认就支持 .env，但根据以往的经验 ，一定要在根目录放一个 .env 文件，并且记得加进 .gitignore。不然某天队友的 API Key 就被你公之于众了，那场面可太尴尬。
主角来了：main.py。我们先搭个骨架，再用依赖注入把 settings 传进去，给 /chat 端点用。
from fastapi import FastAPI, Depends
from models import ChatRequest, ChatResponse
from config import Settings, settings
import httpx
app = FastAPI(title="AI Agent 接口", version="0.1.0")
def get_settings():
return settings
@app.post("/chat", response_model=ChatResponse)
async def chat(
req: ChatRequest,
config: Settings = Depends(get_settings)
):
async with httpx.AsyncClient() as client:
resp = await client.post(
f"{config.ollama_base_url}/api/generate",
json={
"model": config.model_name,
"prompt": req.message,
"stream": False
},
timeout=30.0
)
resp.raise_for_status()
data = resp.json()
return ChatResponse(reply=data["response"])你可能会问："就这？Agent 的'工具'和'编排'呢？"
别急，今天咱们先把大厨请出来。后面几篇我会慢慢给这个骨架添上"菜单"------工具调用逻辑，让它可以查天气、搜文档。
现在先跑起来，体验一下从零到一的快感。
最后啰嗦一句 ，启动命令就一行： fastapi run main.py 。
然后打开 http://localhost:8000/docs ，你会看到一个自带交互界面的 Swagger。直接在里面 Try it out 测试，看到回复的那一瞬间，你心里一定会喊一声"舒坦"。
🔁 第四部分：一个请求的完整生命周期
为了让你心里更有谱，我把整个过程拆成五步：
❶ 前端（或 Swagger）把 用户的一句话 按 ChatRequest 格式发到 /chat
❷ FastAPI 自动校验字段，不对就立刻返回 422 错误，省得垃圾数据钻进大模型
❸ 依赖注入 把 Settings 对象默默准备好，代码里直接用
❹ 用 httpx 异步调用 Ollama 的 /api/generate，把大厨喊醒
❺ Ollama 返回的 response 字段塞进 ChatResponse，Swagger 自动渲染成漂亮的 JSON 文档
你瞧，整个链路清晰得就像一条笔直的大路，每个弯拐在哪里一目了然。以后想加缓存、加日志、加工具，只要顺着这条路插进去就行。
⚠️ 注意事项与进阶思考
· 千万别在公网暴露 Ollama 的 11434 端口，这家伙默认没鉴权！
· 生产环境一定要加请求频率限制，大模型慢，分分钟把你的 FastAPI 线程池打满。
· stream: False 用着爽，但做打字机效果时记得换成流式响应，那又是另一个好玩的话题。
· 接下来我会在这个例子上逐步加上工具调用（比如用搜索引擎的 API），让 Agent 真的"动手干活"。
好啦，今天就先聊到这儿。那种亲手把模型装进接口的踏实感，真的会让人上瘾。如果你也跟着跑通了，评论区炫耀一下；如果卡在哪一步，也可留言甩过来，我拿过键盘咱们一起解决它。
担心错过后续的"加工具"、"写编排"系列？点个关注，咱们下篇见🚀。顺手点赞 + 收藏，别让这篇实战笔记沉底，说不定你的同事今晚就用上了。