常见问题解答

是否可以将 GIS 云套件和 AgentX 部署到同一个Kubernetes环境中，是否会发生容器冲突？
答：可以将云套件和AgentX部署到同一个Kubernetes环境的不同命名空间中，云套件的部署流程请参考：部署云套件，AgentX的部署流程请参考：Kubernetes环境安装SuperMap AgentX Server，为解决许可中心端口冲突的问题，除帮助文档中介绍的基本配置项外，还需修改 AgentX 的 values.yaml 配置文件中的如下配置：

# 许可服务配置
bslicense:
provider: "External"
server: "ws://bslicense-server.<cloudsuite_namespace>.svc.cluster.local:9183"
- bslicense.provider: 许可服务的来源，可选值：Built-in（内置服务）、External（外部服务），此场景下应填写 "External"；
- bslicense.server：许可服务地址，此处应填写“ws://bslicense-server.<cloudsuite_namespace>.svc.cluster.local:9183”，其中<cloudsuite_namespace>需替换为云套件的实际命名空间。
如何将部署在同一个 Kubernetes 环境的云套件和云套件中的 iPortal 配置给 AgentX 进行使用？
答：除帮助文档中介绍的基本配置项外，还需要修改 AgentX 的 values.yaml 配置文件中的如下配置，再启动 AgentX：

# GIS 服务配置
iserver:
provider: "External"
rootUrl: "<cloudsuite_root_url>/iserver"
token: "<cloudsuite_token>"

# GIS 门户配置
iportal:
provider: "External"
rootUrl: "<cloudsuite_root_url>/iportal"
token: "<iportal_token>"
- iserver.provider：SuperMap iServer服务的来源，可选值：Built-in（内置服务）、External（外部服务）、None（不配置），此场景下应填写 "External"；
- iserver.rootUrl：iServer服务地址，此处应填写云套件iServer的地址 "<cloudsuite_root_url>/iserver" ，其中<cloudsuite_root_url>需替换为云套件的根路径；
- iserver.token：iServer的访问令牌，此处应填写云套件的token，需前往云套件首页>用户名>令牌处申请；
  
  图：云套件令牌申请页面
- iportal.provider：SuperMap iPortal服务的来源，可选值：Built-in（内置服务）、External（外部服务）、None（不配置），此场景下应填写 "External"；
- iportal.rootUrl：iPortal服务地址，此处应填写云套件iPortal的地址 "<cloudsuite_root_url>/iportal" ，其中<cloudsuite_root_url>需替换为云套件的根路径；
- iportal.token：iPortal的访问令牌，由于iPortal与云套件安全模块相互独立，无法使用云套件的令牌。同时，云套件中的 iPortal 使用 Keycloak 进行登录，界面屏蔽了申请令牌功能，只能通过命令行发送请求获取。具体请参考下列步骤：
（1）执行以下命令，进入 iPortal 容器：

kubectl exec -it $(kubectl get pods -l app=iportal -o jsonpath='{.items[0].metadata.name}' -n <cloudsuite_namespace>) -n <cloudsuite_namespace> -- /bin/sh

（2）将以下命令复制到容器内，并将云套件管理员用户名和密码替换为真实用户名密码，执行后生成的字符串即为iPortal的token：

bash <<'EOF'
cloudsuite_username='云套件的管理员用户'
cloudsuite_password='云套件的管理员密码'
iportal_host='http://iportal:8090'

TOKEN=$(curl -sS -XPOST "${iportal_host}/iportal/services/security/tokens.json" \
-H "Content-Type: application/json;charset=UTF-8" \
-d "{\"userName\":\"${ADMINUSER}\",\"password\":\"${PASSWORD}\",\"clientType\":\"NONE\",\"expiration\":\"5256000\"}") || exit 1

