智能体与本地离线模型 (Local Models with Agents)

希望在侧边栏聊天或 Agent 节点中直接使用本地模型？

如果你只是希望在侧边栏对话面板或 Agent 节点中直接选用 Ollama 或 LM Studio 作为基础大模型，请直接参阅 AI 模型提供商。对于绝大多数常规交互需求，那是一条更为轻量直接的途径。

而本教程探讨的是一种更高级的工程架构模式：在画布工作流内部，将本地部署的私有模型与 MCP 服务器深度编排。这种架构既赋予了模型安全操作本地文件与生产工具的能力，又确保所有私密数据 100% 物理留存于本机。

本高级教程将系统演示如何将 本地离线 AI 大模型 与 MCP 服务器生态无缝结合，以在不向任何外部云端服务外泄数据的前提下安全处理高敏感信息。这非常适用于分析企业机密文档、审计私有代码仓库或处理高合规要求的个人隐私数据。

为什么将本地离线模型与 MCP 结合？

极致的安全合规优势

✅ 零数据出境 (Zero Data Leaks)：所有计算推理与数据流转完全限制在宿主机内存中；
✅ 零 API 计费开销：充分利用本机 GPU/CPU 算力，告别按 Token 扣费账单；
✅ 绝对的隐私保护：无惧商业机密外泄与第三方模型服务商的数据集抓取；
✅ 全离线可用性：在内网物理隔离环境（Air-Gapped）或无网环境下依然稳定运行。

完美适配的应用场景

企业内部文档：公司保密财报、劳动合同、法务条款与合规审计报告；
核心专有代码：闭源商业核心算法与底层固件源码；
个人隐私机密：私有笔记、身份凭证与敏感财务记录；
自动化本地文件管线：对本地海量资产进行智能重命名、内容检索与自动化清洗。

本教程构建的目标管线

我们将搭建一条具备完整隐私防护闭环的工作流：

部署配置 Filesystem MCP 服务器：精细化授予本地指定受限文件夹的读写访问权；
通过 Ollama 启动本地开源模型（以具备工具调用能力的 qwen3:1.7b 为例）作为智能体大脑；
安全读取加密/保密测试文件：验证智能体能否在没有外网连接的前提下读取敏感数据；
验证零外泄数据流：证实从物理磁盘读取到大模型推理的完整链路均在本地闭环。

前置环境要求

掌握 MCP 的基础概念（详见快速上手教程）；
拥有 macOS、Windows 或 Linux 计算机；
具备基础的命令行操作经验。

第一步：安装并配置本地 Ollama 环境

下载并安装 Ollama

访问 Ollama 官方网站：ollama.org；
下载适配你操作系统的安装包并根据向导完成安装；
打开终端（Terminal / PowerShell），运行以下命令验证安装：
```
ollama --version
```

下载支持工具调用的 Qwen3 模型

在终端中拉取轻量且原生支持 Function Calling 的模型：
```
ollama pull qwen3:1.7b
```
等待下载与权重解压完成；
验证本地可用模型清单：
```
ollama list
```

为什么推荐 Qwen3:1.7b？ 该模型参数量精炼（约 1.7B），几乎可以在任何现代笔记本电脑或低显存设备上飞速运行；更重要的是，它原生支持工具调用（Tool Use / Function Calling），这是与 MCP 协议顺畅对接的绝对硬性指标。

第二步：配置 Filesystem MCP 本地文件服务器

Filesystem MCP Server 提供了对本地文件系统高度受控的安全访问层。为了确保安全性，该服务器仅被允许访问你显式白名单授权的目录，绝无权限越界越权访问宿主机的其它文件夹。

关于该服务器支持的完整指令集，可查阅 Filesystem Server 文档。

创建 MCP 服务器配置

打开 Griptape Nodes，依次点击 Settings → MCP Servers；
点击 + New MCP Server；
填写配置项：
- Server Name/ID：filesystem；
- Connection Type：Local Process (stdio)；
- Configuration JSON：

{
  "transport": "stdio",
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "/Users/jason/Desktop",
    "/Users/jason/Downloads"
  ],
  "env": {},
  "cwd": null,
  "encoding": "utf-8",
  "encoding_error_handler": "strict"
}

⚠️ 极其重要：请务必将上述配置中的 /Users/jason/Desktop 与 /Users/jason/Downloads 替换为你本机真实的桌面与下载目录物理绝对路径（例如 Windows 下写为 C:/Users/YourName/Desktop）。Filesystem 仅能在这些白名单目录及其子文件夹内开展操作。

点击 Create Server 完成注册。

准备本地机密测试文件

在你的桌面上新建一个名为 secret.txt 的纯文本文件；
在文件中写入一段机密内容：
```
The password is: CAPYBARA
```
保存并关闭文件。

