如何为地图添加 AI 聊天

你可以为已经使用 Mapbox、Google Maps 或 MapLibre 运行的地图添加 AI 聊天，而无需更换渲染器。宿主应用继续负责界面、权限、业务逻辑和地图服务商账户，Kaleidr 只提供对话层。该层负责理解位置问题、流式传输地点与地图操作数据、绘制已解析的位置，并随着答案生成而移动实时地图。

添加助手并不意味着把所有产品责任交给模型。生产环境集成仍需要按来源限制的浏览器密钥、有可靠依据的源数据、针对不同服务商的生命周期处理、错误状态、无障碍支持和分析。下文将依次介绍 SDK 挂载、服务商配置、密钥安全、答案依据、用户体验、测试，以及能够判断助手是否真正帮助用户完成任务的指标。请把本文作为架构与集成参考，而不是功能概览。如果想在接入 SDK 前体验对话式地图，可从 Kaleidr AI 开始；如需了解它与手工构建的自定义地图有何区别，请参阅 Kaleidr 与 Google My Maps 对比。

通过Kaleidr SDK将AI聊天连接到实时网页地图，并带有独立的浏览器和后端安全边界。

你将构建什么

完成的体验可协调两个保持同步的表面:一个已在应用程序中运行的交互式地图，以及一个在该地图旁边或上面安装的AI聊天面板。用户用自然语言表达目标，同时用散文和地图状态回答助手。表面不会引起另一个，因为值来自于将它们一起读取。代表性请求如下:

展示今天下午开放的海滨附近适合家庭的场所。

助手解析地理意图，返回相关位置，向实时地图添加引脚，框定结果区域，并给出读者可以通过后续问题进行细化的回答。Kaleidr 的聊天附件正是围绕此循环构建的:product: "chat" 集成将 Kaleidr 控制塔安装在应用程序已渲染的地图上，通过该位置移动时，可检测渲染器、解析位置，并更新摄像头。当前文档在支持的实时地图实例中列出了 Mapbox、Google Maps、MapLibre 和 Leaflet——请参阅 Kaleidr 聊天附件参考和 developer squetart。对话地图适合抵御固定筛选项的情境问题，但传统的搜索框可能仍然是确定性任务的更好界面，例如查找已知的存储ID、选择固定类别或显示预定义的路由。

架构如何工作

添加对话性人工智能并不能将每一项责任转移到模型中;可靠的实现使应用程序、渲染器、人工智能层、源系统和安全边界保持不同。每一层都拥有其他人不应执行的工作，而分离则使答案保持依据，且权限具有可执行性。下图追溯了问题在各层之间的流动方式，以及每个职责名称的表。

将主机应用程序、Kaleidr 聊天、渲染器、权威数据和安全后端分隔的分层AI地图架构。

组件	主要责任
主机应用程序	用户界面、登录用户、租户上下文、权限、工作流程、错误恢复
地图渲染器	地图显示、摄像头、图层、标记、控件以及针对提供方的特定行为
Kaleidr人工智能层	意图解读、流式传输位置答案、支持的地图操作以及聊天界面
位置服务	将实现时使用的分辨率、地理编码、空间上下文、路线和提供方数据
商业系统	权威的私人、运营、库存、客户或财产记录
主机后端	安全检索、授权、租户隔离、审计以及服务器端API调用

语言模型不应成为地址、营业时间、库存、资格、路线、房产状况或内部商业事实的权威来源。人工智能层负责解释请求并协调支持的操作，而权威服务则验证答案所依赖的事实。Kaleidr 的流媒体合约反映了这种分离:散文逐渐送达，解析的场所在结构化的 place 事件中到达，地图操作可以进入 early_actions，源信息可在 grounding 中到达，而最终的 end 活动可承载完整的文本、地点和操作。使用kaleidr.js的开发者从不手动解析这些事件，而构建自定义客户端的团队可以按照SSE Wire-Contract 引用进行操作。

开始前需要准备什么

在安装聊天面板之前，请先确认一份简短的前提，以便在设置时实现集成，而非在运行时无声地进行。现阶段大多数问题都可以追溯到一个缺失的物品——一个未确定的原点、一张没有高度的地图，或者没有合适作用域的钥匙。在此处花费几分钟，请将调试会话保存为仅间接报告的错误。确认以下每一项:

