Chat 参考文档

product: 'chat' 会在您的网页中挂载 Kaleidr Chat 面板。面板直接在页面文档中运行，而不是在 iframe 中运行。它可以连接到您传入的地图对象、指定的 Kaleidr Viewer 或 Tile 元素，也可以不连接地图，仅作为聊天面板使用。

本页是功能参考文档。若要构建第一个页面，请先阅读相应指南：Mapbox、MapLibre、Google Maps 或 Leaflet。

前提条件


套餐	Free 及以上
凭据	可发布密钥 (`kld_pk_live_…`)，或已开启 Control Tower 的 Studio 已发布地图 ID
权限范围	`ai`，默认包含在每个新密钥中
允许的来源	如果密钥指定了允许来源，则必须包含当前页面来源
加载器	`https://cdn.kaleidr.com/embed/v1/kaleidr.js`
地图库	可选。参见支持的地图。

最简挂载

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map,              // your live map object
  contained: true,  // dock inside #chat
});

Kaleidr.mount(target, options) 的 target 可以是 CSS 选择器或元素。它会同步返回一个控制句柄，即使挂载失败也不会抛出异常。Chat 资源包加载和密钥交换在后台进行；如果其中任一步骤失败，控制台会记录一条错误，页面不会渲染内容。唯一会抛出异常的是未传入选项对象的调用：Kaleidr.mount('#chat') 会引发 TypeError。

挂载选项

所有选项都只在挂载时读取一次。要修改选项，请调用 destroy() 后重新挂载。唯一的例外是主题，可以通过 setTheme 更新。

选项	类型	默认值	必填	对 Chat 的作用
`product`	`'chat'`	无	是	选择 Chat 产品。
`publishableKey`	字符串	无	是，除非提供 `shareId`	您的 `kld_pk_…` 密钥。SDK 会在面板发出任何请求前，将其交换为会话令牌。浏览器中使用 `kld_sk_…` 服务器密钥会被拒绝，控制台显示错误，且不会发出请求。
`shareId`	字符串	无	是，除非提供 `publishableKey`	在 Kaleidr AI 磁贴中开启了 Control Tower 的 Studio 已发布地图 ID。仅在未提供密钥时使用。问题产生的费用由地图所有者承担。已发布地图自身的查看器已经显示此面板。参见已发布地图上的 Kaleidr AI。
`map`	活动地图对象	无	否	助手在其上添加标记并移动视图的地图。SDK 根据对象识别地图库。纯聊天面板无需提供。
`mapTarget`	CSS 选择器	无	否	同一页面中供面板控制的 Viewer 或 Tile `<kaleidr-map>` 元素。提供 `map` 时此选项会被忽略。
`contained`	布尔值	`false`	否	`true` 将面板固定在挂载目标内部，目标必须设置定位和尺寸。`false` 将其添加到 `document.body`，成为视口左上角的固定窗口。
`lang`	字符串	如果页面 `<html lang>` 是有效语言标签，则使用它；否则为英语	否	面板的回复语言，使用 BCP 47 标签，例如 `en`、`ko` 或 `pt-BR`。参见语言。
`title`	字符串	根据对话生成的标题	否	聊天窗口标题栏的标题。参见标题和占位文本。
`placeholder`	字符串	`Ask Kaleidr`	否	面板输入框的占位文本。
`theme`	对象或对象的 JSON 字符串	无	否	要应用的 CSS 自定义属性，例如 `{ '--highlight-color': '#7c3aed' }`。它们被写入 `:root`，影响整个页面。
`enabled`	布尔值	无	否	此次挂载的启用控制开关。`false` 会阻止挂载。参见 kaleidr.js。
`apiBase`	URL	`https://api.kaleidr.com/inference-api`	否	执行会话交换和发送问题的 API 地址。必须包含 `/inference-api` 路径。
`base`	URL	`https://cdn.kaleidr.com`	否	加载 Chat 资源包的来源。仅使用来源部分，而且只接受 Kaleidr CDN (`https://cdn.kaleidr.com`)、加载 `kaleidr.js` 的来源或当前页面自身的来源。参见覆盖基础地址。
`apiKey`	字符串	无	否	`publishableKey` 的已弃用别名。

