这几年每次 WWDC 结束Siri 都会成为讨论焦点。以前大家关心的是“它能不能听懂我的口音”现在大家讨论的却是“它为什么能跨 App 完成一连串操作”。从技术演进来看Siri 的 AI 能力并不只是“模型变大”这么简单真正支持这种体验的是一整套 Server 架构、分布式推理以及本地大模型 Agent 的落地方式。本文不聊发布会上的花絮只从工程视角拆解三个问题Server 在大模型 Agent 体系里到底承担什么角色分布式推理为什么是端侧智能的重要铺垫本地大模型 Agent 要跑起来最小可复现的架构长什么样读完你会理解 Siri 类 AI 的底层设计思路也能亲手搭一个带工具调用能力的本地 Agent 示例。如果你是后端开发、AI 应用开发或正在学习本地部署大模型这篇文章会比较适合。代码会尽量保持完整你可以直接复制到本地跑通。1. WWDC 上 Siri 的 AI 升级到底在升级什么1.1 从“听懂命令”到“理解意图”早期的 Siri 本质上是“语音指令映射器”。它先把用户语音转成文字再匹配预先定义好的意图比如“设闹钟”“发短信”“查天气”。这种方式逻辑清晰但扩展性很差用户只要换一种说法系统就可能听不懂。后来 Siri 逐步引入大语言模型能力整个交互范式发生了变化系统先理解用户的真实意图再把意图拆解成多个子任务最后把子任务分配给不同的 App 或服务去完成。比如用户说“帮我看看明天下午有没有空有空的话预订一家川菜馆”这背后不再是单条指令而是涉及日历查询、地点搜索、餐厅预约等多个环节。这种变化看着只是“更智能”实际工程技术栈已经完全不同需要语义理解模块把用户输入解析成结构化任务。需要任务编排模块决定先执行哪一步、后执行哪一步。需要工具调用模块去操作日历、地图、通讯录等外部能力。需要对话上下文管理来记住用户偏好和历史状态。这其实就是一个完整的 Agent 架构。Siri 的升级方向本质上是把系统打造成一个“超级 Agent”而不只是把语音识别做得更准。1.2 为什么不能只靠端侧模型既然要大模型参与一个很自然的想法是能不能把模型直接塞进手机可以但能力边界很明显。手机端侧模型受限于内存、算力和功耗通常参数规模不大适合做摘要、分类、改写等轻量任务。可一旦遇到需要多步推理、复杂工具调用、深度语义理解的请求小模型往往力不从心。于是公开的方案中普遍采用了混合路由策略简单请求直接由端侧模型处理响应快也利于隐私保护。复杂请求会通过加密通道送往专门的 Server 集群由更大的模型负责推理。端侧模型还可以先做本地预筛只把真正需要大模型的请求发送出去。这种“端侧 Server 侧”协同的模式比单纯把所有计算丢到云端更合理。它平衡了响应速度、算力成本和隐私边界。这里的 Server 不仅仅是 Web 服务器而是专门为大模型推理建设的服务层。1.3 对普通开发者的启示很多人认为 Agent 开发就是“调用一个聊天接口再包一层提示词”真正实践后才会发现稳定性和扩展性都依赖底层架构。参考 Siri 这类系统级 AI 的做法本地大模型 Agent 也应该分成清晰的层次模型层本地部署的大模型例如千问系列。推理 Server 层把模型包装成可并发调用的 API 服务。Agent 编排层负责理解用户意图、调用工具、维护上下文。应用层最终的聊天机器人、自动化助手或任务执行脚本。很多教程只教你写第四层忽略了第二层的存在。但第二层恰恰是关键因为 Agent 要调用工具、要处理长对话、要支撑多个请求并发都需要通过 Server 层的统一入口。2. Server 在 AI 与 Agent 体系中的真正含义2.1 别一说 Server 就联想到机房在本地大模型 Agent 场景里“Server”其实可以拆成三个不同层面Server 类型职责常见实现模型推理 Server加载模型、处理推理请求、返回结果llama-server、Ollama、vLLMAgent 调度 Server接收用户请求、编排 Agent 步骤、调用工具FastAPI 服务、LangGraph、自研框架业务能力 Server提供天气、订单、数据库等外部能力HTTP API、MCP Server、微服务理解这三个层面就不会把 Agent 开发简单理解成“请求大模型 API”。比如用户问“现在几点了”如果只给大模型发送文本它可能只能给出一个不准确的回答但如果你让它调用一个工具函数把本机时间返回给它它就能准确作答。这个“工具函数”通常就放在业务能力 Server 中。2.2 模型推理 Server 解决了什么问题如果只在 Python 脚本里用 Transformers 加载模型一次性只处理一个任务很快会遇到这些问题模型加载耗时太长每次启动都要几十秒甚至更久。无法同时服务多个用户请求。缺少统一 API 格式客户端接入成本高。没有完善的并发控制显存容易溢出。模型推理 Server 的本质是把“模型进程”常驻后台然后对外提供一套标准 API。这样多个客户端或 Agent 实例可以共享同一个模型进程模型只加载一次请求按队列进入 GPU 或 CPU 推理。从效果上看这样做既能提升资源利用率也能缩短单次请求的响应时间。在本地开发环境中你可以把 Ollama 或 llama-server 当作模型推理 Server。它们的共同点是启动后监听一个本地端口并提供 OpenAI 兼容的/v1/chat/completions接口。业务代码不需要关心模型权重放在哪里只需要发送 HTTP 请求。2.3 为什么本地大模型也需要一个 Server 层很多新手刚开始做本地大模型 Agent 时喜欢在一个文件里完成所有逻辑加载模型、处理提示词、调用工具、输出结果。这种方式做演示没有问题但一旦你开始构建相对复杂的 Agent就会捉襟见肘。例如 Agent 需要支持多轮对话时上下文可能很长你不能每次都把完整历史重新拼给模型例如 Agent 的工具调用有时耗时较长你可能需要把状态保存到 Redis再例如你需要同时跑多个 Agent 实例如果它们都直接操作同一个模型进程就很容易互相阻塞。通过 Server 层可以做到API 统一无论底层模型是千问、Llama 还是别的模型客户端都用同一套接口。并发隔离Agent 任务和模型推理解耦。状态管理Server 层可以记录请求日志、统计 token 消耗。安全控制在模型前增加鉴权避免任意设备调用。所以如果你的目标是深入做 Agent而不是只写一个测试脚本第一件事不是研究各种花哨的 Agent 框架而是先把一个可靠的模型推理 Server 跑起来。3. 分布式推理从单机到端云协同的必经之路3.1 广义分布式端侧与 Server 协同“分布式推理”听起来很复杂但在 Siri 这类场景里一个最简单的广义分布式模式是用户说话端侧先做语音识别。端侧小模型判断任务复杂度。简单任务直接由手机端模型完成。复杂任务转发到 Server 集群由多台机器上的模型实例协作处理。这种跨设备的协同本身就是一种分布式计算。它把一个完整请求拆分成“哪些步骤在端侧执行、哪些步骤在 Server 执行”最终再合并结果返回给用户。3.2 狭义分布式推理大模型的横向拆分当单台机器无法装下一个模型或者单台机器的算力无法满足请求量时就需要对推理过程本身做分布式拆分。常见的几种方式如下数据并行 / 请求负载均衡多台机器各部署一个完整模型副本请求通过负载均衡分发到不同机器。适合并发请求量高、单模型可以塞进单机的场景。张量并行把神经网络中的矩阵运算切分到多张 GPU 上执行。适合单卡显存放不下完整模型的场景多张卡同时计算同一个请求的一部分。流水线并行把模型按层切分不同层运行在不同机器上。请求像流水线一样经过各层适合极大规模模型。对于普通团队和本地开发场景最常用的是第一种。如果你在公司内部有多台 GPU 机器完全可以在每台机器上部署一个本地大模型服务再在前面加一层网关按负载分发请求。3.3 局域网部署中的“轻量分布式”很多人在搜索“本地部署大模型 局域网访问”这说明大家已经不再满足于只在个人电脑上跑通一个 Demo而是想让团队或家庭局域网内的多台设备都能使用模型。实现方式并不复杂在一台性能较好的机器上启动 Ollama 或 llama-server并让服务监听局域网 IP。在客户端机器上把 API 地址指向那台服务器。如果想做高可用可以部署多台模型服务器再用 Nginx 做简单的反向代理和负载均衡。这种方式算不算分布式推理从严格定义来说这是比单机更高一层的集群部署。如果后续请求量增长你只需要增加模型服务器节点网关会自动把请求分发过去。对于绝大多数内部 Agent 场景这种轻量分布式已经完全够用。3.4 Agent 场景对推理 Server 的更高要求为什么 Agent 和普通聊天不同普通聊天通常是“用户发一条消息模型回一条消息”。Agent 则会经历多个循环模型先判断需要什么工具代码执行工具工具结果返回给模型模型再判断下一步动作。这个过程可能持续多次给推理 Server 带来几方面压力上下文长度增长每次工具调用结果都要重新输入给模型如果工具很多或者任务很长上下文可能迅速膨胀。并发请求增加多个用户同时触发 Agent意味着后台需要同时处理多条推理链路。延迟敏感工具调度循环中任何一次推理超时都会导致整体体验失败。因此Agent 项目对推理 Server 的稳定性、并发能力和上下文窗口提出了更高要求。这也解释了为什么成熟的 Agent 架构总是强调“Server 先行”。4. 本地大模型 Agent 的关键概念4.1 Agent 是完整的执行单元可以先给一个简洁的公式Agent 大模型 工具调用 记忆 执行循环大模型负责理解和生成工具调用负责连接外部系统记忆负责保存上下文和历史决策执行循环负责让 Agent 在没有人工干预的情况下完成多步任务。这样来看Siri 就是一个典型的系统级 Agent它有大模型理解能力能调用各种 App能记住用户偏好还能在多个步骤之间循环执行。4.2 Function Calling 与工具调用Function Calling 是 Agent 最核心的能力。大模型的输出本质是文本它不能直接打开日历、查询数据库或操作文件。Function Calling 做的事情是模型根据用户问题判断需要调用什么函数。模型输出结构化参数例如函数名、参数名和参数值。业务代码接收这些参数真正执行函数。执行结果作为消息重新发送给模型。模型根据工具结果生成最终答案。在 OpenAI 兼容接口中通常使用tools参数来声明可用工具。不过本地部署 Ollama 时不同版本的 tools 支持情况会有差异。为了兼容性本文后面的示例会采用“提示词约束 JSON 输出解析”的方式实现工具调用这种方式逻辑清晰也适合理解 Agent 流程。4.3 Skill 与 Agent 的区别在 Agent 相关资料中经常出现 Skill技能和 Agent 两个词。很多人会把它们混为一谈我在这里做一个简单区分。Skill 是能力的封装。比如“查天气”“发邮件”“生成报表”都可以封装成 Skill。Skill 本身没有自主决策能力它只是等待被调用。Agent 是一个执行闭环。它由大模型驱动接收目标规划步骤调用合适的 Skill并根据执行结果调整后续行为。可以这样理解Skill 是你的工具箱Agent 是使用工具箱的工人。同一个 Skill 可以被不同类型的 Agent 使用同一个 Agent 也可以按需装配多个 Skill。维度SkillAgent是否有决策能力通常没有有大模型驱动是否独立完成任务不能能是否包含执行循环不包含包含相互关系被 Agent 调用调度 Skill 完成目标4.4 先跑通闭环再追求复杂框架目前 Agent 框架有很多但学习路径上我建议先不急着引入复杂框架。先用一个 Python 脚本把“模型 → 判断工具 → 执行工具 → 回填结果 → 输出答案”这个闭环跑通你就理解了 Agent 的本质。之后再去使用框架会容易很多。5. 本地大模型 Agent 实战搭建一个带工具调用的 Demo5.1 环境准备本次实验以常见环境为例重点演示思路操作系统Windows / macOS / Linux 均可。模型服务Ollama也可以使用 llama-server。编程语言Python 3.9 或更高版本。Python 依赖requests。如果你的电脑还没有模型服务可以先按 Ollama 官方方式安装然后执行下面的命令拉取模型。这里以千问系列模型为例具体版本名称请以你本地 Ollama 支持的列表为准# 查看本机 Ollama 中已有的模型 ollama list # 拉取一个适合在本地运行的千问系列模型 ollama pull qwen2.5:7b # 启动 Ollama 服务如果服务已经在后台运行这步会提示端口占用可跳过 ollama serve启动后用下面的命令验证服务是否正常curl http://localhost:11434/v1/models如果能看到模型列表 JSON说明模型推理 Server 已经可用。这里再补充一句如果你更习惯使用 llama.cpp 生态也可以通过 llama-server 启动服务原理相同。命令示例如下llama-server -m /path/to/qwen2.5-7b-instruct-q4_k_m.gguf --host 0.0.0.0 --port 8080不同版本的 llama-server 参数会有差异实际使用时以你本地版本的帮助信息为准。5.2 项目结构与工具函数我们创建一个本地 Agent 项目local-llm-agent结构如下local-llm-agent/ ├── agent.py ├── time_tool.py ├── weather_tool.py └── requirements.txtrequirements.txt 内容如下requeststime_tool.py 用于获取当前时间# 文件路径local-llm-agent/time_tool.py from datetime import datetime def get_current_time() - str: 返回当前本地时间用于演示工具调用。 return datetime.now().strftime(%Y-%m-%d %H:%M:%S) if __name__ __main__: print(get_current_time())weather_tool.py 用于查询天气。真实项目中应该接入天气服务 API这里先用一个模拟函数重点演示代码结构# 文件路径local-llm-agent/weather_tool.py def get_weather(city: str) - str: 模拟查询天气真实场景可替换为第三方天气 API。 # 生产环境中请在这里调用真实天气服务不要返回模拟数据 return f{city}晴气温 23 摄氏度湿度 50% if __name__ __main__: print(get_weather(上海))5.3 Agent 主循环代码agent.py 是整个 Demo 的核心。它会完成下面几步调用本地模型服务让模型判断是否调用工具。如果模型输出 JSON 格式的工具调用指令就解析指令。执行对应的 Python 工具函数。把工具结果重新发送给模型。让模型根据工具结果生成最终回答。代码如下# 文件路径local-llm-agent/agent.py import json import re import requests from time_tool import get_current_time from weather_tool import get_weather # Ollama 的 OpenAI 兼容接口地址 OLLAMA_URL http://localhost:11434/v1/chat/completions MODEL_NAME qwen2.5:7b # 工具注册表上层 Agent 根据模型输出到这里查找可执行函数 TOOL_MAP { get_current_time: get_current_time, get_weather: get_weather, } SYSTEM_PROMPT 你是一个运行在本地大模型上的智能助手。 当用户询问当前时间时你需要输出如下 JSON {tool: get_current_time, args: {}} 当用户询问某个城市天气时你需要输出如下 JSON {tool: get_weather, args: {city: 城市名}} 注意 1. 如果不需要调用工具请直接回答用户问题。 2. 如果需要调用工具只输出 JSON不要输出额外解释。 3. 无论用户用中文还是英文提问工具参数都按规定结构输出。 def call_llm(messages: list) - str: 调用本地大模型返回文本结果。 payload { model: MODEL_NAME, messages: messages, temperature: 0.2, stream: False, } response requests.post(OLLAMA_URL, jsonpayload, timeout120) response.raise_for_status() data response.json() return data[choices][0][message][content] def parse_tool_call(text: str): 从模型输出中解析 JSON 工具调用指令。 try: match re.search(r\{.*\}, text, re.DOTALL) if not match: return None return json.loads(match.group()) except json.JSONDecodeError: return None def run_agent(user_input: str) - None: Agent 主循环理解、调用工具、回填结果、输出最终答案。 messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] max_rounds 3 for _ in range(max_rounds): model_reply call_llm(messages) tool_call parse_tool_call(model_reply) # 如果模型没有返回工具调用说明它已经给出最终答案 if not tool_call or tool not in tool_call: print(Agent, model_reply) return # 根据工具名找到 Python 函数并执行 tool_name tool_call[tool] tool_args tool_call.get(args, {}) if tool_name not in TOOL_MAP: print(Agent检测到未注册工具, tool_name) return tool_func TOOL_MAP[tool_name] tool_result tool_func(**tool_args) # 把 assistant 的工具调用指令和工具执行结果追加到上下文 messages.append({role: assistant, content: model_reply}) messages.append( { role: user, content: f工具{json.dumps(tool_call, ensure_asciiFalse)}执行结果{tool_result}, } ) print(Agent超出最大执行轮次停止循环。) if __name__ __main__: # 简单演示可手动修改下面的问题 run_agent(当前时间是多少) print(---) run_agent(帮我看看上海天气如何)5.4 运行与验证在项目目录下执行python agent.py如果一切正常第一次询问时间时模型会输出类似下面的 JSON{tool: get_current_time, args: {}}Agent 主循环检测到工具调用后会执行本机时间函数把结果回传给模型最终输出类似Agent 当前时间是 2025-06-15 10:23:45。这里有几个值得注意的点prompt 中设置 temperature 为 0.2比默认值更稳定可以有效减少 JSON 输出格式漂移。正则\{.*\}的作用是容错。有些模型喜欢在 JSON 前后添加解释性内容我们只提取大括号部分。Tool 函数名和 Python 函数通过字典映射后续新增工具只要在 TOOL_MAP 中注册即可。5.5 从 Demo 到工程化上面的 Demo 可以跑通但它只是最小闭环。在实际项目中你还需要做几件重要的事情第一把 Agent 封装成 HTTP Server。使用 FastAPI 暴露一个/agent/chat接口前端、小程序或其他后台就能通过网络访问你的 Agent。第二引入请求 ID 与会话管理。每次新对话都创建一个 session_id把 messages 列表保存到 Redis这样 Agent 可以记住更早的历史。第三工具调用结果要校验。模型输出的 args 可能是非法结构因此工具执行前必须做好参数类型检查。第四可以进一步接入 MCP 等工具协议。MCP 的全称是 Model Context Protocol它定义了模型与外部工具之间的标准通信方式。在本地大模型 Agent 中接入 MCP Server 后工具扩展就不再局限于 Python 函数而是可以连接数据库、文件系统和各种业务系统。6. 常见问题与排查思路本地大模型 Agent 入门阶段遇到问题最多的环节不是 Agent 代码而是模型服务。下面整理一些常见问题。问题现象常见原因解决思路请求模型服务时连接不通Ollama 或 llama-server 没有启动或端口被改变先执行 curl 验证 API如果端口占用检查进程列表模型下载速度慢或中断网络不稳定或磁盘空间不足使用较小的模型文件清理磁盘后重新执行 pull模型返回的 JSON 格式不稳定模型参数太小或 temperature 过高降低 temperature 到 0.2 以下尝试更大规模模型用正则兜底解析Agent 工具调用后结果不正确提示词中工具参数说明不清楚在 SYSTEM_PROMPT 中补充参数示例尽量用枚举或固定格式描述请求长时间没有返回本地 CPU/GPU 推理速度慢增加 timeout 时间改用量化版本模型或更小模型llama-server 启动后进程自动退出模型路径错误、显存不足或参数版本不兼容检查启动日志确认模型文件存在减少并发数或换更小模型Ollama 服务能访问但模型生成内容为空上下文过长或模型输出被中断限制历史消息长度检查服务端日志这里我特别强调一个排查步骤遇到 Agent 问题先不要看 Agent 代码先独立测试模型服务。curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:7b, messages: [{role: user, content: 你好}], stream: false }如果模型服务本身能正常返回说明问题大概率出在 Agent 侧的提示词或上下文构造上。再比如网上经常有人搜到llama-server process has terminated with exit status之类报错。这条报错通常不是因为代码逻辑而是模型启动参数有问题比如模型路径错误、没有足够内存或显存、当前版本不支持该权重格式。解决思路是先跑一次llama-server --help查看参数再按最小命令启动不要一上来就带大量自定义配置。7. 最佳实践与工程建议7.1 模型服务独立部署建议把模型推理服务与 Agent 业务逻辑分开不要写在同一个进程里。模型服务可以长时间运行Agent 业务逻辑更新时可以独立重启两者互不干扰。如果团队内部有 GPU 服务器可以让模型服务部署在服务器上局域网内其他成员通过 API 访问。这样既节省本机算力又方便统一升级模型版本。7.2 Agent 必须有循环上限Agent 在执行过程中可能出现模型反复调用某个工具的情况。这时如果循环没有上限程序会一直运行下去浪费计算资源。在架构设计上每个 Agent 任务都应该设置最大迭代次数和时间超时。7.3 工具参数必须严格校验大模型输出 JSON 时并不会保证参数一定合法。比如天气查询工具要求 city 是字符串模型可能输出数字或者传空值。工具层在做实际调用前最好用 Pydantic 或简单 isinstance 做类型校验。对于无法确定的参数宁可让工具返回错误也不要传入外部系统执行。7.4 日志和可观测性很重要本地开发时只打印几个 print 就够用。但一旦 Agent 要接入真实业务就必须记录每次调用的消息内容、模型耗时、token 消耗、工具执行结构。否则模型一旦出现错误输出你将没有足够信息去定位。推荐日志至少包含请求输入与最终输出。中间每次工具调用 JSON。模型单次响应耗时。模型名称与上下文长度。会话 ID 或请求追踪 ID。7.5 从实际需求决定是否引入分布式很多团队刚开始做本地大模型 Agent 时往往喜欢直接规划大规模分布式推理集群。我的建议是先按需来。如果你的场景只是几个人内部使用一台机器部署好模型服务跑通 End-to-End Agent 闭环就已经足够。只有当并发量明显增加、单机吞吐到了瓶颈或者单张显卡已经放不下目标模型时再考虑增加节点、引入负载均衡或张量并行。这种“先单体、后分布式”的思路和主流系统架构演进是完全一致的。现阶段最重要的是先让 Agent 在真实业务中创造价值而不是为了技术名词去堆基础设施。7.6 技术选型时多关注兼容层本地大模型生态更新很快。今天能用的启动命令过几个月就可能调整。项目开发中建议统一使用 OpenAI 兼容 API。这样即使你把后端从 Ollama 换到 vLLM也只需要修改服务地址和模型名Agent 逻辑基本不需要改动。同样的道理也适用于本地大模型 Agent。选择一个生态成熟的基础模型利用统一的接口层屏蔽模型差异是控制后期维护成本的关键。本文中 ollama 承担的角色只是一个模型服务示例生产环境的模型服务端不一定非要和 Agent 代码锁死在一起。开源社区的 MCP、OpenAI 兼容接口、函数调用协议也都在快速演进值得持续关注。但不管底层的工具协议怎么变Agent 的完整闭环始终是理解意图、选择工具、执行动作、观察结果、生成答案。先把这条链路跑熟练才是本地大模型 Agent 开发最重要的一步。
本地大模型Agent实战：Server架构与工具调用详解
这几年每次 WWDC 结束Siri 都会成为讨论焦点。以前大家关心的是“它能不能听懂我的口音”现在大家讨论的却是“它为什么能跨 App 完成一连串操作”。从技术演进来看Siri 的 AI 能力并不只是“模型变大”这么简单真正支持这种体验的是一整套 Server 架构、分布式推理以及本地大模型 Agent 的落地方式。本文不聊发布会上的花絮只从工程视角拆解三个问题Server 在大模型 Agent 体系里到底承担什么角色分布式推理为什么是端侧智能的重要铺垫本地大模型 Agent 要跑起来最小可复现的架构长什么样读完你会理解 Siri 类 AI 的底层设计思路也能亲手搭一个带工具调用能力的本地 Agent 示例。如果你是后端开发、AI 应用开发或正在学习本地部署大模型这篇文章会比较适合。代码会尽量保持完整你可以直接复制到本地跑通。1. WWDC 上 Siri 的 AI 升级到底在升级什么1.1 从“听懂命令”到“理解意图”早期的 Siri 本质上是“语音指令映射器”。它先把用户语音转成文字再匹配预先定义好的意图比如“设闹钟”“发短信”“查天气”。这种方式逻辑清晰但扩展性很差用户只要换一种说法系统就可能听不懂。后来 Siri 逐步引入大语言模型能力整个交互范式发生了变化系统先理解用户的真实意图再把意图拆解成多个子任务最后把子任务分配给不同的 App 或服务去完成。比如用户说“帮我看看明天下午有没有空有空的话预订一家川菜馆”这背后不再是单条指令而是涉及日历查询、地点搜索、餐厅预约等多个环节。这种变化看着只是“更智能”实际工程技术栈已经完全不同需要语义理解模块把用户输入解析成结构化任务。需要任务编排模块决定先执行哪一步、后执行哪一步。需要工具调用模块去操作日历、地图、通讯录等外部能力。需要对话上下文管理来记住用户偏好和历史状态。这其实就是一个完整的 Agent 架构。Siri 的升级方向本质上是把系统打造成一个“超级 Agent”而不只是把语音识别做得更准。1.2 为什么不能只靠端侧模型既然要大模型参与一个很自然的想法是能不能把模型直接塞进手机可以但能力边界很明显。手机端侧模型受限于内存、算力和功耗通常参数规模不大适合做摘要、分类、改写等轻量任务。可一旦遇到需要多步推理、复杂工具调用、深度语义理解的请求小模型往往力不从心。于是公开的方案中普遍采用了混合路由策略简单请求直接由端侧模型处理响应快也利于隐私保护。复杂请求会通过加密通道送往专门的 Server 集群由更大的模型负责推理。端侧模型还可以先做本地预筛只把真正需要大模型的请求发送出去。这种“端侧 Server 侧”协同的模式比单纯把所有计算丢到云端更合理。它平衡了响应速度、算力成本和隐私边界。这里的 Server 不仅仅是 Web 服务器而是专门为大模型推理建设的服务层。1.3 对普通开发者的启示很多人认为 Agent 开发就是“调用一个聊天接口再包一层提示词”真正实践后才会发现稳定性和扩展性都依赖底层架构。参考 Siri 这类系统级 AI 的做法本地大模型 Agent 也应该分成清晰的层次模型层本地部署的大模型例如千问系列。推理 Server 层把模型包装成可并发调用的 API 服务。Agent 编排层负责理解用户意图、调用工具、维护上下文。应用层最终的聊天机器人、自动化助手或任务执行脚本。很多教程只教你写第四层忽略了第二层的存在。但第二层恰恰是关键因为 Agent 要调用工具、要处理长对话、要支撑多个请求并发都需要通过 Server 层的统一入口。2. Server 在 AI 与 Agent 体系中的真正含义2.1 别一说 Server 就联想到机房在本地大模型 Agent 场景里“Server”其实可以拆成三个不同层面Server 类型职责常见实现模型推理 Server加载模型、处理推理请求、返回结果llama-server、Ollama、vLLMAgent 调度 Server接收用户请求、编排 Agent 步骤、调用工具FastAPI 服务、LangGraph、自研框架业务能力 Server提供天气、订单、数据库等外部能力HTTP API、MCP Server、微服务理解这三个层面就不会把 Agent 开发简单理解成“请求大模型 API”。比如用户问“现在几点了”如果只给大模型发送文本它可能只能给出一个不准确的回答但如果你让它调用一个工具函数把本机时间返回给它它就能准确作答。这个“工具函数”通常就放在业务能力 Server 中。2.2 模型推理 Server 解决了什么问题如果只在 Python 脚本里用 Transformers 加载模型一次性只处理一个任务很快会遇到这些问题模型加载耗时太长每次启动都要几十秒甚至更久。无法同时服务多个用户请求。缺少统一 API 格式客户端接入成本高。没有完善的并发控制显存容易溢出。模型推理 Server 的本质是把“模型进程”常驻后台然后对外提供一套标准 API。这样多个客户端或 Agent 实例可以共享同一个模型进程模型只加载一次请求按队列进入 GPU 或 CPU 推理。从效果上看这样做既能提升资源利用率也能缩短单次请求的响应时间。在本地开发环境中你可以把 Ollama 或 llama-server 当作模型推理 Server。它们的共同点是启动后监听一个本地端口并提供 OpenAI 兼容的/v1/chat/completions接口。业务代码不需要关心模型权重放在哪里只需要发送 HTTP 请求。2.3 为什么本地大模型也需要一个 Server 层很多新手刚开始做本地大模型 Agent 时喜欢在一个文件里完成所有逻辑加载模型、处理提示词、调用工具、输出结果。这种方式做演示没有问题但一旦你开始构建相对复杂的 Agent就会捉襟见肘。例如 Agent 需要支持多轮对话时上下文可能很长你不能每次都把完整历史重新拼给模型例如 Agent 的工具调用有时耗时较长你可能需要把状态保存到 Redis再例如你需要同时跑多个 Agent 实例如果它们都直接操作同一个模型进程就很容易互相阻塞。通过 Server 层可以做到API 统一无论底层模型是千问、Llama 还是别的模型客户端都用同一套接口。并发隔离Agent 任务和模型推理解耦。状态管理Server 层可以记录请求日志、统计 token 消耗。安全控制在模型前增加鉴权避免任意设备调用。所以如果你的目标是深入做 Agent而不是只写一个测试脚本第一件事不是研究各种花哨的 Agent 框架而是先把一个可靠的模型推理 Server 跑起来。3. 分布式推理从单机到端云协同的必经之路3.1 广义分布式端侧与 Server 协同“分布式推理”听起来很复杂但在 Siri 这类场景里一个最简单的广义分布式模式是用户说话端侧先做语音识别。端侧小模型判断任务复杂度。简单任务直接由手机端模型完成。复杂任务转发到 Server 集群由多台机器上的模型实例协作处理。这种跨设备的协同本身就是一种分布式计算。它把一个完整请求拆分成“哪些步骤在端侧执行、哪些步骤在 Server 执行”最终再合并结果返回给用户。3.2 狭义分布式推理大模型的横向拆分当单台机器无法装下一个模型或者单台机器的算力无法满足请求量时就需要对推理过程本身做分布式拆分。常见的几种方式如下数据并行 / 请求负载均衡多台机器各部署一个完整模型副本请求通过负载均衡分发到不同机器。适合并发请求量高、单模型可以塞进单机的场景。张量并行把神经网络中的矩阵运算切分到多张 GPU 上执行。适合单卡显存放不下完整模型的场景多张卡同时计算同一个请求的一部分。流水线并行把模型按层切分不同层运行在不同机器上。请求像流水线一样经过各层适合极大规模模型。对于普通团队和本地开发场景最常用的是第一种。如果你在公司内部有多台 GPU 机器完全可以在每台机器上部署一个本地大模型服务再在前面加一层网关按负载分发请求。3.3 局域网部署中的“轻量分布式”很多人在搜索“本地部署大模型 局域网访问”这说明大家已经不再满足于只在个人电脑上跑通一个 Demo而是想让团队或家庭局域网内的多台设备都能使用模型。实现方式并不复杂在一台性能较好的机器上启动 Ollama 或 llama-server并让服务监听局域网 IP。在客户端机器上把 API 地址指向那台服务器。如果想做高可用可以部署多台模型服务器再用 Nginx 做简单的反向代理和负载均衡。这种方式算不算分布式推理从严格定义来说这是比单机更高一层的集群部署。如果后续请求量增长你只需要增加模型服务器节点网关会自动把请求分发过去。对于绝大多数内部 Agent 场景这种轻量分布式已经完全够用。3.4 Agent 场景对推理 Server 的更高要求为什么 Agent 和普通聊天不同普通聊天通常是“用户发一条消息模型回一条消息”。Agent 则会经历多个循环模型先判断需要什么工具代码执行工具工具结果返回给模型模型再判断下一步动作。这个过程可能持续多次给推理 Server 带来几方面压力上下文长度增长每次工具调用结果都要重新输入给模型如果工具很多或者任务很长上下文可能迅速膨胀。并发请求增加多个用户同时触发 Agent意味着后台需要同时处理多条推理链路。延迟敏感工具调度循环中任何一次推理超时都会导致整体体验失败。因此Agent 项目对推理 Server 的稳定性、并发能力和上下文窗口提出了更高要求。这也解释了为什么成熟的 Agent 架构总是强调“Server 先行”。4. 本地大模型 Agent 的关键概念4.1 Agent 是完整的执行单元可以先给一个简洁的公式Agent 大模型 工具调用 记忆 执行循环大模型负责理解和生成工具调用负责连接外部系统记忆负责保存上下文和历史决策执行循环负责让 Agent 在没有人工干预的情况下完成多步任务。这样来看Siri 就是一个典型的系统级 Agent它有大模型理解能力能调用各种 App能记住用户偏好还能在多个步骤之间循环执行。4.2 Function Calling 与工具调用Function Calling 是 Agent 最核心的能力。大模型的输出本质是文本它不能直接打开日历、查询数据库或操作文件。Function Calling 做的事情是模型根据用户问题判断需要调用什么函数。模型输出结构化参数例如函数名、参数名和参数值。业务代码接收这些参数真正执行函数。执行结果作为消息重新发送给模型。模型根据工具结果生成最终答案。在 OpenAI 兼容接口中通常使用tools参数来声明可用工具。不过本地部署 Ollama 时不同版本的 tools 支持情况会有差异。为了兼容性本文后面的示例会采用“提示词约束 JSON 输出解析”的方式实现工具调用这种方式逻辑清晰也适合理解 Agent 流程。4.3 Skill 与 Agent 的区别在 Agent 相关资料中经常出现 Skill技能和 Agent 两个词。很多人会把它们混为一谈我在这里做一个简单区分。Skill 是能力的封装。比如“查天气”“发邮件”“生成报表”都可以封装成 Skill。Skill 本身没有自主决策能力它只是等待被调用。Agent 是一个执行闭环。它由大模型驱动接收目标规划步骤调用合适的 Skill并根据执行结果调整后续行为。可以这样理解Skill 是你的工具箱Agent 是使用工具箱的工人。同一个 Skill 可以被不同类型的 Agent 使用同一个 Agent 也可以按需装配多个 Skill。维度SkillAgent是否有决策能力通常没有有大模型驱动是否独立完成任务不能能是否包含执行循环不包含包含相互关系被 Agent 调用调度 Skill 完成目标4.4 先跑通闭环再追求复杂框架目前 Agent 框架有很多但学习路径上我建议先不急着引入复杂框架。先用一个 Python 脚本把“模型 → 判断工具 → 执行工具 → 回填结果 → 输出答案”这个闭环跑通你就理解了 Agent 的本质。之后再去使用框架会容易很多。5. 本地大模型 Agent 实战搭建一个带工具调用的 Demo5.1 环境准备本次实验以常见环境为例重点演示思路操作系统Windows / macOS / Linux 均可。模型服务Ollama也可以使用 llama-server。编程语言Python 3.9 或更高版本。Python 依赖requests。如果你的电脑还没有模型服务可以先按 Ollama 官方方式安装然后执行下面的命令拉取模型。这里以千问系列模型为例具体版本名称请以你本地 Ollama 支持的列表为准# 查看本机 Ollama 中已有的模型 ollama list # 拉取一个适合在本地运行的千问系列模型 ollama pull qwen2.5:7b # 启动 Ollama 服务如果服务已经在后台运行这步会提示端口占用可跳过 ollama serve启动后用下面的命令验证服务是否正常curl http://localhost:11434/v1/models如果能看到模型列表 JSON说明模型推理 Server 已经可用。这里再补充一句如果你更习惯使用 llama.cpp 生态也可以通过 llama-server 启动服务原理相同。命令示例如下llama-server -m /path/to/qwen2.5-7b-instruct-q4_k_m.gguf --host 0.0.0.0 --port 8080不同版本的 llama-server 参数会有差异实际使用时以你本地版本的帮助信息为准。5.2 项目结构与工具函数我们创建一个本地 Agent 项目local-llm-agent结构如下local-llm-agent/ ├── agent.py ├── time_tool.py ├── weather_tool.py └── requirements.txtrequirements.txt 内容如下requeststime_tool.py 用于获取当前时间# 文件路径local-llm-agent/time_tool.py from datetime import datetime def get_current_time() - str: 返回当前本地时间用于演示工具调用。 return datetime.now().strftime(%Y-%m-%d %H:%M:%S) if __name__ __main__: print(get_current_time())weather_tool.py 用于查询天气。真实项目中应该接入天气服务 API这里先用一个模拟函数重点演示代码结构# 文件路径local-llm-agent/weather_tool.py def get_weather(city: str) - str: 模拟查询天气真实场景可替换为第三方天气 API。 # 生产环境中请在这里调用真实天气服务不要返回模拟数据 return f{city}晴气温 23 摄氏度湿度 50% if __name__ __main__: print(get_weather(上海))5.3 Agent 主循环代码agent.py 是整个 Demo 的核心。它会完成下面几步调用本地模型服务让模型判断是否调用工具。如果模型输出 JSON 格式的工具调用指令就解析指令。执行对应的 Python 工具函数。把工具结果重新发送给模型。让模型根据工具结果生成最终回答。代码如下# 文件路径local-llm-agent/agent.py import json import re import requests from time_tool import get_current_time from weather_tool import get_weather # Ollama 的 OpenAI 兼容接口地址 OLLAMA_URL http://localhost:11434/v1/chat/completions MODEL_NAME qwen2.5:7b # 工具注册表上层 Agent 根据模型输出到这里查找可执行函数 TOOL_MAP { get_current_time: get_current_time, get_weather: get_weather, } SYSTEM_PROMPT 你是一个运行在本地大模型上的智能助手。 当用户询问当前时间时你需要输出如下 JSON {tool: get_current_time, args: {}} 当用户询问某个城市天气时你需要输出如下 JSON {tool: get_weather, args: {city: 城市名}} 注意 1. 如果不需要调用工具请直接回答用户问题。 2. 如果需要调用工具只输出 JSON不要输出额外解释。 3. 无论用户用中文还是英文提问工具参数都按规定结构输出。 def call_llm(messages: list) - str: 调用本地大模型返回文本结果。 payload { model: MODEL_NAME, messages: messages, temperature: 0.2, stream: False, } response requests.post(OLLAMA_URL, jsonpayload, timeout120) response.raise_for_status() data response.json() return data[choices][0][message][content] def parse_tool_call(text: str): 从模型输出中解析 JSON 工具调用指令。 try: match re.search(r\{.*\}, text, re.DOTALL) if not match: return None return json.loads(match.group()) except json.JSONDecodeError: return None def run_agent(user_input: str) - None: Agent 主循环理解、调用工具、回填结果、输出最终答案。 messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] max_rounds 3 for _ in range(max_rounds): model_reply call_llm(messages) tool_call parse_tool_call(model_reply) # 如果模型没有返回工具调用说明它已经给出最终答案 if not tool_call or tool not in tool_call: print(Agent, model_reply) return # 根据工具名找到 Python 函数并执行 tool_name tool_call[tool] tool_args tool_call.get(args, {}) if tool_name not in TOOL_MAP: print(Agent检测到未注册工具, tool_name) return tool_func TOOL_MAP[tool_name] tool_result tool_func(**tool_args) # 把 assistant 的工具调用指令和工具执行结果追加到上下文 messages.append({role: assistant, content: model_reply}) messages.append( { role: user, content: f工具{json.dumps(tool_call, ensure_asciiFalse)}执行结果{tool_result}, } ) print(Agent超出最大执行轮次停止循环。) if __name__ __main__: # 简单演示可手动修改下面的问题 run_agent(当前时间是多少) print(---) run_agent(帮我看看上海天气如何)5.4 运行与验证在项目目录下执行python agent.py如果一切正常第一次询问时间时模型会输出类似下面的 JSON{tool: get_current_time, args: {}}Agent 主循环检测到工具调用后会执行本机时间函数把结果回传给模型最终输出类似Agent 当前时间是 2025-06-15 10:23:45。这里有几个值得注意的点prompt 中设置 temperature 为 0.2比默认值更稳定可以有效减少 JSON 输出格式漂移。正则\{.*\}的作用是容错。有些模型喜欢在 JSON 前后添加解释性内容我们只提取大括号部分。Tool 函数名和 Python 函数通过字典映射后续新增工具只要在 TOOL_MAP 中注册即可。5.5 从 Demo 到工程化上面的 Demo 可以跑通但它只是最小闭环。在实际项目中你还需要做几件重要的事情第一把 Agent 封装成 HTTP Server。使用 FastAPI 暴露一个/agent/chat接口前端、小程序或其他后台就能通过网络访问你的 Agent。第二引入请求 ID 与会话管理。每次新对话都创建一个 session_id把 messages 列表保存到 Redis这样 Agent 可以记住更早的历史。第三工具调用结果要校验。模型输出的 args 可能是非法结构因此工具执行前必须做好参数类型检查。第四可以进一步接入 MCP 等工具协议。MCP 的全称是 Model Context Protocol它定义了模型与外部工具之间的标准通信方式。在本地大模型 Agent 中接入 MCP Server 后工具扩展就不再局限于 Python 函数而是可以连接数据库、文件系统和各种业务系统。6. 常见问题与排查思路本地大模型 Agent 入门阶段遇到问题最多的环节不是 Agent 代码而是模型服务。下面整理一些常见问题。问题现象常见原因解决思路请求模型服务时连接不通Ollama 或 llama-server 没有启动或端口被改变先执行 curl 验证 API如果端口占用检查进程列表模型下载速度慢或中断网络不稳定或磁盘空间不足使用较小的模型文件清理磁盘后重新执行 pull模型返回的 JSON 格式不稳定模型参数太小或 temperature 过高降低 temperature 到 0.2 以下尝试更大规模模型用正则兜底解析Agent 工具调用后结果不正确提示词中工具参数说明不清楚在 SYSTEM_PROMPT 中补充参数示例尽量用枚举或固定格式描述请求长时间没有返回本地 CPU/GPU 推理速度慢增加 timeout 时间改用量化版本模型或更小模型llama-server 启动后进程自动退出模型路径错误、显存不足或参数版本不兼容检查启动日志确认模型文件存在减少并发数或换更小模型Ollama 服务能访问但模型生成内容为空上下文过长或模型输出被中断限制历史消息长度检查服务端日志这里我特别强调一个排查步骤遇到 Agent 问题先不要看 Agent 代码先独立测试模型服务。curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:7b, messages: [{role: user, content: 你好}], stream: false }如果模型服务本身能正常返回说明问题大概率出在 Agent 侧的提示词或上下文构造上。再比如网上经常有人搜到llama-server process has terminated with exit status之类报错。这条报错通常不是因为代码逻辑而是模型启动参数有问题比如模型路径错误、没有足够内存或显存、当前版本不支持该权重格式。解决思路是先跑一次llama-server --help查看参数再按最小命令启动不要一上来就带大量自定义配置。7. 最佳实践与工程建议7.1 模型服务独立部署建议把模型推理服务与 Agent 业务逻辑分开不要写在同一个进程里。模型服务可以长时间运行Agent 业务逻辑更新时可以独立重启两者互不干扰。如果团队内部有 GPU 服务器可以让模型服务部署在服务器上局域网内其他成员通过 API 访问。这样既节省本机算力又方便统一升级模型版本。7.2 Agent 必须有循环上限Agent 在执行过程中可能出现模型反复调用某个工具的情况。这时如果循环没有上限程序会一直运行下去浪费计算资源。在架构设计上每个 Agent 任务都应该设置最大迭代次数和时间超时。7.3 工具参数必须严格校验大模型输出 JSON 时并不会保证参数一定合法。比如天气查询工具要求 city 是字符串模型可能输出数字或者传空值。工具层在做实际调用前最好用 Pydantic 或简单 isinstance 做类型校验。对于无法确定的参数宁可让工具返回错误也不要传入外部系统执行。7.4 日志和可观测性很重要本地开发时只打印几个 print 就够用。但一旦 Agent 要接入真实业务就必须记录每次调用的消息内容、模型耗时、token 消耗、工具执行结构。否则模型一旦出现错误输出你将没有足够信息去定位。推荐日志至少包含请求输入与最终输出。中间每次工具调用 JSON。模型单次响应耗时。模型名称与上下文长度。会话 ID 或请求追踪 ID。7.5 从实际需求决定是否引入分布式很多团队刚开始做本地大模型 Agent 时往往喜欢直接规划大规模分布式推理集群。我的建议是先按需来。如果你的场景只是几个人内部使用一台机器部署好模型服务跑通 End-to-End Agent 闭环就已经足够。只有当并发量明显增加、单机吞吐到了瓶颈或者单张显卡已经放不下目标模型时再考虑增加节点、引入负载均衡或张量并行。这种“先单体、后分布式”的思路和主流系统架构演进是完全一致的。现阶段最重要的是先让 Agent 在真实业务中创造价值而不是为了技术名词去堆基础设施。7.6 技术选型时多关注兼容层本地大模型生态更新很快。今天能用的启动命令过几个月就可能调整。项目开发中建议统一使用 OpenAI 兼容 API。这样即使你把后端从 Ollama 换到 vLLM也只需要修改服务地址和模型名Agent 逻辑基本不需要改动。同样的道理也适用于本地大模型 Agent。选择一个生态成熟的基础模型利用统一的接口层屏蔽模型差异是控制后期维护成本的关键。本文中 ollama 承担的角色只是一个模型服务示例生产环境的模型服务端不一定非要和 Agent 代码锁死在一起。开源社区的 MCP、OpenAI 兼容接口、函数调用协议也都在快速演进值得持续关注。但不管底层的工具协议怎么变Agent 的完整闭环始终是理解意图、选择工具、执行动作、观察结果、生成答案。先把这条链路跑熟练才是本地大模型 Agent 开发最重要的一步。
