> ## Documentation Index
> Fetch the complete documentation index at: https://gisagent.mapgis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题

# 高频问题与解答

本文整理了 GIS Agent 在产品认知、数据使用、成果管理、模型用量和技术排查方面的常见问题。

## 产品认知与定位

### Q1: GIS Agent 是什么？它与通用 AI 工具的核心区别在哪里？

**A:** GIS Agent 并非通用聊天机器人，可以理解为一个面向空间任务的 GIS 工作助手。

* **核心区别：** 通用 AI（如 ChatGPT）擅长处理文本、代码等通用信息，但通常不处理地理空间概念与操作。GIS Agent 结合专业 GIS 能力，可用于执行“缓冲区分析”“流域提取”“三维地质建模”等任务。
* **本质差异：** 通用 AI 更偏向问答式信息处理；GIS Agent 更偏向围绕空间任务生成地图、页面和分析成果。

### Q2: GIS Agent 旨在解决哪些核心痛点？

**A:** 主要包括以下三点：

1. **降低使用门槛：** 传统 GIS 软件操作复杂，学习成本高。GIS Agent 支持自然语言描述需求，用户无需掌握底层库、数据库或后端开发技术。
2. **提升响应效率：** 传统空间分析需求从提出到交付常需数天至数周。GIS Agent 可帮助将部分流程压缩到分钟级或小时级。
3. **沉淀数字资产：** 项目经验易随人员流动而流失。GIS Agent 可将成功交付成果沉淀为可复用的行业 Skill，实现经验的数字化与规模化复用。

### Q3: 产品名称是“GIS Agent”还是“GIS GeoAgent”？

**A:** 内部全称为 **GIS GeoAgent**，对外发布及日常沟通中，统一使用 **GIS Agent** 这一简洁称谓，两者指向同一产品。

## 使用方式与数据

### Q4: 如何开始使用 GIS Agent？第一次上手应该做什么？

**A:** 可以先按以下三步开始：

