聊天

Kaleidr Chat 是一个可添加到已有地图页面的聊天面板。访客输入问题（“泰特现代美术馆附近哪里可以吃早餐？”），回答会在面板中逐步显示，回答中提到的地点也会作为标记出现在您的地图上，镜头会移动以展示这些地点。

面板直接运行在您的网页中，而不是 iframe 中。您只需加载一个脚本，使用可发布密钥和正在运行的地图对象调用 Kaleidr.mount，面板便会关联该地图。您原有的地图库、样式、图层和控件均保持不变。

访客的使用体验

地图左上角会显示写有 Ask Kaleidr 的输入栏。
访客提交问题后，输入栏会展开为聊天窗口，回答以文字形式逐步显示。
回答中提到的每个地点都会变成聊天结果卡片和地图标记。只有一个地点时，镜头会飞向该地点；有多个地点时，镜头会调整视野以容纳所有地点。
点击标记或结果，会打开地点卡片，其中包含简短介绍、照片、路线指引，以及针对该地点的追问输入框。
询问路线时，地图上会绘制路线并调整镜头视野。
前面问题的标记会在本次对话剩余期间一直留在地图上，包括所有受支持的地图以及 Kaleidr Viewer 或 Tile 元素。关闭聊天窗口会结束对话，并移除其标记和路线。

当视口宽度不超过 768 px 时，面板会以底部抽屉而不是浮动窗口显示。

对您的地图执行哪些操作

会执行的操作	不会执行的操作
添加和移除聊天自己的标记	读取、修改或删除您的图层、数据源或标记
将镜头移动到某个地点，或调整视野以容纳多个地点	将您的图层、标记或当前可见区域发送给 Kaleidr
绘制路线，然后移除路线	发生事件时回调您的代码
读取当前缩放级别并随每个问题发送。使用 Mapbox GL JS 和 MapLibre GL JS 时，还会仅在页面内部读取镜头和样式中的标签字体，以便放置并标注聊天标记	接管您地图的控件或交互手势

由于不同地图库提供的镜头和绘图功能不尽相同，实际行为会略有差别。受支持的地图提供对应矩阵，功能与限制列出了面板发送的每项请求及其数据内容。

使用要求

要求	内容
套餐	Free 或更高套餐。提问会消耗组织的 AI 点数。
密钥	从 kaleidr.com/api-keys 获取的可发布密钥 `kld_pk_live_…`。
权限范围	`ai`，所有新密钥默认包含。
允许的来源	如果密钥配置了允许的来源，当前网页的来源必须列在其中。
地图库	Mapbox GL JS、MapLibre GL JS、Google Maps JavaScript API 或 Leaflet；挂载前必须以页面全局变量方式加载。
网页	必须通过 HTTP 或 HTTPS 提供服务。直接从磁盘打开的文件没有可用的来源。
内容安全策略	如果网站启用了此策略，请允许内容安全策略页面列出的主机。

获取 API 密钥介绍了密钥创建过程及允许来源的设置方法。

三种运行方式

您已有的内容	需要传入的参数	结果
自己的 Mapbox、MapLibre、Google 或 Leaflet 地图	`publishableKey` 和 `map`	面板操作您自己的地图，这是最常见的情况。
从 Kaleidr Studio 发布的地图	无需传入：嵌入地图，并在其 Kaleidr AI 磁贴中开启 Control Tower	地图本身带有面板，地图所有者承担提问费用。参见已发布地图上的 Kaleidr AI。
没有地图	仅 `publishableKey`	仅聊天面板：显示回答和地点卡片，不显示地图标记，也不移动镜头。

最简单的可运行网页

这个页面会显示一张 MapLibre 地图，以及停靠在地图中的聊天面板。替换密钥、保存文件，并通过密钥允许的来源提供网页，例如 http://localhost:8080。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on MapLibre</title>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
  </head>
  <body>
    <div id="mapHost" style="position:relative; height:520px">
      <div id="map" style="position:absolute; inset:0; z-index:0"></div>
      <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
    </div>

    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json',
        center: [-0.12, 51.5],
        zoom: 11,
      });

      Kaleidr.mount('#chat', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,
        contained: true,
      });
    </script>
  </body>
</html>

contained: true 会把面板停靠在 #chat 内。若不设置，面板会固定在浏览器视口左上角，不受地图在页面中的位置影响。主题和布局介绍了两种布局。

不支持的行为

在基于面板开发之前，请向团队说明以下限制：

没有回调或事件。 访客提问、回答到达或点击标记时，您的代码不会收到通知。
不能传入自定义上下文。 无法通过面板向助手传递系统指令、角色设定、门店列表或地图图层内容。使用组织上传数据来回答属于另一项受套餐限制的功能；参见您的数据。
没有原生移动端 SDK。 该面板专为网页设计。

您可以使用 lang、title 和 placeholder 分别设置回答语言、面板标题和输入框占位文字。如果不设置 lang，面板会读取页面的 <html lang>。参见聊天参考文档。

完整列表见功能与限制。如果您需要全面控制对话和界面，请改为从自己的后端调用 HTTP API：参见服务端快速入门。

后续步骤

开始构建： Mapbox · MapLibre · Google Maps · Leaflet
了解原理： 功能与限制 · 受支持的地图
适配您的页面： 主题和布局
查阅文档： 聊天参考文档
上线部署： 生产环境检查清单 · 故障排除

访客的使用体验​

对您的地图执行哪些操作​

使用要求​

三种运行方式​

最简单的可运行网页​

不支持的行为​

后续步骤​