企业官网建设流程全解析

1. 端侧 Agent 工程化的核心命题

1.1 从 Demo 到产品：为什么工程化是分水岭

很多人第一次接触端侧 Agent，都是从一个几十行的 Demo 开始的：定义一个工具函数，把 JSON Schema 塞进 prompt，模型返回一段结构化文本，解析出来调用本地 API，跑通了，感觉“不过如此”。但当你真正想把它做成一个能交付、能维护、能在真实设备上稳定运行的产品时，问题会像潮水一样涌上来——工具数量从 3 个涨到 30 个，模型开始选错工具；上下文窗口被工具描述挤爆，推理速度肉眼可见地变慢；同一个工具在不同模型上的调用格式不一致，换一个模型整条链路就崩；用户连续追问三轮，Agent 忘了自己刚才调过什么。

这些问题的本质，不是模型不够聪明，而是工程化缺失。端侧 Agent 和云端 Agent 最大的区别在于：端侧的资源是硬约束。内存可能只有几百 MB 到几 GB，算力被 NPU 或移动 GPU 卡死，功耗和发热直接决定用户体验，模型参数量通常被压到 1B 到 7B 之间。这意味着你不能像云端那样“用更大的模型、更长的上下文、更多的工具描述”来暴力解决问题，你必须把每一 KB 的上下文、每一次推理调用都花在刀刃上。

我个人的判断是：端侧 Agent 的工程化，核心就三件事——工具接口的标准化、上下文的精细化管理、调用链路的可观测与可恢复。这三件事做不好，Demo 永远只是 Demo。这一篇先聊清楚工程化的整体设计思路和工具层的关键细节，下一篇再展开上下文管理和运行时调度。

1.2 端侧 Agent 工程化的四个核心约束

在动手写任何代码之前，先把约束条件列清楚，这决定了后面所有的技术选型。

约束一：算力与内存的硬天花板。端侧设备上，模型推理本身就要占用大量内存。一个 3B 的量化模型，INT4 量化后大约占 1.8 到 2.5 GB，加上 KV Cache、运行时框架、系统占用，留给 Agent 逻辑层的空间非常有限。工具描述、历史对话、系统提示词全部要挤在同一个上下文窗口里，通常这个窗口只有 4K 到 8K token。你不能像云端那样把几十个工具的完整 JSON Schema 全塞进去。

约束二：模型能力的参差不齐。端侧能跑的模型，Function Calling 能力差异极大。有些模型经过专门的工具调用微调，输出格式很稳定；有些模型只是“勉强能输出 JSON”，稍微复杂一点的嵌套结构就开始胡言乱语。工程化必须假设“模型随时可能出错”，在解析层做足容错。

约束三：延迟敏感。用户对着手机或车机说话，期望 1 到 2 秒内看到响应。一次 Agent 调用如果涉及多轮推理（思考→选工具→执行→再思考→生成回答），每一轮都是几百毫秒到几秒的推理开销。工具描述越长，prefill 阶段越慢。这就要求工具层必须极度精简。

约束四：离线与隐私。端侧 Agent 的一大卖点就是数据不出设备。这意味着工具执行、状态管理、日志记录全部要在本地完成，不能依赖任何远程服务。这对工程实现的完整性提出了更高要求。

把这四个约束放在一起，你会发现端侧 Agent 的工程化本质上是一个在极度受限的资源下做取舍的过程。下面这张表是我在实际项目中总结的取舍对照：

1.3 工程化分层架构的整体设计

端侧 Agent 的工程化，我习惯把它拆成四层，从下往上依次是：模型推理层、工具接口层、编排调度层、应用交互层。这一篇重点讲工具接口层，但先把整体架构说清楚，后面才不会迷路。

模型推理层负责把量化模型跑起来，管理 KV Cache，提供统一的推理接口。这一层通常由 llama.cpp、MLC、ONNX Runtime 或厂商的 NPU SDK 承担，工程化的重点是推理参数的统一封装和流式输出的处理。

