本地模型Agent实战：从CLI、skills到harness的工程化边界

1. 为什么“本地模型”突然成了绕不开的话题

这两年我身边做开发的朋友，聊天内容从“你调哪个API”慢慢变成了“你本地跑什么模型”。这个转变不是跟风，而是被现实逼出来的。一方面，云端模型的调用成本在规模化之后非常可观，尤其是做Agent类应用，一次任务可能要来回几十轮推理，token消耗像流水一样；另一方面，数据隐私和响应延迟这两座大山，让很多场景根本没法把请求发到远端。本地模型就是在这个夹缝里长出来的。

所谓本地模型，说白了就是把模型权重下载到自己的机器上，用本地算力完成推理。它可以是几GB的小参数模型跑在笔记本上，也可以是量化后塞进消费级显卡的中等模型。配合Ollama、llama.cpp这类运行时，加载本地模型已经简化到一条命令的程度。但真正让本地模型有价值的，不是“能跑起来”，而是它和Agent、CLI、skills、harness这一整套工程体系结合之后，能撑起什么样的应用边界。

我写这篇东西，是想把过去一段时间在本地模型上踩过的坑、验证过的方案、以及关于边界的思考整理出来。适合两类人看：一类是刚接触本地部署、想知道从哪下手的新手；另一类是在做Agent开发、纠结哪些环节该放本地、哪些该上云的老手。核心关键词会围绕本地模型、Agent、CLI、skills、harness这几个词展开，但不会停留在概念层面，而是落到具体的选型、参数和实操上。

先说结论性的判断：本地模型不是云端模型的廉价替代品，它是一套独立的工程约束条件。你一旦选择本地，整个Agent架构的设计逻辑都要跟着变。这个认知如果一开始没建立起来，后面会走很多弯路。

2. 本地模型的能力边界到底在哪

2.1 参数规模与任务复杂度的匹配关系

很多人第一次跑本地模型，会拿它和云端旗舰模型对比，然后得出“本地模型不行”的结论。这个对比本身就不公平。本地模型的能力边界，首先取决于参数规模和量化等级，而这两者又直接受限于你的硬件。

我整理了一张实际测试中总结的对照表，基于常见的消费级硬件配置：

这张表的关键不是数字本身，而是它揭示的一个规律：本地模型的能力天花板，在硬件买定那一刻就基本确定了。你可以通过量化、推理优化榨出一些性能，但没法突破物理限制。所以做本地模型应用的第一步，不是选模型，而是明确你的硬件能承载什么，然后在这个约束下设计任务。

2.2 量化带来的能力损失与补偿策略

量化是本地部署绕不开的环节。把FP16的模型压到Q4，体积能缩小到四分之一，但能力损失是真实存在的。我的经验是，量化对不同类型的任务影响差异很大。

对于格式转换、信息抽取、简单分类这类任务，Q4量化的损失几乎可以忽略，因为这些任务对模型内部表示的精度要求不高。但对于需要多步推理、数学计算、代码生成的场景，Q4和FP16的差距就明显了。我实测过一个14B模型在Q4和Q8下做同一道逻辑推理题，Q4会漏掉中间步骤直接给错误答案，Q8则能完整推导。

补偿策略有几个方向。一是对关键任务用更高的量化等级，比如Q8甚至FP16，牺牲速度换准确率。二是把复杂任务拆解成多个简单子任务，让量化模型只处理它擅长的部分。三是引入外部工具，比如让模型调用计算器、代码执行器来完成它不擅长的环节。这第三点其实就引出了Agent的价值——本地模型不需要独自完成所有事，它可以是一个调度者。

2.3 上下文窗口的实际可用长度

模型标称的上下文窗口和实际可用长度是两回事。一个标称128K上下文的模型，在本地跑起来之后，受限于显存和推理框架，实际能稳定处理的可能只有8K到32K。超过这个长度，要么速度断崖式下降，要么直接OOM。

我在做长文档处理时踩过这个坑。当时用一个大上下文模型读一份技术文档，前几轮对话还正常，到后面模型开始“忘记”前面的内容，回答质量急剧下降。排查后发现是推理框架在上下文超限时做了截断，但截断的位置不合理，把关键的系统提示词给丢了。

解决办法是主动管理上下文。不要指望模型自己记住所有东西，而是用外部存储把重要信息存起来，需要时再检索注入。这就是本地向量模型发挥作用的地方——用embedding把文档切片存进向量库，Agent需要时查询相关片段，而不是把整份文档塞进上下文。这个思路在Agent架构里非常关键，后面会展开讲。