正在使用的地图箱、Google Maps或地图实例;
具有聊天API访问权限的Kaleidr组织;
可发布的可发布浏览器密钥，可执行ai范围;
至少允许一个浏览器来源用于实时发布密钥;
当前kaleidr.js加载器;
具有显式高度的地图容器;
聊天容器或受支持的自定义元素;
Mapbox或Google Maps所需的提供商凭证;
从真实用户工作流程中得出的代表性问题;
为任何操作事实定义真相源系统。

完整的开发者 API 访问权限（包括可发布密钥、服务器密钥和嵌入支持）随 Kaleidr Pro 与 Enterprise 方案提供；免费方案可能只提供范围限定为地图图块的浏览器密钥。开始构建前，请查看当前 Kaleidr 定价页面和API 密钥文档，确保所选方案能够创建需要的凭证。如果你的账户无法访问 API 密钥页面，请联系 Kaleidr 团队申请权限，不要在浏览器代码中改用服务器凭证。

如何使用 Kaleidr SDK 为地图添加 AI 聊天

当前加载器是一个单脚本标签。你每页在提供方自己的脚本之前或旁边添加一次，并且能够主动缓存是安全的。该标签安装了本指南中每次稍后调用时所依赖的全局入口。

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

加载器会安装window.Kaleidr和<kaleidr-map>元素，仅在需要时才会在后台提取所选的产品包;加载器本身则不会捆绑MapLibre和React。SDK 支持 chat、viewer、editor 和 tile 产品，因此请按照当前页面所示的具体嵌入值来显示您构建的具体内容。对于已拥有的实时地图，命令式API是最清晰的路径。下面的示例将现有的地图对象直接交给了Kaleidr:

<div class="map-chat-layout">
  <div id="map" aria-label="Interactive location map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  function mountKaleidrChat(map) {
    if (!map) {
      throw new Error("A live map instance is required.");
    }

    return Kaleidr.mount("#chat", {
      product: "chat",
      publishableKey: "kld_pk_live_REPLACE_ME",
      map,
    });
  }
</script>

Kaleidr.mount(target, options) 会同步返回一个句柄，而产品包在后台加载，加载完成后，该操作会对该操作进行排队调用。保留返回的手柄，以便主机应用程序在线路变更、账户切换或组件未安装时能够更新摄像头或拆解集成。后续的提供程序示例将每个渲染器的当前设置与此挂载调用相结合;在部署到生产阶段之前，验证了固定的提供程序版本以及最新的 Kaleidr SDK 操作。

为 Mapbox 添加 AI 聊天

Mapbox GL JS 在浏览器容器中创建一个 mapboxgl.Map 实例，且需要访问令牌。Mapbox 建议仅将公共令牌范围用于客户端应用程序的需求范围，并在服务器上实施了 URL 限制，并保留了隐秘范围操作。下面的示例将引导与Kaleidr记录的挂载调用进行对比。加载两个脚本，创建地图，并在地图启动其 load 事件后重新挂载聊天:

<link
  href="https://api.mapbox.com/mapbox-gl-js/v3.27.0/mapbox-gl.css"
  rel="stylesheet"
/>

<script src="https://api.mapbox.com/mapbox-gl-js/v3.27.0/mapbox-gl.js"></script>
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<div class="map-chat-layout">
  <div id="map" aria-label="Mapbox map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

<script>
  const map = new mapboxgl.Map({
    accessToken: "YOUR_MAPBOX_PUBLIC_TOKEN",
    container: "map",
    center: [-0.12, 51.5],
    zoom: 11,
  });

  map.on("load", () => {
    try {
      window.kaleidrChat = Kaleidr.mount("#chat", {
        product: "chat",
        publishableKey: "kld_pk_live_REPLACE_ME",
        map,
      });
    } catch (error) {
      console.error("Kaleidr chat failed to mount:", error);
    }
  });

  map.on("error", (event) => {
    console.error("Mapbox error:", event.error ?? event);
  });
</script>

Kaleidr 的供应商指南目前演示了 Mapbox GL JS v3.0.0，而 Mapbox 的 CDN 指南则记录了稍后的 v3.27.0 构建，因此请保留应用程序已测试的版本，并确认兼容性，然后仅为此集成进行升级。Mapbox 令牌和 Kaleidr 可发布密钥分别验证不同的系统和账单:该令牌对渲染器和 Mapbox 服务进行身份验证，且可发布密钥通过浏览器 SDK 对 AI 聊天范围进行身份验证。最常见的设置故障是缺少映射容器高度、被弃置或超范围的Mapbox令牌，以及在应用程序建立地图实例之前安装聊天。