工具接口层是这一篇的主角，负责定义工具、描述工具、解析模型的工具调用请求、执行工具、把结果格式化回模型。这一层的核心挑战是标准化——让不同模型、不同工具、不同调用格式之间能互相适配。

编排调度层负责决定“什么时候调工具、调哪个、调几次、失败了怎么办”。这一层是 Agent 的“大脑”，涉及意图识别、工具路由、多轮循环控制、状态管理。

应用交互层负责和用户打交道，处理输入输出、UI 渲染、权限控制、日志上报。

提示：很多团队一上来就写编排逻辑，结果工具层没标准化，每加一个工具就要改一遍编排代码。正确的顺序是先把工具接口层做扎实，编排层才能稳定。

2. Function Calling 与 JSON Schema 的工程化落地

2.1 Function Calling 的本质：一场结构化输出的博弈

Function Calling 听起来很玄，但剥开看，它的本质就是让模型输出一段符合特定结构的文本。模型本身并不“调用”任何函数，它只是根据你给的 schema，生成一段 JSON，然后由你的代码去解析并执行真正的函数。理解这一点非常关键，因为它意味着：Function Calling 的可靠性，取决于两件事——模型输出结构化文本的能力，以及你的解析代码的健壮性。

在云端，OpenAI 这类服务提供了原生的 Function Calling 支持，模型经过专门训练，输出格式非常稳定，甚至能保证返回的 JSON 一定符合 schema。但端侧模型没有这个待遇。你面对的是一个通用小模型，它可能：

• 把 JSON 包在 markdown 代码块里
• 在 JSON 前后加一堆解释性文字
• 用单引号代替双引号
• 漏掉必填字段
• 把数字写成字符串
• 在应该输出 JSON 的时候输出了一段自然语言

所以端侧 Function Calling 的工程化，第一步就是放弃对模型“完美输出”的幻想，把解析层做成一个“宽容的解析器 + 严格的校验器”。

2.2 JSON Schema 设计：少即是多

JSON Schema 是描述工具参数的标准格式，但端侧场景下，schema 的设计原则和云端完全不同。云端你可以写一个包含十几个字段、多层嵌套、带各种约束的 schema，端侧不行——schema 越长，占用的上下文越多，模型理解错误的概率越高。

我的经验是，端侧工具的 schema 设计遵循三条铁律：

铁律一：字段数量控制在 5 个以内。超过 5 个字段的工具，模型填错的概率急剧上升。如果业务确实需要很多参数，拆成多个工具，或者把部分参数做成有默认值的可选字段。

铁律二：能用枚举就不用自由文本。比如“设置闹钟”工具，时间用字符串让模型自由发挥，它可能输出“明天早上七点”这种无法解析的内容。改成枚举或者明确的格式约束（如HH:MM），可靠性大幅提升。

铁律三：描述要短，但要说清楚“什么时候用”。很多人的工具描述写的是“这个工具用来查询天气”，但模型真正需要知道的是“当用户询问某地天气、温度、是否下雨时使用”。描述里要包含触发场景，而不只是功能。

下面是一个对比示例，左边是云端风格的 schema，右边是端侧优化后的版本：

// 云端风格：字段多、嵌套深、描述长 { "name": "search_and_book_flight", "description": "搜索航班并预订，支持多种筛选条件和排序方式", "parameters": { "type": "object", "properties": { "departure_city": {"type": "string", "description": "出发城市名称"}, "arrival_city": {"type": "string", "description": "到达城市名称"}, "departure_date": {"type": "string", "description": "出发日期，格式YYYY-MM-DD"}, "return_date": {"type": "string", "description": "返程日期，可选"}, "passengers": {"type": "integer", "description": "乘客数量"}, "cabin_class": {"type": "string", "enum": ["economy", "business", "first"]}, "sort_by": {"type": "string", "enum": ["price", "duration", "departure_time"]}, "max_price": {"type": "number", "description": "最高价格筛选"} }, "required": ["departure_city", "arrival_city", "departure_date"] } }