3. Agent架构在本地环境下的重新设计

3.1 本地Agent与云端Agent的本质差异

Agent这个概念现在被讲得很多，但本地Agent和云端Agent在设计上有一个根本区别：云端Agent可以假设推理能力是充裕的，本地Agent必须假设推理能力是稀缺的。

这个假设差异会传导到整个架构。云端Agent可以设计复杂的多轮反思、自我批判、多路径探索，因为每次推理的成本相对可控。本地Agent如果也这么干，一次任务跑下来可能要几分钟甚至更久，用户体验直接崩掉。所以本地Agent的设计哲学是“一次做对”，尽量减少推理轮次。

具体怎么做？核心是把复杂度从推理阶段前移到设计阶段。比如把任务流程固化下来，用状态机而不是自由推理来控制Agent的行为。再比如用skills把常见操作封装成确定性函数，Agent只需要判断“该用哪个skill”，而不需要每次重新推理“该怎么做”。

3.2 用CLI作为Agent的执行层

CLI在本地Agent架构里扮演的角色，比很多人想象的重要。它不只是给人用的命令行工具，更是Agent调用系统能力的标准接口。

为什么用CLI而不是直接调API？因为CLI天然具备几个优势：一是可组合，一个命令的输出可以作为另一个命令的输入；二是可审计，每条命令的执行记录都清清楚楚；三是可回退，配合版本控制能轻松撤销操作。这些特性对Agent来说都是刚需。

我现在的做法是，把Agent能执行的所有操作都封装成CLI命令。Agent不直接操作文件系统、不直接调数据库，而是通过CLI这一层。这样做的好处是，Agent的行为边界被CLI的接口定义清楚了，不会出现“Agent做了意料之外的事”这种情况。同时，CLI命令本身可以被测试、被mock，整个系统的可维护性提升很多。

像codex cli这类工具，本质上就是把代码操作封装成了Agent可调用的命令集。你不需要让模型直接生成文件修改，而是让它生成一个命令，由CLI来执行。这个抽象层的价值，在本地环境下尤其明显，因为本地环境的容错空间更小。

3.3 skills机制：把能力沉淀为可复用模块

skills是我认为本地Agent最值得投入的方向。它的核心思想很简单：把Agent需要反复使用的知识和操作，从提示词里抽出来，变成独立的、可版本管理的模块。

为什么这对本地模型特别重要？因为本地模型的上下文窗口有限，你不可能把所有领域知识都塞进系统提示词。skills机制让Agent按需加载能力，用到什么加载什么，大大降低了单次推理的上下文压力。

一个典型的skill包含三部分：触发条件（什么时候该用这个skill）、执行逻辑（具体怎么做）、输出格式（返回什么结构）。触发条件通常是一段简短的描述，Agent通过语义匹配来判断是否调用。执行逻辑可以是提示词模板，也可以是CLI命令的组合。输出格式则保证了skill之间的可组合性。

我自己的skills库现在有几十个模块，覆盖代码审查、文档生成、数据清洗、格式转换等场景。每次遇到重复性任务，第一反应就是“这个能不能做成skill”。积累下来之后，Agent的能力边界明显拓宽了，但单次推理的负担并没有增加。

3.4 harness：Agent的运行时骨架

harness这个词在Agent语境下，指的是承载Agent运行的框架层。它负责管理Agent的生命周期、调度工具调用、处理错误和重试、维护状态。你可以把harness理解为Agent的“操作系统”。

本地环境下，harness的设计要特别关注资源管理。因为本地算力有限，不能让多个Agent任务同时抢占资源。我的做法是在harness层做任务队列，串行执行推理密集型的任务，并行执行IO密集型的任务。同时harness要监控显存和内存使用，在接近上限时主动降级或排队。

harness和Agent的区别，经常有人搞混。简单说，Agent是“做什么”，harness是“怎么跑”。Agent定义了任务逻辑，harness提供了执行环境。一个好的harness能让Agent开发者不用关心底层的资源调度、错误处理、日志记录这些脏活累活，专注在任务逻辑上。

4. 从零搭建本地模型Agent的实操路径

4.1 环境准备与模型加载

先说环境。我推荐用Ollama作为模型运行时，它对新手最友好，安装和加载模型都是一条命令的事。在Linux上安装Ollama：

