QGIS AI Agent 完整指南

AI Agent 是 内置的一个聊天面板。你写下任务，它就会在你已经打开的项目中工作，使用项目现有的 layer、CRS、所选内容和屏幕上的当前范围。我们打造了这个工具，所以本指南介绍的是我们自己的产品。

本文涵盖你的第一次运行、Agent 能触达的范围、决定它行为方式的两个 chip，以及如何撤销一次你并不想要的运行。

一个 prompt 能做什么

四句话，依次输入同一个面板，在同一个项目里完成。下面的内容没有一处是手工准备的。

安装并登录

在 QGIS 中，打开 Plugins -> Manage and Install Plugins，搜索 AI Agent，然后点击 Install。它支持 QGIS 3.28 及更高版本，包括 QGIS 4，可运行于 Windows、macOS 和 Linux。

从 TerraLab 工具栏打开面板，点击 Sign in / Sign up。浏览器会打开，你创建一个账户，plugin 会自动完成连接。无需 API key，无需信用卡，注册后即可开始免费运行。

你的第一次运行

一个 prompt 就是一次运行，不论它在 QGIS 里花了多少步骤。一次运行会在 60 次工具调用或 40 分钟时自动停止，所以一个跑偏的任务不会无限运行下去。

它能触达的范围

数据。 本地文件、远程文件、WFS、WMS、XYZ、STAC 和 COG 影像、OpenStreetMap 提取数据、地理编码、路线规划。把一个 GeoPackage 拖到面板上，它就会作为 layer 加载。

分析。 任何 Processing 算法，参数名和已知的坑都是查出来的，不是猜的。缓冲区、连接、分区统计、拓扑检查、基于 OSM 道路的等时圈、沿线的高程剖面。

制图。 符号系统、分类和渐变渲染器、标注，包含地图、图例、比例尺和指北针的打印 layout，然后导出为 PDF 或 PNG。

编辑。 添加、更新和删除要素，几何修复，顶点编辑，合并与拆分，全部在一个真实的、可以回滚的 QGIS 编辑会话中进行。

回答。 某个 QGIS 设置在哪里、手动怎么操作，来自官方 QGIS 文档，并附上链接。问它怎么修复无效几何，你得到的是一个回答，而不是一次运行。

如果安装了 AI Edit 或 AI Segmentation，Agent 也能驱动它们：用一句 prompt 改写影像，或者把某个区域内某类物体的每一个实例都矢量化。

它会检查自己的工作

在 Medium effort 及以上，Agent 会渲染地图并查看自己生成的结果。在那次 layout 运行中，它正是这样做的：判断结果不够清晰易读，并在完成前修正了绘制顺序。

这种行为值得关注，好坏两个方向都是。它报告说 3,124 座建筑物中只有 186 座有可用的高度，而不是悄悄地给一个满是空值的字段套上样式。它同样也可能自信地犯错，所以 trace 始终是该读的东西。

保持掌控

有三样东西介于模型和你的项目之间。

权限 chip，位于 composer 中 + 号旁边，决定它什么时候会停下来问你。

Autopilot 是一个针对当前会话的选择：重启 QGIS 会回到 Balanced，不管你上次选的是什么。有两件事在任何级别下都会询问：任何会消耗 credits 的操作，以及运行原始 Python，你会在它运行前看到代码。

批准卡片就是"询问"的样子。一句话说明即将发生什么，你给出答案，决定之后它会折叠成一行，让长时间的运行保持可读。

撤销。 每一次运行都会留下一个 checkpoint。面板头部的箭头会打开列表，最新的排在最前面，你的项目当前所在的那一行会打上勾。

选择一行，项目就会回到那个状态。restore 操作会先保存它离开时的状态，因此这个操作本身也可以撤销；Ctrl+Alt+Z 则可以直接后退一步，不用打开任何东西。checkpoint 是按运行锚定的，不是按单次工具调用。

给它正确的上下文

Agent 本身就会读取项目：layer 名称、类型、CRS、要素数量、字段名、范围、画布、你的所选内容。你需要额外提供的，是它看不到的东西。

• 附加一张照片、一个数据文件，或者本项目的一个 layer。
• 直接把一个 layer 从 QGIS 的 Layers 面板拖到面板上。
• 把文件拖放到面板的任意位置：数据会作为 layer 加载，图片会发送给模型。
• 在消息里输入 @ 来指定一个数据源，或者你安装的某个 QGIS plugin。

每个项目都有自己的一套对话记录。面板头部的放大镜可以按标题和消息内容搜索，一段对话也可以导出为 Markdown。

两个值得调整的设置

