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 不使用的選項​

不存在的選項​

語言​

標題和佔位文本​

使用哪種憑據​

使用哪張地圖​

元素屬性​

控制句柄​

掛載後面板會執行甚麼操作​

會話交換​

單頁應用中的生命週期​

錯誤​

掛載期間​

面板使用期間​

相關頁面​