为 Google Maps 添加 AI 聊天

Google Maps平台需要一个地图JavaScript API密钥，并支持动态库导入、直接脚本加载和NPM加载程序。Kaleidr 的官方集成指南采用直接回调模式，这是首次集成时最可预测的选项。回调会创建google.maps.Map实例，并直接将其传递给Kaleidr.mount。下面的示例将键、回调和支架连接在一起:

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<div class="map-chat-layout">
  <div id="map" aria-label="Google map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

<script>
  function initMap() {
    try {
      const map = new google.maps.Map(document.getElementById("map"), {
        center: { lat: 51.5, lng: -0.12 },
        zoom: 11,
      });

      window.kaleidrChat = Kaleidr.mount("#chat", {
        product: "chat",
        publishableKey: "kld_pk_live_REPLACE_ME",
        map,
      });
    } catch (error) {
      console.error("Google Maps or Kaleidr initialization failed:", error);
    }
  }

  window.gm_authFailure = function () {
    console.error("Google Maps authentication failed.");
  };
</script>

<script
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_MAPS_KEY&callback=initMap"
  async
></script>

Google 地图密钥和 Kaleidr 密钥可独立服务不同的系统和账单，因此将 Google 密钥限制在所需的网站和 API 上，并将 Kaleidr 密钥限制在准确允许的来源上。谷歌的地图 JavaScript API 密钥加载和账单，而 Kaleidr 可发布密钥加载并支付 AI 聊天功能。另一个区别是:这种集成针对应用程序内的Google MapsJavaScript API实例，并且不附加到单独的Google My地图文档中。

为 MapLibre 添加 AI 聊天

MapLibre GL JS 是一款用于矢量图的开源浏览器渲染器，MapLibre 应用程序必须提供样式以及样式引用的图块、glyph 和 sprite 源。因此，主办团队拥有的渲染器和基础设施决策比使用完全托管的地图服务要多。当前的 MapLibre 文档在版本 6 中使用 ES 模块。下面的示例将该模式与Kaleidr的挂载调用进行调整:

<link
  href="https://unpkg.com/maplibre-gl@6.0.0/dist/maplibre-gl.css"
  rel="stylesheet"
/>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<div class="map-chat-layout">
  <div id="map" aria-label="MapLibre map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

<script type="module">
  import * as maplibregl from "https://unpkg.com/maplibre-gl@6.0.0/dist/maplibre-gl.mjs";

  const map = new maplibregl.Map({
    container: "map",
    style: "https://demotiles.maplibre.org/style.json",
    center: [-0.12, 51.5],
    zoom: 11,
  });

  map.on("load", () => {
    try {
      window.kaleidrChat = Kaleidr.mount("#chat", {
        product: "chat",
        publishableKey: "kld_pk_live_REPLACE_ME",
        map,
      });
    } catch (error) {
      console.error("Kaleidr chat failed to mount:", error);
    }
  });

  map.on("error", (event) => {
    console.error("MapLibre error:", event.error ?? event);
  });
</script>

Kaleidr 当前的 MapLibre 指南采用全局 UMD 式 MapLibre 构建和 Kaleidr 托管式 URL，而该提供程序的文档已移至版本 6 ES 模块，因此请为应用程序选择一种一致的 MapLibre 版本和加载方式，而不是将全局版本和模块构建混合在一起。MapLibre 不提供其自身的通用托管基图，这意味着第三方磁贴或风格提供商会自行提供其所需的凭据、归因、许可、使用和计费要求。Kaleidr 设计的磁贴还可以与 MapLibre 配对，当前的平面图和样式配置支持该工作流程。

助手如何理解地图

通用会话助手可以描述地点，但无法与页面上的地图协调。缩小这一差距，是使助理地图变得有感知性而非仅仅对话的原因。映射感知助手需要一个结构化的交互循环，该循环将语言与渲染器状态连接起来。每个转弯都通过以下顺序进行:

用户提交位置问题。
Kaleidr 识别地点、区域、邻近地点、类别或路线意图。
相关服务会确定位置或获取已批准的数据。
结构化位置和动作事件流式传输到客户端。
该集成会添加引脚、框架区域、突出显示结果，或应用另一个支持的地图操作。
界面将散文答案与可见的地理证据一起呈现。

