最近看到一条挺有感触的消息欧洲人即将发现 AI 到底有多深入地嵌在自己的日常生活里。配送路线、银行风控、智能客服、视频推荐、甚至邮件自动分类背后都有一层又一层的模型在工作。作为一个后端开发者我的第一反应不是“AI 真厉害”而是“这些能力到底是怎么稳定跑起来的”。用户看到的是魔法开发者看到的是工程。比如我最近在做的 AI 应用开发最大的感受就是模型能力只是最外层真正决定体验的是提示词设计、Agent 编排、工具调用、模型部署与异常兜底。本文会从“AI 渗透生活”的现象切入整理一份覆盖 AI 应用开发、AI Agent 构建和 AI 模型部署的完整实战教程包含可运行的 Python/Java 示例、配置片段和常见报错排查思路。不管你只是想入门 AI 开发还是准备把 Agent 接入后端项目都可以直接参考这套流程。1. 背景与核心概念1.1 AI 是怎么进入日常生活的AI 对普通人的渗透通常不是以“对话机器人”的形式出现的而是藏在产品体验背后。比如你在外卖平台下单系统会预测配送时间在视频平台刷内容推荐系统决定你看到什么在银行转账时风控模型会标记可疑交易在电商平台购物售前客服可能已经是 AI 助手。这些场景的共同特点是用户在无感知的状态下享受 AI 带来的效率但并不知道模型在哪个环节、输出了什么、出错时如何兜底。对开发者来说这意味着一个新的能力要求不仅要会调用模型 API还要理解如何把模型的输出对接到业务流程里如何控制不确定性如何在模型“胡说八道”时不让用户看到错误结果。这就是 AI 应用开发和传统后端开发的本质区别。1.2 从 AI 能力到 AI 应用中间的工程差距很多初学者以为“接入大模型 做 AI 应用”其实并不完全正确。模型本身解决的是“生成”问题比如根据一段输入生成文本、总结摘要、提取信息或生成代码。但落到一个真实应用里我们还需要解决提示词的组织和版本管理上下文长度的控制模型输出的结构化解析调用失败时的重试和降级策略多步任务的拆解与工具调用成本和延迟的平衡日志、监控和评估反馈。这一整套链路才是 AI 工程实践的重点。我习惯把它分成三层来看层级核心任务常见技术应用层与业务结合提供接口Spring Boot、FastAPI编排层拆解任务、调用工具、管理状态LangChain、LangGraph模型层提供生成能力OpenAI 兼容 API、开源模型当用户说“AI 已经深入生活”时技术人应该关注的其实是这三层如何协作。1.3 为什么 AI Agent 开发是当前重点相比单纯“调用一次大模型”AI Agent 是一套更完整的自动化链路。Agent 不仅能回答问题还能根据任务目标主动调用工具、检索信息、执行动作并在多次循环中修正结果。典型工作场景包括自动查询订单状态并生成回复根据用户描述自动创建 Jira 任务分析日志文件并输出故障摘要联网搜索资料并整理成周报调用内部 API 完成业务流程操作。这些场景把 AI 从“聊天玩具”变成了“数字员工”也正是目前企业落地最活跃的方向。2. 环境准备与版本说明在开始实战之前先把环境准备好。本文示例以常见环境为例重点演示配置思路版本需要根据你的项目实际情况调整。2.1 基础环境说明操作系统macOS / Linux / WindowsWindows 推荐使用 PowerShell 或 Git BashPython 版本3.10 及以上本文示例基于 Python 3.10Java 版本JDK 17如果使用 Spring AI 示例包管理工具pip 或 poetry构建工具MavenJava 项目IDE推荐 PyCharm、IntelliJ IDEA 或 Visual Studio Code。2.2 大模型 API 准备本文的示例会调用 OpenAI 兼容格式的大模型 API。你可以根据实际情况选择国内云厂商提供的模型服务开源模型自建推理服务自有大模型网关。无论选择哪种核心逻辑都是发送 HTTP 请求到接口携带模型名称、消息列表和参数接收模型生成的文本。建议在环境变量中保存 API Key不要硬编码到代码里export LLM_API_KEYyour_api_key_here export LLM_BASE_URLhttps://your-api-endpoint/v1 export LLM_MODEL_NAMEyour-model-name2.3 项目目录规划为了让代码结构清晰建议按下面的目录组织项目ai-assistant/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 服务入口 │ ├── llm.py # 大语言模型调用封装 │ ├── agent.py # Agent 工作流 │ └── tools.py # 工具函数定义 ├── spring-demo/ │ ├── pom.xml # Maven 配置 │ └── src/main/java/.../SpringAiDemoApplication.java ├── requirements.txt └── .env.example3. 核心原理拆解3.1 大模型应用的基础链路一个最基本的 AI 应用本质上是一条请求链路用户输入问题应用组装系统提示词和用户消息调用大模型 API模型返回文本应用解析文本并返回给用户。下面是最简化的调用代码# app/llm.py import os from openai import OpenAI client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), ) def chat(messages, modelNone): response client.chat.completions.create( modelmodel or os.getenv(LLM_MODEL_NAME), messagesmessages, temperature0.3, ) return response.choices[0].message.content这里有几个细节messages是标准消息列表包含system、user、assistant三种角色temperature控制随机性业务场景一般设低一点base_url可以指向任何 OpenAI 兼容服务。3.2 AI Agent从“回答问题”到“完成任务”Agent 的关键不是“生成”而是“循环”。一个典型的 Agent 工作流程可以拆成下面几步用户给出目标Agent 把目标拆成子任务判断当前子任务是否需要调用工具如果需要调用工具获取结果把工具结果填回上下文判断是否继续执行直到认为任务完成。这个“判断—执行—观察—再判断”的循环是 Agent 的灵魂。我用 LangGraph 实现过几个 Agent 原型整体思路比较清晰。LangGraph 核心概念包括StateGraph定义状态流转图State跨节点传递的数据Node每个处理步骤ToolNode工具调用节点。下面是一个简单的 LangGraph Agent 示例思路# app/agent.py from langgraph.graph import StateGraph, END from typing import TypedDict, List class AgentState(TypedDict): messages: List[dict] def call_model(state: AgentState): # 调用模型生成下一步动作 return {messages: [{role: assistant, content: 调用工具}]} def run_tool(state: AgentState): # 执行工具并返回结果 return {messages: [{role: tool, content: 工具执行结果}]} graph StateGraph(AgentState) graph.add_node(model, call_model) graph.add_node(tool, run_tool) graph.set_entry_point(model) graph.add_edge(model, tool) graph.add_edge(tool, END) app graph.compile()注意这只是一个最小演示。真实项目中还需要管理最大循环次数、错误重试、上下文压缩等逻辑。3.3 模型部署API 调用和自建推理的区别不是所有场景都适合直接调用云端 API。当业务要求数据不出内网、延迟可控或成本可预测时就需要自建模型部署。常见方案使用 FastAPI 封装开源模型推理服务使用 vLLM、TGI 等推理框架提供高性能接口将模型转换为 ONNX 格式部署在 CPU/GPU 服务上。自建推理服务时最重要的是保持 API 协议兼容这样上层应用可以无缝切换# 一个简化的模型推理服务 from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class ChatRequest(BaseModel): messages: list max_tokens: int 512 class ChatResponse(BaseModel): choices: list app.post(/v1/chat/completions, response_modelChatResponse) def chat_completions(req: ChatRequest): # 这里替换为实际模型推理逻辑 content 模拟模型输出 return ChatResponse(choices[{message: {role: assistant, content: content}}])统一协议的好处是上层 Agent 不需要关心底层到底是云端 API 还是自建模型。4. 完整实战搭建一个个人 AI 工作助手下面我们来做一个综合性的小项目一个“个人 AI 工作助手”。这个助手可以处理用户请求遇到需要查询当前时间、计算、查天气等场景时调用对应工具最终返回结构化的结果。这个项目会覆盖AI 应用开发的项目结构设计AI Agent 的工具调用编排Spring AI 的接入方式FastAPI 对外提供接口模型部署与本地联调。4.1 功能需求与设计需求支持普通问答支持“当前时间”查询工具支持简单的四则运算工具当模型判断需要工具时自动调用并返回结果提供 HTTP 接口给前端或其他服务调用。整体流程用户请求进入 FastAPIAgent 分析请求决定是否调用工具执行工具函数把工具结果结合原始问题生成最终回复。4.2 项目依赖fastapi0.115.6 uvicorn0.34.0 openai1.59.6 langgraph0.2.60 langchain-openai0.2.14 pydantic2.10.4 python-dotenv1.0.1安装pip install -r requirements.txt4.3 定义工具函数工具函数不复杂重点是让 Agent 能够识别、调用并理解返回值。# app/tools.py import datetime def get_current_time() - str: 获取当前日期和时间 return datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) def calculator(expression: str) - float: 执行简单的四则运算expression 例如 1 2 * 3 # 生产环境不要直接用 eval这里仅做演示 return eval(expression, {__builtins__: {}}, {}) TOOLS [ { type: function, function: { name: get_current_time, description: 获取当前日期和时间, parameters: { type: object, properties: {}, required: [], }, }, }, { type: function, function: { name: calculator, description: 执行简单的四则运算, parameters: { type: object, properties: { expression: { type: string, description: 数学表达式例如 1 2 * 3, } }, required: [expression], }, }, }, ] TOOL_MAP { get_current_time: get_current_time, calculator: lambda args: calculator(args[expression]), }这里需要注意eval在真实生产环境有安全风险只适合本地演示。实际项目中建议使用ast模块或专门的表达式计算库。4.4 实现 Agent 工具调用逻辑接下来是核心部分让模型决定是否调用工具并在模型返回工具调用请求时执行对应函数。# app/agent.py import json from .llm import chat from .tools import TOOLS, TOOL_MAP def run_agent(user_input: str) - str: messages [ {role: system, content: 你是一个智能工作助手。如果需要获取实时信息请调用对应工具。}, {role: user, content: user_input}, ] # 第一轮请求带工具定义 response chat_with_tools(messages) # 如果模型要求调用工具 if response.get(tool_calls): tool_calls response[tool_calls] messages.append({ role: assistant, content: response.get(content) or , tool_calls: tool_calls, }) for tool_call in tool_calls: fn_name tool_call[function][name] fn_args json.loads(tool_call[function][arguments]) fn_result TOOL_MAP[fn_name](fn_args) messages.append({ role: tool, tool_call_id: tool_call[id], content: json.dumps({result: fn_result}, ensure_asciiFalse), }) # 第二轮请求把工具结果交给模型生成最终回答 final_response chat_with_tools(messages) return final_response.get(content, ) return response.get(content, ) def chat_with_tools(messages): # 这里直接调用 openai 客户端并传入 tools import os from openai import OpenAI client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), ) response client.chat.completions.create( modelos.getenv(LLM_MODEL_NAME), messagesmessages, toolsTOOLS, tool_choiceauto, temperature0.3, ) message response.choices[0].message result {content: message.content} if hasattr(message, tool_calls) and message.tool_calls: result[tool_calls] [ { id: tc.id, type: tc.type, function: { name: tc.function.name, arguments: tc.function.arguments, }, } for tc in message.tool_calls ] return result解释一下工具调用流程第一次把用户消息和工具列表一起发给模型模型返回tool_calls表示“我要调用这些工具”我们把工具调用结果以roletool的方式追回到消息列表再次请求模型让它基于工具结果生成最终回复。这就是 Agent 里的“函数调用”模式。4.5 用 FastAPI 封装 HTTP 接口有了 Agent 逻辑接下来把它暴露成 HTTP 服务。# app/main.py from fastapi import FastAPI from pydantic import BaseModel from .agent import run_agent app FastAPI(titleAI Work Assistant) class ChatRequest(BaseModel): message: str class ChatResponse(BaseModel): reply: str app.post(/api/chat, response_modelChatResponse) def chat(req: ChatRequest): reply run_agent(req.message) return ChatResponse(replyreply)启动服务uvicorn app.main:app --reload --port 8000测试请求curl -X POST http://127.0.0.1:8000/api/chat \ -H Content-Type: application/json \ -d {message: 现在几点}预期输出会类似{ reply: 当前时间是 2025-01-18 14:23:05。 }4.6 Spring AI 接入方式如果你的后端是 Java 技术栈也可以用 Spring AI 接入大模型。Spring AI 是 Spring 生态对 AI 能力的集成方案它把模型调用抽象成ChatClient等组件结合 Spring Boot 的开发习惯代码量会少很多。先看依赖配置!-- spring-demo/pom.xml -- dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency /dependencies因为 Spring AI 的版本迭代较快这里不写死版本号。你需要根据当前使用的 Spring Boot 版本到官方文档确认兼容版本。配置文件# spring-demo/src/main/resources/application.properties spring.ai.openai.api-key${LLM_API_KEY} spring.ai.openai.base-url${LLM_BASE_URL} spring.ai.model.chatyour-model-name然后写一个简单的调用接口// spring-demo/src/main/java/com/example/demo/ChatController.java package com.example.demo; import org.springframework.ai.chat.ChatClient; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/api/spring) public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient chatClient) { this.chatClient chatClient; } PostMapping(/chat) public String chat(RequestBody String message) { return chatClient.call(message); } }Spring AI 的最大好处是它把模型接入变成了 Spring Boot 风格的自动配置团队里 Java 背景的同事可以很快上手。使用 Spring AI 时需要注意不同版本的 API 变动比较大比如ChatClient的包路径、方法名在不同版本中可能不同。如果你项目里遇到import报错建议先到对应版本的官方示例中确认写法。4.7 本地模型部署联调有些环境无法连接外部 API或者数据隐私要求比较高需要在本地部署一个模型服务。这里以一个简单的本地推理接口为例说明如何把服务接入上面的 Agent。我们可以用 FastAPI 起一个本地 OpenAI 兼容接口# local_model_server.py from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Message(BaseModel): role: str content: str class ChatRequest(BaseModel): model: str local-model messages: list[Message] [] tools: list [] tool_choice: str auto temperature: float 0.3 class Choice(BaseModel): message: dict class ChatResponse(BaseModel): choices: list[Choice] app.post(/v1/chat/completions) def chat(req: ChatRequest): # 这里实际上是模型推理逻辑 # 为了演示如果消息里有“工具调用”关键词就返回 tool_calls last_content req.messages[-1].content if req.messages else if 工具 in last_content and req.tools: return ChatResponse( choices[Choice( message{ role: assistant, content: None, tool_calls: [ { id: call_001, type: function, function: { name: get_current_time, arguments: {}, }, } ], } )] ) return ChatResponse( choices[Choice( message{role: assistant, content: 本地模型返回 last_content} )] ) if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port9997)启动本地模型服务后把环境变量指向它export LLM_BASE_URLhttp://127.0.0.1:9997/v1 export LLM_MODEL_NAMElocal-model这样上层 Agent 完全不需要改动就能切换到本地模型。真实场景中这一步通常会用 vLLM 或推理框架替换但接口协议保持一致。5. 常见问题与排查思路在开发 AI 应用和 Agent 的过程中下面这些坑比较常见列出来供你参考。问题现象常见原因解决思路模型不调用工具工具描述不清晰或模型不支持 function calling优化工具描述确认模型支持工具调用工具调用后结果不对工具参数解析错误打印arguments原始 JSON检查字段名返回值格式不稳定模型输出包含多余文本使用 JSON 模式或增加输出解析与校验上下文越来越长Agent 多轮循环累积历史消息引入上下文裁剪、摘要压缩API 请求超时大模型响应慢或网络连接不稳定增加超时时间、重试机制、备用模型切换生产环境报 429触发限流加请求队列、指数退避重试、提高限流配额部署后中文字符乱码编码问题确认终端和 HTTP 响应使用 UTF-8CPU 推理太慢模型参数量大硬件资源不足降低模型规模使用量化或切换到 GPU排查建议按照“先看请求再看响应最后看代码”的顺序打印请求的 messages 和 tools确认参数是否正确打印模型的原始返回值确认工具调用是否触发打印工具函数的执行结果确认数据是否正确最后再确认是 Agent 编排问题还是模型能力问题。6. 最佳实践与工程建议6.1 提示词与上下文管理提示词不是一次性写好的建议按版本管理。系统提示词、工具定义、示例消息都应该纳入 Git 管理方便回溯和对比效果。上下文管理方面我一般遵循下面几个原则系统提示词放在最前面且尽量精简工具调用结果不要全量塞进上下文只保留结构化摘要对连续多轮对话要做消息压缩或滑动窗口对 Agent 的循环次数设置上限默认 5 次以内。6.2 工具调用安全与权限当 Agent 能调用工具时安全问题会成倍放大。工具函数本质上是一个可以被模型自动触发的“API”必须像对待敏感接口一样对待它。建议如下工具函数只暴露最小权限对涉及写操作的函数增加审批流程所有工具调用记录日志便于审计对工具参数做严格校验不信任模型输出涉及用户隐私数据时先脱敏再传入上下文。尤其要注意不要让 Agent 直接执行eval、拼接 SQL、调用删除接口除非你清楚风险并已经做了充分防护。6.3 模型部署与成本控制模型部署不只是“把模型跑起来”还要考虑成本和稳定性。成本控制方面短文本任务用轻量模型复杂推理才用大模型设置 token 使用上限防止接口异常造成费用超标对缓存命中率高的请求增加一层语义缓存批量任务使用异步处理避免阻塞主流程。稳定性方面至少配置两个模型来源一个主用、一个备用增加健康检查和降级逻辑对部署服务做容量规划不要只看延迟。6.4 日志、监控与可观测性AI 应用的失败模式比传统接口复杂因为“回答不对”不是一种异常。所以日志记录非常重要。推荐至少记录以下信息请求 ID 和用户会话 ID完整 messages 序列模型返回的原始内容工具调用名称、参数和返回值耗时和 token 消耗最终返回给用户的文本。有了这些日志当线上用户反馈“回答很奇怪”时我们才能快速定位是提示词问题、工具问题还是模型问题。6.5 数据隐私与合规AI 应用经常涉及用户数据在开发阶段就要考虑数据隐私边界。建议遵循最小化原则尽量不把原始敏感数据直接发送给模型必须先对数据进行脱敏或匿名化在服务内部增加敏感词和私域数据过滤为不同业务场景划分不同的 API Key 和权限遵守所在地区的数据保护法规并做好用户告知和授权。6.6 测试与评估AI 应用不能只靠“感觉回答不错”。建议准备一套评估数据集包含期望回答的关键信息点然后定期回归测试。简单做法准备 20-50 个测试用例每次修改提示词或工具后跑一遍测试集按“答案是否包含关键词”“工具调用是否正确”等规则评分比较不同版本的得分决定是否上线。有条件的话可以把模型回答交给更强模型做打分评估形成自动化评估链路。7. 总结与学习路线这篇文章从 AI 渗透日常生活的现象出发完整拆解了 AI 应用开发和 AI 工程实践的核心链路。我们亲手实现了一个带工具调用能力的个人 AI 工作助手覆盖了 FastAPI 接口封装、OpenAI 兼容 API 的接入、LangGraph 的 Agent 示例以及 Spring AI 的 Java 接入方式。最后整理了常见的报错场景、工具调用的安全边界以及模型部署的成本和稳定性建议。如果你准备继续深入学习建议按下面路线推进先把“一次 API 调用的完整链路”吃透包括请求格式、响应解析、错误处理再练习“工具调用”模式让模型自动决定调哪些函数然后用 LangGraph 或类似框架搭建多步骤 Agent理解状态流转最后尝试用 vLLM 或 FastAPI 自建模型服务掌握模型部署项目中优先关注日志、权限、成本三个问题比“调得聪明”更重要。AI 开发的门槛不在于“会不会调 API”而在于能不能把不稳定的生成能力接入稳定可靠的业务系统。希望这篇文章能帮你把这条路走顺。如果工作中遇到实际问题欢迎按文中排查思路逐步定位也建议收藏起来备用。