// 端侧优化：字段精简、枚举明确、描述聚焦触发场景 { "name": "book_flight", "description": "用户要订机票、查航班时使用", "parameters": { "type": "object", "properties": { "from": {"type": "string", "description": "出发城市"}, "to": {"type": "string", "description": "到达城市"}, "date": {"type": "string", "description": "日期，如2024-06-01"}, "cabin": {"type": "string", "enum": ["经济舱", "商务舱", "头等舱"]} }, "required": ["from", "to", "date"] } }

字段从 8 个减到 4 个，描述从长句变成短句，去掉了排序、价格筛选这些“锦上添花”的参数。实测下来，模型调用成功率从 60% 出头提升到 90% 以上。那些被砍掉的参数，完全可以在工具执行后通过二次交互补充，没必要一次性塞给模型。

2.3 工具描述的动态裁剪策略

即使每个工具的 schema 都精简了，当工具数量达到 20 个以上时，全部塞进上下文依然会爆。这时候需要动态裁剪——根据当前对话的意图，只加载相关的工具子集。

实现思路是维护一个工具分组表，把工具按领域分类（如“设备控制”“信息查询”“日程管理”“通讯”），然后根据用户输入的关键词或轻量意图分类器，决定加载哪一组。比如用户说“帮我定个明天早上的闹钟”，意图分类器识别为“设备控制”，就只加载闹钟、计时器、音量控制这几个工具，其他工具的描述完全不进上下文。

这个意图分类器不需要很复杂，端侧可以用一个小的文本分类模型，或者干脆用关键词匹配加规则。关键是分类要快、要准、要能兜底。如果分类失败，就加载一个“通用工具集”（通常是最高频的 5 到 8 个工具），保证基本可用。

注意：动态裁剪的粒度不要太细，否则每次对话都要重新加载工具描述，prefill 开销反而增加。我的做法是按“会话”粒度加载，一次加载一组，整个会话内保持不变，除非用户明确切换了话题。

2.4 多模型适配：一套工具定义，多种调用格式

端侧设备上可能同时存在多个模型，或者产品需要在不同设备上适配不同模型。每个模型的 Function Calling 格式都不一样：有的用特定的特殊 token 包裹，有的用 XML 标签，有的直接要求输出 JSON。如果每个模型都写一套工具定义，维护成本会爆炸。

工程化的做法是定义一套中立的工具描述格式，然后写适配器转换成各模型需要的格式。中立格式可以用 JSON Schema 作为基础，适配器负责：

• 把 JSON Schema 转换成模型特定的 prompt 模板
• 把模型特定的输出格式解析回统一的调用结构
• 处理模型特有的边界情况（如某些模型不支持嵌套对象）

# 中立工具定义 tool_def = { "name": "set_alarm", "description": "用户要设置闹钟时使用", "parameters": { "type": "object", "properties": { "time": {"type": "string", "description": "时间，如07:30"}, "label": {"type": "string", "description": "闹钟标签"} }, "required": ["time"] } } # 适配器：转换成不同模型的格式 class ToolAdapter: def to_qwen_format(self, tool_def): # Qwen 系列用特定的 tool 标签 return f"<tool>{json.dumps(tool_def, ensure_ascii=False)}</tool>" def to_llama_format(self, tool_def): # Llama 系列用 JSON 数组 return json.dumps([tool_def], ensure_ascii=False) def parse_output(self, model_name, raw_output): # 统一的解析入口，内部按模型分派 if model_name.startswith("qwen"): return self._parse_qwen(raw_output) elif model_name.startswith("llama"): return self._parse_llama(raw_output) else: return self._parse_generic(raw_output)

这套适配器模式的好处是，新增一个模型只需要加一个适配器，工具定义本身不用动。实测下来，适配 5 个不同模型的工作量，从“每个模型改一遍所有工具”变成了“写 5 个适配器”，维护成本降低了一个数量级。

3. MCP 协议在端侧 Agent 中的角色

3.1 MCP 是什么，为什么端侧需要它

MCP（Model Context Protocol）最近热度很高，各种工具和平台都在接入。但很多人对它的理解停留在“又一个工具调用协议”的层面，没搞清楚它真正解决什么问题。我的理解是：MCP 解决的是“工具提供方”和“工具使用方”之间的解耦问题。