Kaleidr 将循环暴露为一组小串流事件，每个事件都带来单一的结果。客户端会订阅一次，并在每个事件到达时进行响应，而不是等待最终的有效载荷。以这种方式阅读该流会保持界面响应，而答案仍在形成。记录的事件是:

place 带有已解决的位置和坐标;
place_linked 丰富了现有场所;
early_actions 可以携带早期地图操作，例如拟合边界或突出显示结果;
grounding 提供依据转弯的来源;
end 是包含完整文本、地点和操作的权威最终信封;
error 以错误消息终止该流。

将这些结构化事件视为应用程序合同，当SDK或API已提供已解析的位置对象时，不要从散文中获取地名。这种区别很重要，因为散文可以转述一个名称，而已解析的位置对象则带有稳定标识符，并协调渲染器所需的位置，以正确绘制结果。在对象而非文本上进行构建，当模型的措辞在发布之间发生变化时，也能保持集成的稳定。

可发布密钥与服务器密钥

Kaleidr 为同一组织和功能范围提供两类凭证。正确区分它们，是浏览器集成中最重要的安全决策：可发布密钥用于浏览器，服务器密钥绝不能进入浏览器。混用两者很容易让原本正常的演示泄露敏感凭证。下图和表格概括了两类密钥各自的使用边界：

将Kaleidr可发布的浏览器密钥、仅限服务器的密钥、功能范围以及独立的地图提供凭证进行分离的安全图。

决策区域	可发布密钥	服务器密钥
预修复	`kld_pk_live_…`	`kld_sk_live_…`
运行时间	浏览器SDK、HTML、`<kaleidr-map>`	仅限后端服务
浏览器曝光	设计用于页面源中	绝不能出现在页面源中
如何进行身份验证	SDK 将其交换为一个短暂的、由源绑定的会话	发送为 `Authorization: Bearer …` 或 `X-Api-Key`
起源控制	实时密钥需要批准来源	未启用浏览器;无 CORS 资助
适当使用	通过 SDK 嵌入聊天、编辑器和磁贴	服务器到服务器平台API调用
主要规则	限制其确切来源，并仅通过SDK使用	安全存储，使其远离浏览器和版本控制

在文档流程下，未经允许来源的实时发布密钥被拒绝，因此在创建密钥时添加精确的生产和预发布环境来源。每个请求的浏览器Origin头与列表完全匹配，因此允许的来源必须是https://app.example.com等原始来源——即无路径或尾随斜线的方案和主机，并且列出您所服务的每个来源，包括本地开发来源。密钥还具有功能范围:用于聊天和推理的 ai、用于编辑器路由的 design，以及用于设计基图和图块的 maps。

平台通过不同的状态码来表示凭证问题，界面应对每个代码进行不同的处理。缺失、无效、撤销或过期的凭证返回401;未使用所需范围的有效密钥返回insufficient_scope;以及配额或并发限制返回429，接口应将其视为容量或计划条件，而非通用产品故障。Mapbox 和 Google Maps 凭据始终与 Kaleidr 凭据保持独立，因此请独立地应用每个提供商的限制。

用可靠的位置数据为 AI 答案提供依据

与地点相关的幻觉尤其有害，因为地图会使错误的答案看起来具体且值得信赖。纯文本中的错误地址会引发第二次观察，而相同的错误则固定在坐标上，并按照验证进行读取。地图的权威正是整合必须获得而非假设的。常见的失效模式在设计之前值得命名:

伪造的企业或设施;
一个模糊的地名解析为错误的城市;
过时的地址或开放时间;
代表同一地点的重复记录;
通过服务请求的路线，该应用程序尚未获得授权;
在可见区域或允许区域外推荐;
一种与内部系统相冲突的操作主张。

依据架构通过分辨率和检索来引导每个答案，而非自由形式生成，使模型保持在其通道中。该模型提出意图，权威服务机构在任何事物到达地图之前，先决定什么是真实的。每个阶段都是应用程序控制的检查点，而不是模型自行执行的步骤。流量从用户的单词到可见的、经过检查的结果，向一个方向读取:

用户意图 → 人工智能解读 → 权威的检索或位置分辨率 → 允许地图操作 → 可见答案