Effort，位于 Send 按钮前的 chip，不是一个模型选择器。它代表你为多少"思考"买单。

Instant 适合"这个项目的 CRS 是什么"这类问题，或者单个样式更改。本指南里的每一次运行，包括提问和自查，都是 Medium 完成的。High 适合那种你原本要专门空出一个下午来做的任务。

Connectors，Settings 的第一页，决定数据从哪里来。三十九个数据源，十个默认开启：OpenStreetMap、Overture、Natural Earth、NASA、Copernicus、Planetary Computer、各国的国家测绘机构等等。每一个都会在你打开之前说明它需要什么，大多数其实什么都不需要。

你安装的 QGIS plugin 也会出现在同一页面上，这样 Agent 就能按名称找到它们。

Personalisation 是另一个值得一看的页面：AI 应该怎么称呼你、你是做什么的、关于你工作的一段描述、长期指令、你的 GIS 经验、公制还是英制、新 layer 应该如何命名，以及它在不同对话之间保留的笔记。

哪些内容会离开你的电脑

每条消息都会发送到我们的托管服务。会传输的内容：你的请求，一份项目描述（CRS、范围，以及每个 layer 的名称、类型、几何类型、可见性、要素数量、字段名和范围，加上当前活动 layer 的一行样本数据），项目文件路径，你最近的 Processing 运行记录，最新的 QGIS 警告，以及你附加的任何内容。

不会传输的内容：你的 raster 和 vector 文件的内容、项目文件本身、要素几何、完整的属性表，以及任何你没有问到的项目。你的 activation key 永远不会出现在工具结果中，layer URI 中的数据库密码会从每一条结果和 traceback 中被清除。

Free 与 Pro

Free 每月给你 10 次运行，使用快速模型，拥有全部工具、全部 connector 和全部 QGIS plugin，仅限个人使用。Pro 每月 250 次运行，49 欧元：较难任务用 Pro 模型，Medium 和 High effort，记忆和长期指令，更长的运行，可商用。

没有任何东西按工具调用计费。60 步的运行和 3 步的运行花费相同。

常见问题

它会弄坏我的项目吗？

它会改动项目，这本来就是它的目的所在，而且改动是可逆的。Balanced 会在任何破坏性操作之前询问你，即使你批准了一个不该批准的操作，运行的 checkpoint 也能把项目恢复原状。不过在一次长会话开始前，还是建议先保存项目，就像你在做任何一批编辑之前会做的那样。

它会往我的 QGIS 里写 Python 吗？

当任务需要时，它可以运行 Python，而这是唯一一件在所有级别下都会询问的事，包括 Autopilot。你会在代码运行前看到它。

它出错的时候会怎样？

它是一个语言模型，所以它可能出错，而且是自信地出错。这正是 activity block 的用处：展开它，看看它选择的参数和返回的数字。我们自己那次运行报告说，3,124 座建筑物中只有 186 座有可用的高度，这正是那种在你信任这张地图之前值得读一读的信息。

一次运行要多久？

一个问题几秒钟，真正的工作要几分钟。在本指南里：底图 43 秒，建筑物及其高度渐变 6 分 30 秒，layout 2 分 37 秒，每个问题都在一分钟以内。在数据抓取运行期间，QGIS 依然可以正常使用。

它能离线使用吗？

不能。没有本地模型，也没有离线模式。plugin 运行在你的电脑上，模型运行在我们的服务器上。

我的数据会被用来训练模型吗？

不会。这个服务只负责规划 QGIS 步骤，仅此而已。

它是开源的吗？

plugin 是开源的，采用 GPL-2.0-or-later 协议：工具执行器、权限模型、文件和网络防护、面板，全都在内。所以在你电脑上运行的那部分是完全可审计的。托管服务、它的 prompt 和开放数据目录则不是。

需要记住的内容

描述结果，而不是操作步骤。Agent 会先读取项目，所以写出具体的 layer 名和路径通常是白打字。

一个 prompt 就是一次运行，不论它花了多少步骤，它会在 60 次工具调用或 40 分钟时自动停止。

activity block 就是这个产品本身。展开它，是你分辨真正好的结果和看起来像那么回事的结果的方法。

每一次运行都会留下一个 checkpoint，restore 本身也可以被撤销，所以批准了一个你后悔的操作，也不是死路一条。

Effort 买到的是规划和检查，不是不同的性格。Instant 负责回答，Medium 负责工作并验证，High 则先思考。

Connectors 决定它能找到什么数据。打开你的国家测绘机构，比任何 prompt 措辞都更有价值。

See plans and pricing