在没有 MCP 之前，每个 Agent 框架都要自己定义工具格式，每个工具提供方都要为不同的框架写不同的适配。MCP 定义了一套标准的通信协议，工具提供方只需要实现一个 MCP Server，任何支持 MCP 的 Agent 都能直接调用。这就像 USB 接口统一了外设连接一样，MCP 统一了工具接入。

对端侧 Agent 来说，MCP 的价值在于生态复用。端侧团队通常人手有限，不可能自己实现所有工具。如果有一个现成的 MCP Server 能提供日历、邮件、文件管理等功能，直接接入就能用，省下大量开发时间。而且 MCP 的协议设计考虑了本地进程通信，适合端侧这种不能依赖远程服务的场景。

3.2 MCP 的核心概念与端侧适配要点

MCP 的核心概念有三个：Server、Client、Transport。Server 提供工具和资源，Client 是 Agent 侧的连接器，Transport 是通信方式（通常是 stdio 或本地 socket）。端侧场景下，Transport 基本只能用 stdio 或本地 IPC，因为不能开网络端口。

端侧适配 MCP 有几个坑要注意：

坑一：进程管理。MCP Server 通常是一个独立进程，端侧启动 Agent 时要同时拉起 Server 进程，退出时要确保清理干净。移动端对后台进程管控很严，Server 进程可能被系统杀掉，需要做重连和状态恢复。

坑二：工具发现的开销。MCP 支持动态发现工具，但端侧不能每次对话都去问 Server “你有哪些工具”。我的做法是启动时发现一次，缓存工具列表，Server 更新工具时通过通知机制同步。

坑三：协议开销。MCP 的完整协议包含不少元数据，端侧要精简。只保留必要的字段，去掉调试信息、版本协商等非核心内容。

# 端侧 MCP Client 的简化实现思路 class EdgeMCPClient: def __init__(self, server_command): self.server_command = server_command self.tools_cache = {} self.process = None def start(self): # 启动 Server 进程，建立 stdio 通道 self.process = subprocess.Popen( self.server_command, stdin=subprocess.PIPE, stdout=subprocess.PIPE ) # 启动时发现一次工具，缓存起来 self.tools_cache = self._discover_tools() def _discover_tools(self): # 发送 tools/list 请求，解析响应 response = self._send_request("tools/list", {}) return {t["name"]: t for t in response.get("tools", [])} def call_tool(self, name, arguments): # 直接调用，不再重新发现 return self._send_request("tools/call", { "name": name, "arguments": arguments })

3.3 MCP 与原生 Function Calling 的取舍

端侧到底该用 MCP 还是原生 Function Calling？我的建议是混合使用：核心高频工具用原生 Function Calling，保证低延迟和稳定性；长尾工具和第三方能力用 MCP 接入，保证扩展性。

原因很简单：MCP 虽然标准化，但多了一层进程通信和协议解析，延迟比原生调用高。对于“设置闹钟”“调节音量”这种高频、低延迟要求的工具，原生调用更合适。而对于“查询快递”“订餐”这种低频、第三方提供的工具，MCP 的标准化优势就体现出来了。

4. 工具执行层的工程化细节

4.1 参数校验与类型转换

模型输出的参数，永远不能直接信任。哪怕 schema 写得再清楚，模型也可能输出类型不对、范围越界、格式错误的值。工具执行层的第一道关卡就是参数校验。

校验分三步：结构校验、类型校验、业务校验。结构校验检查必填字段是否齐全、字段名是否正确；类型校验检查值的类型是否符合 schema；业务校验检查值是否在合理范围内（如时间格式是否正确、枚举值是否合法）。