curl -sS -XPUT "${iportal_host}/iportal/manager/security/users/${cloudsuite_username}.json?token=${TOKEN}" \
-H "Content-Type: application/json" \
-d "{\"name\":\"${cloudsuite_username}\",\"password\":\"${cloudsuite_password}\",\"roles\":[\"NOPASSWORD\",\"ADMIN\"],\"description\":\"keycloak user\",\"userGroups\":[\"THIRD_PART_AUTHORIZED\"]}" >/dev/null || exit 1

NEW_TOKEN=$(curl -sS -XPOST "${iportal_host}/iportal/services/security/tokens.json" \
-H "Content-Type: application/json;charset=UTF-8" \
-d "{\"userName\":\"${cloudsuite_username}\",\"password\":\"${cloudsuite_password}\",\"clientType\":\"NONE\",\"expiration\":\"5256000\"}") || exit 1

echo "iportal token：${NEW_TOKEN}"
EOF

此外，还需要在云套件中进行一些配置，以解锁AgentX中更多功能：

（1）如需使用AgentX的iServer GPA MCP 服务，需要在云套件中开启“处理自动化服务”，如下图所示：

图：云套件处理自动化服务页面

（2）如需使用 AgentX 的 iPortal MCP 服务，需要在云套件的iPortal 中配置 GPA 共享存储，如下图所示：

图：云套件iPortal GPA共享存储配置页面

还需要在服务器>服务器列表中，在“iPortal根地址”中填写云套件iPortal的地址 "<cloudsuite_root_url>/iportal"，其中<cloudsuite_root_url>需替换为云套件的根路径：

图：云套件iPortal中iPortal根地址配置页面

（3）如需使用iPortal MapStudio AI制图功能，需要在云套件的iPortal中配置 AI 制图地址，服务地址填写为：

<agentx_root_url>/agentx/workflow/api/mapping/v1

图：云套件iPortal中地图工作室AI制图地址配置页面
知识库问答中的知识库在进行文档解析时报错 “Value error, batch size is invalid, it should not be larger than 10...”，可能的原因是什么导致的，应该如何解决？
答：是因为所使用的词嵌入（Embeddiing）模型单次允许输入的最大数据条数小于系统配置的单次允许输入的最大数据条数，系统默认值为16，而部分模型（如text-embedding-V4）所允许的单次输入最大值仅为10。该问题可以通过修改配置文件解决：Docker环境下，修改.env配置文件中的EMBEDDING BATCH SIZE参数，将默认值修改为当前使用的词嵌入模型单次允许输入的最大数据条数；Kubernetes环境下，修改values.yaml配置文件中的chatflow.embeddingBatchSize参数，根据模型实际情况进行设置。
为什么配置qwen3-32b大模型后，无法使用MapStudio AI制图助理以及自主规划智能体？
答：因为qwen3模型默认关闭“流式输出”功能、开启“思考模式”，但上述两个AI模块依赖流式输出模式，且需开启思考。所以推荐按以下内容进行配置，即开启流式输出及思考模式：
llm:
  BASIC_MODEL:
    base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
    model: "qwen3-32b"
    api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    streaming: True
    extra_body:
      enable_thinking: True