curl -fsSL https://ollama.com/install.sh | sh

安装完成后，拉取一个适合你硬件的模型。以14B量化模型为例：

ollama pull qwen2.5:14b-instruct-q4_K_M

拉取完成后，用以下命令验证模型能正常加载和推理：

ollama run qwen2.5:14b-instruct-q4_K_M "用一句话解释什么是向量数据库"

如果这条命令能正常返回结果，说明基础环境没问题。接下来要确认API接口可用，因为Agent需要通过API调用模型：

curl http://localhost:11434/api/generate -d '{ "model": "qwen2.5:14b-instruct-q4_K_M", "prompt": "test", "stream": false }'

注意：Ollama默认监听11434端口，如果这台机器有公网暴露风险，务必配置防火墙规则，只允许本地访问。本地模型服务不应该直接暴露在网络上。

4.2 向量模型的本地部署

Agent要处理长文档和知识检索，就需要本地向量模型。这里我用easyocr之外的另一个常见需求场景来说明——文档语义检索。向量模型的选择标准是体积小、速度快、语义区分度够用。

我常用的是一个轻量级embedding模型，通过Ollama加载：

ollama pull nomic-embed-text

然后写一个简单的Python脚本来验证向量化效果：

import requests import numpy as np def get_embedding(text): response = requests.post( "http://localhost:11434/api/embeddings", json={"model": "nomic-embed-text", "prompt": text} ) return np.array(response.json()["embedding"]) vec1 = get_embedding("本地模型部署") vec2 = get_embedding("在本地运行AI模型") vec3 = get_embedding("今天天气不错") similarity_12 = np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2)) similarity_13 = np.dot(vec1, vec3) / (np.linalg.norm(vec1) * np.linalg.norm(vec3)) print(f"语义相近: {similarity_12:.4f}") print(f"语义无关: {similarity_13:.4f}")

正常情况下，语义相近的文本相似度应该在0.8以上，语义无关的应该在0.5以下。如果差距不明显，说明模型选择有问题，需要换一个embedding模型。

4.3 Agent主循环的实现

Agent的核心是一个循环：观察当前状态、决定下一步动作、执行动作、更新状态。下面是一个最小化的本地Agent实现框架：

import json import requests class LocalAgent: def __init__(self, model_name, skills, max_steps=10): self.model_name = model_name self.skills = skills self.max_steps = max_steps self.history = [] def think(self, task, context): skill_descriptions = "\n".join([ f"- {name}: {skill['description']}" for name, skill in self.skills.items() ]) prompt = f"""你是一个本地Agent，需要完成任务：{task} 当前上下文： {context} 可用技能： {skill_descriptions} 请判断下一步应该使用哪个技能，以JSON格式返回： {{"skill": "技能名", "params": {{...}}, "reasoning": "判断理由"}} 如果任务已完成，返回：{{"skill": "done", "result": "最终结果"}} """ response = requests.post( "http://localhost:11434/api/generate", json={ "model": self.model_name, "prompt": prompt, "stream": False, "format": "json" } ) return json.loads(response.json()["response"]) def execute(self, skill_name, params): if skill_name == "done": return params.get("result", "") skill = self.skills.get(skill_name) if not skill: return f"错误：未知技能 {skill_name}" return skill["execute"](**params) def run(self, task): context = "" for step in range(self.max_steps): decision = self.think(task, context) result = self.execute(decision["skill"], decision.get("params", {})) self.history.append({ "step": step, "skill": decision["skill"], "reasoning": decision.get("reasoning", ""), "result": str(result)[:500] }) if decision["skill"] == "done": return result context += f"\n步骤{step+1}：使用{decision['skill']}，结果：{str(result)[:200]}" return "达到最大步数限制，任务未完成"

这个框架的关键设计点：用format: "json"强制模型输出结构化结果，避免解析失败；限制最大步数防止无限循环；每步的结果截断后加入上下文，控制上下文长度。

4.4 一个完整的skill示例

以“代码文件审查”这个skill为例，展示skill的完整定义：

def review_code(file_path, focus="general"): with open(file_path, "r") as f: code = f.read() prompt = f"""请审查以下代码，关注点：{focus} 代码内容：

{code}

请按以下格式输出： 1. 潜在问题（按严重程度排序） 2. 改进建议 3. 代码亮点（如果有） """ response = requests.post( "http://localhost:11434/api/generate", json={ "model": "qwen2.5:14b-instruct-q4_K_M", "prompt": prompt, "stream": False } ) return response.json()["response"] code_review_skill = { "description": "审查代码文件，识别潜在问题并给出改进建议。参数：file_path（文件路径），focus（关注点，可选）", "execute": review_code }

