AI 地图 SDK 通过 UI 组件、结构化地点事件、地图操作和浏览器安全认证，将人工智能连接到可实际运行的地图体验。地图仍由渲染器显示，事实记录则继续由权威系统负责。当产品需要对话式地图交互、嵌入式空间组件，或需要更快地把 AI 输出转化为可见的地理操作时，可以选择 AI 地图 SDK。
下文将介绍组件职责、架构、Kaleidr 集成路径、安全边界、评估标准和常见错误。有关实际挂载步骤，请参阅如何向地图添加 AI 聊天；有关 SDK 下层的检索能力，请参阅什么是位置智能 API？。
AI 地图 SDK 核心要点
- 产品集成层： 连接宿主 UI、AI 推理、结构化地理信息和实时渲染器，而不只是一个聊天机器人。
- 结构化事件： 应优先使用地点、操作、依据来源、配额、结束和错误对象，而不是从自然语言文本中解析坐标。
- 凭据分离： 浏览器使用受来源限制的可发布密钥；服务器密钥仅保存在宿主后端。
- 服务商适配器： 在产品支持时，无需替换渲染器即可连接 Mapbox、Google Maps、MapLibre 或 Leaflet。
- 数据权威： AI 负责解释意图；经过批准的位置与业务系统负责验证事实。
AI 地图 SDK 概览
AI 地图 SDK 位于主机应用程序、地图渲染器以及提供位置事实的系统之间。SDK不应成为地址、列表状态、库存、营业时间、路线或私人业务记录的事实来源。可靠的生产原则是，人工智能负责解释地理意图，权威系统验证事实，而SDK将批准的结果转化为可见的地图行为。
| 组件 | 主要责任 |
|---|---|
| 主机应用程序 | 用户、会话、租户上下文、权限、工作流程和业务逻辑 |
| 人工智能地图 SDK | 用户界面组件、意图交由、身份验证、流媒体、结构化地图操作以及生命周期 |
| 地图渲染器 | 相机、图层、标记、控件、样式以及特定提供者的行为 |
| 平台API | 推断、地点检索、路由、设计、排名或其他记录的服务 |
| 位置服务 | 地理编码、地点、路线、边界、瓷砖和空间环境 |
| 商业系统 | 权威库存、房产、资产、客户、资格和运营记录 |
| 分析 | 问题、结果、地图操作、错误、任务完成以及产品结果 |
AI 地图 SDK 实际能做什么？
确切的范围取决于平台，但一个功能强大的AI地图SDK通常处理七个协同工作。首先，SDK 将 AI 输出连接到已在应用程序中运行的实时映射对象。Mapbox GL JS、Google Maps JavaScript API 和 MapLibre GL JS 各自通过相机、边界、事件和渲染方法对可编程地图对象进行曝光;SDK 需要一个提供程序的适配器，以便一个结构化操作能够成为正确的提供方特定操作——将结果区域框成，平移至位置，添加标记、高亮显示功能、显示路由或保存地理上下文。Kaleidr 当前的聊天附件通过该附件支持 Mapbox、Google 地图、MapLibre 和 Leaflet 的实时地图实例和文档支持 聊天附件 SDK现有提供商继续渲染地图。
第二，SDK 会把 AI 输出转换为结构化地理事件，而不是让宿主应用从自然语言文本中解析重要地点。有效的契约会分别表示流式文本、已解析地点、增强元数据、地图操作、依据来源、配额信息，以及最终成功或错误状态。Kaleidr 的服务器发送事件契约包含 place、place_linked、early_actions、grounding、quota、end 和 error 事件；其中 end 是权威的终止对象。使用 kaleidr.js 的开发者无需手动解析数据流，构建自定义客户端的团队则可以遵循文档中的 SSE 线路契约。MDN 也介绍了此类数据流所基于的浏览器服务器发送事件模型。
第三，SDK 可以提供可重用的用户界面组件——聊天面板、查看器、编辑器、搜索控制或自定义元素，因此每个团队都不会重建该界面。 网页组件 支持可重复使用的自定义HTML元素;Kaleidr的加载器同时安装window.Kaleidr以进行命令式安装，以及用于在聊天、查看、编辑器和设计基图产品之间进行声明嵌入的<kaleidr-map>元素。kaleidr.js 参考， <kaleidr-map> 元素)
第四，浏览器安全认证必须区分可发布的凭据、服务器凭据、允许的来源、短暂的会话、功能范围、撤销和配额。Kaleidr 使用可发布密钥(kld_pk_live_…)来存储浏览器 SDK 和网页组件(仅限于已批准的来源，并交换为短暂的会话)，以及服务器密钥(kld_sk_live_…)，这些密钥必须不使用 HTML、浏览器 JavaScript、客户端捆绑包和公共仓库。可受能力范围分别为ai、maps和design路线系列;未使用必要范围的有效密钥可返回403，而无效或被撤销的凭据则返回401。参见 认证与范围 而且 允许的起源。
第五，SDK 会规范生命周期和提供方差:映射对象可能尚未存在，容器可能缺乏高度，样式可能仍在加载中，单页应用程序可能会改变路由，或者当流处于活动状态时，组件可能无法安装。Kaleidr 的加载器会同步返回一个手柄，而所选的产品套装则在后台加载;在套装准备好前进行的调用会排列，手柄会暴露 destroy() 为拆解。可预测的挂载和破坏行为可防止SPA路由更改，并防止多地图页面泄露听点或重复聊天内容。
第六，SDK 将浏览器组件连接到平台 API，而不会将两者混淆。SDK 是面向 UI、会话交换、流解析和地图附件的集成层。该API在https://api.kaleidr.com/inference-api/b2b/v1/下暴露了服务器可访问的推理、检索、路由、设计及相关路由(端点参考)
第七，稳定的产品合约会明确支持的操作、受控的地图对象、所需的密钥和范围、错误、事件、拆解、版本控制、数据权限和计量。Kaleidr 引脚在 /embed/v1/ 下嵌入资产，需要一条新的主要路径来打破电线变化(CDN版本控制)该合同允许主机应用程序在不进行逆向工程无记录UI行为的情况下升级加载器。
它与地图 API 或 GIS 有何不同？
这些术语有关联，但不应被视为同义词。地图库或渲染器绘制地图，并控制相机、图层和地图事件。地图或位置API提供远程地理数据或操作，例如地理编码、地点、路线或磁贴。人工智能API产生推理或模型输出。AI 地图 SDK 提供跨 AI 的集成、映射状态、身份验证、用户界面和结构化操作。地理信息系统平台涵盖更广泛的数据管理、分析、编辑、出版和治理。渲染器可以显示地图而不理解用户的自然语言目标;AI API 可以在不掌握页面地图的情况下解释句子;SDK 通过文档化的应用程序合同将这些系统连接起来。
| 类别 | 它提供了什么 | 示例责任 |
|---|---|---|
| 地图库或渲染器 | 地图对象和可视化渲染引擎 | 绘制地图、控制摄像头、添加图层、处理地图事件 |
| 地图或位置API | 远程地理数据或操作 | 地理代码，找到一个位置，计算一条路线，返回瓦片 |
| 人工智能API | 推断或模型输出 | 解释问题、生成文本、分类意图 |
| 人工智能地图 SDK | 跨人工智能、地图状态、Auth、UI 和操作的产品集成 | 连接聊天、串流位置、应用地图操作、管理生命周期 |
| 地理信息系统平台 | 数据管理、分析、编辑、出版、治理 | 维护权威层次，运行空间分析，管理记录 |
核心架构如何运作？
生产环境中的 AI 地图 SDK 通常遵循清晰的流程：用户提问或应用程序发出事件；宿主提供上下文和权限；SDK 协调浏览器会话或宿主后端调用；推理、检索、路由或设计 API 返回结构化地点、依据来源和允许的操作；服务商适配器转换这些结果；随后实时地图、Viewer、Editor 或设计过的底图得到更新。宿主应用程序仍需负责已登录用户、租户上下文、权限、批准的数据集、私有数据检索、重要业务操作、保留与日志，以及最终的错误恢复。SDK 不应绕过这些控制。
地图感知需要读取或接收地理上下文，包括中心与缩放级别、可见边界、选中地点、活动图层、绘制的几何对象、筛选条件、语言和区域。系统应返回结构化地理结果，例如坐标、稳定地点 ID、几何对象、边界、路线几何、操作类型、来源、置信度，以及明确的无结果或错误状态。应使用基于允许列表的操作契约，而不是让模型生成任意 JavaScript 或不受限制的服务商调用。带有西、南、东、北字段的 fit_bounds 等概念操作可以说明这种设计；实际实现必须使用所选平台文档中定义的准确操作格式。
如何集成 Kaleidr SDK？
从版本固定的CDN路径加载一次当前的Kaleidr加载器 https://cdn.kaleidr.com/embed/v1/kaleidr.js 安装产品前。对于已拥有受支持的实时地图实例的应用程序，请在页面中放置地图和聊天容器，然后在真人地图对象存在后，使用命令式API进行聊天。
// myMap must be a live Mapbox, Google Maps, MapLibre,
// or other currently supported map instance.
const chatHandle = Kaleidr.mount("#map-chat", {
product: "chat",
publishableKey: "kld_pk_live_REPLACE_ME",
map: myMap,
enabled: true
});
// Keep the handle for cleanup in an SPA or component lifecycle.
window.addEventListener("beforeunload", () => {
chatHandle.destroy();
});
该示例由当前的 Kaleidr 改编 快速启动 以及装载机参考。应用程序在安装聊天前必须初始化 myMap。可发布的密钥必须包含 ai 范围，且应用程序的来源必须出现在密钥的允许来源列表中。已发布的 Kaleidr 地图使用 <kaleidr-map product="viewer" share-id="…"> 的声明性查看器路径;该查看器为共享链接，目前无需使用 API 密钥，尽管仍适用由发布者定义的允许域。查看器嵌入)
何时使用 SDK，何时使用平台 API？
当主机应用程序需要支持的聊天、查看、编辑器或基图组件、自动浏览器会话交换、可重复使用的用户界面、提供程序附件、流解析、生命周期处理以及更快的实现时间时，请使用SDK。当主机后端需要自定义用户界面、服务器端编排、推理前进行私有数据检索、完全控制渲染、非浏览器客户端、直接访问已记录的路由家族或自定义日志记录和策略时，请直接使用平台API。混合实现通常最强:用于浏览器用户界面和地图交互的 SDK、授权和私有检索的主机后端，以及用于受控服务器工作流的平台 API。不要将服务器密钥移动到浏览器代码中;请将服务器凭据保留在后端，并仅从可信环境调用已记录的流媒体终端。终点)
如何为数据提供依据并保护密钥？
地图使答案看起来准确，即使其基本事实较弱。常见风险包括伪造场所、不正确的坐标、陈旧的商业状态、无根据的路线主张、地名碰撞、重复实体、超出预期地理范围的结果，以及与私有系统相冲突的摘要。更用的是此序列:自然语言意图、授权检索或位置分辨率、结构化地理对象、允许的地图操作，然后是带有源上下文的可见答案。解析重要位置以稳定标识符，保留关键属性的源和更新时间，保持内部系统在操作事实上的权威性，显示无结果和模糊状态，要求确认进行相应编辑，限制用户和租户的私有检索，并将最终结构化结果视为应用合同。
浏览器端应使用专为浏览器设计的可发布密钥，将其限制到准确的生产和预发布来源，在本地开发之外使用 HTTPS，并在路由或租户发生变化时销毁 SDK 集成；不能仅因为地图需要一个标记就暴露私有记录。后端应把服务器密钥保存在机密管理器中，在检索前执行授权，限制传入推理流程的字段，分别处理 401、403、422、429 和临时 503 响应，把终止性的 SSE error 事件视为数据流结束，并审计敏感访问。Mapbox、Google Maps、MapLibre 图块服务商及其他服务仍各自拥有凭据、条款、署名、计费和配额；Kaleidr 密钥不会替代地图服务商的凭据。Kaleidr 还记录了固定版本的 CDN 路径、组织级用量计量、组织密钥之间共享的配额，以及数据流中的 quota 事件（配额与速率限制）。
如何评估 AI 地图 SDK？
确认渲染兼容性——支持的提供方和版本，无论SDK是否需要映射对象或CSS选择器，无论是拥有该地图还是附加到一个、准备要求、摄像头和标记行为、多地图支持以及移动或WebGL约束。询问平台是否返回位置对象、稳定ID、坐标、几何图形、源引用、动作对象、无结果状态、终端结果以及显式错误;避免使用从模型散文中提取地理事实的制作架构。验证可发布和服务器凭证分离、来源限制、短时浏览器会话、范围、撤销、CORS、租户隔离、隐私数据边界以及审计支持。测试脚本加载、框架拆解、路由更改、服务器端渲染边界、并发映射、错误恢复和加载。确定SDK是否仅是UI封装，或者平台是否还会公开用于自定义工作流的文档API。审查主要版本策略、变更日志、弃用窗口、CDN 固定、提供商可移植性以及数据导出路径。衡量时间以首次获得有用结果、流时长、错误和无结果率、地图操作成功、提供商与人工智能使用、配额利用率以及每个完成用户任务的成本，而仅用于SDK加载。
常见案例包括对话场所发现、旅行和目的地产品(人工智能驱动的旅游地图);物业与市场搜索;存储定位器;SaaS工作流程中的嵌入式地图创建;使用设计基础地图进行品牌地图体验;以及在授权资产和地区进行内部运营。在每种情况下，AI层都会解释请求，而主机系统则验证事实并执行权限。
| 错误 | 会发生什么 | 建议更正 |
|---|---|---|
| 在实时地图存在之前安装 | SDK 无法附加到预定的渲染器 | 先初始化地图并传递实时对象 |
| 将SDK视为真相的源泉 | 生成的事实可以推翻权威记录 | 保持地方和商业体系的权威性 |
| 解析散文坐标 | 集成变得脆弱 | 使用结构化场所和行动事件 |
| 在浏览器中暴露服务器密钥 | 后端持证人人公开 | 使用受原产地限制的可发布密钥 |
| 遗忘允许的起源 | 浏览器请求失败，出现CORS或源错误 | 添加精确的分期和生产来源 |
| 将地图提供器与人工智能凭证混合 | 安全性、账单和调试变得不明确 | 独立管理每个提供商 |
| 允许任意生成的操作 | 该模型可以触发不受支持的行为 | 使用一个文档化的操作允许列表 |
| 忽略拆解 | SPA 泄露监听器、流式传输或重复组件 | 保留操作程序并调用 destroy() |
| 仅跟踪 SDK 加载 | 技术激活被误认为是用户价值 | 衡量已解决的任务和下游结果 |
| 跳过移动和无障碍测试 | 聊天可能会模糊地图或陷阱焦点 | 测试响应式布局、键盘顺序和标签 |
最终结论
AI 地图 SDK 是将人工智能输出转化为受管控空间产品体验的应用层。该图层将自然语言意图与结构化场所、支持的地图操作、可重用的界面、浏览器安全认证以及实时渲染器连接起来。当产品需要对话地图交互、嵌入式空间组件，或从推理到可见地理行为的更快路径时，请使用AI地图SDK。当主机团队需要自定义接口或服务器端编排时，请使用直接API，当浏览器从维护的组件中受益时，同时使用后端必须控制私有检索、策略和授权。评估SDK是否保留数据权限、生成结构化的地理结果、支持已使用的渲染器、执行安全的凭据边界、处理生命周期和错误，以及改进可衡量的用户任务——而不仅仅是演示加载的速度。
为现有地图添加 AI 层
使用一个加载器、一个可发布密钥和实时地图实例，即可将 Kaleidr Chat 连接到受支持的 Mapbox、Google Maps 或 MapLibre 实现。请阅读 Kaleidr SDK 快速入门 了解聊天挂载方法。当宿主后端需要使用服务器密钥执行推理、检索、路由或设计工作流时，请使用 平台 API 端点。
常见问题
什么是 AI 地图 SDK？
AI地图SDK是一种软件开发工具包，可将AI推理与实时地图或嵌入式空间组件连接起来。它可以管理用户界面、身份验证、结构化场所事件、地图操作、提供程序适配器、生命周期以及平台API访问。
AI 地图 SDK 与地图 API 相同吗？
不。地图API通常提供数据或远程地理操作。AI 地图 SDK 提供了连接 AI、UI、地图状态、身份验证和结构化操作的应用程序集成层。
它会取代 Mapbox、Google Maps 或 MapLibre 吗？
不一定。Kaleidr 当前的聊天 SDK 会连接到受支持的实时地图，而现有服务提供商则继续渲染该地图。
浏览器应该使用服务器 API 密钥吗？
不。通过 SDK 使用可发布的浏览器安全密钥。将服务器密钥放在后端。
它可以使用私有业务数据吗？
是的，通过授权架构。主机后端应仅检索允许的记录，执行租户和对象访问，减少暴露的字段，并保持商业系统的权威性。
参考文献
- Google. Maps JavaScript API Overview. Google Maps Platform documentation. Accessed 1 August 2026. https://developers.google.com/maps/documentation/javascript/overview
- Google. Maps JavaScript API: Maps Reference. Google Maps Platform documentation. Accessed 1 August 2026. https://developers.google.com/maps/documentation/javascript/reference/map
- Kaleidr. Auth & scopes. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes
- Kaleidr. CDN versioning. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/reference/cdn-versioning
- Kaleidr. Chat — attach AI to your map. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/sdk/chat-attach
- Kaleidr. CORS & allowed origins. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins
- Kaleidr. Endpoints. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/platform-api/endpoints
- Kaleidr. Introduction. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/
- Kaleidr. kaleidr.js — the loader. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
- Kaleidr. kaleidr-map — the element. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/sdk/kaleidr-map-element
- Kaleidr. Quota & rate limits. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/platform-api/quota-and-rate-limits
- Kaleidr. Quickstart. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/quickstart
- Kaleidr. SSE wire contract. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/platform-api/sse-wire-contract
- Kaleidr. Viewer — embed a published map. Kaleidr Developer Docs. Accessed 1 August 2026. https://docs.kaleidr.com/sdk/viewer-embed
- Mapbox. Map — Mapbox GL JS. Accessed 1 August 2026. https://docs.mapbox.com/mapbox-gl-js/api/map/
- MapLibre. Map — MapLibre GL JS. Accessed 1 August 2026. https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/
- MDN Web Docs. Using Custom Elements. Accessed 1 August 2026. https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
- MDN Web Docs. Using Server-Sent Events. Accessed 1 August 2026. https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events
@misc{kaleidr_sdk_loader,
title = {kaleidr.js -- the loader},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 1 August 2026},
url = {https://docs.kaleidr.com/sdk/kaleidr-js}
}
@misc{kaleidr_chat_attach,
title = {Chat -- attach AI to your map},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 1 August 2026},
url = {https://docs.kaleidr.com/sdk/chat-attach}
}
@misc{kaleidr_auth_scopes,
title = {Auth \& scopes},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 1 August 2026},
url = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}
@misc{kaleidr_sse_contract,
title = {SSE wire contract},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 1 August 2026},
url = {https://docs.kaleidr.com/platform-api/sse-wire-contract}
}
@misc{mdn_custom_elements,
title = {Using Custom Elements},
author = {{MDN Web Docs}},
note = {Accessed 1 August 2026},
url = {https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements}
}
@misc{mdn_server_sent_events,
title = {Using Server-Sent Events},
author = {{MDN Web Docs}},
note = {Accessed 1 August 2026},
url = {https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events}
}
@misc{mapbox_map_object,
title = {Map -- Mapbox GL JS},
author = {{Mapbox}},
note = {Accessed 1 August 2026},
url = {https://docs.mapbox.com/mapbox-gl-js/api/map/}
}
@misc{maplibre_map_object,
title = {Map -- MapLibre GL JS},
author = {{MapLibre}},
note = {Accessed 1 August 2026},
url = {https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/}
}