为什么通过iServer GPA MCP工具执行生成缓冲区分析等耗时长的任务会报错，但在SuperMap iServer的GPA服务中查询却显示已执行成功？
答：此问题通常并非GPA服务本身执行失败，而是由于工具内置的超时机制所导致。
- MCP Inspector超时限制：MCP Inspector在等待GPA任务返回结果时，设有固定的超时时间。当分析任务执行时间超过此限制时，Inspector会主动中断等待并报错，但此时iServer上的GPA任务仍在继续或已完成。
- iServer GPA MCP 工具执行时限：当前的iServer GPA MCP设计支持的单次工具最长执行时间为30秒。对于超过此时限的“长耗时”GPA任务，MCP服务端会提前终止会话并返回超时错误，但此时iServer上的GPA任务也仍在继续或已完成。
当前的iServer GPA MCP工具适用于轻量级、快速的空间分析。对于处理大数据量或可能长时间运行的任务，建议直接调用iServer的GPA接口，以获得稳定可靠的结果。
配置豆包大模型doubao-1-5-pro-32k-character-250715后，为何Map Studio AI制图助理与WebGPA AI建模助理均无法正常调用，出现制图指令未生效、知识库查询未触发等情况？
答：因为所选模型doubao-1-5-pro-32k-character-250715不支持 Function Calling（工具调用）功能。当通过 MapStudio AI制图助理或 WebGPA AI建模助理发起相关操作时，模型无法正确识别并调用对应的工具（如设置颜色、查询知识库等），导致指令未实际执行。建议更换其他支持工具调用的模型。
已在iServer WebGPA AI 建模助理界面或 support\geoprocessing\conf\gpa-settings.xml 配置文件中配置好了 AgentX服务地址并可正常使用，为何在使用过程中界面仍再次显示需注册地址？
答：该问题通常由 AgentX服务地址不可正常访问导致的，请恢复该服务或将其更换为有效的服务地址（可直接在建模助理界面中重新填写地址），随后刷新建模助理界面即可。
如何在 iServer WebGPA AI 建模助理中修改已配置的 AgentX服务地址？
答：若当前 AgentX服务可正常访问，请先关闭该服务，然后刷新建模助理界面，在显示的注册页面中填写新地址并注册即可。
在Kubernetes 环境中执行 ./shutdown.sh -v 卸载 SuperMap AgentX Server 时，进程长时间无响应，应如何处理？
答：该情况通常是由于 Kubernetes 集群状态异常或资源协调延迟导致的进程阻塞。您可以通过以下命令强制删除相关 Pod 以完成卸载
- 获取 Pod 名称：kubectl get pods -n
- 强制删除该 Pod：kubectl delete pod -n --grace-period=0 --force
执行后，Pod 将被强制终止，即可继续完成卸载流程。建议操作前确认无其他依赖服务，以免影响业务运行。
为什么将包含只读数据源的工作空间发布为 iServer 数据服务与叠加分析服务后，通过 SuperMap AgentX Server 执行叠加分析，提示执行成功，但结果数据源却为空，也未生成临时数据源，且 iServer MCP 容器、iServer 容器均无相关日志？
答：该现象为 iServer 产品预期设计，并非功能异常：
- 结果存储规则：叠加分析若指定结果数据源名称，会在原工作空间创建该名称的数据源用于保存结果数据集；未指定时，被分析数据集为 udb/udbx 格式则结果数据集将保存至原数据源，为只读矢量文件格式数据源则结果保存至内存数据源（非文件型临时数据源，因此文件目录中无法查见）。
- 结果查看方式：内存数据源中的结果数据集，可在 iServer 数据集列表中查询到。
相关规则说明可参考 iServer 官方文档：datasetOverlayResults

在上传大文件或处理大批量文档时，会遇到处理失败或超时的情况，应该如何解决？

答：这通常是因为默认的批处理参数与您的服务器硬件配置不匹配。我们提供了三个性能调优参数，您可以通过调整它们来平衡处理速度和系统资源占用，从而避免处理失败或超时。

这三个参数可以在 .env 文件（Docker环境）/values.yaml（Kubernetes环境）中进行配置，配置完成后重启服务以使生效：

参数名	说明	默认值
EMBEDDING_BATCH_SIZE	Embedding模型每次允许最多输入的数据条数。	16
DOC_BULK_SIZE	每批次处理的文档块数量。	4
MAX_CONTENT_LENGTH	单次上传文件的最大限制（单位：KB）。	268435456

配置示例

.env 文件

# ENV for Chatflow
...
##表示embedding模型每次允许最多输入的数据条数，根据模型实际情况设置，默认是16。
EMBEDDING BATCH SIZE=16
##每批次处理的文档块数量
DOC_BULK_SIZE=4
##上传文件的最大限制
MAX_CONTENT_LENGTH=268435456
...

