从零搭建本地大模型Agent：Ollama + FastAPI 实战指南

引言随着AI技术的爆发云端大模型API的调用成本不断攀升同时数据隐私问题也日益受到关注。越来越多的开发者开始将目光投向本地化部署方案。今天我将手把手教你如何利用Ollama FastAPI在本地搭建一个具备Agent能力的AI助手让它能够自主调用工具、执行任务彻底告别云端依赖。Ollama是一款极简的本地大模型管理工具它封装了复杂的模型下载、GPU加速和推理过程让开发者只需一条命令就能在本地运行Llama、Qwen、DeepSeek等主流模型。FastAPI则是构建高性能API的利器可以帮助我们将模型能力快速封装成REST服务。二者结合就能打造一个完全本地化、可扩展、具备Agent能力的AI应用系统。为什么需要Agent普通的大模型只能被动回答用户问题而Agent智能体能够自主判断用户意图、调用外部工具、执行多步骤任务。例如“帮我在北京订一间今晚的酒店” → Agent自动搜索酒店、比较价格、完成预订。2026年4月最新更新Ollama v0.21.0已正式发布新增Hermes Agent联动、Copilot CLI集成和多项性能修复本地Agent体验大幅提升。v0.18.3版本更是实现了VS Code原生集成一行命令即可在IDE中调用本地模型。目录一、环境搭建与Ollama部署二、模型下载与基础对话三、FastAPI封装REST接口四、Agent工具调用实战五、进阶优化与避坑指南六、总结一、环境搭建与Ollama部署1.1 安装Ollama访问 Ollama官网 下载对应操作系统的安装包双击安装即可。# Windows: 双击 OllamaSetup.exe 安装# macOS: brew install ollama# Linux: curl https://ollama.com/install.sh | sh验证安装ollama--version1.2 路径迁移可选推荐Ollama默认安装在C盘Windows模型也会存储在C盘。如果C盘空间紧张建议迁移到其他盘符。打开任务管理器结束Ollama进程将C:\Users\用户名\.ollama整个文件夹剪切到目标路径如D:\AIWorld\.ollama新增系统环境变量OLLAMA_MODELS变量值设为D:\AIWorld\.ollama\models重新启动Ollama小提示迁移后首次启动会重新加载已有模型无需重新下载。二、模型下载与基础对话2.1 拉取模型Ollama官方模型库支持Qwen、DeepSeek、Llama、Mistral等主流模型。本文以轻量高效的Qwen2.5:7B为例。# 拉取模型约4GB取决于网速ollama pull qwen2.5:7b# 查看已下载的模型列表ollama list# 直接运行对话ollama run qwen2.5:7b2.2 测试对话运行ollama run qwen2.5:7b后可以直接在终端中与模型对话输入exit退出。截图示例此处插入终端对话截图模型正常运行后的对话界面输入问题模型会生成回复三、FastAPI封装REST接口3.1 安装依赖pipinstallfastapi uvicorn requests pydantic3.2 基础API封装代码创建main.py编写最简API接口importrequestsfromfastapiimportFastAPIfrompydanticimportBaseModel appFastAPI(title本地大模型API)classChatRequest(BaseModel):prompt:strmodel:strqwen2.5:7bstream:boolFalseapp.post(/chat)defchat(request:ChatRequest):对话接口urlhttp://localhost:11434/api/generatedata{model:request.model,prompt:request.prompt,stream:request.stream}responserequests.post(url,jsondata)ifresponse.status_code200:return{response:response.json()[response]}else:return{error:f请求失败:{response.text}}3.3 启动服务uvicorn main:app--host0.0.0.0--port8000--reload访问http://localhost:8000/docs即可看到Swagger交互式文档在线测试API。截图示例FastAPI自动生成的API文档界面可以在这里直接测试接口四、Agent工具调用实战这是文章的核心部分。我们将让大模型具备自主调用外部工具的能力——当用户需要查询实时信息时Agent会主动调用天气API并返回结果。4.1 工具调用的核心原理Ollama从v0.18.3版本开始优化了工具调用的解析能力并支持流式工具调用。其流程是用户发送请求同时告诉模型可用的工具列表模型判断是否需要调用工具如需调用则返回tool_calls开发者执行工具函数将结果返回给模型模型根据工具结果生成最终回复4.2 完整Agent代码创建agent.pyimportrequestsimportjsonfromfastapiimportFastAPIfrompydanticimportBaseModelfromtypingimportList,Dict,Any appFastAPI(title本地AI Agent)# 定义可用工具 defget_current_weather(location:str,unit:strcelsius)-str:获取指定位置的天气模拟# 实际应用中可调用真实天气APIreturnf{location}的天气晴朗温度25{unit}defcalculate(expression:str)-str:计算数学表达式try:returnstr(eval(expression))except:return计算错误# 工具注册表TOOLS{get_current_weather:get_current_weather,calculate:calculate,}# 工具Schema告诉模型如何调用TOOLS_SCHEMA[{type:function,function:{name:get_current_weather,description:获取指定位置的天气,parameters:{type:object,properties:{location:{type:string,description:城市名},unit:{type:string,enum:[celsius,fahrenheit]}},required:[location]}}},{type:function,function:{name:calculate,description:计算数学表达式,parameters:{type:object,properties:{expression:{type:string,description:数学表达式}},required:[expression]}}}]classAgentRequest(BaseModel):prompt:strmodel:strqwen2.5:7bdefcall_ollama_with_tools(prompt:str,model:str):调用Ollama并处理工具调用urlhttp://localhost:11434/api/chatmessages[{role:user,content:prompt}]# 第一次请求模型决定是否调用工具payload{model:model,messages:messages,tools:TOOLS_SCHEMA,stream:False}responserequests.post(url,jsonpayload)ifresponse.status_code!200:returnfAPI错误:{response.text}resultresponse.json()messageresult.get(message,{})# 检查是否有工具调用tool_callsmessage.get(tool_calls,[])iftool_calls:# 执行工具调用fortool_callintool_calls:func_nametool_call[function][name]argumentsjson.loads(tool_call[function][arguments])iffunc_nameinTOOLS:tool_resultTOOLS[func_name](**arguments)# 将工具结果添加到对话中messages.append(message)messages.append({role:tool,content:tool_result,tool_call_id:tool_call.get(id,unknown)})# 第二次请求模型根据工具结果生成最终回答final_payload{model:model,messages:messages,stream:False}final_responserequests.post(url,jsonfinal_payload)returnfinal_response.json()[message][content]else:# 无工具调用直接返回returnmessage.get(content,)app.post(/agent)asyncdefagent_chat(request:AgentRequest):Agent对话接口responsecall_ollama_with_tools(request.prompt,request.model)return{response:response}if__name____main__:importuvicorn uvicorn.run(app,host0.0.0.0,port8000)4.3 测试Agentpython agent.py测试1工具调用天气查询curl-XPOST http://localhost:8000/agent\-HContent-Type: application/json\-d{prompt: 深圳今天天气怎么样}测试2工具调用数学计算curl-XPOST http://localhost:8000/agent\-HContent-Type: application/json\-d{prompt: 帮我计算 123 * 456 等于多少}测试3普通问答curl-XPOST http://localhost:8000/agent\-HContent-Type: application/json\-d{prompt: 介绍一下人工智能}截图示例这里推荐使用Postman 或 Apifox 等图形化工具工具调用成功后模型返回的包含计算结果的回复4.4 LangChain Ollama Agent更强大如果你需要更复杂的Agent能力可以使用LangChain框架。首先安装依赖pipinstalllangchain langchain-communityfromlangchain_community.llmsimportOllamafromlangchain.agentsimportinitialize_agent,Toolfromlangchain.agentsimportAgentType# 初始化本地模型llmOllama(modelqwen2.5:7b)# 定义工具tools[Tool(name天气查询,funcget_current_weather,description查询城市天气),Tool(name计算器,funccalculate,description数学计算)]# 初始化Agentagentinitialize_agent(tools,llm,agentAgentType.ZERO_SHOT_REACT_DESCRIPTION,verboseTrue)# 执行resultagent.run(深圳今天天气怎么样)print(result)五、进阶优化与避坑指南5.1 GPU加速配置默认情况下Ollama会使用CPU运行。如果需要GPU加速确保NVIDIA驱动已安装然后使用以下命令启动# Windows: 确保NVIDIA CUDA环境已配置ollama run qwen2.5:7b --num-gpu15.2 修改默认端口Ollama默认使用11434端口如需修改# Windows (PowerShell)$env:OLLAMA_HOST0.0.0.0:11435ollama serve# Linux/macOSexportOLLAMA_HOST0.0.0.0:11435ollama serve5.3 模型下载加速如果模型下载缓慢可以使用代理# Windows (PowerShell)$env:HTTP_PROXYhttp://127.0.0.1:7890ollama pull qwen2.5:7b# Linux/macOSexportHTTP_PROXYhttp://127.0.0.1:7890 ollama pull qwen2.5:7b5.4 常见错误及解决方案错误原因解决方案connection refusedOllama服务未启动确保ollama serve在后台运行no model found模型未下载执行ollama pull [model_name]out of memory显存/内存不足使用更小的模型如qwen2.5:1.5btool call not working模型不支持工具调用Qwen、Llama 3.1、DeepSeek等均支持5.5 性能优化建议使用4-bit量化模型qwen2.5:7b-q4占用约4GB显存质量损失极小合理设置上下文长度--num-ctx 2048监控资源使用ollama ps查看运行中的模型六、总结本文从零开始带领大家完成了以下工作✅ 部署Ollama本地大模型运行环境✅ 下载并测试Qwen2.5-7B模型✅ 使用FastAPI封装REST接口✅ 实现Agent工具调用让大模型能够自主执行任务技术架构总览用户请求 → FastAPI → Ollama API → 本地模型推理 → 工具调用判断 → 执行工具 → 返回结果后续扩展方向集成更多工具如搜索引擎、数据库查询、文件操作等构建RAG知识库结合Chroma向量数据库让模型回答私有文档问题开发Web前端使用React/Next.js构建聊天界面VS Code原生集成Ollama v0.18.3已支持一行命令集成到IDE参考资料Ollama官方文档FastAPI官方文档Qwen模型库互动提问你在本地部署过程中遇到了什么问题欢迎在评论区留言交流本文代码已上传至GitHub需要的朋友可以私信获取。如果觉得有用记得点赞收藏哦⭐