企业官网建设流程全解析

做了大半年端侧 Agent 的工程化落地，终于能抽出时间把这段经历完整梳理一遍。前两篇聊了 Agent 的基本认知和端侧推理环境，这篇进入真正的硬骨头：工程化。所谓工程化，就是让 Agent 从“能跑”变成“能上线、能长期运行、能迭代维护”，这件事比模型选型难多了，也坑多了。读完这篇，你会得到一套可以直接用的端侧 Agent 工程化框架：从架构分层、框架选型、模型量化，到并发控制、记忆管理、工具调用安全，每一节都附上了我实际踩坑后修正的做法和可复算的参数。适合正在做端侧 AI 助手、智能硬件语音交互、离线知识库 Agent 的开发者，也适合准备从云端 Agent 转向端侧的团队做参考。

1. 从 Demo 到产品：端侧 Agent 工程化到底在解决什么

1.1 端侧 Agent 和云端 Agent 的本质差异

先定义一下我理解的端侧 Agent。所谓端侧，是指 Agent 的推理和大部分逻辑运行在用户设备上——手机、平板、PC、车机、边缘盒子，而不是跑到云端再回传结果。这个定位带来的价值很明确：一是隐私数据不出设备，敏感信息不需要上传到任何远端；二是交互延迟可控，本地推理省去了网络往返，体感更跟手；三是断网也能用，地铁、电梯、地下室这些弱网场景不会直接让助手变成废柴；四是长期来看推理成本趋近于零，不用按 token 付费。

这些优势反过来塑造了工程化的约束。云端 Agent 遇到瓶颈可以加机器、加 GPU，端侧 Agent 的内存、算力、功耗全是硬边界。同样一个 Agent 架构，在云端可能只是性能问题，到了端侧就是能不能跑起来的问题。我见过不少团队把云端那套 LangChain 全家桶搬到 Android 上，结果光依赖树就装了五十多个包，启动黑屏三秒，内存吃满直接崩。这不是框架不好，而是没有理解端侧约束下的架构选择逻辑。

端侧工程化的本质，是在资源受限的前提下，把 Agent 的复杂度降下来，同时把确定性提上去。云端可以对大模型抱有无限想象，端侧必须做减法。每一步设计都要先问一句：这个东西在目标设备上跑得动吗？跑不动再好看都是白搭。

1.2 “能上线”的四个硬指标

我们内部对“能上线”有一套硬指标，不是能跑通几个 Demo 就算完。第一个是任务成功率。用一个真实的 Agent 任务集（比如 20 个固定场景），每个场景跑 10 次，成功率必须达到 85% 以上，低于这个数直接回炉。任务集不是随便选的，要覆盖日常使用频率最高的操作，比如“帮我查天气并提醒我带伞”“把这段文字翻译成英文并保存到备忘录”这类多步闭环任务。

第二个是性能水位。主要是首 token 延迟和平均生成速度，不同设备差异很大，但至少要保证用户感知不到明显卡顿。如果用户问一个问题要等五秒才听到第一个字，这个产品基本没法用。第三个是资源水位。内存峰值必须控制在设备可用内存的一半以内，避免和系统其他应用抢资源；CPU/功耗在持续对话 10 分钟的情况下不能导致设备明显发热降频，否则用户一边充电一边用着，手机烫得能煎鸡蛋，再好的体验也白搭。

第四个是可观测性。线上出问题要能定位到是哪一轮对话、哪个工具调用、哪个 prompt 出了问题，否则后面的迭代无从谈起。这四个指标里，任务成功率是最难达标的，因为它不单是模型能力问题，还牵扯到规划、工具调用、记忆整个链条的工程质量。工程化的第一课，就是把这四个指标变成每日自动跑的回归测试，而不是上线前临时补一枪。

2. 框架选型与架构分层：别一上来就 LangChain

2.1 Harness 与 Agent：先分清运行环境与业务逻辑