values.yaml

chatflow:
...
#表示embedding模型每次允许最多输入的数据条数，根据模型实际情况设置，默认是16。
embeddingBatchSize:16
#每批次处理的文档块数量
docBulkSize:4
#上传文件的最大限制
maxContentLength:268435456
...

推荐配置参考

参数名	8GB内存	16GB内存	32GB内存	调优建议
EMBEDDING_BATCH_SIZE	4	8	16	根据内存大小调整，数值过大会导致内存溢出
DOC_BULK_SIZE	2	4	8	控制并发处理量，数值过高可能引起系统无响应
MAX_CONTENT_LENGTH	64MB	128MB	256MB	限制单次上传文件大小，避免大文件占用过多内存

为什么MCP 容器（iserver-mcp-server）访问目标 HTTPS 服务时出现超时，访问 HTTP 服务却正常，且同主机上的 Nginx 容器还可正常访问该 HTTPS 服务，应如何解决？
答：该问题通常由容器网络接口的 MTU（最大传输单元）与网络链路 MTU 不匹配导致。当容器默认 MTU（通常为 1500）大于网络链路实际允许的 MTU（例如 1450）时，部分数据包（如 TLS 握手或 HTTPS 响应）可能因过大而被丢弃，造成连接超时。

解决方案

（1）临时修复（立即生效）

在宿主机上修改指定容器的 MTU 值：

# 获取容器 PID
CONTAINER_PID=$(docker inspect -f '{{.State.Pid}}' <容器名>)
# 修改容器 eth0 网卡 MTU（例如设为 1450）
nsenter -t $CONTAINER_PID -n ip link set dev eth0 mtu 1450

（2）永久修复（集成到 Docker Compose）

在 docker-compose.yml 中为自定义网络设置 MTU，确保重启后配置不丢失，修改后重启服务即可生效：

networks:
  agentx-net:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: 1450   # 根据实际网络环境调整
调用大模型时出现“BadRequestError: auto tool choice requires --enable-auto-tool-choice and --tool-call-parser to be set”或类似报错，应该如何解决？
答：该报错多发在离线部署模型场景中，原因是在部署时未正确配置相关参数。
- 如果您是基于GPUStack部署模型，需要在左侧导航栏中点击部署，找到目标模型，点击右侧的编辑按钮，进入编辑页面，在“高级”选项卡下，为“LLM模型”添加--enable-auto-tool-choice和--tool-call-parser这两个参数。
- 如果您是使用 vLLM、SGLang、Ollama 等推理引擎部署模型，需要在启动命令中为--enable-auto-tool-choice和--tool-call-parser配置模型。示例命令可参考vLLM方式部署。
在模型广场添加模型后，模型可用性检查不通过，应该如何解决？
答：常见原因有：模型提供商错误、模型服务标识错误（正确示例：Qwen32-32B，不支持在标识中添加 / ）、凭据信息错误或失效、模型服务地址不可达。
从旧版本工作流低代码搭建中导出的工作流，导入到最新版本后无法正常运行，应该如何解决？
答：这是因为新版本对工作流结构或依赖项做了优化，旧版工作流需适配。导入后，系统会自动弹出提示框，点击 “全部审查”，按指引更新即可恢复运行。
在低代码搭建中使用本地向量数据库 ChromaDB 时出现“Error building Component Chroma DB:
Could not connect to tenant default_tenant.Are you sure it exists?”报错，应该如何解决？
答：该报错通常是因为 ChromaDB 在未指定持久化路径时，会尝试在默认路径（如当前工作目录）创建 SQLite 文件。在 Docker 容器环境下，默认路径往往缺少写入权限，导致数据库文件无法创建，进而引发初始化失败。所以在使用 ChromaDB 组件时，请将持久化路径设置为容器内具备写入权限的目录目录：/app/data/ 。
首页精选资源展示的工作流模板，运行时报错”OpenAlError Details: The api _key client option must be set either by passing api_key...“，应该如何解决？

