跳到主要内容

快速入门

本页按大多数团队的使用顺序，介绍三种最简便且可运行的集成方式：

  1. 在现有地图上添加聊天。 聊天面板回答有关地点的问题，并将结果作为图钉、相机移动和路线显示在你的地图上。
  2. 已发布地图。 将在 Kaleidr Studio 设计的地图嵌入你的网页。
  3. 底图。 将 Kaleidr 设计的现成底图放在你的网页中。

每种方式只需要一个 HTML 文件。三种方式均可使用 Free 套餐。

方式产品所需密钥显示位置
在你的地图上聊天chat发布密钥网页中，覆盖在地图上方
已发布地图viewer无需密钥Kaleidr iframe 内
底图tile发布密钥Kaleidr iframe 内

如果想先了解整体模型，请阅读 Kaleidr 的工作原理。如果不确定需要哪个产品，请阅读选择适合的方案。

开始之前​

  • Kaleidr 账户。 在 kaleidr.com 注册。Free 套餐足以运行本页所有示例。

  • 发布密钥，用于聊天和底图。请前往 kaleidr.com/api-keys 创建；它以 kld_pk_live_ 开头。获取 API 密钥介绍表单的操作方式。已发布地图不需要密钥。

  • 网页服务器。 即使在本地，也请通过 HTTP 提供文件服务。在文件所在目录中可使用以下任一种方法：

    python -m http.server 8000
    # or
    npx serve -l 8000

    然后打开 http://localhost:8000/your-file.html。不要直接从硬盘打开文件：file:// 网页没有可以加入密钥允许来源列表的来源。

  • 如果密钥设置了允许来源，必须包含你的网页来源。 未设置允许来源的密钥可在任何网站使用；设置列表后只能在所列网站使用，因此测试时请添加 http://localhost:8000。

  • 如果网站使用内容安全策略，必须允许 Kaleidr 资源加载。 未发送 Content-Security-Policy 标头的网站不需要额外设置。否则请阅读内容安全策略。

三种方式都使用同一个 script 标签。你只需自行加载这一个文件，挂载产品时它会获取对应产品的代码。

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

在你的地图上聊天​

完成后，你将得到一张 MapLibre GL JS 地图，聊天面板停靠在地图中。询问“在 Bryant Park 附近哪里能吃到拉面？”时，回答会流式显示在面板内，为每个地点添加图钉，并移动相机以展示这些地点。

此示例使用 MapLibre GL JS。Chat 也可连接 Mapbox GL JS、Google Maps JavaScript API 和 Leaflet；参阅支持的地图。

1. 创建网页​

将文件保存为 chat.html，并把 kld_pk_live_… 替换为你的发布密钥。

<!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" />
    <style>
      body { margin: 0; }
      /* The chat panel docks inside this box, so it must be positioned and sized. */
      #stage { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; }
    </style>
  </head>
  <body>
    <div id="stage">
      <div id="map"></div>
    </div>

    <!-- 1. Your map library, loaded as a page global (window.maplibregl). -->
    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <!-- 2. The Kaleidr loader. -->
    <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', // replace with your own style
        center: [-73.9857, 40.7484], // [longitude, latitude]
        zoom: 11,
      });

      const chat = Kaleidr.mount('#stage', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,             // the live map instance, not a selector
        contained: true, // dock the panel inside #stage
      });

      // When you remove the map (for example on a route change in a single-page app):
      // chat.destroy();
    </script>
  </body>
</html>

请注意文件中的三个细节：

  • 地图程序库必须是网页全局变量。 聊天代码从 window.maplibregl 查找 MapLibre。通过 script 标签加载 MapLibre 会自动设置它。如果改从 npm 导入，请在挂载前自行赋值：window.maplibregl = maplibregl。
  • map 是地图对象。 请传入你创建的实例，而不是 CSS 选择器。
  • contained: true 需要有定位方式和高度的容器。 面板显示在挂载目标内。如果没有 contained，面板会作为固定窗口出现在浏览器视口左上角。