实际控制源于这种流动。在规划前将位置解析为坐标并建立稳定标识符，显示用于答案的地理区域，在响应依据时保留源链接或标签，并将公共场所事实与私人操作数据区分开来。拒绝不受支持的操作，而非即兴操作，提供可见的无结果状态，让用户纠正位置模糊性，并记录用于商业回答的源和租户上下文。最重要的是，将最终的结构化结果视为契约，而非伴随它的自由形式的散文。有关地点身份、证据和推荐信号的更广泛讨论，请参阅Kaleidr关于AI驱动的本地商业发现的文章，以及对话面背后的架构与安全原理，请参阅在交互式地图中添加AI聊天助手。

助手可以使用私有业务数据吗？

人工智能聊天面板不应被公司运营数据库的无限制访问，因为单个过于宽泛的查询可能暴露出远超当前问题的需求。因此，私有数据集成需要明确的检索和授权设计，而不需要模型能够通过的开放式连接。最安全的默认规则是，在每个新增内容为特定数据集、字段设置和访问规则提供合理性之前，不会暴露任何内容。在将任何私人来源连接到助手之前，先确定以下边界:

助手可以查询哪些数据集;
哪些属性可以离开源系统;
哪位用户和租户可以访问每一张记录;
租户隔离的执行方式;
哪些字段具有敏感性;
检索是否贯穿主机后端;
记录的内容以及记录时间的长数;
源归因如何保存;
适用哪些区域、合同或留任要求;
哪些操作需要人为确认。

Kaleidr Enterprise 描述了针对位置感知产品堆栈的推理 API、排名系统、分析以及部署支持，但公共文档并非为每个私有数据库建立一个通用连接器。检索路径取决于您自己的系统、权限模型和合规性约束，这些限制是通用连接器无法代表您承担的。将私有数据路径视为特定实现或企业集成，直到为您的环境记录确切的来源、授权和检索机制。

实用地图聊天的 UX 模式

如果聊天和地图需要关注，而非配合，技术上正确的集成仍然会失败。隐藏地图的面板，或无需说明的跳转地图，导致用户无法确定该信任的表面。下面的模式将两者保持为一个答案，而每个模式都涉及一种特定的配对方式，即容易破裂。

保持地图可见

地图是答案的一部分，而不是聊天可以覆盖的背景。在桌面上，避免将其隐藏在全屏聊天表面，在移动设备上，请使用可调整的表格或紧凑的聊天模式，以保留足够的地图上下文，从而理解结果。无法看到引脚的用户无法判断答案是否正确。

显示助手触发的更改

当助手添加标记时，应更换摄像头、突出显示区域或启动路线，使动作清晰可见。地图状态的突然跳跃，且无可见原因，会读成错误，因此会动画化或标注变化。用户应始终理解地图移动的原因。

保留手动控件

用户在助理行动后仍需进行平底锅、缩放、重置、定位、滤镜和直接标记选择。人工智能应添加交互路径，而不是移除用户已依赖的现有恢复路径。将对话视为一种与标准对话并列的又一控制，而非替代它们。

支持撤销和重置

提供清晰的清除助手标记、恢复前置摄像头以及重启对话的方法。不可逆的地图状态会在探索性问题时产生混淆，用户通常希望将一个答案与最后一个答案进行比较。一次重置费用使死胡同重新变成一次探索。

提供推荐问题

建议会向用户介绍系统可以执行哪些操作，并减少空置或不受支持的请求。将示例基于实际的产品工作流程，而非通用的旅游提示，因为一个反映实际任务的建议既能证明价值，又能引导模型向能够很好地回答的查询方向。随着产品的增长，将它们旋转，因此面板会持续宣传当前功能，而不是冷冻启动器。

设计无结果和错误状态

区分一个无匹配结果，源于一个模糊的地点、一个已过期的会话、一个不允许的来源、一个提供者错误、一个配额条件以及一个不受支持的请求。出现问题并不足以实现地图工作流程，其中恢复步骤在错误来源和空结果集之间存在明显差异。说明状况并提供下一步。

为无障碍使用进行设计

标记聊天区域和地图，保留键盘顺序，并宣布流媒体状态，且不会压倒屏幕阅读器。仅通过标记颜色传达的任何信息都必须以文字身份提供，因此无法分辨颜色的用户仍会收到完整答案。这里的可访问性与依据一样:答案必须在被宣读后继续，而不仅仅是被看清。

需要跟踪的事件和指标