最近圈子里的讨论经常提到 Harness，很多人把 Harness 和 Agent 混为一谈，这里必须先理清。Agent 指的是那个“会思考、会规划、会调用工具”的智能体逻辑，它本质上是一个循环（Loop）：接收任务，拆解计划，调用工具，观察结果，修正计划，直到完成任务。而 Harness 是这个循环得以运行的整套基础设施，包括上下文管理、工具执行器、策略控制、日志追踪、错误恢复这些机制。

打个比方，Agent 是员工，Harness 是公司的管理制度和办公环境。员工再能干，没有流程、没有工具系统、没有安全规范，也干不成事。在端侧场景里，Harness 设计的好坏直接决定了 Agent 能不能稳定运行。我见过一个很典型的反面案例：团队花大力气调 prompt、调模型，Agent 在单测里表现得很好，一旦接入真实工具链就频繁挂掉——缺超时控制、缺重试机制、缺上下文清理，问题不在“智能”而在“环境”。

所以端侧工程化第一步，不是选什么大模型，而是想清楚你的 Harness 要怎么搭：循环怎么调度、工具怎么注册、上下文怎么管理、异常怎么恢复。这些定了，Agent 逻辑的迭代才有基础。没有好的 Harness，Agent 的聪明才智根本无处发挥。

2.2 主流框架横向对比，以及我为什么最终自研

谈到框架，市面上的选择其实很多——LangChain、LangGraph、Dify、CrewAI 各有拥趸。我先把它们的真实使用情况放在一张表里对比，再讲我的结论。

这张表的核心结论是：端侧场景下，主流云端框架的性价比都不高。LangChain 最大的问题是抽象层级太多，链式调用、回调、各种 Memory 模块叠在一起，在端侧那点内存和 CPU 预算下根本跑不转，而且依赖里掺杂了大量网络请求相关的组件，天然和离线优先的设计冲突。Dify 就更不用说了，它本质是一个服务端应用平台，端侧根本没有它的位置。CrewAI 偏研究原型，框架自身的稳定性都不够撑起生产环境。

我最终选了自研 Harness 加最少依赖的路线，核心原因有三个。第一是可控性，端侧环境比云端复杂得多，不同设备的 CPU、NPU、内存、系统版本差异很大，只有自己掌控调度逻辑才能逐个适配。第二是裁剪性，自研 Harness 可以做到只有几个模块，哪些要哪些不要自己定，依赖体积从几百 MB 压到几十 KB 级别。第三是可测试性，自研之后，我可以直接注入 Mock 模型和 Mock 工具做单测，框架层级越少，测试路径越短。

当然，自研的前提是你真的理解 Agent 循环的原理，否则容易把框架里的坑重新踩一遍。如果你还在学习阶段，先拿 LangChain 跑通业务逻辑完全没问题，但不要默认它可以直接进端侧生产。

2.3 端侧 Agent 的参考架构与模块职责

这里给出我们团队在端侧落地时用的分层架构，已经过了三版迭代，目前比较稳定。整体分四层：接入层、会话层、调度层和模型层。接入层负责对接不同入口，比如语音助手、消息通知、App 内对话，把输入统一成标准消息格式；会话层管理会话状态，包括上下文窗口、用户配置、长期记忆的读写；调度层是 Harness 最核心的部分，负责 Agent 主循环、工具注册与执行、策略控制（比如什么时候该摘要、什么时候该终止）、任务优先级管理；模型层则是对推理引擎的封装，屏蔽底层是 llama.cpp、MNN 还是 ONNX Runtime，向上提供统一的 generate 接口，返回 token 流和统计信息。

这个分层的好处是所有模块可以独立测试、独立替换。比如模型层从 CPU 切换到 NPU，调度层完全不用动；记忆模块从本地 JSON 换到 SQLite，会话层接口也不变。我特别想提醒的是，调度层里一定要预留“干预点”（hook），比如每一轮 Agent 循环之后留一个回调，方便观测和注入策略。没有干预点的 Harness，后面想加日志、加审计、加安全策略都只能改核心代码，非常痛苦。