Chat 不使用的选项

Chat 挂载会接受但忽略 center、zoom、pitch、bearing、styleId、viewerBase 和 tileBase。面板不会设置初始相机视角；地图保留您此前指定的视图。

不存在的选项

目前没有强制指定地图库、语音或回调函数的选项。参见目前尚不支持的功能。

语言

lang 设置面板的回复语言。每次提问时都会发送该值。

传入的值	使用的语言
`lang: 'ko'`，或元素上的 `lang="ko"`	按原样使用该语言标签。
未传入 `lang`，页面包含 `<html lang="fr">`	若标签格式正确，则使用页面语言。
未传入 `lang`，且页面没有 `<html lang>` 或其格式错误	英语。

允许的值： BCP 47 语言标签，例如 en、ko、ja、pt-BR、zh-Hant。超过 35 个字符的标签会被 API 拒绝，此后每个问题都会返回 422 lang_too_long。
只在格式正确时采用页面语言： 两个或三个字母，后面可接最多三个以连字符分隔、每个含一至八个字母或数字的子标签。尚未替换的模板占位符会被跳过并改用英语，因此损坏的 <html lang> 不会使 Chat 停止工作。
显式设置的 lang 始终优先于页面语言。
lang 不会翻译标题和占位文本。 它们的默认值为英语。请将 title 和 placeholder 设为与 lang 相同的语言。

标题和占位文本

Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map,
  contained: true,
  lang: 'fr',
  title: 'Demandez à propos d’un lieu',
  placeholder: 'Posez une question',
});

placeholder 替换输入框中默认显示的“Ask Kaleidr”。
title 是聊天窗口标题。开始对话时，窗口和标题栏才会出现；之后每次对话的标题栏都显示您设置的标题。若不提供 title，标题栏显示访客第一条问题的缩略版本。最小化的聊天显示该对话自己的标题，该标题来自访客的第一条问题，与是否提供 title 无关。
在元素中，标题属性是 chat-title，而非 title。HTML 元素的 title 是浏览器的悬停提示，会显示在元素内容上方。

使用哪种凭据

传入的值	结果
`publishableKey`	将密钥交换为会话。如果也提供 `shareId`，则忽略它。
仅 `shareId`	根据已发布地图交换会话。
两者均未提供	面板会显示，但每个问题都会失败。挂载时不记录错误。

使用哪张地图

传入的值	结果
`map`	使用该地图对象。如果也提供 `mapTarget`，则忽略它。
仅 `mapTarget`	选择器匹配的 Kaleidr Viewer 或 Tile 元素。每次需要地图时才解析选择器，因此可以先挂载面板、后挂载地图元素。
两者均未提供，或对象/选择器无法识别	仅聊天：没有标记、相机移动或路线。控制台不记录内容。

元素属性

<kaleidr-map product="chat"> 是声明式写法。元素本身就是挂载目标。

<kaleidr-map product="chat" share-id="YOUR_MAP_ID" contained
             map-target="#store-map"
             style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>

属性	对应选项	备注
`product="chat"`	`product`	必填。
`publishable-key`	`publishableKey`
`share-id`	`shareId`
`map-target`	`mapTarget`	CSS 选择器。
`contained`	`contained`	不带值表示 `true`。`contained="false"` 表示 `false`。
`lang`	`lang`	BCP 47 标签。参见语言。
`chat-title`	`title`	标题栏文本。不是 `title`；后者是 HTML 悬停提示。
`placeholder`	`placeholder`	输入框占位文本。
`theme`	`theme`	JSON 字符串。挂载后修改会应用新值。
`flag`	`enabled`	`flag="false"` 阻止挂载。
`api-base`	`apiBase`
`base`	`base`
`api-key`	`apiKey`	`publishable-key` 的已弃用别名。

关于元素写法需要注意：

