简介ArcGIS Pro/GeoScene Pro简易AI助手源码面向GIS二次开发者和需要使用AI辅助空间分析的专业用户以Addin插件形式集成在软件界面内直接调用deepseek服务免去切换窗口的繁琐。插件当前支持ArcGIS Pro 3.3与GeoScene Pro 5.1安装时需按说明替换FixDLL文件夹中的原始文件。资源包约80.92MB共1250个文件包含229个C#源文件、92个DLL库文件、54个JSON配置、3个XAML界面文件以及esriaddinx安装包等目录结构清晰方便开发者直接编译、调试或二次扩展。已有806人学习下载适合具备Pro插件开发基础、希望快速接入大模型能力的GIS工程师参考。借助这套源码可深入理解Pro加载项开发流程、DockPane界面定制、AI服务对接等关键实现缩短同类工具的自研周期。 在 ArcGIS Pro 里做数据处理做得多了就会发现真正浪费时间的往往不是操作本身而是“想不起函数名、记不住参数、搞不清数据状态”这几个环节。后来 DeepSeek 开放 API我花了一个周末把一套能直接跑在 ArcGISPro/GeoScenePro 里的简易 AI 助手源码整理了出来在 Pro 的 Python 窗口或者自定义脚本工具里输入一句话就能拿到带数据分析结果的回答甚至可以反推出对应的 arcpy 代码。这套源码不依赖外部服务也不需要改 Pro 底层环境核心就是“把当前工程上下文提取出来 调用 DeepSeek API”拿到手改个 Key 就能用适合 GIS 从业者、学生和做二次开发的朋友。1. 项目整体设计与思路拆解1.1 这个 AI 助手要解决什么实际问题我发现很多 GIS 相关的提问比如“这个图层的坐标系是什么”“要素类里有多少条记录”“字段计算器里怎么用 left 函数”本质上都可以拆成两件事一是从当前工程里读取真实数据二是让语言模型基于这些数据输出判断或代码。如果只是把问题直接丢给模型它只能给你一个通识性的答案并不知道你当前打开的是哪个图层、有什么字段。所以这套助手的核心设计思路是先通过 arcpy 读取当前 ArcGIS Project或 GeoScene 工程里的地图、图层、字段、范围和坐标系信息把这些信息拼进 Prompt再交给 DeepSeek 去理解、总结、出建议或生成代码。这个“上下文感知”是整套源码最有价值的地方。举个例子你问“我当前图层里面积字段加起来是多少”模型并不知道面积字段叫什么但脚本已经先把字段列表、数据类型、甚至要素范围都拿到了再结合你的提问模型给出的答案就会精准很多而不是泛泛而谈。1.2 为什么选 DeepSeek 而不是其他模型技术选型上我确实对比过几条路。GPT 系列模型能力很强但国内直连不便而且频繁调用时成本不低本地开源模型虽然数据隐私好但想跑出理想效果至少需要一张大显存显卡部署一套推理服务对绝大多数 GIS 从业者来说都不现实。DeepSeek 的 API 走的是 OpenAI 兼容格式Python 里用标准库就能调调用成本低中文理解也足够好对 GIS 这种需要中英文混合输出的场景非常合适是我最终把它作为默认接入模型的核心原因。需要说明的是这套源码里我把 API 地址和模型名都做成了可配置项。也就是说如果你后续想换成其他兼容 OpenAI 接口的服务只需要改动配置文件里的 base_url 和 model 字段代码主体基本不用动。这也是我刻意保留的扩展性设计避免被单一厂商绑定。1.3 技术路线为什么用 Python 脚本工具而不是 Add-inArcGIS Pro 的二次开发起码有三条常见路线Python 脚本、脚本工具Script Tool、以及基于 .NET 的 Add-in。我选择前两者核心原因是上手门槛和交付效率。Add-in 功能上限高但需要 Visual Studio、ArcGIS Pro SDK还要处理安装包签名和版本兼容对大多数想“快速给自己写个助手”的人来说太重了。Python 脚本工具可以直接放进任意工具箱团队里其他人不用写代码也能用只需要一个输入框点一下就能得到结果。另外ArcGIS Pro 内置的 Python 环境已经预装了 arcpy 和大部分科学计算库我们的 AI 助手只需要用 urllib 请求 API连 requests 都不用装这进一步降低了部署难度。源码整体是单文件结构核心逻辑只分两块采集工程上下文、调用大模型阅读和维护都非常直接。2. 环境准备与核心源码结构2.1 确认 ArcGIS Pro / GeoScene Pro 的 Python 运行环境ArcGIS Pro 自带的 Python 是 conda 管理的 3.x 环境通常在安装目录下比如C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3。GeoScene Pro 作为同类产品Python 环境结构非常接近也提供 arcpy 兼容模块。你不需要手动安装 Python直接用 Pro 内置的环境就行。在动手之前先打开 ArcGIS Pro 的 Python 窗口或者 Notebook运行下面这行代码确认环境没问题import arcpy print(arcpy.GetInstallInfo()[Version])如果你能正常输出版本号说明环境是可用的。如果这里就报错那大概率是安装有问题而不是我们代码的问题先解决环境再说。2.2 申请 DeepSeek API Key 与环境变量配置访问 DeepSeek 开放平台注册账号后在“API Keys”页面创建一个 Key。注意 Key 只会在创建时完整显示一次一定要先复制保存好。我不建议把 Key 硬编码在源码里因为脚本可能会分享给同事或上传到代码仓库一旦泄露就会被别人盗刷额度。推荐做法是配置成环境变量。Windows 下可以在系统环境变量里新建一个DEEPSEEK_API_KEY也可以在脚本开头临时读取本地配置文件。源码里我写了这样一段兼容逻辑import os API_KEY os.getenv(DEEPSEEK_API_KEY, ) if not API_KEY: raise RuntimeError(未检测到 DEEPSEEK_API_KEY 环境变量请先配置后再运行。)这样既不影响直接运行也能防止 Key 被硬编码进仓库。2.3 源码目录结构与核心模块职责整套代码我保持了单文件的简洁结构方便直接拖到 Pro 里运行。核心模块只有几个函数get_project_context() # 读取当前工程的地图、图层、字段信息 get_layer_detail(layer) # 提取单个图层的空间参考、范围、要素类类型 ask_deepseek(prompt) # 调用 DeepSeek API 并返回回答 build_prompt(question) # 将工程上下文和用户提问组装成 Prompt main(question) # 主入口供脚本工具调用这样的分层好处是如果你想加入更多能力比如“让 AI 自动执行工具”只需要在build_prompt后面加一个工具调用分发函数即可不影响现有逻辑。对于只是想快速用起来的人你甚至只需要关注ask_deepseek和get_project_context这两个函数就够了。3. 实操过程与核心环节实现3.1 第一步在 Python 窗口跑通最简单的问答打开 ArcGIS Pro新建一个空白工程在“分析”选项卡里找到 Python 窗口。先跑一个最简单的 DeepSeek 调用验证网络和 Key 都正常这里我用的是 Python 标准库 urllibimport urllib.request import json API_URL https://api.deepseek.com/chat/completions API_KEY sk-你的key # 测试用建议正式使用改为环境变量 payload { model: deepseek-chat, messages: [{role: user, content: 用一句话介绍 arcpy 是什么}], temperature: 0.3 } req urllib.request.Request( API_URL, datajson.dumps(payload).encode(utf-8), headers{Content-Type: application/json, Authorization: fBearer {API_KEY}}, methodPOST ) with urllib.request.urlopen(req, timeout30) as resp: result json.loads(resp.read().decode(utf-8)) print(result[choices][0][message][content])如果你看到正常的中文回复说明 API 调用链路是通的。这一步容易踩的坑是代理设置。有些企业网络环境下Python 的 urllib 会走系统代理导致请求失败或超时这个我在第 4 节会展开说。这里先确认一个点如果拿到的是HTTP Error 401那就是 Key 写错了重新复制一遍再试。3.2 第二步把地图图层上下文传给模型这一步是整套源码的关键。我们要在对话前先获取当前工程的信息并组装成模型能读懂的文本。以获取当前地图和图层基本信息为例import arcpy import json def get_project_context(): aprx arcpy.mp.ArcGISProject(CURRENT) if aprx is None: return 当前没有打开的工程 ctx_lines [] for map_item in aprx.listMaps(): ctx_lines.append(f地图名称: {map_item.name}) for layer in map_item.listLayers(): try: desc arcpy.Describe(layer) sr desc.spatialReference ctx_lines.append( f 图层: {layer.name} | 类型: {layer.type} | f坐标系: {sr.name if sr else 未知} | f可见: {layer.visible} ) except Exception: ctx_lines.append(f 图层: {layer.name} | 无法读取详细信息) return \n.join(ctx_lines)拿到上下文之后把它和用户的提问一起拼进 Promptdef build_prompt(question): context get_project_context() system_msg 你是一位熟悉 ArcGIS Pro 和 arcpy 的 GIS 专家请基于用户提供的工程上下文回答问题。 user_msg f当前工程上下文如下\n{context}\n\n用户的问题是{question} return [ {role: system, content: system_msg}, {role: user, content: user_msg} ]这里有一个细节值得展开arcpy.Describe(layer)是获取图层底层信息最稳定的入口。在 ArcGIS Pro 里很多图层对象表面属性和底层数据源属性不一致比如一个符号化图层和它的源要素类直接用layer.name拿到的只是显示名称真正要判断坐标系、字段类型、数据格式必须走 Describe。这样模型拿到的上下文才足够真实可靠。3.3 第三步封装成带界面的自定义脚本工具如果只是自己在 Python 窗口里玩到上面那步已经够了。但如果想让不写代码的同事也能用就得把它封成一个工具箱脚本工具。具体操作如下在“目录”窗格中找到你的工具箱比如默认的“我的工具箱”右键选择“添加” - “脚本”。脚本名称填AI 助手标签可以填GIS AI。在“参数”选项卡里添加两个参数第一个参数显示名称“问题”数据类型选择“字符串”类型为“必需”方向为“输入”。第二个参数显示名称“回答”数据类型选择“字符串”类型为“可选”方向为“输出”。在“执行”选项卡里选择“将脚本文件导入”把写好的.py文件导入进去。在脚本文件里通过arcpy.GetParameterAsText(0)拿用户输入的问题通过arcpy.SetParameterAsText(1, answer)把结果返回给工具界面。脚本工具的主入口大概是这样def main(question): messages build_prompt(question) answer ask_deepseek(messages) arcpy.AddMessage(answer) return answer if __name__ __main__: question arcpy.GetParameterAsText(0) # 工具界面输入的参数 result main(question) arcpy.SetParameterAsText(1, result) # 把结果写回输出参数注意一个小细节脚本工具的运行目录和环境变量可能与 Python 窗口不同。如果你在工具里发现读不到DEEPSEEK_API_KEY要么在工具箱属性里把“环境变量”指过去要么在脚本里直接加一行os.environ的动态读取逻辑这个在第 4 节的 FAQ 里我会给出具体处理方案。3.4 第四步运行与效果验证都配置好之后双击工具箱里的“AI 助手”在“问题”框里输入一句话比如帮我分析当前地图里第一个图层的主要字段并推荐一个适合人口数据的符号化方案。工具执行过程中底部“地理处理”窗格会实时打印 OpenAI 风格的日志最后输出框里会显示模型的回答。第一次跑通的时候你会明显感觉到它已经不像一个“聊天机器人”而更像一个“懂你当前数据状态的顾问”。实测下来这类带上下文的任务比如“这个图层适合用什么配色”“写出按字段分组汇总的 arcpy 代码”回答的可用率比不带上下文高很多。原因很简单模型看到的不是空泛的问题而是带有真实字段名、真实坐标系的具体场景它给出的答案自然更贴近你的工程。4. 常见问题与排查技巧实录4.1 API 请求超时与网络异常这是所有人第一次跑都会遇到的高频问题。症状通常是urllib.error.URLError: urlopen error timed out。原因大部分出在网络代理上ArcGIS Pro 的 Python 环境默认继承 Windows 系统代理设置如果你的网络代理对 HTTPS 请求限速或拦截API 请求就会超时。我的排查思路是先在 Python 窗口里跑一下urllib.request.urlopen(https://api.deepseek.com, timeout5)如果能通说明网络没问题如果超时或报Tunnel connection failed就得在代码里显式清掉代理设置或者让网络管理员放行这个域名import urllib.request urllib.request.proxy_handler urllib.request.ProxyHandler({}) opener urllib.request.build_opener(urllib.request.ProxyHandler({})) urllib.request.install_opener(opener)注意这段代码要放在所有urlopen调用之前执行。我自己踩过坑只给单个请求设了 proxy 为{}其他请求还是走系统代理排查了半天才发现是代理对象没有全局安装。4.2 中文乱码与字段编码问题ArcGIS Pro 的 Python 3 环境对中文支持其实很好了但有一个典型场景会乱码在脚本工具输出参数里如果返回的字符串包含中文而工具运行的临时编码不是 UTF-8就会在“回答”框里显示乱码。解决办法是在脚本开头强制指定编码环境import sys import io sys.stdout io.TextIOWrapper(sys.stdout.buffer, encodingutf-8)另外json.dumps(payload)时一定要带上ensure_asciiFalse否则中文会被转成\uXXXX一长串模型能读懂但可读性差调试时很难受。4.3 第三方库冲突导致 arcpy 环境异常我见过不少人在 ArcGIS Pro 自带的 Python 环境里用conda install装了一堆第三方库结果某次更新后 arcpy 直接崩溃或报ImportError: DLL load failed。这类问题 90% 是 conda 环境依赖被破坏。如果遇到这个情况尽量不要自己去修依赖最省事的方案是用 ArcGIS Pro 自带的“Python 环境管理器”克隆一个新的环境在新环境里只装必要库。我们的 AI 助手源码只用标准库和 arcpy本身不会引入任何额外依赖所以环境越干净越稳定。切记不要在arcgispro-py3这个基础环境里乱装东西一旦坏了恢复起来很折腾。4.4 其他高频问题速查表格形式列几个我常被问到的问题问题现象核心原因解决办法返回HTTP Error 401API Key 写错或未激活到 DeepSeek 平台重新生成 Key确认环境变量已更新脚本工具里报“找不到 arcpy”ArcGIS Pro 环境变量异常或使用了外部 Python切换回 arcgispro-py3 环境运行不要用系统 Python模型回答明显偏离 GIS 主题Prompt 里没注入系统角色确保 messages 里包含 system 角色指明“你是 GIS 专家”工具能跑但输出为空输出参数类型设置错误检查工具箱参数方向选“输出”数据类型选“字符串”调用费用失控未设置 max_tokens 上限在 payload 里固定 max_tokens比如 1024还有一个容易被忽略的安全问题不要把DEEPSEEK_API_KEY直接写在要分享出去的.pyt文件或脚本文件里。如果一定要分享就把读取 Key 的逻辑单独抽到一个配置文件并在分享前把配置文件从工程里删掉只保留读取逻辑。写在最后的一个扩展建议这套源码我用了大半年最大的体会是“上下文”比“模型能力”更重要。接入同一套模型给不给工程上下文回答质量完全是两个级别。如果你已经跑通了基础版本下一步可以试着把ask_deepseek的返回结果改成“带代码执行”的模式也就是让模型输出 arcpy 代码再用arcpy.Execute去执行这样就能从一个“问答助手”升级成“能帮你干活的助手”。不过这一步建议先从只读操作开始比如查字段、统计数量、导出表格信息等你对工具的输出稳定度有信心之后再去碰创建数据、修改数据这类写操作。毕竟让 AI 直接改 GIS 数据一旦出错影响面可比写错一行代码大多了。本文还有配套的精品资源点击获取 用DeepSeek API为ArcGIS Pro打造上下文感知AI助手
简介ArcGIS Pro/GeoScene Pro简易AI助手源码面向GIS二次开发者和需要使用AI辅助空间分析的专业用户以Addin插件形式集成在软件界面内直接调用deepseek服务免去切换窗口的繁琐。插件当前支持ArcGIS Pro 3.3与GeoScene Pro 5.1安装时需按说明替换FixDLL文件夹中的原始文件。资源包约80.92MB共1250个文件包含229个C#源文件、92个DLL库文件、54个JSON配置、3个XAML界面文件以及esriaddinx安装包等目录结构清晰方便开发者直接编译、调试或二次扩展。已有806人学习下载适合具备Pro插件开发基础、希望快速接入大模型能力的GIS工程师参考。借助这套源码可深入理解Pro加载项开发流程、DockPane界面定制、AI服务对接等关键实现缩短同类工具的自研周期。 在 ArcGIS Pro 里做数据处理做得多了就会发现真正浪费时间的往往不是操作本身而是“想不起函数名、记不住参数、搞不清数据状态”这几个环节。后来 DeepSeek 开放 API我花了一个周末把一套能直接跑在 ArcGISPro/GeoScenePro 里的简易 AI 助手源码整理了出来在 Pro 的 Python 窗口或者自定义脚本工具里输入一句话就能拿到带数据分析结果的回答甚至可以反推出对应的 arcpy 代码。这套源码不依赖外部服务也不需要改 Pro 底层环境核心就是“把当前工程上下文提取出来 调用 DeepSeek API”拿到手改个 Key 就能用适合 GIS 从业者、学生和做二次开发的朋友。1. 项目整体设计与思路拆解1.1 这个 AI 助手要解决什么实际问题我发现很多 GIS 相关的提问比如“这个图层的坐标系是什么”“要素类里有多少条记录”“字段计算器里怎么用 left 函数”本质上都可以拆成两件事一是从当前工程里读取真实数据二是让语言模型基于这些数据输出判断或代码。如果只是把问题直接丢给模型它只能给你一个通识性的答案并不知道你当前打开的是哪个图层、有什么字段。所以这套助手的核心设计思路是先通过 arcpy 读取当前 ArcGIS Project或 GeoScene 工程里的地图、图层、字段、范围和坐标系信息把这些信息拼进 Prompt再交给 DeepSeek 去理解、总结、出建议或生成代码。这个“上下文感知”是整套源码最有价值的地方。举个例子你问“我当前图层里面积字段加起来是多少”模型并不知道面积字段叫什么但脚本已经先把字段列表、数据类型、甚至要素范围都拿到了再结合你的提问模型给出的答案就会精准很多而不是泛泛而谈。1.2 为什么选 DeepSeek 而不是其他模型技术选型上我确实对比过几条路。GPT 系列模型能力很强但国内直连不便而且频繁调用时成本不低本地开源模型虽然数据隐私好但想跑出理想效果至少需要一张大显存显卡部署一套推理服务对绝大多数 GIS 从业者来说都不现实。DeepSeek 的 API 走的是 OpenAI 兼容格式Python 里用标准库就能调调用成本低中文理解也足够好对 GIS 这种需要中英文混合输出的场景非常合适是我最终把它作为默认接入模型的核心原因。需要说明的是这套源码里我把 API 地址和模型名都做成了可配置项。也就是说如果你后续想换成其他兼容 OpenAI 接口的服务只需要改动配置文件里的 base_url 和 model 字段代码主体基本不用动。这也是我刻意保留的扩展性设计避免被单一厂商绑定。1.3 技术路线为什么用 Python 脚本工具而不是 Add-inArcGIS Pro 的二次开发起码有三条常见路线Python 脚本、脚本工具Script Tool、以及基于 .NET 的 Add-in。我选择前两者核心原因是上手门槛和交付效率。Add-in 功能上限高但需要 Visual Studio、ArcGIS Pro SDK还要处理安装包签名和版本兼容对大多数想“快速给自己写个助手”的人来说太重了。Python 脚本工具可以直接放进任意工具箱团队里其他人不用写代码也能用只需要一个输入框点一下就能得到结果。另外ArcGIS Pro 内置的 Python 环境已经预装了 arcpy 和大部分科学计算库我们的 AI 助手只需要用 urllib 请求 API连 requests 都不用装这进一步降低了部署难度。源码整体是单文件结构核心逻辑只分两块采集工程上下文、调用大模型阅读和维护都非常直接。2. 环境准备与核心源码结构2.1 确认 ArcGIS Pro / GeoScene Pro 的 Python 运行环境ArcGIS Pro 自带的 Python 是 conda 管理的 3.x 环境通常在安装目录下比如C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3。GeoScene Pro 作为同类产品Python 环境结构非常接近也提供 arcpy 兼容模块。你不需要手动安装 Python直接用 Pro 内置的环境就行。在动手之前先打开 ArcGIS Pro 的 Python 窗口或者 Notebook运行下面这行代码确认环境没问题import arcpy print(arcpy.GetInstallInfo()[Version])如果你能正常输出版本号说明环境是可用的。如果这里就报错那大概率是安装有问题而不是我们代码的问题先解决环境再说。2.2 申请 DeepSeek API Key 与环境变量配置访问 DeepSeek 开放平台注册账号后在“API Keys”页面创建一个 Key。注意 Key 只会在创建时完整显示一次一定要先复制保存好。我不建议把 Key 硬编码在源码里因为脚本可能会分享给同事或上传到代码仓库一旦泄露就会被别人盗刷额度。推荐做法是配置成环境变量。Windows 下可以在系统环境变量里新建一个DEEPSEEK_API_KEY也可以在脚本开头临时读取本地配置文件。源码里我写了这样一段兼容逻辑import os API_KEY os.getenv(DEEPSEEK_API_KEY, ) if not API_KEY: raise RuntimeError(未检测到 DEEPSEEK_API_KEY 环境变量请先配置后再运行。)这样既不影响直接运行也能防止 Key 被硬编码进仓库。2.3 源码目录结构与核心模块职责整套代码我保持了单文件的简洁结构方便直接拖到 Pro 里运行。核心模块只有几个函数get_project_context() # 读取当前工程的地图、图层、字段信息 get_layer_detail(layer) # 提取单个图层的空间参考、范围、要素类类型 ask_deepseek(prompt) # 调用 DeepSeek API 并返回回答 build_prompt(question) # 将工程上下文和用户提问组装成 Prompt main(question) # 主入口供脚本工具调用这样的分层好处是如果你想加入更多能力比如“让 AI 自动执行工具”只需要在build_prompt后面加一个工具调用分发函数即可不影响现有逻辑。对于只是想快速用起来的人你甚至只需要关注ask_deepseek和get_project_context这两个函数就够了。3. 实操过程与核心环节实现3.1 第一步在 Python 窗口跑通最简单的问答打开 ArcGIS Pro新建一个空白工程在“分析”选项卡里找到 Python 窗口。先跑一个最简单的 DeepSeek 调用验证网络和 Key 都正常这里我用的是 Python 标准库 urllibimport urllib.request import json API_URL https://api.deepseek.com/chat/completions API_KEY sk-你的key # 测试用建议正式使用改为环境变量 payload { model: deepseek-chat, messages: [{role: user, content: 用一句话介绍 arcpy 是什么}], temperature: 0.3 } req urllib.request.Request( API_URL, datajson.dumps(payload).encode(utf-8), headers{Content-Type: application/json, Authorization: fBearer {API_KEY}}, methodPOST ) with urllib.request.urlopen(req, timeout30) as resp: result json.loads(resp.read().decode(utf-8)) print(result[choices][0][message][content])如果你看到正常的中文回复说明 API 调用链路是通的。这一步容易踩的坑是代理设置。有些企业网络环境下Python 的 urllib 会走系统代理导致请求失败或超时这个我在第 4 节会展开说。这里先确认一个点如果拿到的是HTTP Error 401那就是 Key 写错了重新复制一遍再试。3.2 第二步把地图图层上下文传给模型这一步是整套源码的关键。我们要在对话前先获取当前工程的信息并组装成模型能读懂的文本。以获取当前地图和图层基本信息为例import arcpy import json def get_project_context(): aprx arcpy.mp.ArcGISProject(CURRENT) if aprx is None: return 当前没有打开的工程 ctx_lines [] for map_item in aprx.listMaps(): ctx_lines.append(f地图名称: {map_item.name}) for layer in map_item.listLayers(): try: desc arcpy.Describe(layer) sr desc.spatialReference ctx_lines.append( f 图层: {layer.name} | 类型: {layer.type} | f坐标系: {sr.name if sr else 未知} | f可见: {layer.visible} ) except Exception: ctx_lines.append(f 图层: {layer.name} | 无法读取详细信息) return \n.join(ctx_lines)拿到上下文之后把它和用户的提问一起拼进 Promptdef build_prompt(question): context get_project_context() system_msg 你是一位熟悉 ArcGIS Pro 和 arcpy 的 GIS 专家请基于用户提供的工程上下文回答问题。 user_msg f当前工程上下文如下\n{context}\n\n用户的问题是{question} return [ {role: system, content: system_msg}, {role: user, content: user_msg} ]这里有一个细节值得展开arcpy.Describe(layer)是获取图层底层信息最稳定的入口。在 ArcGIS Pro 里很多图层对象表面属性和底层数据源属性不一致比如一个符号化图层和它的源要素类直接用layer.name拿到的只是显示名称真正要判断坐标系、字段类型、数据格式必须走 Describe。这样模型拿到的上下文才足够真实可靠。3.3 第三步封装成带界面的自定义脚本工具如果只是自己在 Python 窗口里玩到上面那步已经够了。但如果想让不写代码的同事也能用就得把它封成一个工具箱脚本工具。具体操作如下在“目录”窗格中找到你的工具箱比如默认的“我的工具箱”右键选择“添加” - “脚本”。脚本名称填AI 助手标签可以填GIS AI。在“参数”选项卡里添加两个参数第一个参数显示名称“问题”数据类型选择“字符串”类型为“必需”方向为“输入”。第二个参数显示名称“回答”数据类型选择“字符串”类型为“可选”方向为“输出”。在“执行”选项卡里选择“将脚本文件导入”把写好的.py文件导入进去。在脚本文件里通过arcpy.GetParameterAsText(0)拿用户输入的问题通过arcpy.SetParameterAsText(1, answer)把结果返回给工具界面。脚本工具的主入口大概是这样def main(question): messages build_prompt(question) answer ask_deepseek(messages) arcpy.AddMessage(answer) return answer if __name__ __main__: question arcpy.GetParameterAsText(0) # 工具界面输入的参数 result main(question) arcpy.SetParameterAsText(1, result) # 把结果写回输出参数注意一个小细节脚本工具的运行目录和环境变量可能与 Python 窗口不同。如果你在工具里发现读不到DEEPSEEK_API_KEY要么在工具箱属性里把“环境变量”指过去要么在脚本里直接加一行os.environ的动态读取逻辑这个在第 4 节的 FAQ 里我会给出具体处理方案。3.4 第四步运行与效果验证都配置好之后双击工具箱里的“AI 助手”在“问题”框里输入一句话比如帮我分析当前地图里第一个图层的主要字段并推荐一个适合人口数据的符号化方案。工具执行过程中底部“地理处理”窗格会实时打印 OpenAI 风格的日志最后输出框里会显示模型的回答。第一次跑通的时候你会明显感觉到它已经不像一个“聊天机器人”而更像一个“懂你当前数据状态的顾问”。实测下来这类带上下文的任务比如“这个图层适合用什么配色”“写出按字段分组汇总的 arcpy 代码”回答的可用率比不带上下文高很多。原因很简单模型看到的不是空泛的问题而是带有真实字段名、真实坐标系的具体场景它给出的答案自然更贴近你的工程。4. 常见问题与排查技巧实录4.1 API 请求超时与网络异常这是所有人第一次跑都会遇到的高频问题。症状通常是urllib.error.URLError: urlopen error timed out。原因大部分出在网络代理上ArcGIS Pro 的 Python 环境默认继承 Windows 系统代理设置如果你的网络代理对 HTTPS 请求限速或拦截API 请求就会超时。我的排查思路是先在 Python 窗口里跑一下urllib.request.urlopen(https://api.deepseek.com, timeout5)如果能通说明网络没问题如果超时或报Tunnel connection failed就得在代码里显式清掉代理设置或者让网络管理员放行这个域名import urllib.request urllib.request.proxy_handler urllib.request.ProxyHandler({}) opener urllib.request.build_opener(urllib.request.ProxyHandler({})) urllib.request.install_opener(opener)注意这段代码要放在所有urlopen调用之前执行。我自己踩过坑只给单个请求设了 proxy 为{}其他请求还是走系统代理排查了半天才发现是代理对象没有全局安装。4.2 中文乱码与字段编码问题ArcGIS Pro 的 Python 3 环境对中文支持其实很好了但有一个典型场景会乱码在脚本工具输出参数里如果返回的字符串包含中文而工具运行的临时编码不是 UTF-8就会在“回答”框里显示乱码。解决办法是在脚本开头强制指定编码环境import sys import io sys.stdout io.TextIOWrapper(sys.stdout.buffer, encodingutf-8)另外json.dumps(payload)时一定要带上ensure_asciiFalse否则中文会被转成\uXXXX一长串模型能读懂但可读性差调试时很难受。4.3 第三方库冲突导致 arcpy 环境异常我见过不少人在 ArcGIS Pro 自带的 Python 环境里用conda install装了一堆第三方库结果某次更新后 arcpy 直接崩溃或报ImportError: DLL load failed。这类问题 90% 是 conda 环境依赖被破坏。如果遇到这个情况尽量不要自己去修依赖最省事的方案是用 ArcGIS Pro 自带的“Python 环境管理器”克隆一个新的环境在新环境里只装必要库。我们的 AI 助手源码只用标准库和 arcpy本身不会引入任何额外依赖所以环境越干净越稳定。切记不要在arcgispro-py3这个基础环境里乱装东西一旦坏了恢复起来很折腾。4.4 其他高频问题速查表格形式列几个我常被问到的问题问题现象核心原因解决办法返回HTTP Error 401API Key 写错或未激活到 DeepSeek 平台重新生成 Key确认环境变量已更新脚本工具里报“找不到 arcpy”ArcGIS Pro 环境变量异常或使用了外部 Python切换回 arcgispro-py3 环境运行不要用系统 Python模型回答明显偏离 GIS 主题Prompt 里没注入系统角色确保 messages 里包含 system 角色指明“你是 GIS 专家”工具能跑但输出为空输出参数类型设置错误检查工具箱参数方向选“输出”数据类型选“字符串”调用费用失控未设置 max_tokens 上限在 payload 里固定 max_tokens比如 1024还有一个容易被忽略的安全问题不要把DEEPSEEK_API_KEY直接写在要分享出去的.pyt文件或脚本文件里。如果一定要分享就把读取 Key 的逻辑单独抽到一个配置文件并在分享前把配置文件从工程里删掉只保留读取逻辑。写在最后的一个扩展建议这套源码我用了大半年最大的体会是“上下文”比“模型能力”更重要。接入同一套模型给不给工程上下文回答质量完全是两个级别。如果你已经跑通了基础版本下一步可以试着把ask_deepseek的返回结果改成“带代码执行”的模式也就是让模型输出 arcpy 代码再用arcpy.Execute去执行这样就能从一个“问答助手”升级成“能帮你干活的助手”。不过这一步建议先从只读操作开始比如查字段、统计数量、导出表格信息等你对工具的输出稳定度有信心之后再去碰创建数据、修改数据这类写操作。毕竟让 AI 直接改 GIS 数据一旦出错影响面可比写错一行代码大多了。本文还有配套的精品资源点击获取