另外，如果团队里有 Rust 基础，端侧 Harness 我个人强烈推荐用 Rust 写。原因很实在：内存占用确定、没有 GC 停顿、交叉编译方便，一套代码可以编出 Android、Linux、嵌入式三个平台的版本。我们后来把 Python 原型用 Rust 重写后，常驻内存直接降了 40%，这对端侧是决定性的。但要注意 Rust 开发效率前期会慢一些，业务验证期用 Python 跑逻辑、稳定期再迁 Rust，是比较务实的路径。

3. 硬件约束下的模型部署：量化、推理引擎与性能实测

3.1 先算内存账：模型选型的量化公式

端侧模型选型的第一件事不是看榜单分数，而是算内存账。模型权重在内存里的占用有一个很简单的公式：权重体积（GB）约等于参数量（B）乘以量化位数（bit）再除以 8。举个例子，2B 模型 FP16 是 2×16÷8 = 4GB，INT8 是 2GB，INT4 是 1GB。这还只是权重，实际运行还要加上 KV Cache、临时激活值和推理引擎开销，一般要在权重体积基础上再留 30% 到 50% 的余量。

我通常会倒推着选：如果设备可用内存是 2GB，那留给模型的上限是 1.2GB 左右，算下来只能选 1B 到 2B 的 INT4 量化模型；如果设备可用内存是 4GB，可以选 3B 到 4B 的 INT4；7B INT4 的权重就有 3.5GB，加上运行时很容易超过 5GB，绝大多数手机根本顶不住。这个账不先算清楚，后面部署阶段必然返工。

还有一个容易忽略的量是 KV Cache 的占用，它和上下文长度直接相关。粗略估算，每 1K token 的 KV Cache 在 INT8 下大约占 1MB 左右（按模型层数和头数有浮动），端侧通常把上下文限制在 4K 到 8K 就是出于这个考量。上下文越长，KV Cache 越大，内存压力指数级上升，这也是后面治理上下文膨胀的根本原因。

3.2 推理引擎对比：llama.cpp、MNN、ONNX Runtime

模型文件选定之后，接下来面临的是推理引擎选型。这里没有银弹，关键看你的目标设备形态。llama.cpp 是我在 Linux 设备和树莓派上的首选，它对 CPU 推理的优化做得非常到位，原生支持 GGUF 格式和各类量化，社区活跃度极高，XNNPACK 后端在 ARM 平台上有明显加速。它的另一大优势是把模型封装成一个单文件（GGUF），分发和版本管理都极度简单，部署的时候拷一个文件过去就行。

移动端（Android/iOS）场景，我会优先看 MNN。它对移动端做过多轮针对性优化，支持 CPU/GPU/NPU 的异构调用，在部分高通平台上能吃到 NPU 加速的红利。但 MNN 的算子支持和动态 shape 处理不如 ONNX Runtime 成熟，如果你要部署的模型里有比较新的算子，可能得先做一层算子兼容性检查。ONNX Runtime 则胜在中间格式的通用性，生态里几乎所有模型都能导出 ONNX，转给其他引擎的路径也更灵活。

我在实测中发现一个高频坑：引擎支持动态 shape 与否，直接决定端侧 Agent 的体验。Agent 生成时上下文长度不断变化，如果引擎不支持动态 shape，就得把输入固定到最大长度，内存和延迟都会浪费很多。选引擎时一定先翻它的文档，确认 dynamic shape 支持情况，再决定要不要额外套一层 Padding 逻辑。这个步骤看起来不起眼，但踩过坑的人都知道，它能把一个看似 OK 的部署方案直接推翻。

3.3 性能与功耗的平衡：一个实测数据参考

把实测数据放在这里给大家一个参考。我们在骁龙平台、8GB 内存设备上跑 Qwen2.5-3B 的 INT4 量化模型，CPU 推理单线程的情况下，平均生成速度大概在每秒 15 到 20 token，首 token 延迟约 300 到 500ms。换到 1.8B INT4 模型，生成速度能到 25 到 35 token/s，首 token 延迟降到 200ms 内。作为对比，人类阅读速度大约每秒 5 到 8 token，所以 1.8B 级别的速度其实已经能满足问答和助手场景；3B 更适合对 reasoning 要求更高的任务。