无法接收活动地图对象。 不存在 map 属性。若要连接您自己的 Mapbox、MapLibre、Google 或 Leaflet 地图，请调用 Kaleidr.mount。元素方式通过 map-target 控制 Kaleidr Viewer 或 Tile，或作为纯聊天面板运行。
元素连接时只读取一次属性。 之后更改只有 theme 会立即生效。挂载后修改 share-id、publishable-key、map-target、contained、lang、chat-title、placeholder 或 flag 均无效；请移除该元素并插入新元素。
相机属性无效。 在 Chat 挂载时忽略 center、zoom、pitch 和 bearing，之后修改会记录“不支持”警告。
元素默认使用 display:block。 若使用 contained，需给元素设置定位和尺寸。示例仍在样式中明确指定 display:block，以兼容 16.4 之前的 Safari；该版本中元素默认仍为行内元素。参见主题与布局。
移除元素会销毁挂载。 再次插入会创建新面板和新会话。

四种产品的完整属性表见 kaleidr-map 元素。

控制句柄

所有产品的 Kaleidr.mount 都返回相同结构的句柄。对于 Chat：

成员	在 Chat 中	行为
`product`	`'chat'`	只读。
`setTheme(theme)`	支持	接受 CSS 自定义属性对象或其 JSON 字符串。将新值添加到已有设置。键名若没有前缀 `--`，会自动补上。无效 JSON 字符串或数组会被忽略并显示警告。
`destroy()`	支持	移除面板、地点卡片、标记和路线，并停止会话续期。可安全多次调用。
`setCamera(camera)`	不支持	记录警告且不执行操作。使用您自己的地图库 API 移动地图。
`setStyle(style)`	不支持	记录警告且不执行操作。

handle.setTheme({ '--highlight-color': '#0ea5e9' });
handle.destroy();

面板加载完成前发出的调用会进入队列，待准备好后执行。如果面板尚未加载就调用 destroy()，挂载会被取消。

句柄没有 ready Promise、on() 方法或 map 成员，也无法发送消息或读取对话。如果挂载时启用开关关闭，句柄就是一个不起作用的占位对象：所有方法均无效，控制台会显示一条警告，指出阻止挂载的控制项。

不支持的方法会记录：