def validate_and_convert(tool_def, raw_args): """校验并转换模型输出的参数""" schema = tool_def["parameters"] properties = schema.get("properties", {}) required = schema.get("required", []) # 第一步：结构校验 for field in required: if field not in raw_args: raise ValidationError(f"缺少必填字段: {field}") # 第二步：类型校验与转换 converted = {} for key, value in raw_args.items(): if key not in properties: continue # 忽略未知字段，不报错 expected_type = properties[key].get("type") converted[key] = coerce_type(value, expected_type) # 第三步：业务校验 for key, value in converted.items(): if "enum" in properties[key]: if value not in properties[key]["enum"]: raise ValidationError(f"{key} 的值 {value} 不在允许范围内") return converted def coerce_type(value, expected_type): """宽容的类型转换""" if expected_type == "string": return str(value) elif expected_type == "integer": try: return int(float(value)) # 处理 "3.0" 这种情况 except (ValueError, TypeError): raise ValidationError(f"无法转换为整数: {value}") elif expected_type == "number": try: return float(value) except (ValueError, TypeError): raise ValidationError(f"无法转换为数字: {value}") elif expected_type == "boolean": if isinstance(value, str): return value.lower() in ("true", "1", "yes") return bool(value) return value

这里有个细节值得说：未知字段直接忽略，不要报错。模型有时候会“自作主张”加一些 schema 里没有的字段，如果因此报错，整个调用就失败了。忽略未知字段，只处理认识的字段，容错性更好。

4.2 工具执行的超时与降级

端侧工具执行可能涉及 IO 操作（读文件、查数据库、调系统 API），这些操作可能超时或失败。工程化必须给每个工具设置超时时间和降级策略。

超时时间根据工具类型设定：纯计算类工具 500ms，本地 IO 类 2s，涉及系统 API 的 3s。超时后不能直接抛异常给模型，而是返回一个结构化的错误信息，让模型知道“这个工具失败了”，它可以决定是重试、换工具还是直接告诉用户。

import signal class TimeoutError(Exception): pass def execute_with_timeout(func, args, timeout_sec): """带超时的工具执行""" def handler(signum, frame): raise TimeoutError(f"工具执行超时（{timeout_sec}s）") old_handler = signal.signal(signal.SIGALRM, handler) signal.alarm(timeout_sec) try: result = func(**args) return {"status": "success", "data": result} except TimeoutError as e: return {"status": "timeout", "message": str(e)} except Exception as e: return {"status": "error", "message": str(e)} finally: signal.alarm(0) signal.signal(signal.SIGALRM, old_handler)

返回给模型的结果统一用{"status": ..., "data/message": ...}的结构，模型看到status就知道成功还是失败，看到message就知道失败原因。这种结构化反馈比直接抛异常或返回裸数据要好得多，模型能据此做出更合理的决策。

4.3 工具结果的格式化与截断

工具执行完，结果要格式化后回传给模型。这里有两个关键点：格式要统一，长度要控制。

格式统一是指所有工具的结果都用同一种结构返回，模型不需要为每个工具学习不同的结果格式。我通常用：

{ "tool": "set_alarm", "status": "success", "result": "闹钟已设置为明天 07:30", "truncated": false }

长度控制是指结果不能太长，否则会挤爆上下文。比如查询通讯录返回了 500 条记录，全塞回去上下文就爆了。这时候要截断 + 摘要：只返回前 N 条，并告诉模型“还有更多结果”。N 的取值根据上下文剩余空间动态调整，通常 3 到 5 条。

实操心得：截断的时候一定要在结果里明确标注“已截断，共 X 条，显示前 Y 条”，否则模型会以为这就是全部结果，给出错误的回答。我踩过这个坑，用户问“通讯录里有多少人”，模型看到截断后的 5 条，回答“5 个人”，实际有 500 个。

4.4 工具调用的幂等性设计

端侧 Agent 可能因为各种原因重试工具调用（模型输出不稳定、网络抖动、用户重复触发）。如果工具不是幂等的，重试就会产生副作用——重复设置闹钟、重复发送消息、重复扣款。

幂等性设计有两个层面：工具本身的幂等和调用层的去重。工具本身尽量设计成幂等的，比如“设置闹钟”用“设置”而不是“添加”，重复调用结果一样。调用层则维护一个近期调用记录，相同工具 + 相同参数在短时间内重复调用，直接返回缓存结果，不真正执行。