答：该报错通常是因为没有为工作流模板配置对应的模型。需要以管理员身份进入后台管理页面，在模型管理->模型广场添加对应的语言模型，并分配给工作流式智能体。其中，生态空间分析助手模板需要配置 Qwen 系列模型，城市绿线详规审查助手、地块高度监控助手、校园污染监控助手需要配置 DeepSeek 系列模型。
工作流执行时报错“当前系统返回了HTTP 401权限错误，这通常是服务器认证 token 配置问题，导致暂时无法执行空间分析工具。”，应该如何解决？

答：工作流执行时报错权限不够的问题，是因为GPA MCP工具访问 iServer 时没有相应的权限，可以通过以下步骤进行解决：
（1）访问AgentX关联的SuperMap iServer地址（http://IP:Port，Docker环境默认端口为8090，Kubernetes环境默认端口30090）；

（2）以管理员身份登陆 iServer，点击右上角“令牌”，依次输入“用户名“、”密码”，“客户端标识类型”选择“无客户端限制”
选择“有效期”，点击“生成令牌”；

图：iServer 令牌申请入口

（3）根据产品包类型，修改对应的配置文件，在配置文件中找到配置项后，将步骤（2）得到的令牌和对应的iServer地址填写进去，保存后重启AgentX即可生效。

Docker安装包，修改.env配置文件

...
# ENV for gpa mcp server
GPA_ISERVER_ROOT_URL=http://{ip地址}:{端口}/iserver
GPA_ISERVER_TOKEN=<生成的令牌>
...

Kubernetes安装包，修改values.yaml配置文件

# GIS 服务配置

iserver:
  provider: "Built-in"       #可选值： Built-in | External | None
  username: "agentx_admin"
  password: "agentx@2025"
  rootUrl: "http://agentx-iserver:8090/iserver"
  token: "<生成的令牌>"

...
在知识问答中构建知识库，解析文档时报错“Error code: 422 - {'detail: [{'type: 'string_type', 'loc': ['body', 'input, 'str'], 'msg': 'Input should be a valid string", 'input': [[564]]}？”，应该如何解决？

答：需前往模型管理->模型分配->知识问答，在知识问答使用的向量模型卡片上点击“设置”图标，在额外参数中添加如下参数设置：

{ "check_embedding_ctx_length": false }

技能压缩包上传失败时，应如何处理？

答：技能压缩包上传失败通常是由于压缩包内容未通过安全性或规范性校验。请根据页面或日志中的失败提示，对照以下规则检查并调整压缩包后重新上传：

提示	原因	处理方法
压缩包解压失败	压缩包已损坏、格式异常，或无法被系统正常解压	重新打包技能文件，确认压缩包可在本地正常解压后再次上传
解压后文件大小超过限制	压缩包解压后的总文件大小超过 100 MB	删除不必要的文件，压缩图片或拆分技能内容，确保解压后总大小不超过 100 MB
目录层级过深	压缩包内目录嵌套超过 5 层	简化目录结构，最多保留 5 层子目录
检测到非法路径	压缩包内包含 `..`、绝对路径等可能导致路径穿越的文件路径	重新打包，确保所有文件路径均为普通相对路径，不包含 `..` 或绝对路径
包含不允许的文件类型	压缩包中包含不在白名单内的文件类型	仅保留支持的文件类型：`.md`、`.txt`、`.json`、`.yaml`、`.yml`、`.png`、`.jpg`、`.svg`、`.html`、`.css`、`.js`、`.py`

自主规划使用iPortal地图可视化工具出图后显示“无权限进行操作”，应该如何解决？
答：请用户在iPortal中将地图资源和地图所使用到的数据资源权限设置为公开或者可下载。