原始聊天打开并不证明其价值，因此可以利用助手来测量它是否真的能帮助用户完成地图任务。以下事件名称是编辑推荐，而非关于自动释放的Kaleidr Analytics事件的主张。将它们调整到你自己的模式中，但保持尝试、成功与失败之间的分割，而这些指标随后依赖于这些模式。从类似这样的事件集开始:

map_chat_opened
map_chat_question_submitted
map_chat_answer_returned
map_chat_no_result
map_chat_error
map_action_applied
map_result_selected
map_marker_opened
map_chat_followup_submitted
map_chat_shared
map_chat_to_editor

从这些事件中，真正体现有用性的指标是完成和结果衡量，而非数量。打开和问题计数描述流量，但他们却对助手是否解决了任务没有说明。因此，一个有用的仪表板将每个活动计数与其预期生成的结果进行对比。将其按在跟踪已完成工作的指标上，例如:

问题完成率;
回答成功率;
无结果率
技术错误率
地图操作成功率;
结果选择率;
开标率;
后续问题率
时间到有益结果;
储蓄或分享费率;
下游转换
完成聊天驱动地图操作的用户的七天回报率。

按提供程序、设备、查询类型、客户账户和激活工作流对结果进行细分，因为聚合数会显示助手工作的位置和不工作位置。高开率与较低的选择率相结合，通常意味着好奇心而非产品价值，这正是仅通过追踪方式打开时所鼓励的误读。共同阅读这些片段，说明哪些领域值得投入更多投资，哪些需要重新思考。

生产测试检查清单

内部演示提示通常比用户实际输入的问题更清晰且更具体。仅针对整洁的输入进行测试，会隐藏最重要的故障状态，从拼写错误的地方到过期的会话。下面的列表故意将模糊的语言、提供者错误和生命周期事件混杂在一起，因为每个事件都会在集成中练习不同的部分。在发货前，请根据这些混乱的输入和错误条件对助理进行锻炼:

模糊的问题;
位置拼写错误;
不同地区的重复地名;
空结果集;
无效的可发布密钥;
不允许的来源;
已过期的浏览器会话;
缺少能力范围;
429 配额或并发回复;
缓慢或中断的网络;
提供者配额或身份验证失败;
地图样式重新加载;
移动尺寸和定向变化
仅限键盘导航;
屏幕阅读器标签和实时更新;
无根据的请求;
未经授权的私有数据请求;
在地图准备就绪前进行聊天安装;
一页上的多个地图实例;
路线变更及组件卸载;
用户、组织或租户切换。

常见实现错误

以下故障在集成中反复发生，且每个故障都有清晰的校正。没有一种是异域，这正是它们容易意外发货的原因。将表格作为清单，说明哪些会中断、为何会断裂，以及该做什么。

错误	会发生什么	建议更正
在可用地图实例存在之前安装聊天	助手无法控制预期的渲染器	安装在提供程序记录的初始化点之后，然后通过实时地图对象
曝光 Kaleidr 服务器密钥	后端承载者可公开恢复	在浏览器中使用受来源限制的可发布密钥
忘记配置允许的来源	实时浏览器身份验证会被拒绝，或密钥保护范围过宽	创建密钥时添加准确的生产与预发布环境来源
将模型散文视为源数据	错误的事实可以被呈现为权威	使用已解决的场所、依据点和权威的商业系统
允许不受限制的地图操作	接口可以进入意外状态	仅应用有记录和允许列出的操作
更换手动控制	用户会失去恢复和直接导航	保留标准地图控制和重置路径
仅跟踪聊天功能	参与被误认为是任务成功	跟踪答案、地图操作、结果选择和下游结果
无视无结果状态	用户将沉默解读为一种破碎的产品	返回一条特定的空状态信息和一个恢复建议
混合服务提供商和Kaleidr证书	账单、安全和调试变得不明确	保持凭据、限制和监控分开
未测试移动布局	聊天遮蔽地图或打破触摸导航	使用响应式面板和测试方向更改

三个渲染模型的中性技术对比，每个模型都连接到相同的Kaleidr AI聊天层。

Mapbox、Google Maps 还是 MapLibre：应该选择哪一个？

Kaleidr 是人工智能交互层，因此渲染器决策仍然属于主机产品，而非助手。正确的渲染器取决于您现有的工具、样式控制以及基础设施需求，而聊天层对此没有变化。下表总结了每个渲染器的拟合位置以及主队继续拥有的内容，Kaleidr 在这三个方面均以一致的对话层添加。