功耗方面，持续对话 10 分钟后，CPU 推理会让设备功耗明显上升，发热导致降频会让生成速度再掉 20% 到 30%。我们的处理方式是把推理任务绑到特定大小核，限制最高频率，虽然峰值速度略降，但长期运行更稳定。另外一个实用策略是空闲时卸载模型，把内存让给系统，用两秒左右的热加载时间换整机体验，在很多场景下都值得。

功耗的测定方法其实不难：Android 上可以通过电池统计接口拿整机电流，Linux 设备直接读电源管理节点。关键是压测脚本要固定场景——同样的对话流程、同样的负载时长，数据才具有可比性。我们内部就吃过一次亏，两次压测间隔了半个月，系统版本和应用状态都变了，数据对比失真，后面所有功耗测试都固定在同一台设备、同一个系统版本上跑。

4. 并发、延迟与稳定性：端侧 Agent 怎么扛真实流量

4.1 端侧的并发形态和云端完全不同

很多后端背景的同事接手端侧 Agent 时会问同一个问题：这个 Agent 能扛多少并发？我对端侧并发的理解是，单设备场景下几乎没有“高并发”这回事，真实形态是三类叠加：多轮对话中用户的连续追问、Agent 自动触发的后台任务、以及系统里多个 Agent 实例（比如语音助手和消息摘要助手同时存在）。真正的难点不是并发数量，而是这三类请求在共享同一个模型实例时，怎么保证延迟和数据一致性。

端侧模型实例通常是不能并发推理的。一个 3B INT4 模型推理时，激活值和 KV Cache 的内存占用会随着 batch 增大成倍上升，端侧设备那点内存根本撑不住多 batch。而且同一时间跑两个推理，CPU 资源也会被抢占，最终两个请求都变慢，体验更差。所以我们默认的做法是：单个模型实例同一时间只服务一个请求，其他请求进队列等待。这个决策会让吞吐看起来“很低”，但实际上端侧 Agent 的请求频率本身不高，串行化换来的是每个请求都有充足资源，用户体感反而更好。

4.2 请求队列、背压与降级策略

把请求串行化之后，队列设计就成了稳定性的核心。我们的实现比较简单：一个有界队列加一个工作线程。队列长度上限按设备能力设置，比如 8 或者 16，满了之后新请求立即拒绝并返回“Agent 正忙，请稍后再试”，而不是无脑堆积到内存爆炸。这是典型的背压（backpressure）策略，端侧虽然需求峰值不高，但也要防住异常场景下的请求洪峰。简化版的实现思路长这样：

# 简化版请求队列伪代码 queue = asyncio.Queue(maxsize=8) async def enqueue(request): if queue.full(): return AgentBusy() # 背压：立即拒绝 await queue.put(request) async def worker(model): while True: request = await queue.get() try: result = await model.generate(request) await notify(request, result) # 通知会话层回传结果 finally: queue.task_done()

降级策略同样重要。我们内部把请求分成两级：交互级和后台级。用户正在对话的请求属于交互级，永远优先出队；摘要生成、自动整理这类属于后台级，可以等，甚至可以在内存压力大时直接丢弃，再安排下次重跑。这个策略用一句话概括：宁可牺牲后台任务的完整度，也要保住用户面对的那条对话链路。

还要提一下重试与幂等。工具调用可能失败，整条链路的某个环节可能超时，所以 Harness 里必须有重试机制。但重试的前提是操作要幂等——同一个工具调用执行两次不能产生双倍副作用。比如发送通知这个 Skill，我们要求它内部生成一个 requestID，目标系统按这个 ID 去重；没有幂等设计的重试，在真实场景里很容易变成发三次短信。这个问题云端也常见，但端侧离用户操作更近，一旦发生用户感知更直接。

4.3 上下文膨胀治理：token 预算与摘要压缩

端侧 Agent 最容易出现的问题之一，是长对话后上下文越滚越大，最终把内存和配额吃掉。我们给每个会话设定了一个 token 预算，比如 4K，一旦超出就触发上下文治理。治理手段按顺序递进：先做滑动窗口，只保留最近 N 轮对话；如果仍然超限，就触发摘要生成，把更早的对话压成一段摘要；再配合关键事实抽取，把“用户住在北京、偏好环保产品”这类长期信息单独落到记忆存储里，而不是留在上下文里反复占空间。

