聊天

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
瞭解原理： 功能與限制 · 受支持的地圖
適配您的頁面： 主題和佈局
查閱文檔： 聊天參考文檔
上線部署： 生產環境檢查清單 · 故障排除

訪客的使用體驗​

對您的地圖執行哪些操作​

使用要求​

三種運行方式​

最簡單的可運行網頁​

不支持的行為​

後續步驟​