第三步：在画布上搭建纯离线智能体工作流

1. 配置 Ollama Prompt 本地模型节点

从左侧算子库中拖入一个 Ollama Prompt 节点；
配置模型核心参数：
- Model：qwen3:1.7b
- Temperature：0.1（低温度可确保工具调用的确定性与准确度）
- Max Tokens：-1（不设人为上限）
- Stream：True
- Use Native Tools：True（必须开启：指示模型使用原生 Function Calling 特性对接 MCP）

2. 创建智能体 (Agent) 节点

拖入一个 Agent 节点；
将 Ollama Prompt 节点的 prompt_model_config 输出端口连线至 Agent 节点的 prompt_model_config 输入端口；
将 Agent 节点的 Prompt 暂时保持留空。

3. 创建 MCPTask 算子节点

拖入一个 MCPTask 节点；
将 Agent 节点的 agent 输出连线至 MCPTask 节点的 agent 输入；
配置 MCPTask 属性：
- MCP Server Name：选择刚刚创建的 filesystem；
- Prompt："what's the password in secret.txt? it's in the desktop folder"（请问 desktop 文件夹下的 secret.txt 里面记录的密码是什么？）。

第四步：执行高安全工作流并检验输出

触发执行

首先执行 Ollama Prompt 节点完成本地权重的热加载；
运行 Agent 节点完成智能体实例初始化；
运行 MCPTask 节点启动文件检索与解析。

预期结果验证

MCPTask 节点将呈现如下推理与答案输出：

<think>
Okay, the user asked for the password in secret.txt. After checking the allowed directories and listing the contents, the secret.txt file was found. Reading the file revealed the password "CAPYBARA". Since the user requested the password, the assistant needs to provide it. The previous steps were successful, so the final answer is the password.
</think>

The password in secret.txt is **CAPYBARA**.

可以看到，Qwen3 模型在本地自主列出了白名单目录下的文件，精准命中了 secret.txt，并通过 Filesystem 驱动读取了其中的文本，最终在本地完成语义理解并输出了密码。

为什么这种架构能做到绝对的物理安全？

数据流向全景透视

graph LR
    A[本机敏感物理文件] --> B[Filesystem MCP 进程]
    B --> C[Ollama 本地模型进程]
    C --> D[Griptape Nodes 画布]

    subgraph Security ["🔒 宿主机内部完全闭环隔离环境"]
        A
        B
        C
        D
    end

四重安全护栏

零外部网络通信：大模型权重加载、向量运算与逻辑解码均在你的本地显卡与内存中进行；
数据流不出机箱：文本内容直接通过操作系统本地匿名管道 (stdio) 传递，绝不经过外部公共网络；
零云端落盘与持久化：没有任何数据会被推送到外部云存储中；
白名单物理沙箱：Filesystem MCP 严密封锁了非授权目录，智能体无法越权窥探其它驱动器。

本地模型选型与优化指引

模型规格对比天梯

模型名称	参数体量	推理速度	工具调用能力	推荐应用场景
`qwen3:1.7b`	小型 (~1.7B)	极快	基础稳定工具调用	日常轻量文件读取与字段提取
`qwen3:4b`	中型 (~4B)	中等	出色逻辑推理与容错	复杂多层逻辑分析与长文本总结
`llama4`	大型	较慢	顶级复杂长程推理	深度长篇代码重构与综合多步决策

性能调优建议

预留充足系统内存：对于中大型模型，建议本机配备 16GB 以上统一内存或独立显存；
释放显存占用：在运行 4B 以上模型时，建议关闭其它消耗显存的大型 3D 渲染工具；
任务分流：对于纯文件匹配过滤任务，优先选用 qwen3:1.7b 以获得毫秒级即时响应。

常见疑难排查 (Troubleshooting)

提示模型不存在 (Model Not Found)

# 检查本地已缓存的模型列表
ollama list

# 若缺失，请重新拉取对应权重
ollama pull qwen3:1.7b

文件系统权限被拒绝 (Filesystem Access Denied)

仔细核对 MCP 配置中填入的绝对路径是否存在拼写笔误；
确保运行 Griptape Nodes 的当前系统用户对该文件夹具备真实的物理读取权限；
macOS 用户请检查系统偏好设置中是否授予了终端/应用对“桌面”与“下载”文件夹的访问权限。

工具调用失败或未触发 (Tool Use Not Working)

检查 Ollama Prompt 节点中的 Use Native Tools 是否已设置为 True；
确认所选模型版本是否支持 Function Calling（部分纯对话模型不支持工具语法，推荐使用 Qwen3 或 Llama 系列）；
检查 MCP 设置面板中 Filesystem 服务是否处于激活启用状态。