供应商	适合时	主队注意事项
Mapbox	该应用程序使用Mapbox的托管开发工具、样式、数据生态系统以及GL JS渲染器	公共令牌、URL 限制、提供商使用、样式生命周期和 Mapbox 计费
Google Maps	该应用程序依赖于Google Maps平台、谷歌位置上下文或现有的地图JavaScript实现	受限的谷歌API密钥、启用的API、谷歌账单、回调或加载器生命周期
MapLibre	该团队希望提供开源渲染器，并加强对样式、磁贴和基础设施的控制	风格与图块源、归因、托管、性能、提供商许可以及版本管理
Kaleidr	该应用程序需要在支持的渲染器上进行对话位置交互	可发布密钥、`ai` 范围、允许来源、组织配额、依据和产品分析

当当前地图已满足应用程序渲染需求时，请勿仅将渲染器切换以添加聊天。将现有的实时地图实例传递给Kaleidr，并测量对话层是否改进了特定定义的用户任务。渲染器迁移是一个大而独立的决定，它应基于自身的渲染和基础设施优势，而非聊天功能。

最终实现检查清单

已确认现有的地图工作流程
已确认支持渲染器
服务提供商地图加载成功
供应商凭证受限
已确认Kaleidr计划与访问
可发布密钥
ai 范围已确认
允许的来源已配置
服务器密钥被排除在浏览器代码之外
kaleidr.js 加载一次
实时地图实例传递给Kaleidr.mount
与应用程序生命周期相关的聊天生命周期
已确认支持的地图操作
实源系统记录
实现无结果和错误状态
已实现配额处理
添加了分析事件
安全与隐私审查已完成
可访问性测试
测试了移动行为
真实用户问题测试

结论

Mapbox、Google Maps 和 MapLibre 无需更换，无需添加具有地图感知意识的 AI 聊天，因为渲染器仍会拥有地图显示和提供方特定的行为。主机应用程序继续拥有用户、权限、业务逻辑和数据治理，而 Kaleidr 则添加了解析位置意图的对话层，流式传输结构化的位置结果、图块位置以及坐标支持的地图操作。两个职责保持鲜明，这正是使集成保持可调试和答案的基础。

当自然语言能减少位置工作流程中有意义的摩擦时，而不是仅仅在页面上添加聊天框时，这一集成就获得了一席之地。只有在答案保持依据、浏览器和服务器凭据保持分离、提供方职责明确、分析衡量已完成的地图任务而非仅聊天活动时，它才会成功。与这四个条件相比，助手成为一条真正的互动路径，而非新奇事物。需要先发制人、先进行地图创作(不仅在现有地图上进行聊天)的团队，也可以从Kaleidr Studio开始。

为现有地图添加 AI 交互

将Kaleidr聊天连接到已运行的Mapbox、Google Maps或MapLibre地图，无需更换渲染器。当前的 SDK 只需要实时地图实例和一个源限制的可发布密钥，且在这三个情况下，挂载调用完全相同。使用 ai 范围创建一个密钥，添加允许的来源，然后将地图传递给 Kaleidr.mount。

获取 Kaleidr API 密钥

查看完整实现

Kaleidr 的开发人员文档涵盖了本指南总结的部分，深度涵盖生产构建需求。SDK 快速启动、提供者专用指南和身份验证模型与查看器、编辑器、磁贴和平台-API 引用并列。从工作原型转向强化集成时，先开始。

阅读开发者文档

常见问题

可以为现有地图添加 AI 聊天吗？

是的。Kaleidr 的聊天产品接受实时地图实例，并当前记录 Mapbox、Google 地图、MapLibre 和 Leaflet 附件。现有的渲染器负责显示地图，而 Kaleidr 会在上面添加对话图层。

需要替换 Mapbox、Google Maps 或 MapLibre 吗？

不。主机应用程序可以保留其现有的渲染器，而Kaleidr作为AI交互层连接到实时地图实例。将地图实例传递给Kaleidr.mount就足够了——无需进行渲染器迁移。

Kaleidr 如何连接实时地图？

加载kaleidr.js，创建或获取提供方的实时地图对象，并调用Kaleidr.mount，使用可发布的密钥和地图实例。Kaleidr 自动检测受支持的渲染器，并通过它协调标记和摄像头。

应该使用可发布密钥还是服务器密钥？

