“Perplexity AI 推出 Portable Computer 本地智能体应用”——看到这个标题很多人的第一反应是Perplexity 是不是要做硬件了其实不用急着为“电脑”两个字激动。把它放到 2025 年 AI 应用的演进路径里看真正值得关注的不是一款新设备而是智能体正在从“云端大模型 聊天框”转向“本地模型 本地工具 本地权限”的组合形态。如果你正在做 Agent 开发、AI 应用集成或者只是想找一个能离线跑、不按 token 付费的本地智能体方案这篇文章值得读完。我会先解释“本地智能体”到底是什么再拆出它和普通 Chatbot、RPA、Copilot 的区别然后给出一套可以直接跑的最小 Python 示例最后聊聊生产环境里最容易踩的坑。先说结论本地智能体并不等于“把大模型下载到电脑上”。真正的难点在于让模型安全、受控地调用本机文件、终端、浏览器和外部搜索并且把权限边界做扎实。Perplexity 这类产品把应用命名为 Portable Computer想强调的是智能体可以“携带”你的工作上下文、技能配置和任务流程从一个终端迁移到另一个终端。1. 为什么“本地智能体”突然值得关注过去一年里我们见到的绝大多数 Agent 都是“云端 Agent”。任务输入后先交给云端大模型推理再通过云端 API 调用外部工具。这种模式的好处是模型能力强、接入快但坏处也很明显数据离开本机。代码、文档、企业内部的经营数据都要先发给云端接口很多团队过不了合规这一关。成本不可控。一个复杂任务可能要多次调用模型一次任务消耗几十万 token 并不罕见。延迟不稳定。网络抖动、服务排队都会让 Agent 的交互体验变得很“重”。离线不可用。在本地开发、差旅、内网环境里云端 Agent 基本失效。Perplexity AI 做搜索起家核心能力是“检索 综合回答”。如果它把这类能力封装成一个跑在用户本机的“本地智能体应用”那方向其实很明确让 AI 的推理可以落到本地模型上让检索能力和本机文件、浏览器上下文打通同时把敏感数据留在本机。这里有一个容易被误解的点本地智能体不是“不需要联网”而是“不必把所有数据都交给云端”。它仍然可能通过一个个工具接口去访问搜索、数据库或内部系统但会话状态、工具调用、权限检查都在本地完成。对开发者来说价值在于你可以把 Agent 训练成一支“本地任务队列”而不是一次性的问答服务。2. “Portable Computer”到底解决什么问题单纯从名字看“Portable Computer”会被理解成个人电脑。但如果把“Portable”理解为“可携带的工作环境”就会更接近这类产品的本意。假设你有一套智能体配置它知道你常用的代码仓库路径知道你的纪要模板知道应该调用哪个本地模型知道哪些目录可以被写入。以前这些配置散落在各个脚本和命令行参数里。换成“Portable Computer”这类本地智能体应用后这套配置可以打包成一个可迁移的工作区换一台电脑跑一个注册命令智能体的工具、模型、上下文就都恢复出来了。所以它解决的真正问题是本地智能体如何变成你的“数字工作台”而不是一次性的玩具 Demo。很多团队已经有本地模型但一直没有把 Agent 工程化原因不是模型不行而是缺少四个环节工具注册、任务编排、状态管理、权限控制。这四个环节才是本地智能体的骨架。另一方面热搜词里有“本地免费智能体”。这听起来很吸引人但我建议换个角度看本地智能体不是零成本而是把成本从“API 账单”转移到了“硬件成本和维护成本”。一台能流畅跑 7B 参数模型的家用电脑要求并不低你还得处理依赖、更新模型、调试工具调用。所谓“免费”更多是指没有按 token 付费的心理负担。3. 本地智能体的核心概念与边界要把本地智能体讲清楚先得把它和几个容易混淆的概念区分开。概念核心特点典型形态本地智能体 vs 它Chatbot单轮/多轮问答没有任务执行能力ChatGPT、各类百科机器人智能体多出“调用工具”和“完成任务”的能力RPA按固定规则操作界面、鼠标、键盘按键精灵、UIPath智能体可以根据任务目标动态编排步骤不是固定流程Copilot面向特定场景的辅助生成通常由人确认代码补全、文档助手智能体被赋予更多自主权可以在边界内自行执行Local Agent模型、工具、权限、记忆都在本机本文演示的 Agent强调数据不出本机、可离线、可定制再往下拆本地智能体通常包含五个核心能力意图理解与任务拆解把用户一句自然语言拆成多个子任务。工具调用读取文件、写文件、执行命令、查数据库、调用外部搜索 API。上下文管理维护会话历史、临时记忆、长期记忆。决策与终止判断任务是否完成是否需要继续调用工具。权限控制限制能访问的目录、能执行的命令、能调用的外部接口。如果你做过 Agent会知道前四点是工程问题第五点才是安全问题。许多 Demo 能跑通是因为根本没有做权限控制一旦接入真实工作环境本地智能体会变成一个拥有“高权限”的自动化脚本这是非常危险的。4. 技术架构一个本地智能体由哪几层组成下面是一个比较通用的本地智能体分层架构不特别绑定某一家产品层级职责常见技术模型层推理、生成、意图理解Ollama、vLLM、llama.cpp、云端 API智能体核心层任务拆解、工具选择、状态流转ReAct、Plan-and-Execute、LangGraph、自研循环工具层暴露本机和外部能力命令行、文件系统、浏览器、搜索 API、MCP记忆层存储短期和长期上下文SQLite、向量数据库、JSON 会话文件权限层校验每个工具调用是否被允许ACL、白名单、沙箱、审计日志很多本地智能体项目写不好问题不在模型层而在智能体核心层的“重复循环”没写清楚。一个最简单的智能体循环是接收用户诉求 - 调用模型 - 判断是否需要工具 - 执行工具 - 把结果回填给模型 - 再次判断 - 输出最终答案听起来简单但实际工程里需要处理多轮工具调用、异常、超时、模型输出格式错误、上下文超长等一堆问题。下面我们用一个最小 Demo 把这个循环跑通。5. 环境准备与前置条件为了让示例尽量通用我采用“OpenAI 兼容接口 任意本地模型服务”的方式。也就是说只要你的本地模型工具能提供一个 HTTP 接口下面的代码就能适配。5.1 推荐环境Python 3.10 及以上一台至少 16GB 内存的电脑如果跑 7B 模型内存越大越流畅本地模型服务例如 Ollama 或 llama.cpp代码编辑器、命令行终端版本细节请以实际项目为准下面重点演示通用思路。如果你用 Ollama启动后再拉取一个模型常见地址是http://127.0.0.1:11434Ollama 的 OpenAI 兼容接口一般在/v1路径下。如果版本有差异以本地服务实际日志为准。5.2 创建项目目录mkdir local-agent-demo cd local-agent-demo python -m venv .venv source .venv/bin/activate5.3 安装依赖示例代码尽量用 Python 标准库只额外用 PyYAML 读取配置文件。# requirements.txt pyyaml6.0安装命令pip install -r requirements.txt5.4 准备配置文件我用一个config.yaml描述智能体的基本信息。把工作目录限定在./workspace避免 Agent 乱读系统文件。# config.yaml agent: name: local-agent-demo model: qwen2.5:7b base_url: http://127.0.0.1:11434 temperature: 0.2 max_steps: 5 workspace: ./workspace这里需要注意model名称必须与你本地模型服务里实际存在的模型一致。如果不存在运行时会报模型不存在或 404 错误。6. 完整示例代码实现下面实现一个最小的本地智能体。它具备三个工具数学计算、读取文件、追加文件。整个过程会让模型先判断是否需要调用工具如果需要就输出一个 JSON 动作由程序执行后把结果回填给模型。代码如下# local_agent/agent.py import ast import json import operator import os import urllib.request import yaml SYSTEM_PROMPT 你是一个运行在用户本机上的本地智能体。 你可以使用以下工具完成用户的任务 1. calculator: 计算数学表达式参数为 {expr: 1 2 * 3} 2. read_file: 读取工作区内的文本文件参数为 {path: notes.txt} 3. append_file: 向工作区内的文本文件追加内容参数为 {path: notes.txt, content: 要追加的内容} 如果需要调用工具请只返回一个 JSON 对象不要包含 markdown 代码块不要输出其他文字。 如果不需要调用工具直接给用户最终回答。 _ALLOWED_OPS { ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul, ast.Div: operator.truediv, ast.Mod: operator.mod, } def safe_math(expr): 只允许数字常量和基础运算的表达式求值避免直接 eval。 tree ast.parse(expr, modeeval) def evaluate(node): if isinstance(node, ast.Expression): return evaluate(node.body) if isinstance(node, ast.Constant): if isinstance(node.value, (int, float)): return node.value raise ValueError(只允许数字常量) if isinstance(node, ast.BinOp): if type(node.op) in _ALLOWED_OPS: return _ALLOWED_OPS[type(node.op)]( evaluate(node.left), evaluate(node.right) ) raise ValueError(不支持的运算) if isinstance(node, ast.UnaryOp): if isinstance(node.op, ast.USub): return -evaluate(node.operand) if isinstance(node.op, ast.UAdd): return evaluate(node.operand) raise ValueError(不支持的一元运算) raise ValueError(不支持的表达式) return evaluate(tree) def safe_resolve_workspace_path(workspace, path): 防止读取或写入工作区之外的路径。 base os.path.abspath(workspace) target os.path.abspath(os.path.join(base, path)) if not target.startswith(base): raise PermissionError(f路径超出工作区: {path}) return target def read_file(workspace, path): target safe_resolve_workspace_path(workspace, path) with open(target, r, encodingutf-8) as f: return f.read() def append_file(workspace, path, content): target safe_resolve_workspace_path(workspace, path) os.makedirs(os.path.dirname(target), exist_okTrue) with open(target, a, encodingutf-8) as f: f.write(content \n) return append ok def execute_action(action, workspace): tool action.get(tool) args action.get(args, {}) or {} if tool calculator: return safe_math(args[expr]) if tool read_file: return read_file(workspace, args[path]) if tool append_file: return append_file(workspace, args[path], args[content]) raise ValueError(f未知工具: {tool}) def extract_json(text): start text.find({) end text.rfind(}) if start -1 or end -1 or end start: raise ValueError(未找到 JSON 对象) return json.loads(text[start:end 1]) def parse_action(text): try: obj extract_json(text) if isinstance(obj, dict) and tool in obj: obj[args] obj.get(args) or {} return obj except (ValueError, json.JSONDecodeError): pass return None class LocalAgent: def __init__(self, base_url, model, workspace, temperature0.2, api_keyNone, system_promptSYSTEM_PROMPT, max_steps5): self.base_url base_url.rstrip(/) self.model model self.api_key api_key self.temperature temperature self.workspace workspace self.max_steps max_steps self.messages [{role: system, content: system_prompt}] def chat(self, messages): payload { model: self.model, messages: messages, temperature: self.temperature, stream: False, } headers {Content-Type: application/json} if self.api_key: headers[Authorization] fBearer {self.api_key} request urllib.request.Request( f{self.base_url}/v1/chat/completions, datajson.dumps(payload).encode(utf-8), headersheaders, methodPOST, ) with urllib.request.urlopen(request, timeout180) as response: body json.loads(response.read().decode(utf-8)) return body[choices][0][message][content] def run(self, user_input): self.messages.append({role: user, content: user_input}) for _ in range(self.max_steps): reply self.chat(self.messages) action parse_action(reply) # 没有工具调用说明可以输出最终结果 if action is None: self.messages.append({role: assistant, content: reply}) return reply # 执行工具调用并把结果回填给模型 try: result execute_action(action, self.workspace) except Exception as exc: result {error: str(exc)} self.messages.append({role: assistant, content: reply}) self.messages.append({ role: user, content: faction_result: {json.dumps(result, ensure_asciiFalse)} }) raise RuntimeError(智能体执行步骤超过 max_steps任务未完成) def load_config(path): with open(path, r, encodingutf-8) as f: return yaml.safe_load(f) def main(): config load_config(config.yaml) agent_config config[agent] agent LocalAgent( base_urlagent_config[base_url], modelagent_config[model], workspaceagent_config[workspace], temperatureagent_config.get(temperature, 0.2), max_stepsagent_config.get(max_steps, 5), ) os.makedirs(agent.workspace, exist_okTrue) print(本地智能体已启动输入 exit 或 quit 退出。) while True: try: user_input input(你 ).strip() except (EOFError, KeyboardInterrupt): break if not user_input: continue if user_input.lower() in {exit, quit}: break output agent.run(user_input) print(Agent, output) if __name__ __main__: main()这段代码的关键逻辑有三个安全求值safe_math用 AST 解析表达式只放行数字和基础运算符而不是直接使用eval。路径白名单safe_resolve_workspace_path会把相对路径解析后强制限定在工作区目录内防止../穿越。循环结构run方法会在用户消息和工具执行结果之间反复调用模型直到模型认为任务完成。7. 运行结果与效果验证启动本地模型服务后在项目目录执行python local_agent/agent.py如果配置正确会看到本地智能体已启动输入 exit 或 quit 退出。 你我们可以依次测试三个能力。7.1 测试数学计算你 帮我计算 (12 88) * 3如果模型正确输出了 JSON 动作Agent 会调用calculator然后输出类似Agent 300这个测试是为了验证“工具调用回路”是否通模型生成了 JSON程序解析了 JSON执行了工具又让模型基于结果生成最终回答。7.2 测试文件写入你 把 2025-03-01 计划完成本地智能体文章 追加到 notes.txt然后查看工作区cat workspace/notes.txt如果能看到追加内容说明文件工具链路正常。7.3 测试文件读取你 读取 notes.txt如果模型把文件内容读出来说明多步状态回填成功。7.4 验证失败时的排查顺序如果 Agent 没有调用工具而是直接硬答先检查模型是否支持遵循复杂的 JSON 指令。小参数模型可能经常输出多余文字。System Prompt 是否足够严格。可以把“不要输出 markdown 代码块”写得再清楚一些。本地模型服务是否真的监听了/v1路径。可以先用 curl 验证curl http://127.0.0.1:11434/v1/models如果返回模型列表说明 OpenAI 兼容接口可用如果 404说明要检查服务配置或使用原生接口。8. 常见问题与排查思路问题现象可能原因排查方式解决方案启动时提示模型不存在配置里的模型名与本地服务不一致用/v1/models查看模型列表修改config.yaml中的模型名运行时接口 404本地服务没有启用 OpenAI 兼容接口查看服务启动日志和/v1/models响应升级服务版本或改用服务支持的原生接口Agent 不调用工具总是直接回答模型指令遵循能力弱打印模型完整输出检查输出中是否有 JSON换成更大的模型或调整 System Prompt输出一长串 JSON 但解析失败模型在 JSON 前后加了 标记或解释文字检查extract_json是否截取到了完整 JSON在 System Prompt 中强调不要输出额外文字文件操作提示权限错误路径中存在..或绝对路径查看异常信息中的路径把要操作的文件放到工作区内执行步骤超时模型响应太慢或进入死循环降低max_steps查看调用日志检查模型负载或为工具调用增加超时限制内存不足导致模型卡顿电脑配置跑不动当前模型查看 CPU/GPU 内存占用换用量化版本或更小参数量的模型这里最容易被忽视的是“模型输出格式”问题。本地模型和云端模型不一样云端模型经过大量指令微调输出 JSON 很稳定本地开源模型如果没做过强化训练可能第一次返回 JSON第二次就开始说“好的我来帮你计算”。所以在工程上解析层要尽量宽容但也不能盲目接受危险参数。9. 最佳实践与工程建议把本地智能体从 Demo 推进到实际项目有六个建议值得提前记下。9.1 权限控制是最优先级本地智能体最大的优势是能调用本机资源最大的风险也在这里。任何工具调用都要有白名单、路径校验和审计日志。不要让 Agent 默认拥有“执行任意命令”的权限。如果必须执行命令至少要做命令白名单、超时控制、输出截断、非 root 用户运行。9.2 把工具做成可观测的每次工具调用都要记录调用时间、工具名、参数、返回结果、耗时。没有日志的 Agent 在线上几乎无法排查问题。建议把run方法里的工具执行分支加上日志[2025-03-01 12:00:01] toolcalculator args{expr: (12 88) * 3} result3009.3 设置任务执行上限本地智能体不应该无限循环。max_steps、单次工具超时、总执行时间都要有限制。否则一个错误 Prompt 可能让模型连续调用几十次工具浪费算力。9.4 选择合适大小的本地模型普通办公电脑上7B 模型比 70B 模型实用得多。可以先从量化版本开始跑通流程后再根据效果决定是否升级。不要把“跑得动”和“效果好”混为一谈预留性能测试时间。9.5 上下文管理要趁早做这个 Demo 只是把消息全部存在内存里真实场景很快就会撞上模型上下文窗口限制。后续要引入会话窗口裁剪、摘要压缩、向量检索记忆库。建议在第一天就考虑“哪些内容必须长期保存哪些内容用完即丢”。9.6 备份和回滚要覆盖配置本地智能体一旦能改文件就具备了自动化修改项目、文档甚至数据库入口的潜力。任何可能产生写入的操作都要考虑“改坏了能不能回滚”。工作区建议纳入 Git 管理工具函数里涉及关键写入时可以先写临时文件再做原子替换。10. 总结与后续学习方向本地智能体是“云端 Agent”之外的一条重要技术路线。它把模型的推理能力、工具的执行能力、本机的数据资产和用户的权限边界放在同一个进程里管理。Perplexity AI 推出 Portable Computer 这类本地智能体应用本质上是在告诉开发者不要把 AI 应用做成云端大模型的代理而应该把 AI 应用做成用户本机的一个可编程工作台。如果你想继续深入三个方向最值得投入工具协议标准化研究 MCP 这类协议把本地文件、数据库、浏览器、搜索服务统一成一套工具接口。本地检索增强把本地知识库用向量数据库组织起来让智能体在回答前先检索本地文档而不是直接把整篇文档塞进上下文。评测与回归给本地智能体建一份自动化评测集每次改 Prompt、换模型、加工具后跑一遍回归测试避免“改一个工具丢三个能力”。这篇文章里的最小示例代码并不复杂但它已经包含了本地智能体的核心循环模型、工具、状态、权限。你完全可以在它基础上扩展自己的工具集也可以把它接到现有办公流程里。只是想提醒一点不要让智能体拥有超过它实际需要的权限永远给它一个“只读优先、写入受控、执行有痕”的工作环境。这是本地智能体从玩具走向生产工具的关键一步。
本地智能体实战：从Perplexity Portable Computer到最小Python实现
“Perplexity AI 推出 Portable Computer 本地智能体应用”——看到这个标题很多人的第一反应是Perplexity 是不是要做硬件了其实不用急着为“电脑”两个字激动。把它放到 2025 年 AI 应用的演进路径里看真正值得关注的不是一款新设备而是智能体正在从“云端大模型 聊天框”转向“本地模型 本地工具 本地权限”的组合形态。如果你正在做 Agent 开发、AI 应用集成或者只是想找一个能离线跑、不按 token 付费的本地智能体方案这篇文章值得读完。我会先解释“本地智能体”到底是什么再拆出它和普通 Chatbot、RPA、Copilot 的区别然后给出一套可以直接跑的最小 Python 示例最后聊聊生产环境里最容易踩的坑。先说结论本地智能体并不等于“把大模型下载到电脑上”。真正的难点在于让模型安全、受控地调用本机文件、终端、浏览器和外部搜索并且把权限边界做扎实。Perplexity 这类产品把应用命名为 Portable Computer想强调的是智能体可以“携带”你的工作上下文、技能配置和任务流程从一个终端迁移到另一个终端。1. 为什么“本地智能体”突然值得关注过去一年里我们见到的绝大多数 Agent 都是“云端 Agent”。任务输入后先交给云端大模型推理再通过云端 API 调用外部工具。这种模式的好处是模型能力强、接入快但坏处也很明显数据离开本机。代码、文档、企业内部的经营数据都要先发给云端接口很多团队过不了合规这一关。成本不可控。一个复杂任务可能要多次调用模型一次任务消耗几十万 token 并不罕见。延迟不稳定。网络抖动、服务排队都会让 Agent 的交互体验变得很“重”。离线不可用。在本地开发、差旅、内网环境里云端 Agent 基本失效。Perplexity AI 做搜索起家核心能力是“检索 综合回答”。如果它把这类能力封装成一个跑在用户本机的“本地智能体应用”那方向其实很明确让 AI 的推理可以落到本地模型上让检索能力和本机文件、浏览器上下文打通同时把敏感数据留在本机。这里有一个容易被误解的点本地智能体不是“不需要联网”而是“不必把所有数据都交给云端”。它仍然可能通过一个个工具接口去访问搜索、数据库或内部系统但会话状态、工具调用、权限检查都在本地完成。对开发者来说价值在于你可以把 Agent 训练成一支“本地任务队列”而不是一次性的问答服务。2. “Portable Computer”到底解决什么问题单纯从名字看“Portable Computer”会被理解成个人电脑。但如果把“Portable”理解为“可携带的工作环境”就会更接近这类产品的本意。假设你有一套智能体配置它知道你常用的代码仓库路径知道你的纪要模板知道应该调用哪个本地模型知道哪些目录可以被写入。以前这些配置散落在各个脚本和命令行参数里。换成“Portable Computer”这类本地智能体应用后这套配置可以打包成一个可迁移的工作区换一台电脑跑一个注册命令智能体的工具、模型、上下文就都恢复出来了。所以它解决的真正问题是本地智能体如何变成你的“数字工作台”而不是一次性的玩具 Demo。很多团队已经有本地模型但一直没有把 Agent 工程化原因不是模型不行而是缺少四个环节工具注册、任务编排、状态管理、权限控制。这四个环节才是本地智能体的骨架。另一方面热搜词里有“本地免费智能体”。这听起来很吸引人但我建议换个角度看本地智能体不是零成本而是把成本从“API 账单”转移到了“硬件成本和维护成本”。一台能流畅跑 7B 参数模型的家用电脑要求并不低你还得处理依赖、更新模型、调试工具调用。所谓“免费”更多是指没有按 token 付费的心理负担。3. 本地智能体的核心概念与边界要把本地智能体讲清楚先得把它和几个容易混淆的概念区分开。概念核心特点典型形态本地智能体 vs 它Chatbot单轮/多轮问答没有任务执行能力ChatGPT、各类百科机器人智能体多出“调用工具”和“完成任务”的能力RPA按固定规则操作界面、鼠标、键盘按键精灵、UIPath智能体可以根据任务目标动态编排步骤不是固定流程Copilot面向特定场景的辅助生成通常由人确认代码补全、文档助手智能体被赋予更多自主权可以在边界内自行执行Local Agent模型、工具、权限、记忆都在本机本文演示的 Agent强调数据不出本机、可离线、可定制再往下拆本地智能体通常包含五个核心能力意图理解与任务拆解把用户一句自然语言拆成多个子任务。工具调用读取文件、写文件、执行命令、查数据库、调用外部搜索 API。上下文管理维护会话历史、临时记忆、长期记忆。决策与终止判断任务是否完成是否需要继续调用工具。权限控制限制能访问的目录、能执行的命令、能调用的外部接口。如果你做过 Agent会知道前四点是工程问题第五点才是安全问题。许多 Demo 能跑通是因为根本没有做权限控制一旦接入真实工作环境本地智能体会变成一个拥有“高权限”的自动化脚本这是非常危险的。4. 技术架构一个本地智能体由哪几层组成下面是一个比较通用的本地智能体分层架构不特别绑定某一家产品层级职责常见技术模型层推理、生成、意图理解Ollama、vLLM、llama.cpp、云端 API智能体核心层任务拆解、工具选择、状态流转ReAct、Plan-and-Execute、LangGraph、自研循环工具层暴露本机和外部能力命令行、文件系统、浏览器、搜索 API、MCP记忆层存储短期和长期上下文SQLite、向量数据库、JSON 会话文件权限层校验每个工具调用是否被允许ACL、白名单、沙箱、审计日志很多本地智能体项目写不好问题不在模型层而在智能体核心层的“重复循环”没写清楚。一个最简单的智能体循环是接收用户诉求 - 调用模型 - 判断是否需要工具 - 执行工具 - 把结果回填给模型 - 再次判断 - 输出最终答案听起来简单但实际工程里需要处理多轮工具调用、异常、超时、模型输出格式错误、上下文超长等一堆问题。下面我们用一个最小 Demo 把这个循环跑通。5. 环境准备与前置条件为了让示例尽量通用我采用“OpenAI 兼容接口 任意本地模型服务”的方式。也就是说只要你的本地模型工具能提供一个 HTTP 接口下面的代码就能适配。5.1 推荐环境Python 3.10 及以上一台至少 16GB 内存的电脑如果跑 7B 模型内存越大越流畅本地模型服务例如 Ollama 或 llama.cpp代码编辑器、命令行终端版本细节请以实际项目为准下面重点演示通用思路。如果你用 Ollama启动后再拉取一个模型常见地址是http://127.0.0.1:11434Ollama 的 OpenAI 兼容接口一般在/v1路径下。如果版本有差异以本地服务实际日志为准。5.2 创建项目目录mkdir local-agent-demo cd local-agent-demo python -m venv .venv source .venv/bin/activate5.3 安装依赖示例代码尽量用 Python 标准库只额外用 PyYAML 读取配置文件。# requirements.txt pyyaml6.0安装命令pip install -r requirements.txt5.4 准备配置文件我用一个config.yaml描述智能体的基本信息。把工作目录限定在./workspace避免 Agent 乱读系统文件。# config.yaml agent: name: local-agent-demo model: qwen2.5:7b base_url: http://127.0.0.1:11434 temperature: 0.2 max_steps: 5 workspace: ./workspace这里需要注意model名称必须与你本地模型服务里实际存在的模型一致。如果不存在运行时会报模型不存在或 404 错误。6. 完整示例代码实现下面实现一个最小的本地智能体。它具备三个工具数学计算、读取文件、追加文件。整个过程会让模型先判断是否需要调用工具如果需要就输出一个 JSON 动作由程序执行后把结果回填给模型。代码如下# local_agent/agent.py import ast import json import operator import os import urllib.request import yaml SYSTEM_PROMPT 你是一个运行在用户本机上的本地智能体。 你可以使用以下工具完成用户的任务 1. calculator: 计算数学表达式参数为 {expr: 1 2 * 3} 2. read_file: 读取工作区内的文本文件参数为 {path: notes.txt} 3. append_file: 向工作区内的文本文件追加内容参数为 {path: notes.txt, content: 要追加的内容} 如果需要调用工具请只返回一个 JSON 对象不要包含 markdown 代码块不要输出其他文字。 如果不需要调用工具直接给用户最终回答。 _ALLOWED_OPS { ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul, ast.Div: operator.truediv, ast.Mod: operator.mod, } def safe_math(expr): 只允许数字常量和基础运算的表达式求值避免直接 eval。 tree ast.parse(expr, modeeval) def evaluate(node): if isinstance(node, ast.Expression): return evaluate(node.body) if isinstance(node, ast.Constant): if isinstance(node.value, (int, float)): return node.value raise ValueError(只允许数字常量) if isinstance(node, ast.BinOp): if type(node.op) in _ALLOWED_OPS: return _ALLOWED_OPS[type(node.op)]( evaluate(node.left), evaluate(node.right) ) raise ValueError(不支持的运算) if isinstance(node, ast.UnaryOp): if isinstance(node.op, ast.USub): return -evaluate(node.operand) if isinstance(node.op, ast.UAdd): return evaluate(node.operand) raise ValueError(不支持的一元运算) raise ValueError(不支持的表达式) return evaluate(tree) def safe_resolve_workspace_path(workspace, path): 防止读取或写入工作区之外的路径。 base os.path.abspath(workspace) target os.path.abspath(os.path.join(base, path)) if not target.startswith(base): raise PermissionError(f路径超出工作区: {path}) return target def read_file(workspace, path): target safe_resolve_workspace_path(workspace, path) with open(target, r, encodingutf-8) as f: return f.read() def append_file(workspace, path, content): target safe_resolve_workspace_path(workspace, path) os.makedirs(os.path.dirname(target), exist_okTrue) with open(target, a, encodingutf-8) as f: f.write(content \n) return append ok def execute_action(action, workspace): tool action.get(tool) args action.get(args, {}) or {} if tool calculator: return safe_math(args[expr]) if tool read_file: return read_file(workspace, args[path]) if tool append_file: return append_file(workspace, args[path], args[content]) raise ValueError(f未知工具: {tool}) def extract_json(text): start text.find({) end text.rfind(}) if start -1 or end -1 or end start: raise ValueError(未找到 JSON 对象) return json.loads(text[start:end 1]) def parse_action(text): try: obj extract_json(text) if isinstance(obj, dict) and tool in obj: obj[args] obj.get(args) or {} return obj except (ValueError, json.JSONDecodeError): pass return None class LocalAgent: def __init__(self, base_url, model, workspace, temperature0.2, api_keyNone, system_promptSYSTEM_PROMPT, max_steps5): self.base_url base_url.rstrip(/) self.model model self.api_key api_key self.temperature temperature self.workspace workspace self.max_steps max_steps self.messages [{role: system, content: system_prompt}] def chat(self, messages): payload { model: self.model, messages: messages, temperature: self.temperature, stream: False, } headers {Content-Type: application/json} if self.api_key: headers[Authorization] fBearer {self.api_key} request urllib.request.Request( f{self.base_url}/v1/chat/completions, datajson.dumps(payload).encode(utf-8), headersheaders, methodPOST, ) with urllib.request.urlopen(request, timeout180) as response: body json.loads(response.read().decode(utf-8)) return body[choices][0][message][content] def run(self, user_input): self.messages.append({role: user, content: user_input}) for _ in range(self.max_steps): reply self.chat(self.messages) action parse_action(reply) # 没有工具调用说明可以输出最终结果 if action is None: self.messages.append({role: assistant, content: reply}) return reply # 执行工具调用并把结果回填给模型 try: result execute_action(action, self.workspace) except Exception as exc: result {error: str(exc)} self.messages.append({role: assistant, content: reply}) self.messages.append({ role: user, content: faction_result: {json.dumps(result, ensure_asciiFalse)} }) raise RuntimeError(智能体执行步骤超过 max_steps任务未完成) def load_config(path): with open(path, r, encodingutf-8) as f: return yaml.safe_load(f) def main(): config load_config(config.yaml) agent_config config[agent] agent LocalAgent( base_urlagent_config[base_url], modelagent_config[model], workspaceagent_config[workspace], temperatureagent_config.get(temperature, 0.2), max_stepsagent_config.get(max_steps, 5), ) os.makedirs(agent.workspace, exist_okTrue) print(本地智能体已启动输入 exit 或 quit 退出。) while True: try: user_input input(你 ).strip() except (EOFError, KeyboardInterrupt): break if not user_input: continue if user_input.lower() in {exit, quit}: break output agent.run(user_input) print(Agent, output) if __name__ __main__: main()这段代码的关键逻辑有三个安全求值safe_math用 AST 解析表达式只放行数字和基础运算符而不是直接使用eval。路径白名单safe_resolve_workspace_path会把相对路径解析后强制限定在工作区目录内防止../穿越。循环结构run方法会在用户消息和工具执行结果之间反复调用模型直到模型认为任务完成。7. 运行结果与效果验证启动本地模型服务后在项目目录执行python local_agent/agent.py如果配置正确会看到本地智能体已启动输入 exit 或 quit 退出。 你我们可以依次测试三个能力。7.1 测试数学计算你 帮我计算 (12 88) * 3如果模型正确输出了 JSON 动作Agent 会调用calculator然后输出类似Agent 300这个测试是为了验证“工具调用回路”是否通模型生成了 JSON程序解析了 JSON执行了工具又让模型基于结果生成最终回答。7.2 测试文件写入你 把 2025-03-01 计划完成本地智能体文章 追加到 notes.txt然后查看工作区cat workspace/notes.txt如果能看到追加内容说明文件工具链路正常。7.3 测试文件读取你 读取 notes.txt如果模型把文件内容读出来说明多步状态回填成功。7.4 验证失败时的排查顺序如果 Agent 没有调用工具而是直接硬答先检查模型是否支持遵循复杂的 JSON 指令。小参数模型可能经常输出多余文字。System Prompt 是否足够严格。可以把“不要输出 markdown 代码块”写得再清楚一些。本地模型服务是否真的监听了/v1路径。可以先用 curl 验证curl http://127.0.0.1:11434/v1/models如果返回模型列表说明 OpenAI 兼容接口可用如果 404说明要检查服务配置或使用原生接口。8. 常见问题与排查思路问题现象可能原因排查方式解决方案启动时提示模型不存在配置里的模型名与本地服务不一致用/v1/models查看模型列表修改config.yaml中的模型名运行时接口 404本地服务没有启用 OpenAI 兼容接口查看服务启动日志和/v1/models响应升级服务版本或改用服务支持的原生接口Agent 不调用工具总是直接回答模型指令遵循能力弱打印模型完整输出检查输出中是否有 JSON换成更大的模型或调整 System Prompt输出一长串 JSON 但解析失败模型在 JSON 前后加了 标记或解释文字检查extract_json是否截取到了完整 JSON在 System Prompt 中强调不要输出额外文字文件操作提示权限错误路径中存在..或绝对路径查看异常信息中的路径把要操作的文件放到工作区内执行步骤超时模型响应太慢或进入死循环降低max_steps查看调用日志检查模型负载或为工具调用增加超时限制内存不足导致模型卡顿电脑配置跑不动当前模型查看 CPU/GPU 内存占用换用量化版本或更小参数量的模型这里最容易被忽视的是“模型输出格式”问题。本地模型和云端模型不一样云端模型经过大量指令微调输出 JSON 很稳定本地开源模型如果没做过强化训练可能第一次返回 JSON第二次就开始说“好的我来帮你计算”。所以在工程上解析层要尽量宽容但也不能盲目接受危险参数。9. 最佳实践与工程建议把本地智能体从 Demo 推进到实际项目有六个建议值得提前记下。9.1 权限控制是最优先级本地智能体最大的优势是能调用本机资源最大的风险也在这里。任何工具调用都要有白名单、路径校验和审计日志。不要让 Agent 默认拥有“执行任意命令”的权限。如果必须执行命令至少要做命令白名单、超时控制、输出截断、非 root 用户运行。9.2 把工具做成可观测的每次工具调用都要记录调用时间、工具名、参数、返回结果、耗时。没有日志的 Agent 在线上几乎无法排查问题。建议把run方法里的工具执行分支加上日志[2025-03-01 12:00:01] toolcalculator args{expr: (12 88) * 3} result3009.3 设置任务执行上限本地智能体不应该无限循环。max_steps、单次工具超时、总执行时间都要有限制。否则一个错误 Prompt 可能让模型连续调用几十次工具浪费算力。9.4 选择合适大小的本地模型普通办公电脑上7B 模型比 70B 模型实用得多。可以先从量化版本开始跑通流程后再根据效果决定是否升级。不要把“跑得动”和“效果好”混为一谈预留性能测试时间。9.5 上下文管理要趁早做这个 Demo 只是把消息全部存在内存里真实场景很快就会撞上模型上下文窗口限制。后续要引入会话窗口裁剪、摘要压缩、向量检索记忆库。建议在第一天就考虑“哪些内容必须长期保存哪些内容用完即丢”。9.6 备份和回滚要覆盖配置本地智能体一旦能改文件就具备了自动化修改项目、文档甚至数据库入口的潜力。任何可能产生写入的操作都要考虑“改坏了能不能回滚”。工作区建议纳入 Git 管理工具函数里涉及关键写入时可以先写临时文件再做原子替换。10. 总结与后续学习方向本地智能体是“云端 Agent”之外的一条重要技术路线。它把模型的推理能力、工具的执行能力、本机的数据资产和用户的权限边界放在同一个进程里管理。Perplexity AI 推出 Portable Computer 这类本地智能体应用本质上是在告诉开发者不要把 AI 应用做成云端大模型的代理而应该把 AI 应用做成用户本机的一个可编程工作台。如果你想继续深入三个方向最值得投入工具协议标准化研究 MCP 这类协议把本地文件、数据库、浏览器、搜索服务统一成一套工具接口。本地检索增强把本地知识库用向量数据库组织起来让智能体在回答前先检索本地文档而不是直接把整篇文档塞进上下文。评测与回归给本地智能体建一份自动化评测集每次改 Prompt、换模型、加工具后跑一遍回归测试避免“改一个工具丢三个能力”。这篇文章里的最小示例代码并不复杂但它已经包含了本地智能体的核心循环模型、工具、状态、权限。你完全可以在它基础上扩展自己的工具集也可以把它接到现有办公流程里。只是想提醒一点不要让智能体拥有超过它实际需要的权限永远给它一个“只读优先、写入受控、执行有痕”的工作环境。这是本地智能体从玩具走向生产工具的关键一步。