1. 打开 [快速开始](https://gisagent.mapgis.com/docs/quickstart.md)。
2. 先用一句自然语言描述你的目标。
3. 查看生成结果，并继续补充修改要求。

使用方法可以概括为：

> 说清数据、说清操作、说清输出。

例如：

> 使用武汉市行政区划和 POI 数据，统计餐饮网点密度，输出专题图并发布为 Web 页面。

### Q5: 如何描述需求，才能让 GIS Agent 更容易理解？

**A:** 建议使用一个固定结构：

> 使用 \[数据源]，完成 \[操作]，输出为 \[结果]。

你可以在这个结构上继续补充：

* **空间范围**：例如“武汉市洪山区”。
* **分析目标**：例如“统计密度”“缓冲区分析”“三维建模”。
* **输出形式**：例如“Web 页面”“专题图”“报告”“可分享链接”。

如果描述太短，例如只输入“如何使用”“需求”“帮我做一个地图”，Agent 很难判断你真正想做什么，回答通常会比较泛。

### Q6: 使用 GIS Agent 是否需要自行准备 API Key 或大模型？

**A: 不需要**。

GIS Agent 目前支持在线使用。用户登录后即可直接使用，系统会自动调度内置能力，无需自行申请和管理 API Key 或额外模型资源。

### Q7: GIS Agent 在处理中国地理数据方面有何优势？支持哪些坐标系？

**A:** 主要特点在于本地化适配、坐标支持和数据处理能力。

* **坐标系支持：** 内置 GIS 时空数据库内核，支持 **CGCS2000、北京 54、西安 80** 等国内常用坐标系。
* **默认坐标系：** 常规 Web 地图与在线成果默认使用 **WGS84（EPSG:4326）**。
* **坐标转换：** 支持根据任务要求转换到其他坐标系，用于叠加分析、服务发布或成果导出。
* **数据理解：** 支持中文地理命名规范与行政区划体系相关数据处理。
* **安全合规：** 支持满足国内数据处理场景下的安全与合规要求。

### Q8: GIS Agent 中的数据从哪里来？

**A:** GIS Agent 本身不预存空间数据。其数据来源于：

1. **用户上传：** 支持上传 Shapefile、GeoJSON、CSV 等格式的本地数据。
2. **指定数据库：** 可连接并调用用户指定的时空数据库中的数据（例如 OSM 数据）。
3. **在线服务：** 支持接入合规的在线地图服务（WMS/WFS）作为数据源。

**操作建议：** 在对话中明确指定数据源，例如：“使用当前数据库中的 OSM 数据进行缓冲区分析”。

### Q9: 能否对现有数据进行范围裁剪或合并操作？

**A:** 可以。这是处理大规模数据（如全量 OSM）以提升性能的常见操作。

* **操作逻辑：** 通过时空数据库对数据按行政区划或其他范围进行裁剪或合并，再将结果发布为矢量瓦片服务（Vector Tile），可提升前端加载速度与业务贴合度。
* **提示词参考：** “针对数据库中的 OSM 数据，按‘北京市’行政区划进行裁剪，并发布为矢量瓦片服务。”

### Q10: 数据更新频率是怎样的？

**A:** 数据更新频率取决于所使用的数据源，不同类型差异较大。

* **实时数据：** 如航班、地震等，通常为秒级或分钟级更新。
* **气象数据：** 如雷达、台风等，通常为分钟级或小时级更新。
* **基础地理数据：** 多为按需获取或按数据源发布节奏更新。

**使用建议：** 如任务对时效性要求较高，建议在需求中明确说明“使用最新数据”或指定数据来源。

## 成果输出与管理

### Q11: 使用 GIS Agent 生成的分析成果（地图、报告、文件）保存在哪里？

**A:** 保存位置取决于使用模式：

* **在线使用模式：** 所有成果保存在用户的个人项目空间，可通过“我的作品”或“项目列表”进行查看、管理、分享与再编辑。
* **工作空间模式：** 若在任务工作空间中运行，生成的文件通常保存在当前工作空间目录 `/workspace/sessions/[session-id]/` 下。

### Q12: 生成的报告或地图支持导出哪些格式？可以导出图片吗？

**A:** 支持，常见导出格式如下：

* **HTML**：可在浏览器中打开并进行交互浏览。
* **PNG、JPG**：便于分享与汇报。
* **GeoJSON、SHP**：便于在其他 GIS 软件中继续使用。
* **MBTiles**：便于离线分发与服务化使用。
* **WMS/WFS**：可作为在线地图服务发布。
* **PDF、Word、Markdown**：适合导出分析报告、记录和说明文档。

### Q13: 如何离线查看生成结果？

**A:** 如果成果是导出的 HTML 文件，通常可以直接在浏览器中打开进行离线查看。

* **适合离线查看的内容：** 页面结构、图层组织、交互框架和本地静态成果。
* **需要注意：** 若地图依赖在线底图、在线瓦片或远程接口，离线状态下底图和部分动态数据可能无法正常加载。

**建议：** 如需要完整离线交付，可提前说明“使用可离线资源”或导出为本地瓦片、静态图片等形式。

### Q14: 可以自定义地图样式吗？

**A:** 可以。建议在需求中明确说明样式要求，GIS Agent 会按描述调整制图表达。

可描述的内容包括：

* 颜色方案
* 图标样式
* 标注内容与显示方式
* 图层顺序
* 主题风格，如科技风、简洁风、深色风等

**提示词示例：** “请使用蓝绿色渐变配色，重点区域用高亮描边，POI 使用餐饮图标，并保留中文标注。”

### Q15: 如何处理地方独立坐标系或坐标不匹配的数据？

**A:** GIS Agent 支持坐标处理与数据融合。

* **常见做法：** 先说明原始数据使用的坐标系，再让 GIS Agent 进行转换、校正或叠加分析。
* **指令示例：** “将我上传的‘地块.shp’（北京 54 坐标系）转换到 WGS84 坐标系，并与‘POI数据.csv’进行叠加分析。”
* **补充建议：** 如果转换后位置仍不对，可继续补充原始坐标系、来源或参考底图信息。

### Q16: GIS Agent 是否支持天地图地理编码与位置纠偏？

**A:** 支持。GIS Agent 可基于天地图进行地理编码、位置比对和坐标纠偏，适合处理地名定位、坐标偏移和位置校正类任务。

* **地名转坐标：** 输入地名或地址，例如“武汉黄鹤楼”，可解析为标准经纬度。
* **坐标比对与纠偏：** 可对比原始坐标和标准坐标，判断是否存在偏移。
* **位置校正：** 对于模糊、错误或偏移明显的点位，可结合地名给出修正结果。

常见适用场景包括：

* GPS 设备采集的坐标与地图底图对不上
* 不同坐标系（GCJ-02 / BD-09 / WGS84）混用导致偏移
* 需要从地名获取经纬度用于地图标注
* 校验第三方数据的位置准确性

**使用建议：** 如果需要纠偏，可以直接说：“请帮我看看这个位置准不准，并帮我纠偏。” 如果同时提供地名和坐标，判断会更准确。

## 技术问题排查指南

> **说明：** 本节整理的是常见技术问题的排查方式，侧重提供具体操作路径。模型额度用完、切换模型见文末「模型与用量」。

### Q17: 页面预览报错或功能异常

**A:** 请按以下优先级尝试修复：

1. **先让 Agent 排查：** 将问题现象直接告知 Agent，让其分析日志并尝试修复。
2. **切换模型重试：** 不同模型能力存在差异，可尝试切换至 Qwen3.7、Xiaomi MiMo 或 DeepSeek 等模型（以实际列表为准）再次执行任务；具体操作见 Q27。
3. **提供详细错误日志：** 打开应用日志或浏览器控制台（F12），复制红色 JS Error 报错信息反馈给 AI 以引导精准修复。
4. **版本回退：** 如果修改导致问题，回退到上一个可用版本通常更省时间。

### Q18: 成果已生成但页面不显示

**A:** 此问题多为前端渲染或数据加载异常。

* **操作步骤：**
  1. 按 **F12** 打开浏览器开发者工具。
  2. 切换到 **控制台 (Console)** 标签页。
  3. 复制其中的报错信息（通常是红色错误日志）。
  4. 将错误日志反馈给 Agent，例如：“控制台报错‘XXX’，请帮我排查页面为什么不显示。”
* **解析：** 此方法有助于定位渲染异常、瓦片加载失败或跨域（CORS）等问题。

### Q19: 地图显示空白怎么办？

**A:** 地图空白通常与网络、数据源或空间范围配置有关，可按以下顺序排查。

* **常见原因：**
  * 网络连接异常，导致底图、瓦片或远程数据未加载成功。
  * 数据源 API 暂时不可用或返回异常。
  * 坐标范围、中心点或缩放层级设置错误，导致地图没有落在正确区域。
* **解决方法：**
  1. 检查网络连接是否正常。
  2. 确认坐标范围、中心点和缩放层级是否正确。
  3. 刷新页面后重新加载地图。
  4. 尝试更换数据源或底图服务。

### Q20: 数据加载缓慢怎么办？

**A:** 该问题通常与数据量、接口响应速度或当前网络环境有关。

* **常见原因：**
  * 查询范围过大，返回数据量过多。
  * 外部 API 响应较慢。
  * 当前网络带宽受限或连接不稳定。
* **解决方法：**
  1. 缩小查询范围。
  2. 减少一次性加载的数据量。
  3. 优先使用缓存数据或已裁剪结果。
  4. 等待几分钟后重试。

**建议：** 如需长期稳定展示，可提前进行数据裁剪、瓦片化或专题结果缓存。

### Q21: 3D 效果无法显示怎么办？

**A:** 3D 场景依赖浏览器图形能力和本机硬件环境，通常与 WebGL 或硬件加速有关。

* **常见原因：**
  * 浏览器不支持 WebGL 或相关能力未正常启用。
  * 显卡驱动版本过旧。
  * 浏览器硬件加速未开启。
* **解决方法：**
  1. 更新浏览器到最新版本。
  2. 更新显卡驱动。
  3. 开启浏览器硬件加速。
  4. 尝试更换其他现代浏览器。

### Q22: 地图或界面出现中文乱码怎么办？

**A:** 中文乱码通常与字体缺失或文件编码设置有关。

* **常见原因：**
  * 浏览器或页面运行环境缺少可用中文字体。
  * 文件编码不是 UTF-8。
* **解决方法：**
  1. 安装或补充可用中文字体。
  2. 检查相关文件编码是否为 UTF-8。
  3. 尝试使用支持中文显示更稳定的现代浏览器。
* **可尝试：** 在对话中补充以下提示词，引入公共字体库。

```
使用字体 https://fonts.loli.net/css?family=Open+Sans
```

* **解析：** 该指令会引导前端代码加载 Open Sans 字体，有时可帮助缓解字体缺失导致的显示问题。

### Q23: 任务执行时对话栏转圈或卡住不动

**A:** 需区分情况处理。

* **仅对话栏转圈：** 这通常是前端显示延迟，任务本身可能已经完成，可先查看页面或继续操作。
* **项目页面无法加载：** 请依次尝试：
  1. **刷新页面。**
  2. 在对话框输入 `/` 唤起工具栏，点击 **重启应用**。
  3. 让 Agent 帮你排查，例如输入：“项目没有成功启动，目前无法预览，请帮我检查并修复。”

### Q24: 网站卡死或无响应

**A:** 通常与对话过长或页面一次性加载内容过多有关。

* **可先尝试：** **刷新页面**，然后重新发起对话。
* **后续建议：** 通过缩小分析数据的地理范围或复杂度，降低页面负载，减少卡死概率。

### Q25: 发送需求后报 “The input is too long” 或 “Range of input length should be \[1, 258048]”

**A:** 这类报错不是需求本身有问题，而是**当前对话的上下文长度超出了模型单次可接收的上限**。

* **典型现象：**
  * 报错形如 `InternalError.Algo.InvalidParameter: The input is too long: the request payload exceeds the maximum message size accepted by the service.`
  * 或 `InternalError.Algo.InvalidParameter: Range of input length should be [1, 258048]`
  * 同一条需求反复重发都失败，例如多次提交“成果编制模块的‘导出全部图件’按钮，改成‘导出选中图件’，各个图件应该可选”均无响应。
* **原因：** 长对话会累积历史消息、文件内容和日志，即使本次输入只有一句话，整体请求体积仍然超限。
* **解决方法：**
  1. **手动压缩上下文**：在对话框直接输入 `/compact` 并发送，平台会把历史对话压缩为一段摘要，保留核心参数与命令历史，释放 token 空间。
  2. 压缩后重新发送原始需求，此时通常能正常执行。
  3. 若 `/compact` 后仍报同样错误，请**新开一个对话**，并在首条消息中带上关键上下文（模块名、页面、期望行为），必要时附上相关文件路径或截图。
* **使用建议：** 修改类任务尽量“一个需求一次小步提交”，长任务分段处理，避免在同一个对话里持续累积大量结果与日志。

## 模型与用量

### Q26: 提示“流量/额度用完”或“请求受限”，是限制使用量了吗？

**A:** 大概率是。先看报错原文，不同提示对应不同处理：

| 报错/现象 | 更可能是 | 处理 |
| :- | :- | :- |
| `quota exceeded`、`insufficient_quota`、`insufficient balance`、`余额不足`、`当前套餐额度已用完`、`429 Too Many Requests` | 当前模型/套餐的额度或频率用完 | 换一个可用模型，或换套餐/等额度重置；见 Q27 |
| `The input is too long`、`Range of input length should be [1, 258048]` | 上下文超长，不是额度 | 用 `/compact` 压缩或新开对话；见 Q25 |
| `concurrent session limit exceeded` | 并发会话数超限 | 关闭其他会话/等待；联系管理员调整授权 |
| `Model not found`、`no running instances available` | 模型服务/部署问题 | 换模型或联系管理员；不是套餐额度 |
| `401`、`403`、`Invalid API key` | 密钥/权限问题 | 联系管理员检查密钥与授权 |
| 网络超时、`502/503/504` | 网络或模型服务暂时不可用 | 重试；持续失败换模型并反馈 |

**解释：**

* “流量/额度”通常限制的是**某个模型或某个套餐**，不是 GIS Agent 软件本身；换模型或换套餐可以继续。
* 这不等于数据丢失：当前会话记录、已上传文件、已生成代码都在；切换后回复“继续”即可。
* 如果所有模型都提示额度用完，通常是套餐共用额度或账户余额问题，需要换套餐或联系管理员，单换模型解决不了。

### Q27: 额度用完时，怎么切换模型？

**A:** 在对话输入框右下角找到**模型胶囊**（显示当前模型名，如 `Qwen3.6-Plus`），点开选择另一个可用模型，再回复“继续”。

1. 点击模型胶囊（在模式胶囊 `Build/Plan` 右侧）。
2. 在“模型”菜单里选择可用模型，例如 `Qwen3.7`、`Xiaomi MiMo`、`DeepSeek`；以实际列表为准。
3. 回复“继续”或重述上一条需求；同一会话切换，上下文通常保留。
4. 新对话：在发送前先选模型，避免默认模型额度已用完。

![额度用完提示](https://mintcdn.com/mapgis/xJ0UoVxlBNauX_Db/docs/faq-assets/quota-exhausted.png?fit=max\&auto=format\&n=xJ0UoVxlBNauX_Db\&q=85\&s=e7904a845188d1ef647d8f1ed8141b1a)

*图 1：额度用完提示示意；这不是网络故障。*

![切换模型示意](https://mintcdn.com/mapgis/xJ0UoVxlBNauX_Db/docs/faq-assets/switch-model.png?fit=max\&auto=format\&n=xJ0UoVxlBNauX_Db\&q=85\&s=3cbfdc0d374dcb6e365cc06684236d1d)

*图 2：切换模型示意：点击模型胶囊 → 选择可用模型 → 回复“继续”。*

**注意：**

* 模型胶囊和模式胶囊是两个不同的按钮：**模型**决定用哪个大模型，**模式**（Plan/Build）决定能不能写文件；不要混淆。
* 切换模型不会自动压缩上下文；如果同时报 `input is too long`，先 `/compact`（Q25）。
* 如果模型列表里没有可用模型，或切换后仍提示额度用完，说明套餐/账户层面受限，需要换套餐或联系管理员。
* 切换模型后如果任务中断，回复“继续”即可；必要时把上一步的目标和验收标准再贴一遍。

**推荐顺序：** 先换模型（Qwen3.7 / Xiaomi MiMo / DeepSeek）→ 仍不行再换套餐 → 所有模型都不可用再联系管理员。更偏氛围编程的流程建议见[额度/套餐用完](https://gisagent.mapgis.com/docs/vibe-code-quota.md)。

***

**使用提示：** 若遇到未涵盖的问题，建议在对话中清晰描述现象，包括数据情况、操作步骤和错误提示，Agent 将为您提供定制化解决方案。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.