class IdempotentExecutor: def __init__(self, window_sec=30): self.recent_calls = {} # (tool_name, args_hash) -> (timestamp, result) self.window_sec = window_sec def execute(self, tool_name, args, func): key = (tool_name, self._hash_args(args)) now = time.time() # 检查是否有近期相同调用 if key in self.recent_calls: ts, result = self.recent_calls[key] if now - ts < self.window_sec: return result # 直接返回缓存结果 # 执行并记录 result = func(**args) self.recent_calls[key] = (now, result) return result def _hash_args(self, args): return hashlib.md5( json.dumps(args, sort_keys=True).encode() ).hexdigest()

这个去重窗口设 30 秒比较合适，太短起不到去重效果，太长可能误伤用户真实的重复操作。

5. 常见问题与排查技巧实录

5.1 模型不调用工具，直接回答

这是最常见的问题。用户说“帮我设个闹钟”，模型不调用set_alarm，而是回复“好的，请问您想设几点？”。原因通常是工具描述没有说清楚触发场景，或者系统提示词没有强调“必须用工具”。

排查思路：先看工具描述，是不是只写了“设置闹钟”而没写“用户要设置闹钟时使用”。再看系统提示词，有没有明确要求“当用户请求涉及工具能力时，必须调用工具，不要自己回答”。最后看模型，有些小模型的工具调用能力确实弱，换个模型或者加 few-shot 示例。

5.2 工具调用参数错误

模型调用了工具，但参数不对——缺字段、类型错、值越界。排查顺序：先看 schema 是不是太复杂，字段太多或嵌套太深；再看描述是不是有歧义，比如“时间”字段没说明格式；最后看模型输出，是不是被截断了（上下文不够导致 JSON 不完整）。

一个容易被忽略的点是上下文长度。如果工具描述 + 历史对话 + 系统提示词加起来接近上下文窗口上限，模型输出 JSON 时可能被截断，导致解析失败。这时候要主动裁剪历史对话，给输出留足空间。

5.3 多轮调用陷入死循环

Agent 调用工具 A，结果不理想，又调用工具 A，反复循环。这是编排层的问题，但工具层可以做防护：限制单个工具在单次会话中的最大调用次数，超过就强制返回错误，让模型换策略。

class CallLimiter: def __init__(self, max_calls_per_tool=3): self.counts = {} self.max_calls = max_calls_per_tool def check(self, tool_name): count = self.counts.get(tool_name, 0) if count >= self.max_calls: return False, f"工具 {tool_name} 调用次数已达上限" self.counts[tool_name] = count + 1 return True, None

5.4 常见问题速查表

5.5 几个踩过的坑

坑一：工具描述里的示例会误导模型。我在工具描述里写了个示例参数{"time": "07:30"}，结果模型不管用户说什么，都输出07:30。后来把示例去掉，只保留格式说明，问题解决。工具描述里尽量不放具体值示例，放格式模板就好。

坑二：枚举值用英文，模型输出中文。schema 里枚举写的是["economy", "business"]，但用户说的是中文，模型有时候输出中文枚举值。后来把枚举值改成中文，匹配率大幅提升。端侧场景下，枚举值用用户语言，不要用英文。

坑三：工具名太长影响解析。工具名search_flight_and_book这种长名字，模型有时候会拼错或者截断。工具名控制在 15 个字符以内，用简短动词开头，如book_flight。

坑四：并发调用导致状态混乱。模型一次输出了两个工具调用，代码并发执行，两个工具都修改了同一个状态，结果错乱。端侧工具执行默认串行，除非明确无状态依赖，才考虑并发。

工具层的工程化，说到底就是把模型当成一个“能力很强但很不靠谱的实习生”——它能帮你干活，但你得把任务交代清楚、把边界划明白、把错误兜住。schema 精简、描述清晰、校验严格、容错充分，这十六个字是我做了多个端侧 Agent 项目后最深的体会。下一篇会聊上下文管理和运行时调度，那部分才是真正决定 Agent 能不能“连续对话不崩”的关键。