摘要在工程上的实现需要特别小心：摘要本身也要调用模型，一轮摘要可能消耗几百 token 和几秒时间，不能让用户明显感知卡顿。我们的做法是在用户对话的间隙（比如上一轮回复结束后的空闲窗口）异步触发摘要，并且给摘要设置单独的、更小的模型上下文，避免挤占主对话的推理资源。实际跑下来，摘要策略的效果很明显：40 轮以内的对话，上下文占用能被控制在预算的 80% 以内，长对话不再成为系统负担。

token 预算的具体数值要按设备调整，我们的经验值是：预算不能超过模型上下文窗口的 70%，留出 30% 给当前这一轮的输入输出。假设模型支持 8K 上下文，预算就设 5.6K 左右，触发摘要的阈值设在预算的 70% 也就是 3.9K。这样设置的好处是，摘要本身也需要消耗 token，不至于在摘要过程中又把上下文撑爆。

5. 记忆与工具调用：两个最容易被低估的工程点

5.1 长期记忆的持久化与摘要时机

端侧 Agent 的记忆分为短期记忆和长期记忆两层。短期记忆就是当前会话上下文，通常由 Harness 直接管理，不需要额外设计；长期记忆才是工程化的分水岭——它要跨会话保存用户偏好、历史事实、任务状态，并且在合适的时机写回上下文，让 Agent 在下一轮对话中能用上。没有长期记忆的 Agent 像个失忆症患者，每次对话都当第一次见面，体验很难有质的提升。

我们在端侧采用的长期记忆实现很朴素：本地 SQLite 加向量检索（如果有能力，也可以纯结构化存储）。每轮对话结束后，由调度层决定哪些信息值得写入，写入前会先做一次去重和票选。其中去重是必须做的，否则同一件事在十轮对话里写十次，记忆库就废了。记忆的写入时机我强烈建议放在异步任务里，不要在用户交互路径上同步阻塞，否则用户每说一句话都要等记忆落盘，卡顿感极强。

摘要时机的选择，我踩过比较深的坑是“每轮都摘要”。早期实现是对话每增加一轮就生成一次摘要，结果模型频繁被摘要任务打断，对话质量反而下降。后来改成两个触发条件：上下文达到 token 预算的 70% 时触发一次，且两次摘要之间至少间隔 5 轮对话。这个策略既保证了摘要的时效性，又不至于频繁抢占推理资源。摘要一定要保留关键事实的原文，不能过度抽象，否则 Agent 后续回忆时只能得到“用户喜欢 XX”的模糊结论，而丢失了“用户在上个月买过 X 型号产品”这种具体信息。

一个额外的提醒：长期记忆的存储格式要预留版本字段。Agent 的记忆结构在迭代中一定会变，没有版本控制，升级后旧记忆全部无法解析，用户的历史数据直接丢失，这是线上事故级别的错误。

5.2 Skill 调用的校验、超时与幂等

工具调用在 Agent 生态里的名字很多：Tool、Function、Skill，本质上都是让模型具备调用外部能力的手段。端侧工程化对 Skill 的要求，比云端更强调安全和可控，因为端侧 Agent 距离用户和系统权限太近了，一个错误调用可能直接影响系统功能。我们要求每个 Skill 在注册时必须提供 JSON Schema，字段包括参数名、类型、必填性、取值范围，比如这样：

{ "name": "send_message", "description": "发送一条系统通知", "parameters": { "type": "object", "properties": { "receiver": { "type": "string", "minLength": 1 }, "content": { "type": "string", "maxLength": 200 } }, "required": ["receiver", "content"] } }

模型返回的工具调用请求，在执行前必须经过三重检查。第一重是 schema 校验，参数类型不对、必填缺失就直接拒绝，不要尝试“智能补全”，补错的风险远大于收益。第二重是权限校验，Skill 根据可访问的系统能力分级，读取本地文件是普通权限，发送通知、拨打电话则需要高权限，高权限操作必须由用户二次确认。第三重是内容校验，参数里如果出现路径穿越、命令注入这类模式，直接拦截。端侧 Agent 最容易在这三重校验上偷工减料，但这一环恰恰是不能省的。