[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. See the handle matrix at https://docs.kaleidr.com/sdk/kaleidr-map-element#handle-matrix.

四种产品的完整矩阵见 kaleidr-map 元素。

挂载后面板会执行什么操作

呈现显示“Ask Kaleidr”或您指定的 placeholder 的输入栏。第一次提问会将其展开为聊天窗口。
每个问题会连同此前的对话、对话 ID、连接地图时的地图缩放级别，以及语言标签发送：优先使用您的 lang，其次页面语言，最后 en。离开页面的数据列出了所有请求。
回复中提到的地点会成为结果卡片和连接地图上的标记。相机会移动到单个地点，或将多个地点纳入视野。
一个挂载实例一次只显示一个对话，每个对话都有独立 ID。关闭聊天窗口会清除对话和标记，下一次提问会用新 ID 开始新对话。最小化会保留原对话；下一次提问开始新对话，而恢复最小化对话会使用其原 ID 继续。刷新页面会重新开始。不会持久保存任何内容。

会话交换

您的可发布密钥不会直接用于提问。在面板发出任何请求前，SDK 会将密钥交换为短期会话令牌，并且只将令牌交给面板。

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
x-api-key: kld_pk_live_…
content-type: application/json

{"product":"chat"}

{ "session_token": "kld_sess_live_…", "expires_in": 900, "product": "chat", "basemap_style_id": null }

行为	详情
绑定关系	会话仅对请求它的来源和 `chat` 产品有效。
续期	SDK 会在当前会话到期前 90 秒申请新会话；当后台标签页恢复可见且会话已过期或即将过期时，也会申请新会话。
续期失败	只要面板仍挂载，就每 30 秒重试一次。
首次交换失败	挂载失败。记录一条错误，不显示任何内容，也不会重试。要重试请重新挂载。
无密钥但有 `shareId`	使用 `POST …/b2b/v1/sdk/share-sessions`，请求体为 `{"share_id":"…"}`。会话持续 300 秒。如果续期返回 401、403 或 404，SDK 会停止请求，直到页面重新加载。

身份验证和权限范围完整介绍密钥、会话和权限。

单页应用中的生命周期

包含地图的视图被移除时调用 handle.destroy()。请先销毁聊天面板，再移除地图，以便面板清除其标记。
视图返回时重新挂载。这会启动新的会话交换和新对话。
destroy() 不会移除面板的样式表或写入 :root 的主题属性。参见 destroy() 会移除和保留哪些内容。
如果替换地图对象（例如重新创建地图），请销毁面板并使用新对象重新挂载。面板始终保留最初传入的地图对象引用。

框架集成展示 React、Next.js 和 Vue 的挂载与清理模式。

错误

SDK 对挂载失败只在控制台记录一条错误，而不重复服务器的具体原因。如果是 HTTP 错误，请在浏览器 Network 标签页打开该请求并查看 JSON 响应体。403 或 404 的错误代码位于 detail 字段；429 的错误代码位于 error 字段，说明文字位于 detail。

挂载期间

控制台	网络	原因
`[kaleidr:chat] mount target not found: <selector>`	未发出请求	选择器未匹配任何元素。
`[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`	未发出请求	传入了服务器密钥。
`[kaleidr:chat] [kaleidr] failed to load <url>`	`chat.js` 请求失败	资源包被阻止或 CDN 不可用。
先出现 CORS 错误，随后出现包含 `[kaleidr:chat]` 的错误	`POST …/sdk/sessions` 被 CORS 阻止	密钥未知、已撤销或已过期，或页面来源不在允许来源列表中。API 只向获准来源返回 CORS 标头，因此浏览器会隐藏状态码和响应体。
`[kaleidr:chat] kaleidr session exchange failed (403)`	403 `insufficient_scope`	密钥没有 `ai` 权限范围。
同上	403 `product_not_allowed`	密钥被限制为不包括 `chat` 的产品。
同上	403 `tier_capability_not_allowed`	组织当前的套餐不支持该功能。
`[kaleidr:chat] kaleidr session exchange failed (429)`	429 `rate_limited`	该密钥一分钟内发出超过 30 次会话请求。
`[kaleidr:chat] kaleidr session exchange failed (404)`	404 `sessions_disabled`	平台已关闭会话交换，不是密钥问题。
`[kaleidr:chat] kaleidr session exchange failed (503)`	503 `sessions_not_configured`	平台故障。重新加载页面以重试。
使用 `shareId` 而未使用密钥挂载时，出现 `[kaleidr:chat] kaleidr session exchange failed (403)` 或 `(404)`	403 `chat_disabled`、403 `origin_not_allowed` 或 404 `not_found`	已发布地图拒绝了 Chat。参见已发布地图上的 Kaleidr AI。
`[kaleidr] embed is disabled — …`（警告）	未发出请求	启用控制开关处于关闭状态。消息会指明具体控制项。
`[kaleidr] theme string must be JSON …`（警告）	不适用	`theme` 的值是非 JSON 字符串。面板可以挂载，但不会应用该主题。

面板使用期间

面板会将故障作为对话中的一行消息展示给访客。您的代码不会收到通知。

访客看到的内容	状态码	原因
"Sorry — that didn't go through. Please try again."	401	会话不再有效：密钥已撤销或过期、当前来源已从允许来源中移除，或挂载时没有提供凭据。
同上	5xx 或网络故障	暂时性故障。
"You've reached your usage limit for now."，已知时还会显示重置时间	429 `quota_exceeded`	组织的 AI 点数已用尽，或该密钥已达到每月上限。
同上	429 `rate_limited`	密钥请求速率达到限制。页面的所有访客共用一个密钥。
同上	429 `visitor_limit_reached`	仅适用于无密钥 Chat：此访客达到每分钟或每日限额。

错误列出完整目录；配额和速率限制解释各项限制。

前提条件​

最简挂载​

挂载选项​

Chat 不使用的选项​

不存在的选项​

语言​

标题和占位文本​

使用哪种凭据​

使用哪张地图​

元素属性​

控制句柄​

挂载后面板会执行什么操作​

会话交换​

单页应用中的生命周期​

错误​

挂载期间​

面板使用期间​

相关页面​