通过浏览器SDK使用可发布密钥进行聊天、编辑器或磁贴嵌入，并仅使用服务器密钥用于后台平台API请求。可发布的密钥设计为出现在页面源中;服务器密钥绝不能出现。

如何防止助手编造地点？

通过权威的定位服务解决场所，利用结构化场所和依据活动，并将商业系统作为真相的源泉。允许列出助手可能采取的地图操作，并提供明确的无结果和模糊性，使答案出现不确定，而非虚构位置。

Kaleidr 会承担 Mapbox 或 Google Maps 的使用费吗？

不。服务提供商账户和Kaleidr账户是独立的:Mapbox或Google向渲染器及相关服务提供商服务进行账单，而Kaleidr则针对Kaleidr组织对AI功能进行账单。各供应商各自独立地实施其限制和配额。

AI 聊天适合所有地图吗？

不。固定的搜索框、筛选器或直接的地图控制通常更适合简单的确定性任务，例如开设一家知名门店或选择一个类别。当用户需要表达上下文、更改或多变量位置意图时，人工智能聊天最有用，而这些意图是固定滤波器无法捕捉的。

参考文献

Google. Load the Maps JavaScript API. Google Maps Platform documentation. Accessed 24 July 2026. https://developers.google.com/maps/documentation/javascript/load-maps-js-api
Google. Google Maps Platform security guidance. Google Maps Platform documentation. Accessed 24 July 2026. https://developers.google.com/maps/api-security-best-practices
Kaleidr. Attach Kaleidr AI to a Google map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/guides/attach-ai-to-google-maps
Kaleidr. Attach Kaleidr AI to a Mapbox map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/guides/attach-ai-to-mapbox
Kaleidr. Attach Kaleidr AI to a MapLibre map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/guides/attach-ai-to-maplibre
Kaleidr. Auth & scopes. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes
Kaleidr. Chat — attach AI to your map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/sdk/chat-attach
Kaleidr. CORS & allowed origins. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins
Kaleidr. Get an API key. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/get-an-api-key
Kaleidr. Pricing & Plans. kaleidr.com. Accessed 24 July 2026. https://kaleidr.com/pricing
Kaleidr. Quickstart. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/quickstart
Kaleidr. SSE wire contract. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/platform-api/sse-wire-contract
Mapbox. Get started with Mapbox GL JS using a CDN. Mapbox GL JS documentation. Accessed 24 July 2026. https://docs.mapbox.com/mapbox-gl-js/guides/get-started/use-with-cdn/
Mapbox. How to use Mapbox securely. Mapbox Help. Accessed 24 July 2026. https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/
MapLibre. Display a map. MapLibre GL JS documentation. Accessed 24 July 2026. https://maplibre.org/maplibre-gl-js/docs/examples/display-a-map/
MapLibre. Map event types. MapLibre GL JS API documentation. Accessed 24 July 2026. https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapEventType/

@misc{kaleidr_chat_attach,
  title  = {Chat — attach AI to your map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/sdk/chat-attach}
}

@misc{kaleidr_auth_scopes,
  title  = {Auth \& scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{kaleidr_mapbox_guide,
  title  = {Attach Kaleidr AI to a Mapbox map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/guides/attach-ai-to-mapbox}
}

@misc{kaleidr_google_maps_guide,
  title  = {Attach Kaleidr AI to a Google map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/guides/attach-ai-to-google-maps}
}

@misc{kaleidr_maplibre_guide,
  title  = {Attach Kaleidr AI to a MapLibre map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/guides/attach-ai-to-maplibre}
}

@misc{mapbox_cdn_guide,
  title  = {Get started with Mapbox GL JS using a CDN},
  author = {{Mapbox}},
  note   = {Mapbox GL JS documentation; accessed 24 July 2026},
  url    = {https://docs.mapbox.com/mapbox-gl-js/guides/get-started/use-with-cdn/}
}

@misc{google_maps_js_loader,
  title  = {Load the Maps JavaScript API},
  author = {{Google}},
  note   = {Google Maps Platform documentation; accessed 24 July 2026},
  url    = {https://developers.google.com/maps/documentation/javascript/load-maps-js-api}
}

@misc{maplibre_display_map,
  title  = {Display a map},
  author = {{MapLibre}},
  note   = {MapLibre GL JS documentation; accessed 24 July 2026},
  url    = {https://maplibre.org/maplibre-gl-js/docs/examples/display-a-map/}
}