超时熔断是我反复强调的一点。工具调用不能无限等待，我们在 Harness 里给每个 Skill 设了明确的超时时间，默认 5 秒，超过就把该次调用标记为失败，并让 Agent 走异常分支（比如更换工具或直接向用户说明）。幂等设计同样不能省，前文提到的 requestID 机制就是基础款，更严格的做法是让 Skill 在执行前先检查目标状态，已经完成的操作直接返回成功，避免重试造成重复副作用。真实场景里，模型经常会出现连续两次调用同一个 Skill 的情况，没有幂等保护，轻则重复发送，重则数据写乱。

6. 高频问题排查速查表与几条真实经验

6.1 端侧 Agent 工程化高频问题速查

把我们在端侧 Agent 落地这一年里遇到的高频问题整理成一张速查表，基本都是能直接复用的排查思路。

这张表解决的是“出了问题怎么查”，但更重要的经验是别等问题出现才去查。端侧 Agent 从第一天就应当把日志、指标、异常上报埋好，否则线上问题全靠猜，效率极低。我们内部有一个不成文的规定：任何一次线上问题，如果事后拿不出完整的问题现场日志，都算开发团队的失职。这个规定听起来苛刻，但执行下来之后，排查周期从按天计缩短到了按小时计。

6.2 几条说烂了但真的救过命的经验

第一，先跑通最小闭环再上框架。我们最开始用最原始的“while 循环 + 请求模型 + 解析 JSON”拼出一个能跑通的 Agent，再把其中反复出现的逻辑抽象成 Harness 模块。这样的好处是每一步都在为真实问题设计，而不是被框架的概念绑架。等到你理解了循环的每一个环节，再去看框架源码，很多当时觉得玄妙的设计就都一目了然了。

第二，端侧 Agent 追求的是确定性，不是聪明。云端你可以让模型自由发挥，端侧由于资源紧张，我们反而希望模型少一些自由发挥，多一些结构化输出。比如工具调用参数，宁可让模型输出 JSON 再校验，也不要它用自然语言描述意图再由 Harness 去猜。效果上的差距可以在后续用更好的模型补，但工程稳定性是底线，底层逻辑一旦崩塌，上面全是空中楼阁。

第三，内存峰值一定要压测出来。不要看文档里写的建议内存，直接跑一个 100 轮以上的压测任务，把内存曲线打出来，你会看到很多平时根本察觉不到的问题，比如长上下文后的 KV Cache 尖峰、工具调用临时对象的堆积。我们第一次做百轮压测时，内存曲线在 80 轮附近出现了明显的台阶式上涨，定位结果是某个 Skill 在重复往上下文里塞历史记录。这种问题，靠人工点几个场景是永远发现不了的。

第四，日志和可观测性从第一天就埋。后期的每一次智能优化，没有观测数据支撑都等于拍脑袋。我们曾经花两周调 Agent 的规划 prompt，效果时好时坏，后来上了完整日志追踪才发现，问题根本不在 prompt，而在某个工具返回了空结果，导致规划路径每次都不一样。先看数据，再改方案，这条规矩救过我太多次了。

我个人在这一年多里最大的体会是：端侧 Agent 的工程化和云端最大的不同，在于所有决策都被资源边界逼着做减法。云端你可以无脑上大模型、堆框架、加并发，端侧每一步都要算账——内存账、延迟账、功耗账、维护账。这个约束一开始觉得憋屈，做久了反而成为产品竞争力的来源，因为它逼着你把 Agent 的每个环节都理清楚，而不是让框架替你兜底。

先写到这。端侧 Agent 工程化的另一半——多 Agent 协作、评估体系、持续集成与灰度发布——内容量同样不小，我放到下一篇（下）里继续讲。如果你正在做端侧 Agent 或者准备从云端迁过来，欢迎带着具体问题来交流，多数坑我都替你踩过了。