在本地电脑上跑智能体

这篇适合谁，读完能做什么

适合有代码或文档不便上传云端、想试试本地模型，或者只想省下按 token 计费的开发者。读完你应该能在一台普通电脑上装好 Foundry Local、跑起 Qwen 模型，并知道怎样让它调用工具、检索本地文档，以及什么时候应该把任务交给云端模型。^[1]

为什么要在本地跑智能体

在本地跑智能体有三个理由，在工程工作中经常遇到：^[1]^[2]

隐私：代码和文档不离开这台机器，提示词、代码片段和客户数据都不会穿过网络边界。
成本：本地推理没有按 token 计费的账单，全天迭代的成本只是电费。
离线：在飞机上、安全设施里或网络中断时，智能体仍然能工作。^[1]

代价是用小语言模型（SLM）替代云端的前沿大模型。SLM 运行在 CPU、GPU 或 NPU 上，参数量小得多。

SLM 擅长结构化、边界清晰的任务，比如对已知文档做分类、抽取和摘要，也擅长调用工具，决定调用哪个函数、传什么参数，以及在自己的数据上快速、低成本、私密地迭代。它不擅长跨长上下文的开放式多步推理，也缺少广泛的世界知识。^[1]

所以本地智能体的思路是：让 SLM 负责编排，让工具干重活。模型不需要记住整个代码库，只需要知道什么时候调用 read_file 和 search_docs，这正好发挥它的长处。^[1]

Foundry Local：本地的 OpenAI 兼容接口

Microsoft Foundry Local 是一个轻量运行时，在本机上下载、管理并提供模型服务。它最重要的特点是暴露了 OpenAI 兼容的 HTTP 接口。OpenAI SDK 和 Microsoft Agent Framework 的 OpenAI 客户端只需要改 base_url，就能直接使用它。之前在云端写的智能体代码基本能照搬，变的只是端点，从云端换成了本机。^[1]

Foundry Local 还会根据硬件自动选择模型的版本，可能是 CPU 版、CUDA/GPU 版或 NPU 版，不必为每台机器手动优化。^[1]

安装和启动

按照官方文档，为你的操作系统安装 Foundry Local^[2]。然后下载并运行一个 Qwen 模型，检查服务状态：^[1]

# Install (example; follow the docs for your platform)
winget install Microsoft.FoundryLocal      # Windows
# brew install microsoft/foundrylocal/foundrylocal   # macOS

# Download and run a Qwen model, then start the local service
foundry model run qwen2.5-7b-instruct
foundry service status

服务启动后，本机会有一个 OpenAI 兼容的端点，通常形如 http://localhost:PORT/v1^[1]。示例笔记本用 foundry-local-sdk 自动发现端点，不需要把端口号写死在代码里。^[1]

为什么选 Qwen 做本地智能体

智能体要能调用工具，否则只是聊天。很多 SLM 能聊天，但生成的工具调用经常格式不对或不稳定。Qwen 模型经过函数调用的训练，能稳定地输出格式正确的工具调用结构，这正是把本地聊天模型变成本地智能体的关键。^[1]

本地检索：Chroma

文档检索是本地智能体最有用的地方。与其指望 SLM 记住框架的文档，不如把文档嵌入到本地向量数据库里，让智能体按需检索相关的片段。示例使用 Chroma，这是一个嵌入式向量库，在进程内运行，不需要单独维护服务器。^[1]

整条流水线都在本地：本地嵌入模型生成向量，向量存在本地，检索在本地完成，最后由本地 SLM 生成答案。这和智能体式 RAG 的模式相同，变化只是每个环节都跑在你的机器上。^[1]

本地 MCP 服务器

MCP 是一种传输协议，不是云服务。MCP 服务器可以作为本地进程，通过 stdio 对智能体提供工具。这样就能离线复用文件系统、git 操作、数据库查询等 MCP 服务器生态。^[1]

但要注意，本地 MCP 服务器仍以你的用户权限运行，能访问的东西和你一样多。应当限定它的范围，比如只开放一个项目目录，而不是整个主目录，并把它的输出当作需要校验的输入。^[1]

混合部署怎么分流

本地优先不等于只用本地。按敏感程度和难度分流是比较稳妥的做法：^[1]

敏感的代码或数据，或者需要离线工作：交给本地 SLM。
简单、边界清晰的任务：交给本地 SLM，速度快、成本低。
对非敏感数据做困难的多步推理：交给云端模型。
云端不可用时：全部回退到本地 SLM，让智能体降低质量地继续工作，而不是直接失败。^[1]

这就是模型路由的思路，只是其中一个「模型」换成了你自己的电脑。^[1]

示例助手能做什么

示例笔记本里，工程助手完全在工作站上运行，它可以：^[1]

通过 Qwen 的函数调用来调用工具。
列出并读取项目目录里的文件。
分析源代码，输出基本的指标。
用 Chroma 对文档目录做本地 RAG 检索。
连接本地 MCP 服务器。

笔记本用 FoundryLocalManager 和 OpenAI SDK 创建客户端，把管理器提供的端点作为 base_url 传入，并使用一个本地占位的 API 密钥。这些工具都是普通的 Python 函数，限定在项目目录内。例如 read_file 会检查解析后的路径是否在项目根目录之内，否则返回拒绝访问。^[1]

限制和常见问题

硬件方面，示例给出的现实下限是约 8 GB 内存，16 GB 以上比较从容。GPU 或 NPU 能加速，但不是必需的。^[1]
运行示例需要 Python 3.12 及以上，安装 requirements.txt 中的依赖，另外还要装 foundry-local-sdk、openai 和 chromadb。^[1]
工具要限定在单一的项目根目录内。即使在本地，能读取任意路径的工具也是隐患。^[1]
本地模型的回答质量不能和云端大模型等同看待。本文只讲架构与分流，不评价模型质量。