示例样式是一张细节较少的世界地图。图钉仍会落在正确的坐标，但如需查看街道，请使用自己的地图样式。

2. 提供网页服务并提问​

在文件所在目录启动本地服务器，打开 http://localhost:8000/chat.html。

预期结果：

  • 地图填满窗口，左上角出现带文本输入框的聊天面板。
  • 在浏览器“网络”标签页中，对 https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions 的请求返回 200。这表示 SDK 正在用密钥换取短期会话。
  • 输入一个有关地点的问题，例如 Where can I get ramen near Bryant Park?。回答会流式进入面板，每个地点出现图钉，相机也会调整以显示它们。“网络”标签页会出现对 …/b2b/v1/chat/control/stream 的请求，并在回答生成期间保持打开。
  • 控制台不应出现包含 [kaleidr 的行。

3. 如果无法正常运行​

现象原因解决方法
面板未显示，控制台先对 …/sdk/sessions 报 CORS 错误，随后出现 [kaleidr:chat] 错误密钥错误、已被撤销，或网页来源不在密钥的允许来源列表中。API 响应不包含 CORS 标头，浏览器因此报告 CORS 失败。检查密钥。在 kaleidr.com/api-keys 添加包含端口的精确来源，或在测试期间清空列表。
面板在浏览器左上角，而不是地图内部缺少 contained: true，或挂载目标没有定位传入 contained: true，并为目标设置 position: relative 和高度。
面板能回答，但地图上没有图钉地图程序库不是网页全局变量，聊天无法创建图钉用 script 标签加载程序库，或先设置 window.maplibregl 再调用 Kaleidr.mount。

故障排除按控制台原始消息解释各种症状。

下一步：将 Chat 连接到 MapLibre提供完整指南；功能和限制说明面板能做什么、不能做什么。

已发布地图​

完成后，你将在自己的网页中显示 Kaleidr Studio 设计的地图。这种方式无需 API 密钥，只需地图的公开 ID。

1. 发布地图并复制 ID​

  1. 在 Kaleidr Studio 打开地图，选择 Publish（发布）。
  2. 在 Publish & embed（发布与嵌入） 页面选择 Go Live（上线）。
  3. 在 Embed code（嵌入代码） 下复制代码片段。ID 是地址的最后一段，例如 https://map-embed.kaleidr.com/embed/abc123 的 ID 为 abc123。

**预期结果：**项目状态显示 live，嵌入代码下的实时预览会呈现访客看到的地图。

2. 创建网页​

将文件保存为 map.html，把 YOUR_SHARE_ID 替换为复制的 ID。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A published Kaleidr map</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="viewer"
      share-id="YOUR_SHARE_ID"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

元素需要设置高度，否则地图使用 500 像素的后备高度。<kaleidr-map> 默认是 display:block，所以高度生效。代码片段也写了 display:block，以兼容 Safari 16.4 之前的版本；那些版本中元素保持行内状态，设置高度无效。

如果无法添加脚本（例如网站构建器或 CMS 字段），请使用 Studio 的 iFrame 标签页提供的普通 iframe。它不需要加载器：

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_SHARE_ID"
  width="100%"
  height="480"
  style="border:0;"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"
></iframe>

3. 提供网页服务​

打开 http://localhost:8000/map.html。

预期结果：

  • 地图宽度与页面相同、高 480 像素，并从你在 Studio 保存的视图开始显示。
  • 指针位于地图上方时滚动会缩放地图；指针位于地图旁边时，滚动会移动页面。
  • 在“元素”面板中，有一个 <iframe> 位于 <kaleidr-map> 内，其地址以 https://map-embed.kaleidr.com/embed/ 开头。

如果框架显示 "This map isn't available — it may have been unpublished, paused, or the link is incorrect."，说明 ID 错误或地图尚未上线。如果显示 "This map isn't allowed to render on this site. Please contact the map owner."，说明地图只允许在其他域名显示。

下一步：嵌入地图说明如何限制地图的显示域名；已发布地图上的聊天可让访客无需密钥即可聊天。

底图​

完成后，你的网页将显示 Kaleidr 设计的现成互动底图，无须安装地图程序库，也不用自己编写样式。

1. 创建网页​

保存为 basemap.html，将 kld_pk_live_… 替换为你的发布密钥。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A Kaleidr basemap</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="tile"
      publishable-key="kld_pk_live_…"
      style-id="kaleidr-morning"
      center="-73.9857,40.7484"
      zoom="11"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>
  • style-id 指定底图样式。请始终填写。kaleidr-morning 是通用样式之一；其他样式见 Tile。
  • center 采用 longitude,latitude 格式。设置 center 后再设置 zoom：单独的 zoom 在没有 center 时会被忽略。

2. 提供网页服务​

打开 http://localhost:8000/basemap.html。

预期结果：

  • 底图以曼哈顿中城为中心，高 480 像素。
  • “网络”标签页中，对 https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions 的请求返回 200，随后从 https://map-embed.kaleidr.com 加载 iframe。
  • 指针位于地图上方时滚动会缩放地图。

如果没有显示内容，控制台对 …/sdk/sessions 报 CORS 错误，说明密钥错误或你的来源不在允许来源列表中，与聊天方式的情况相同。

每个 Tile 会话都计入你所在组织每月地图加载额度的一次加载。参阅配额与速率限制。

下一步：使用 Tile介绍运行时切换样式与控制相机。

实际加载了什么​

三种方式使用的是相同的两个组件：

  • Kaleidr.mount(target, options) 从 JavaScript 挂载产品，立即返回句柄。产品代码在后台加载，产品就绪前对句柄发出的调用会被保留并在就绪后执行。
  • <kaleidr-map> 通过 HTML 完成同样的工作。其属性是带连字符的挂载选项（share-id、style-id、publishable-key），但有两个例外：enabled 对应 flag 属性，聊天的 title 选项对应 chat-title 属性。

在自己的地图上使用 Chat 时，请调用 Kaleidr.mount，因为它需要实时地图对象。其他产品可以使用任意一种方式。

所有产品的句柄都包含 destroy() 方法。其他方法取决于产品，例如 setCamera 可用于 viewer、tile 和 editor，但不支持 chat；在 Chat 中，助手会自行移动地图，而你仍可使用地图程序库自己的相机方法。完整列表参阅元素 <kaleidr-map>。

现在需要了解的限制​

  • Chat 会添加自己的图钉、路线和相机移动。 它不会修改你的图层或标记，也不会向 Kaleidr 发送这些内容；网页不会收到面板事件。参阅功能和限制。
  • Viewer 和 Tile 在 iframe 中运行。 不能向它们添加自己的图层或标记。需要自定义图层时，请保留自己的地图并连接 Chat。
  • Kaleidr 底图通过 Tile 显示。 不支持在你自己的地图程序库中直接加载 Kaleidr 样式或瓦片。
  • SDK 用于网页。 没有 npm 软件包或原生移动 SDK。后端应调用服务器 API。
  • 使用密钥的挂载会消耗额度。 Chat 回答消耗组织的 AI 积分，每个 Tile 会话消耗一次地图加载。参阅Kaleidr 的工作原理。

下一步选择​

你想做什么阅读
将 Chat 接入 Mapbox GL JS连接 Chat 与 Mapbox
将 Chat 接入 MapLibre GL JS连接 Chat 与 MapLibre
将 Chat 接入 Google Maps连接 Chat 与 Google Maps
将 Chat 接入 Leaflet连接 Chat 与 Leaflet
放置面板并匹配品牌色彩主题和布局
让访客在已发布地图上聊天已发布地图上的聊天
嵌入地图并限制域名嵌入地图
显示底图并切换样式使用 Tile
在网页中放入地图编辑器连接编辑器
在 React、Next.js 或 Vue 中使用 SDK框架集成
从后端调用 Kaleidr服务器快速入门
使用自己的业务数据生成回答你的数据
发布到生产环境上线检查清单