地理空间 AI 智能体（Code Agent）中国区部署实践
内容提要
该文介绍将开源项目sample-geospatial-code-agent部署至亚马逊云科技中国区的实践。方案采用ECS Fargate+ALB架构，底图适配天地图，用Bedrock Minimax M2.5推理，Secrets Manager管理凭证。通过国内镜像加速构建、自动降采样、调整超时等优化，实现非技术用户用自然语言完成遥感分析。
延伸解读
中国区部署的关键适配点
原项目基于海外区服务生态构建，直接部署到中国区会遇到底图偏移、网络延迟、依赖下载慢等问题。本文通过替换天地图底图、调整ALB超时、使用国内镜像源等适配，实现了与海外区一致的使用体验。这些适配点对于其他海外开源项目迁移至中国区具有参考价值。
Code Agent 架构的优势
相比传统Tool Agent，Code Agent让LLM直接生成Python脚本执行，中间数据留在内存不回传上下文，在遥感分析场景中速度更快、成本更低。这种架构减少了上下文传输开销，适合处理大规模数据，但需要严格管理代码执行的安全性和资源限制。
网络与性能优化实践
中国区部署面临跨境网络延迟和国内审查挑战，本文通过调整ALB idle timeout至300秒、使用SSE流式响应、自动降采样限制数据量等措施保障长连接稳定性和响应速度。这些优化对于跨境调用海外服务或处理大数据量的应用具有借鉴意义。
Q&A
sample-geospatial-code-agent 项目在中国区部署时，底图为什么选择天地图而不是高德或百度？
因为高德和腾讯地图使用 GCJ-02 坐标系，存在 100-700 米的偏移；百度地图使用 BD-09，是二次偏移。而天地图使用 CGCS2000 坐标系，与 WGS-84 基本一致，无偏移，可以直接与遥感影像叠加，保证分析结果的准确性。
在中国区部署该地理空间 AI 智能体时，如何解决 Docker 镜像构建慢的问题？
通过使用国内镜像源加速：将 apt 源替换为阿里云镜像（mirrors.aliyun.com），将 pip 源也替换为阿里云 PyPI 镜像，并将基础镜像从 Docker Hub 改为 public.ecr.aws。这样 GDAL 安装时间从 30 分钟以上降至 1-2 分钟，Python 依赖安装提速 5-10 倍。
该方案中如何管理敏感凭证（如 AWS 密钥、天地图 API Key）？
敏感凭证统一存储在 AWS Secrets Manager 中，ECS 任务通过环境变量注入，避免将敏感信息写入镜像或代码。具体做法是创建 Secrets Manager 密钥，然后在 Task Definition 中通过 secrets 字段引用，并给 ecsTaskExecutionRole 添加读取 Secrets Manager 的权限。
为什么需要将 ALB 的 idle timeout 调整为 300 秒？
因为遥感分析任务执行时间较长，Agent 在生成代码和执行期间可能 60-180 秒没有 SSE 数据发送，默认的 60 秒 idle timeout 会导致 ALB 主动断开连接。调高至 300 秒可以避免长连接被中途断开，确保分析任务顺利完成。
该方案中如何避免用户选择大范围区域时导致数据量过大或内存溢出？
通过自动降采样逻辑：限制最大像素数为 400 万（约 2000x2000 像素），当用户选择大范围多边形时，根据估算的像素数自动降低分辨率（如从 10 米降到更低），从而控制单次下载数据量不超过约 50MB，避免超时或 OOM。
在中国区部署时，如何解决跨境调用 Bedrock 的延迟和超时问题？
主要措施包括：将 uvicorn 的 keep-alive 超时设置为 300 秒以保持长连接；ECS 安全组开放 TCP 443 出站；使用 SSE 流式响应保持连接；同时通过自动降采样减少数据量，降低整体处理时间。
该方案中 Agent 的 System Prompt 做了哪些增强？
原项目的 System Prompt 仅两行描述，在使用 Minimax M2.5 等模型时，Agent 无法正确区分 visualize_map_raster_layer（叠加地图）和 visualize_image（仅聊天显示）。增强后增加了明确的工具使用规则，确保分析结果正确叠加到地图上。
该方案中如何实现文件下载功能？
通过新增 /download/{filename} 接口，Agent 将分析结果拷贝到本地临时目录（DOWNLOAD_DIR），前端通过 HTTP 下载，替代了原项目中的 S3 pre-signed URL 方式。
