每次 AI 行业出现新的融资、新的模型和新的产品形态都会引发一轮关于“AI 会不会改变世界”的讨论。但对大多数开发者来说与其关注估值和叙事不如先把一个 AI 应用从“能跑”推进到“能上线”。说到底大模型只是一套推理引擎真正决定应用价值的是模型接入、工具编排、上下文管理、异常处理、日志监控和部署运维这些工程细节。这套东西组合在一起才是一个可以长期维护的 AI 应用而不只是聊天窗口里的一次演示。这篇文章以“从零搭建一个最小 AI Agent 服务”为主线使用 FastAPI 作为 Web 框架通过 OpenAI 兼容协议接入本地模型服务实现一次完整的“用户提问 - 模型判断是否需要工具 - 程序执行工具 - 模型汇总结果”闭环。读完以后你能掌握 AI 应用开发的基本工程结构知道哪些环节容易出问题、怎么排查也清楚从学习环境到生产环境还需要补哪些能力。1. 先想清楚AI 应用和“调接口”之间差在哪里1.1 一个 AI 应用的最小组成很多人第一次接触大模型应用时觉得只要拿到 API Key调一次 Chat Completions 接口能返回文本就算完成了一个 AI 项目。这一步确实能帮你建立“模型返回结果”的基本体感但它距离一个真正的应用还有不少距离。一个可用的 AI 应用至少包含四层第一层是模型接入层。应用要能稳定地连接模型服务把模型名、接口地址、API Key、超时时间、最大 Token 数等参数统一管理起来不能散落在代码里。第二层是业务流程层。真实场景不是简单的一问一答而是需要根据用户输入判断下一步动作。比如用户问“现在几点了”你需要让模型意识到这件事需要调用时间查询工具而不是凭空编一个时间出来。第三层是工具执行层。模型本身不执行代码它只能输出“我想调用哪个工具、传什么参数”的结构化文本。真正执行工具的是你的程序要做参数校验、异常隔离、结果格式化再把执行结果回传给模型。第四层是服务与运维层。外部是以 HTTP 接口形式暴露能力内部要处理并发、日志、配置、错误重试、资源限制和部署问题。把这四层想清楚就不会把“写一个 demo”和“做一个应用”混为一谈。1.2 “能跑”和“能上线”之间的工程差距先看一张对比表能直观反映学习环境和生产环境的差别。维度学习环境生产环境模型地址写死在本机配置文件通过环境变量或配置中心注入API Key明文放在代码里密钥管理禁止进仓库错误处理失败就退出或返回空区分超时、限流、格式错误并重试日志不记或只 print记录请求 ID、模型、耗时、Token 数上下文单次请求不保存管理多轮历史并控制长度工具调用演示能跑通就行校验参数、隔离异常、防止危险操作部署本地 uvicorn 启动Docker 镜像 环境隔离 进程守护性能单用户自测控制并发、设置超时、加缓存这张表背后有一个核心结论模型只是应用的一部分工程能力决定应用能走多远。把基础工程结构搭好后面扩展 RAG、多模型路由、Agent 编排时才不会推倒重来。2. 环境准备用本地模型跑通最小链路避免一开始就陷入网络和费用问题2.1 运行时环境与依赖为了降低复现成本示例采用 Python 3.10 以上版本Web 框架使用 FastAPI模型访问使用兼容 OpenAI Chat Completions 的客户端。模型服务优先选择本地运行的方式这样不需要提前申请外部服务也不需要担心额度问题。建议先创建独立目录和虚拟环境避免污染系统环境。mkdir ai-agent-demo cd ai-agent-demo python3 -m venv .venv source .venv/bin/activate然后创建依赖文件requirements.txt。fastapi0.115.0 uvicorn[standard]0.30.0 openai1.40.0 pydantic-settings2.4.0版本号只代表编写示例时的选择实际项目安装前建议确认当前稳定版本。安装依赖pip install -r requirements.txt2.2 起一个本地模型服务本地模型服务的方案有很多这里使用 Ollama 的 OpenAI 兼容端点。它的好处是配置简单本地跑起来之后应用层的请求方式和远程模型基本一致后续切换模型服务时改动很小。启动本地模型的常规流程是ollama pull qwen2.5 ollama serve ollama run qwen2.5pull用于下载模型serve启动本地服务run可以直接做一次对话验证。Ollama 默认监听的地址是http://localhost:11434它的 OpenAI 兼容端点通常是http://localhost:11434/v1。注意不同模型对工具调用、JSON 输出的支持能力不同。示例代码会采用“提示词约束模型输出 JSON再由程序解析”的实现方式对模型能力要求较低因此即使本地模型不支持原生的 function calling也能跑通整套流程。2.3 项目目录结构建议一开始就按模块拆分而不是把所有代码写进一个文件。示例项目结构如下ai-agent-demo/ config.py # 配置管理 tools.py # 工具定义和执行 agent.py # Agent 核心逻辑 main.py # FastAPI 服务入口 requirements.txt Dockerfile这个结构对应的分层思路是配置只负责读取参数工具只负责具体操作Agent 只负责模型交互和流程控制入口只负责 HTTP 暴露。这样每个文件的职责单一后续排查问题时定位更快。3. 实现一个可以对话的 AI Agent从普通回答到工具调用3.1 先写配置管理把模型地址、模型名、API Key 等参数统一放到config.py中。使用pydantic-settings读取环境变量方便以后在部署环境里通过.env或容器环境变量覆盖。from pydantic_settings import BaseSettings, SettingsConfigDict class Settings(BaseSettings): # Ollama 的 OpenAI 兼容端点 openai_base_url: str http://localhost:11434/v1 # Ollama 本地模式不校验 Key但字段要保留 openai_api_key: str ollama model_name: str qwen2.5 max_tokens: int 1024 temperature: float 0.7 request_timeout: float 60.0 model_config SettingsConfigDict(env_file.env, env_file_encodingutf-8) settings Settings()这样做的目的很明确模型名、端口、超时时间都属于环境相关配置一旦写死在业务代码里换环境时必须改代码容易出错。3.2 定义可执行工具工具层的价值在于让模型具备“行动能力”。示例定义两个工具一个是查询当前时间一个做简单的四则运算。from datetime import datetime from zoneinfo import ZoneInfo import ast TOOL_DESCRIPTIONS [ { name: get_current_time, description: 获取指定时区的当前时间, args: { timezone: 时区名称例如 Asia/Shanghai } }, { name: safe_calc, description: 计算一个简单的四则运算表达式, args: { expr: 数学表达式例如 17*23 } } ] def get_current_time(timezone: str) - str: try: tz ZoneInfo(timezone) except Exception: tz ZoneInfo(Asia/Shanghai) return datetime.now(tz).strftime(%Y-%m-%d %H:%M:%S %Z) def safe_calc(expr: str) - str: allowed_nodes ( ast.Expression, ast.BinOp, ast.Constant, ast.UnaryOp, ast.Add, ast.Sub, ast.Mult, ast.Div, ast.Mod, ) tree ast.parse(expr.strip(), modeeval) for node in ast.walk(tree): if not isinstance(node, allowed_nodes): raise ValueError(funsupported expression node: {type(node).__name__}) result eval(compile(tree, string, eval), {__builtins__: {}}, {}) return str(result) TOOLS { get_current_time: get_current_time, safe_calc: safe_calc, }这里强调一点不要直接在程序里用裸eval执行用户输入。safe_calc虽然仍然调用了eval但已经做了节点白名单限制并且关闭了内建函数能挡住大部分明显危险表达式。生产环境如果场景更复杂建议使用专门的表达式解析库并进一步限制数字长度、运算次数和递归深度。工具描述为什么会出现在 Python 代码里因为模型本身不知道你的程序有哪些能力。它只能通过 System Prompt 中的描述知道“有哪些工具、参数是什么、什么时候用”。所以工具描述就是模型调用工具时的“接口文档”一定要写清楚。3.3 实现 Agent 核心循环Agent 的核心循环可以分成四步组装完整消息把系统提示词、历史对话、用户问题一起发给模型。模型返回结构化 JSON可能是“我想调用某个工具”也可能是“直接回复用户”。程序解析 JSON。如果是工具调用执行工具把结果拼到消息里再发给模型。模型看到工具结果后生成最终回答。代码如下import asyncio import json import logging from openai import AsyncOpenAI from config import settings from tools import TOOLS, TOOL_DESCRIPTIONS logger logging.getLogger(agent) client AsyncOpenAI( base_urlsettings.openai_base_url, api_keysettings.openai_api_key, timeoutsettings.request_timeout, max_retries2, ) def build_system_prompt(tools_desc: list[dict]) - str: return ( 你是一个 AI 助手。你需要根据用户问题判断是否调用工具。\n 可用工具\n f{json.dumps(tools_desc, ensure_asciiFalse, indent2)}\n 如果需要调用工具只输出 JSON{\tool\: \工具名\, \args\: {}}\n 如果不需要调用工具只输出 JSON{\reply\: \回答内容\}\n 不要输出多余文字。 ) async def ask_model(messages: list[dict], temperature: float 0.0) - str: resp await client.chat.completions.create( modelsettings.model_name, messagesmessages, temperaturetemperature, max_tokenssettings.max_tokens, ) content resp.choices[0].message.content if not content: raise ValueError(model returned empty content) logger.info(model reply: %s, content) return content.strip() def parse_tool_json(content: str) - dict: text content.strip() if text.startswith(): text text.strip() if text.startswith(json): text text[4:] text text.strip() obj json.loads(text) if tool in obj and args in obj: return {type: tool, tool: obj[tool], args: obj[args]} if reply in obj: return {type: reply, content: obj[reply]} raise ValueError(funknown response format: {content}) async def run_agent(user_input: str, history: list[dict] | None None) - str: history history or [] messages [ {role: system, content: build_system_prompt(TOOL_DESCRIPTIONS)} ] messages.extend(history) messages.append({role: user, content: user_input}) for _ in range(3): content await ask_model(messages, temperature0.0) parsed parse_tool_json(content) if parsed[type] reply: return parsed[content] tool_name parsed[tool] if tool_name not in TOOLS: return f工具不存在: {tool_name} try: tool_result TOOLS[tool_name](**parsed[args]) except Exception as exc: tool_result f工具执行失败: {exc} messages.append({role: assistant, content: content}) messages.append( { role: user, content: json.dumps( {tool_result: tool_result}, ensure_asciiFalse ), } ) await asyncio.sleep(0.1) return tool call loop exceeded max iterations这里有几个关键设计。把temperature设为 0.0是为了让模型在“是否需要调用工具”的判断上尽量稳定。低温度能减少随机性但这不代表输出一定符合预期所以要保留解析和兜底逻辑。循环最多执行 3 次避免模型陷入“反复要求调用工具”的死循环。每次工具执行结果必须通过user消息回传并且要把模型上一轮的原始输出同时保留为assistant消息这样模型才能理解整个上下文脉络。如果工具执行过程中抛出异常不能让异常直接打到客户端。这里用try except把错误变成文本回传给模型由模型生成对用户的解释。这种设计比直接返回 500 更友好也让模型有机会修正自己的调用参数。3.4 暴露 HTTP 接口main.py是服务入口负责把 Agent 能力包装成 HTTP 接口。from fastapi import FastAPI from pydantic import BaseModel, Field from agent import run_agent app FastAPI() class ChatRequest(BaseModel): message: str Field(..., min_length1, description用户输入) history: list[dict] Field(default_factorylist, description多轮对话历史) class ChatResponse(BaseModel): reply: str app.post(/chat, response_modelChatResponse) async def chat(req: ChatRequest) - ChatResponse: reply await run_agent(req.message, req.history) return ChatResponse(replyreply)请求体里保留了history字段是为了支持多轮对话。前端或客户端需要自己维护历史记录避免每次请求都把无意义的旧消息重发一遍。启动服务uvicorn main:app --reload --host 0.0.0.0 --port 80003.5 验证 Agent 是否真的会调用工具启动后用curl做两个验证。第一个验证是普通问答不需要调用工具curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d {message: 你好简单介绍一下你自己, history: []}第二个验证是触发工具调用curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d {message: 当前北京时间是多少, history: []}正常时响应类似{ reply: 当前北京时间是 2025-01-08 14:32:00 CST。 }再验证一次四则运算curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d {message: 17*23 等于多少, history: []}如果 Agent 逻辑正常模型会先输出调用safe_calc的 JSON程序执行计算后把结果回传最终返回“391”或类似表述。从日志中也能看到完整链路模型第一次输出带tool字段程序执行工具后第二次输出带reply字段。这两条日志是判断 Agent 是否按预期工作的关键证据。4. 生产化改造配置、错误、日志、部署一个都不能少4.1 配置外置化学习环境里可以把模型名写死在配置文件中但生产环境不建议这么做。原因有三点一是模型服务可能在多个环境间切换测试环境用本地模型生产环境用在线服务配置必须跟随环境变化。 二是 API Key 涉及敏感信息不应进入 Git 仓库。 三是不同模型的行为差异很大有时候需要针对不同模型调整temperature、max_tokens和timeout。推荐的落地方式是使用环境变量export OPENAI_BASE_URLhttp://your-model-service/v1 export OPENAI_API_KEYyour-api-key export MODEL_NAMEyour-model-name export MAX_TOKENS2048配合pydantic-settings这些变量会自动覆盖配置文件中的默认值。容器部署时再通过容器编排工具注入这样代码仓库里永远不会出现真实密钥。4.2 错误类型和重试策略模型服务的错误不能一刀切处理。常见错误类型不同处理策略也不同。错误类型现象处理策略网络超时请求长时间无响应设置合理的超时时间最多重试 2 次限流返回 429 或速率限制错误退避重试并做并发控制服务不可用返回 5xx短时间重试短时间内失败则熔断鉴权失败返回 401/403不重试直接检查 Key 和权限模型返回空无content检查模型能力、提示词和max_tokens输出格式非法JSON 解析失败记录原始输出必要时让模型重试一次AsyncOpenAI的max_retries参数可以处理一部分临时错误但业务层仍然需要捕获异常避免某个请求的失败拖垮整个进程。最基础的做法是在ask_model外层再加一层重试逻辑并记录第一次失败的原因。也可以增加一个简单的熔断思路连续失败超过阈值时不再继续调用模型直接返回降级文案等一小段时间后再恢复。这个逻辑在真实系统中通常由独立组件完成但小型项目可以先用一个计数变量实现。4.3 日志与可观测性模型应用的日志比普通 Web 应用更关键因为模型输出是概率性的同一个问题在不同时间、不同参数下可能产生完全不同的结果。没有日志你很难判断问题是模型本身的原因还是你的 Prompt 或工具代码写错了。每个请求至少应该记录这些信息请求 ID串联整个链路。用户问题摘要方便回溯。模型名和参数model、temperature、max_tokens。每一轮模型输出判断输出格式是否正确。工具名、参数和结果判断工具调用是否符合预期。耗时和 Token 使用评估成本和性能。异常堆栈排错时最直接的信息。示例中可以在ask_model里补充 Token 统计。openaiSDK 的响应对象会包含usage字段配合日志模块输出即可。生产环境如果有多台实例还需要把日志统一采集到日志平台而不是只存在本地文件中。4.4 用 Docker 部署本地跑通后下一步就是让应用能在服务器上稳定运行。Docker 是常见的打包方式。创建DockerfileFROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8000]构建和启动docker build -t ai-agent-demo . docker run -d --name ai-agent-demo \ -p 8000:8000 \ -e OPENAI_BASE_URLhttp://your-model-service/v1 \ -e OPENAI_API_KEYyour-api-key \ -e MODEL_NAMEyour-model-name \ ai-agent-demo需要注意本地模型服务和应用如果部署在同一个 Docker 容器中要把模型服务一起打包或者通过 Docker 网络访问宿主机上的模型服务。更常见的做法是模型服务单独部署应用通过内部地址访问。5. 常见问题排查现象、原因、定位、修复5.1 模型一直返回空字符串现象接口正常响应但reply为空。可能原因模型输出了空content提示词让模型不知道该怎么回答max_tokens设置过小导致回复被截断某些模型在拒绝回答时会返回空内容。检查方式先看服务端日志中model reply这一行是否有内容。如果日志里也是空说明是模型侧返回为空如果日志里有内容但接口返回空说明是解析逻辑出问题。处理建议把max_tokens调大把temperature降低简化提示词必要时换一个对话能力更强的模型。不要用空字符串作为合法回复在ask_model中直接对空内容抛出异常触发重试或降级。5.2 模型不按约定输出 JSON现象日志里能看到模型返回了大段文字不是 JSON或者返回的role消息无法被json.loads解析。可能原因模型本身对 JSON 指令的理解能力弱提示词中给出的示例太少模型回复被 json 代码块包裹导致解析失败。检查方式把日志里模型返回的原始内容完整打印出来肉眼确认格式。重点看有没有多余文字、单引号、注释、尾逗号。处理建议在parse_tool_json中增加代码块剥离逻辑这是处理真实模型输出最实用的兼容手段。如果模型经常返回非标准 JSON可以在提示词里增加“必须输出严格的 JSON不要使用 Markdown 代码块”的明确约束并在解析失败时把错误信息回传给模型让模型修正输出。5.3 多轮对话“失忆”现象第一轮对话正常第二轮再问“我刚刚问的是什么”时模型答不上来。可能原因客户端没有把历史传给后端后端没有把历史写入messages历史消息太长被截断。检查方式看一下请求体中的history是否非空再看服务端日志里发给模型的messages是否包含全部上下文。处理建议把上一轮的用户问题和模型回复一起放入history传给run_agent。随着对话变长还需要做历史截断或摘要。简单的方法是按消息条数截断保留最近 6 到 10 条复杂但更可用的是用模型对更早的对话做摘要再拼到系统提示词中。5.4 并发上来后接口变慢现象单用户测试很快多用户同时访问时响应时间明显上升。可能原因本地模型服务串行处理请求模型 API 有速率限制后端 worker 数不足每次请求没有设置超时导致慢请求占满连接。检查方式查看模型服务日志和 Web 服务日志确认瓶颈在哪一层。压测工具可以看到 QPS 和 P95 延迟。处理建议给模型调用增加超时时间加一层本地缓存对相同问题在短时间内直接返回控制后端并发数避免模型服务被瞬间打垮部署时增加 worker 数量但要同时考虑模型服务本身的负载能力。真正的高并发场景需要引入消息队列或异步任务系统把耗时请求从 HTTP 同步链路中剥离出去。6. 最佳实践与后续扩展路线6.1 五条可以直接落地的工程建议第一系统提示词要纳入版本管理。提示词和代码一样会演化建议把build_system_prompt里的提示词抽成单独文件或配置项改动时按版本记录。第二不要直接暴露模型原始输出。对外接口要有自己的响应结构模型返回的内容必须经过格式校验、长度限制和脱敏处理避免模型输出异常内容直接透传给客户端。第三工具必须做输入校验和异常隔离。模型生成的参数不可信工具内部要做到“参数不合法就报错不影响主流程”。不要在业务代码里执行未经白名单过滤的表达式。第四每次请求都要有请求 ID。无论是日志、异常追踪还是用户反馈一个请求 ID 能把整个链路串起来。FastAPI 中可以使用中间件生成也可以让调用方传入。第五先建立回归测试集再迭代 Prompt。准备一组固定问题例如“普通问答”“需要调用计算工具”“需要调用时间工具”“模型输出格式错误”等每次修改 Prompt 后跑一遍防止旧场景回归。6.2 发布前检查清单作为一个 AI 应用发布前建议按下面这份清单逐项确认。检查项确认内容配置模型地址、Key、模型名是否通过环境变量注入超时每次模型调用是否设置了超时和重试日志请求 ID、模型输出、工具调用、Token 数是否完整记录工具工具参数是否校验异常是否隔离输出对外响应是否统一封装模型输出是否校验并发是否有限流策略后端 worker 数是否合理安全Key 是否进入仓库模型输出是否需要脱敏回滚是否保留上一个版本的镜像或发布包6.3 后续扩展方向Agent、RAG、多模型路由与评测示例实现的是一个最简单版本的 Agent模型判断、程序执行、结果回传。真实项目在此基础上可以做很多扩展。Agent 编排是第一个方向。可以把多个工具串成完整任务比如“先搜索资料再总结摘要最后生成报告”。这类场景需要引入任务拆解和状态管理常见方案是使用 LangGraph 或自研状态机。选型时不要盲目追新先看团队对生态的熟悉程度。RAG 是第二个方向。当需要回答私有知识库问题时可以先把文档切片、向量化检索到相关片段后再让模型基于片段生成回答。RAG 的关键不是“拼接一个向量库”而是切片策略、召回质量、重排序和引用溯源。多模型路由是第三个方向。不同模型在成本、速度、能力上差异很大可以按任务复杂度路由。比如简单的分类任务使用小模型复杂推理任务使用大模型。此时需要把模型接入层抽象成统一接口并记录每个请求的模型使用情况方便成本核算。评测是最容易被忽略的方向。AI 应用不能只靠“感觉变好了”建议沉淀评测集把典型问题和期望答案写下来每次改 Prompt、换模型、调参数后都跑一遍用通过率判断结果。如果团队使用 Java 技术栈可以关注 Spring AI它把模型调用、Prompt 模板、结构化输出等能力做了统一抽象适合在现有 Spring Boot 项目中集成。但无论选择什么框架核心工程问题仍然是上下文怎么管理、工具怎么编排、错误怎么处理、链路怎么追踪。6.4 给新手的下一步练习建议如果第一次接触 AI 应用开发不要急着做复杂系统按下面的顺序练习会更容易形成闭环。第一先复现本文示例跑通本地模型服务和两个工具调用。这是整个领域的最小可运行单元。第二给项目增加一个新的工具。比如本地文件搜索、时间范围计算、简单 HTTP 请求等。新增工具时你会自然体会到“工具描述写不好模型就不会用”这一现实问题。第三引入 RAG 的简化版本。准备一个几百字的文本文件做一次最简单的“检索后回答”。体验一下输入长度限制、切片和召回的基本逻辑。第四把日志和评测集补上。哪怕只在本地跑也让每次修改 Prompt 有据可查。AI 应用开发的门槛不在于“能不能调用一个大模型”而在于能不能把模型的不确定性放进一个确定性的工程框架里。模型负责理解和生成程序负责流程、校验、执行和兜底。把这套思路想清楚后续无论模型产品怎么迭代你都能快速把新能力接入到自己的应用中。