把这个skill注册到Agent的skills字典里，Agent就能在需要时调用它。注意skill的description要写得足够清晰，因为Agent完全依赖这段描述来判断何时使用这个skill。

5. 本地模型Agent的常见问题与排查

5.1 推理速度慢到无法接受

这是最常见的抱怨。本地模型推理速度受多个因素影响，排查要按顺序来。

先确认是不是模型规模超出了硬件承载能力。用ollama ps查看模型加载后的显存占用，如果接近或超过显存上限，系统会频繁在显存和内存之间交换数据，速度自然慢。解决办法是换更小的模型或更低的量化等级。

如果硬件没问题，检查是不是上下文太长。本地推理的时间复杂度和上下文长度是平方关系，上下文翻倍，推理时间可能变成四倍。解决办法是精简提示词，把不必要的历史记录从上下文中移除。

还有一个容易被忽略的因素是并发。如果同时有多个请求打到Ollama，它会排队处理，每个请求的响应时间都会拉长。在Agent场景下，要确保同一时间只有一个推理请求在跑。

5.2 模型输出格式不稳定

本地小模型在结构化输出上的表现，确实不如大模型稳定。你要求它返回JSON，它可能返回一段带解释的文字，或者JSON格式有语法错误。

应对策略有三层。第一层是用推理框架的格式化输出功能，比如Ollama的format: "json"参数，它会在解码阶段约束输出格式。第二层是在提示词里给出明确的示例，few-shot对本地模型的效果提升很明显。第三层是在代码里做容错解析，用正则提取JSON部分，解析失败时重试或降级处理。

我实测下来，三层策略叠加之后，结构化输出的成功率能从60%左右提升到95%以上。剩下5%的失败案例，通常是任务本身太复杂，需要拆解。

5.3 Agent陷入死循环

Agent反复调用同一个skill，或者在不同skill之间来回跳转，就是死循环。根本原因是模型无法判断任务是否已经完成。

解决办法是在harness层加约束。一是设置最大步数，超过就强制终止。二是检测重复动作，如果连续两步调用了同一个skill且参数相同，就中断并报错。三是在提示词里明确告诉模型“如果任务已完成，必须返回done”，并给出done的示例。

还有一个更隐蔽的死循环原因：skill执行失败但返回了看似成功的结果，Agent以为成功了继续下一步，但下一步又依赖上一步的真实结果，于是又回到失败的skill。这种情况要在skill层面做好错误处理，失败时返回明确的错误标识，让Agent能识别并采取不同策略。

5.4 常见问题速查表

提示：排查本地模型问题时，养成先看日志的习惯。Ollama的日志在~/.ollama/logs/目录下，里面会记录每次请求的耗时、token数、错误信息。很多问题看日志就能定位，不用瞎猜。

6. 关于边界的几点个人思考

本地模型的边界，本质上是你愿意为“可控性”付出多少代价的边界。云端模型用钱换能力，本地模型用硬件和工程复杂度换可控性。这个交换是否划算，取决于你的具体场景。

我自己的判断标准是：如果任务涉及敏感数据、需要离线运行、或者调用频率高到云端成本不可接受，那就值得投入本地方案。但如果只是偶尔用用、对延迟不敏感、数据也不敏感，那云端模型仍然是更省心的选择。

Agent、CLI、skills、harness这一套体系，本质上是在本地模型的约束下，尽可能逼近云端Agent的体验。CLI提供了确定性的执行层，skills提供了可复用的能力层，harness提供了稳定的运行时。三者配合，让本地模型的能力边界向外推了一截。

但边界终究是边界。本地模型不会在所有任务上追平云端模型，就像本地数据库不会在所有场景替代云数据库一样。认清这一点，把本地模型用在它擅长的地方，才是务实的做法。

最后分享一个我踩过的坑：不要试图用一个本地模型解决所有问题。我一开始也是这么想的，结果配了一个大模型，什么任务都往里塞，速度慢不说，效果还不好。后来改成小模型做路由和简单任务，大模型只处理复杂推理，整体体验反而上去了。这个思路和微服务架构里的“合适的技术做合适的事”是一个道理。