So fügen Sie einer Karte einen KI-Chat hinzu

Sie können einer bereits mit Mapbox, Google Maps oder MapLibre betriebenen Karte KI-Chat hinzufügen, ohne den Renderer auszutauschen. Die Host-Anwendung behält ihre Oberfläche, Berechtigungen, Geschäftslogik und ihr Anbieterkonto; Kaleidr ergänzt ausschließlich die Konversationsebene. Diese Ebene interpretiert räumliche Fragen, streamt Orts- und Aktionsdaten, zeichnet aufgelöste Standorte ein und bewegt die Live-Karte, während die Antwort entsteht.

Durch den Assistenten gehen nicht sämtliche Produktverantwortlichkeiten auf das Modell über. Eine produktionsreife Integration benötigt weiterhin einen auf bestimmte Ursprünge beschränkten Browser-Schlüssel, fundierte Quelldaten, anbieterspezifisches Lifecycle-Handling, Fehlerzustände, Barrierefreiheit und Analysen. Die folgenden Abschnitte behandeln nacheinander die SDK-Einbindung, die Einrichtung je Anbieter, die Schlüsselsicherheit, die Fundierung, UX, Tests und Kennzahlen, die zeigen, ob der Assistent eine reale Aufgabe erleichtert. Nutzen Sie den Artikel als Architektur- und Integrationsreferenz, nicht als bloße Funktionsübersicht. Wenn Sie die Konversationskarte vor der SDK-Einbindung testen möchten, beginnen Sie mit Kaleidr AI. Den Unterschied zu manuell erstellten benutzerdefinierten Karten erläutert Kaleidr vs. Google My Maps.

Was Sie erstellen

Das fertige Erlebnis koordiniert zwei Oberflächen, die synchronisiert bleiben: eine interaktive Karte, die bereits in Ihrer Anwendung läuft, und ein KI-Chat-Panel, das Kaleidr neben oder über dieser Karte montiert. Ein Benutzer drückt ein Ziel in natürlicher Sprache aus, und der Assistent antwortet gleichzeitig in Prosa und im Kartenzustand. Keine der beiden Oberflächen führt die andere, weil der Wert aus dem gemeinsamen Lesen kommt. Eine repräsentative Anfrage sieht so aus:

Zeigen Sine familienfreundliche Orte in der Nähe der Uferpromenade, die heute Nachmittag geöffnet sind.

Der Assistent löst die geografische Absicht, gibt die relevanten Stellen zurück, fügt der Live-Karte Pins hinzu, rahmt den Ergebnisbereich ein und präsentiert eine Antwort, die der Leser mit einer Folgefrage verfeinern kann. Kaleidrs Chat-Anhang basiert genau auf dieser Schleife: Die product: "chat"-Integration mountet den Kaleidr Control Tower über eine Karte, die Ihre Anwendung bereits rendert, erkennt den Renderer, plottet aufgelöste Orte und aktualisiert die Kamera, wenn sich die Konversation zwischen den Standorten bewegt. Die aktuelle Dokumentation listet Mapbox, Google Maps, MapLibre und Leaflet unter unterstützten Live-Map-Instanzen auf – siehe Kaleidr-Chat-Anhang-Referenz und Entwickler-Schnellstart. Eine Konversationskarte eignet sich für Kontextfragen, die festen Filtern widerstehen, aber ein herkömmliches Suchfeld kann immer noch die bessere Schnittstelle für deterministische Aufgaben sein, wie das Auffinden einer bekannten Speicher-ID, das Auswählen einer festen Kategorie oder das Anzeigen einer vordefinierten Route.

So funktioniert die Architektur

Das Hinzufügen von Conversational AI überträgt nicht jede Verantwortung auf das Modell; eine zuverlässige Implementierung hält die Anwendung, den Renderer, die KI-Schicht, die Quellsysteme und die Sicherheitsgrenzen deutlich. Jede Schicht besitzt eine Aufgabe, die andere nicht ausführen sollten, und diese Trennung ist es, die Antworten geerdet und Berechtigungen durchsetzbar hält. Das folgende Diagramm zeichnet nach, wie eine Frage über diese Ebenen fließt, und die Tabelle, die folgt, benennt jede Verantwortung.

Das Sprachmodell sollte nicht zur maßgeblichen Quelle für Adressen, Öffnungszeiten, Inventar, Berechtigung, Routen, Eigentumsstatus oder interne Geschäftsdaten werden. Die KI-Schicht interpretiert die Anfrage und koordiniert unterstützte Aktionen, während maßgebliche Dienste die Fakten bestätigen, von denen die Antwort abhängt. Kaleidrs Streaming-Vertrag spiegelt diese Trennung wider: Prose kommt schrittweise an, gelöste Orte kommen als strukturierte place-Ereignissen an, Kartenoperationen können in early_actions eintreffen, Quellinformationen können in grounding eintreffen, und das letzte end-Event trägt den vollständigen Text, die Orte und die Aktionen. Entwickler, die kaleidr.js verwenden, analysieren diese Ereignisse niemals von Hand, und Teams, die einen benutzerdefinierten Kunden aufbauen, können der SSE-Übertragungsreferenz folgen.

Was Sie vor dem Start benötigen

Bevor Sie das Chat-Panel einbinden, bestätigen Sie eine kurze Liste von Voraussetzungen, damit die Integration beim Setup laut fehlschlägt, anstatt zur Laufzeit leise. Die meisten Probleme in diesem Stadium gehen auf einen fehlenden Gegenstand zurück - einen ungesetzten Ursprung, eine Karte ohne Höhe oder einen Schlüssel ohne den richtigen Umfang. Ein paar Minuten, die hier verbracht werden, speichern eine Debugging-Sitzung gegen einen Fehler, den der Browser nur indirekt meldet. Bestätigen Sie jede der folgenden:

• eine funktionierenden Mapbox-, Google Maps- oder MapLibre-Karteninstanz;
• eine Kaleidr-Organisation mit Chat-API-Zugang;
• einen kaleiderveröffentlichbaren browserschlüssel, der den qzaq-umfang trägt;
• mindestens eine zulässige Browser-Ursprungsursprung für den Live-veröffentlichbaren Schlüssel;
• den aktuellen kaleidr.js-Lader;
• einen Kartencontainer mit einer expliziten Höhe;
• einen Chat-Container oder ein unterstütztes benutzerdefiniertes Element;
• die von Mapbox oder Google Maps geforderten Anbieter-Anrechen;
• repräsentative Fragen aus dem realen Benutzerworkflow;
• definierte Source-of-Treth-Systeme für alle betrieblichen Fakten.

Der vollständige Entwickler-API-Zugang – veröffentlichbare Schlüssel, Serverschlüssel und Einbettungsunterstützung – wird mit Kaleidr Pro- und Enterprise-Plänen geliefert, während der freie Zugriff nur mit Kacheln gescopte Browserschlüssel freigibt. Überprüfen Sie die aktuelle Kaleidr-Preisseite und API-Key-Dokumentation, bevor Sie erstellen, so dass der Plan, den Sie annehmen, mit den Anmeldeinformationen übereinstimmt, die Sie tatsächlich prägen können. Wenn die API-Schlüsselseite für Ihr Konto eingeschränkt ist, fordern Sie den Zugriff vom Kaleidr-Team an, anstatt eine Serverberechtigung in Browsercode zu ersetzen.

So fügen Sie einer Karte mit dem Kaleidr SDK KI-Chat hinzu

Der aktuelle Loader ist ein einziges Skript-Tag. Sie fügen es einmal pro Seite, vor oder neben dem eigenen Skript des Anbieters, hinzu, und es ist sicher, aggressiv zu cachen. Das Tag installiert den globalen Einstiegspunkt, von dem jeder spätere Aufruf in diesem Handbuch abhängt.

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

Der Loader installiert window. Kaleidr und das <kaleidr-map>-Element und zieht das ausgewählte Produktbündel nur bei Bedarf im Hintergrund; der Lader selbst bündelt weder MapLibre noch React. Das SDK unterstützt die Produkte chat, viewer, editor und Kacheln, also folgen Sie dem genauen Produktwert, der auf der aktuellen Seite für die spezifische Einbettung angezeigt wird, die Sie erstellen. Für eine Live-Karte, die Sie bereits besitzen, ist die imperative API der klarste Pfad. Das folgende Beispiel gibt das vorhandene Kartenobjekt direkt an Kaleidr:

<div class="map-chat-layout">
  <div id="map" aria-label="Interactive location map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  function mountKaleidrChat(map) {
    if (!map) {
      throw new Error("A live map instance is required.");
    }

    return Kaleidr.mount("#chat", {
      product: "chat",
      publishableKey: "kld_pk_live_REPLACE_ME",
      map,
    });
  }
</script>

Kaleidr.mount(target, options) gibt einen Griff synchron zurück, während das Produktbündel im Hintergrund geladen wird, und die anstehenden Anrufe an diesem Griff gelten, sobald das Laden abgeschlossen ist. Behalten Sie den zurückgegebenen Handgriff, damit die Hostanwendung die Kamera aktualisieren oder die Integration während Routenänderungen, Kontoschaltern oder Komponentenaufbauen abreißen kann. Die folgenden Anbieterbeispiele kombinieren das aktuelle Setup jedes Renderers mit diesem Mount-Beruf; validieren Sie die gepinnte Anbieterversion und das neueste Kaleidr SDK-Verhalten in der Staging, bevor Sie in der Produktion bereitstellen.

KI-Chat zu Mapbox hinzufügen

Mapbox GL JS erstellt eine mapboxgl. Map-Instanz in einem Browser-Container, die ein Zugriffs-Token erfordert. Mapbox empfiehlt ein öffentliches Token, das nur für die Clientanwendung benötigt wird, mit URL-Einschränkungen und auf einem Server gespeicherten Secret-Scope-Operationen. Das folgende Beispiel passt zu dieser Anleitung mit Kaleidrs dokumentiertem Mount Call. Laden Sie beide Skripte, erstellen Sie die Karte und mounten Sie den Chat, sobald die Karte ihr load-Event abfeuert:

<link
  href="https://api.mapbox.com/mapbox-gl-js/v3.27.0/mapbox-gl.css"
  rel="stylesheet"
/>

<script src="https://api.mapbox.com/mapbox-gl-js/v3.27.0/mapbox-gl.js"></script>
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<div class="map-chat-layout">
  <div id="map" aria-label="Mapbox map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

<script>
  const map = new mapboxgl.Map({
    accessToken: "YOUR_MAPBOX_PUBLIC_TOKEN",
    container: "map",
    center: [-0.12, 51.5],
    zoom: 11,
  });

  map.on("load", () => {
    try {
      window.kaleidrChat = Kaleidr.mount("#chat", {
        product: "chat",
        publishableKey: "kld_pk_live_REPLACE_ME",
        map,
      });
    } catch (error) {
      console.error("Kaleidr chat failed to mount:", error);
    }
  });

  map.on("error", (event) => {
    console.error("Mapbox error:", event.error ?? event);
  });
</script>

Der Anbieterhandbuch von Kaleidr zeigt derzeit Mapbox GL JS v3.0.0, während der CDN-Guide von Mapbox einen späteren v3.27.0-Build dokumentiert, also behalten Sie die Version bei, die Ihre Anwendung bereits getestet hat, und bestätigen Sie die Kompatibilität, bevor Sie sie nur für diese Integration aktualisieren. Das Mapbox-Token und der veröffentlichbare Kaleidr-Schlüssel authentifizieren verschiedene Systeme und Rechnungen separat: Das Token authentifiziert den Renderer und die Mapbox-Dienste, und der veröffentlichbare Schlüssel authentifiziert den KI-Chat-Bereich über das Browser-SDK. Die häufigsten Setup-Fehler sind eine fehlende Map-Container-Höhe, ein abgelehntes oder überskopiertes Mapbox-Token und das Einhängen des Chats, bevor die Anwendung die Karteninstanz eingerichtet hat.

KI-Chat zu Google Maps hinzufügen

Die Google Maps Platform benötigt einen Maps-JavaScript-API-Schlüssel und unterstützt den dynamischen Bibliotheksimport, das direkte Laden von Skripten und einen NPM-Loader. Der offizielle Integrationsleitfaden von Kaleidr verwendet das direkte Rückrufmuster, das die vorhersehbarste Option für eine erste Integration ist. Der Callback erstellt die google.maps. Map-Instanz und übergibt sie direkt an Kaleidr.mount. Das folgende Beispiel verdrahtet den Schlüssel, den Callback und die Halterung zusammen:

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

<div class="map-chat-layout">
  <div id="map" aria-label="Google map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

<script>
  function initMap() {
    try {
      const map = new google.maps.Map(document.getElementById("map"), {
        center: { lat: 51.5, lng: -0.12 },
        zoom: 11,
      });

      window.kaleidrChat = Kaleidr.mount("#chat", {
        product: "chat",
        publishableKey: "kld_pk_live_REPLACE_ME",
        map,
      });
    } catch (error) {
      console.error("Google Maps or Kaleidr initialization failed:", error);
    }
  }

  window.gm_authFailure = function () {
    console.error("Google Maps authentication failed.");
  };
</script>

<script
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_MAPS_KEY&callback=initMap"
  async
></script>

Der Google Maps-Schlüssel und der Kaleidr-Schlüssel dienen verschiedenen Systemen und Rechnungen unabhängig voneinander, beschränken also den Google-Schlüssel auf die erforderlichen Websites und APIs und beschränken den Kaleidr-Schlüssel auf die genau erlaubten Ursprünge. Googles Maps JavaScript API-Schlüssel lädt und berechnet die Google-Karte, während der kaleider veröffentlichbare Schlüssel die KI-Chat-Funktion lädt und abrechnet. Eine weitere Unterscheidung ist wichtig: Diese Integration zielt auf eine Google Maps JavaScript API-Instanz innerhalb einer Anwendung ab und fügt kein Google My Maps-Dokument hinzu, das ein separates Produkt ist.

KI-Chat zu MapLibre hinzufügen

MapLibre GL JS ist ein Open-Source-Browser-Renderer für Vektor-Kacheln-Karten, und eine MapLibre-Anwendung muss einen Stil sowie die Kacheln-, Glyphen- und Sprite-Quellen liefern, die Referenzen stylen. Das Host-Team besitzt daher mehr von der Renderer- und Infrastrukturentscheidung als mit einem vollständig verwalteten Kartendienst. Die aktuelle MapLibre-Dokumentation verwendet ES-Module in Version 6. Das folgende Beispiel passt dieses Muster an Kaleidrs Mount-Anruf an:

<link
  href="https://unpkg.com/maplibre-gl@6.0.0/dist/maplibre-gl.css"
  rel="stylesheet"
/>

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

<div class="map-chat-layout">
  <div id="map" aria-label="MapLibre map"></div>
  <aside id="chat" aria-label="AI map assistant"></aside>
</div>

<script type="module">
  import * as maplibregl from "https://unpkg.com/maplibre-gl@6.0.0/dist/maplibre-gl.mjs";

  const map = new maplibregl.Map({
    container: "map",
    style: "https://demotiles.maplibre.org/style.json",
    center: [-0.12, 51.5],
    zoom: 11,
  });

  map.on("load", () => {
    try {
      window.kaleidrChat = Kaleidr.mount("#chat", {
        product: "chat",
        publishableKey: "kld_pk_live_REPLACE_ME",
        map,
      });
    } catch (error) {
      console.error("Kaleidr chat failed to mount:", error);
    }
  });

  map.on("error", (event) => {
    console.error("MapLibre error:", event.error ?? event);
  });
</script>

Der aktuelle MapLibre-Guide von Kaleidr verwendet einen globalen MapLibre-Build im UMD-Stil und eine von Kaleidr gehostete URL, während die Dokumentation des Anbieters auf die Version 6-ES-Module umgestellt wurde. Wählen Sie daher eine konsistente MapLibre-Version und eine Lademethode für die Anwendung, anstatt globale und Modul-Builds zu mischen. MapLibre liefert keine universell gehostete Basiskarte für sich, was bedeutet, dass ein Drittanbieter-Kachel- oder Stilanbieter seine eigenen Anmelde-, Attributions-, Lizenz-, Nutzungs- und Abrechnungsanforderungen mitbringt, die Sie befolgen müssen. Kaleidr-designte Kacheln können auch mit MapLibre kombiniert werden, wo der aktuelle Plan und die Stilkonfiguration diesen Workflow unterstützen.

Was macht den Assistenten kartenbewusst?

Ein universeller Gesprächsassistent kann Orte beschreiben, aber er kann sich nicht mit der Karte auf der Seite koordinieren. Diese Lücke zu schließen, ist das, was einen Assistenten eher kartenbewusst als nur gesprächsorientiert macht. Ein map-aware Assistent benötigt eine strukturierte Interaktionsschleife, die Sprache mit dem Renderer-State verbindet. Jede Kurver läuft durch die folgende Reihenfolge:

1. Der Benutzer stellt eine Standortfrage.
2. Kaleidr identifiziert Orts-, Gebiets-, Näherungs-, Kategorie- oder Routenabsichten.
3. Die entsprechenden Dienste lösen Orte oder rufen genehmigte Daten ab.
4. Strukturierter Ort und Action-Veranstaltungen streamen zum Client.
5. Die Integration fügt Pins hinzu, rahmt einen Bereich ein, hebt ein Ergebnis hervor oder wendet eine andere unterstützte Kartenoperation an.
6. Die Schnittstelle präsentiert die Proseantwort zusammen mit sichtbaren geografischen Beweisen.

Kaleidr entlarven die Schleife als eine kleine Reihe von Stream-Gegenereignissen, und jede trägt eine einzige Art von Ergebnis. Der Kunde abonniert einmal und reagiert auf jede Veranstaltung, wenn es ankommt, anstatt auf eine endgültige Nutzlast zu warten. Das Lesen des Streams auf diese Weise hält die Benutzeroberfläche reaktionsschnell, während sich die Antwort noch bildet. Die dokumentierten Ereignisse sind:

• place trägt einen aufgelösten Ort und Koordinaten;
• place_linked bereichert einen bestehenden Ort;
• early_actions kann frühe Kartenaktionen wie Anpassungsgrenzen oder Hervorhebung eines Ergebnisses durchführen.
• grounding trägt Quellen für fundierte Kurven;
• end ist der maßgebliche Abschlussumschlag, der den vollständigen Text, die Orte und die Aktionen enthält.
• error beendet den Stream mit einer Fehlermeldung.

Behandeln Sie diese strukturierten Ereignisse als Anwendungsvertrag und kratzen Sie keine Ortsnamen von der Prosa, wenn das SDK oder die API bereits aufgelöste Ortsobjekte bereitstellt. Die Unterscheidung ist wichtig, da Prosa einen Namen paraphrasieren kann, während ein aufgelöstes Ortsobjekt die stabile Kennung trägt und den Renderer koordiniert, um das Ergebnis korrekt zu zeichnen. Aufbauen auf den Objekten und nicht auf dem Text halten auch die Integration stabil, wenn sich der Wortlaut des Modells zwischen den Releases ändert.

Veröffentlichbare Schlüssel und Server-Schlüssel

Kaleidr bietet zwei Anmeldeinformationen für die gleichen Organisations- und Leistungsbereiche an, und die Geradehaltung ist die wichtigste Sicherheitsentscheidung in einer Browser-Integration. Der veröffentlichbare Schlüssel gehört in den Browser, und der Serverschlüssel tut es nie. Sie zu vermischen ist der Fehler, der am ehesten eine funktionierende Demo in eine durchgesickerte Qualifikation verwandeln wird. Das Diagramm und die folgende Tabelle fassen zusammen, wie jeder reist:

Ein Live-veröffentlichbarer Schlüssel ohne zulässige Ursprünge wird unter dem dokumentierten Fluss abgelehnt, also fügen Sie beim Mintieren des Schlüssels exakte Produktions- und Staging-Ursprünge hinzu. Der Browser-Origin-Header jeder Anfrage wird genau mit der Liste abgeglichen, so dass ein zulässiger Ursprung ein bloßer Ursprung sein muss, z. B. https://app.example.com - Schema und Host ohne Pfad oder Trailing-Slash - und Sie listen jeden Ursprung auf, von dem Sie dienen, einschließlich Ihrer lokalen Entwicklungsursprung. Schlüssel tragen auch Leistungsbereiche: ai für Chat und Inferenz, design für Editor-Routen und maps für entworfene Basiskarten und Kacheln.

Die Plattform signalisiert Anmeldeinformationenprobleme mit unterschiedlichen Statuscodes, und die Schnittstelle sollte jede andere behandeln. Ein fehlender, ungültiger, widerrufener oder abgelaufener Anmeldeinformationen gibt 401 zurück; ein gültiger Schlüssel ohne den erforderlichen Umfang gibt 403 mit insufficient_scope zurück; und Kontingent- oder Konkurrenzbeschränkungen 429, die die Schnittstelle als Kapazitäts- oder Planbedingen und nicht als generische Produktfehler behandeln sollte. Mapbox- und Google Maps-Anmeldeinformationen bleiben unabhängig von Kaleidr-Anmeldeinformationen und wenden daher die Einschränkungen jedes Anbieters unabhängig an.

KI-Antworten mit zuverlässigen Standortdaten fundieren

Ortsbezogene Halluzinationen sind besonders schädlich, weil eine Karte eine falsche Antwort konkret und vertrauenswürdig aussehen lässt. Eine falsche Adresse im Klartext lädt zu einem zweiten Blick ein, während der gleiche Fehler, der an eine Koordinate gepinnt ist, als verifiziert gelesen wird. Die Autorität der Karte ist genau das, was die Integration verdienen muss, anstatt anzunehmen. Die üblichen Fehlermodi sind es wert, benannt zu werden, bevor Sie gegen sie entwerfen:

• ein fabriziertes Unternehmen oder eine Einrichtung;
• ein mehrdeutiger Ortsname, der auf die falsche Stadt aufgelöst wird;
• eine veraltete Adresse oder Öffnungszeit;
• doppelte Aufzeichnungen, die denselben Ort darstellen;
• eine Route, die über eine Dienstleistung angefordert wird, die der Antrag nicht autorisiert hat;
• eine Empfehlung außerhalb des sichtbaren oder zulässigen Bereichs;
• eine operative Behauptung, die mit einem internen System in Konflikt steht.

Eine fundierte Architektur hält das Modell in seiner Spur, indem sie jede Antwort durch Auflösung und Abruf statt durch Freiformgenerierung leitet. Das Modell schlägt Absicht vor, und autoritative Dienste entscheiden, was wahr ist, bevor etwas die Karte erreicht. Jede Stufe ist ein Kontrollpunkt, den die Anwendungssteuerung steuert, nicht ein Schritt, den das Modell selbst durchführt. Der Fluss liest sich in eine Richtung, von den Wörtern des Benutzers zu einem sichtbaren, überprüften Ergebnis:

Benutzerabsicht → KI-Interpretation → autoritatives Abrufen oder Platzieren von Auflösung → erlaubte Kartenaktion → sichtbare Antwort

Die praktischen Kontrollen folgen aus diesem Fluss. Beheben Sie Orte in Koordinaten und stabile Identifierungen vor der Darstellung, zeigen Sie das geografische Gebiet an, das für die Antwort verwendet wird, halten Sie Quelllinks oder Beschriftungen, wenn eine Antwort geerdet ist, und unterscheiden Sie öffentliche Orts Fakten von privaten Betriebsdaten. Reject-nicht unterstützte Aktionen, anstatt sie zu improvisieren, geben Sie einen sichtbaren Zustand ohne Ergebnis an, lassen Sie Benutzer die Standortmehrdeutigkeit korrigieren und protokollieren Sie den Quell- und Mandantenkontext, der für geschäftliche Antworten verwendet wird. Behandeln Sie vor allem das endliche strukturierte Ergebnis als Vertrag und nicht als die damit einhergehende Freiformprose. Eine umfassendere Diskussion über Ortsidentitäts-, Beweis- und Empfehlungssignale finden Sie im Kaleidr-Artikel über KI-gestützte lokale Geschäftserkennung und für die Architektur- und Sicherheitsprinzipien hinter der Konversationsoberfläche siehe Hinzufügen eines KI-Chat-Assistenten zu einer interaktiven Karte.

Kann der Assistent private Geschäftsdaten verwenden?

Ein KI-Chat-Panel sollte niemals uneingeschränkten Zugriff auf die operative Datenbank eines Unternehmens erhalten, da eine einzige überbreite Abfrage weit mehr als die aktuellen Fragenanforderungen aufdecken kann. Die Integration privater Daten erfordert daher ein explizites Abruf- und Autorisierungsdesign, keine offene Verbindung, durch die das Modell wandern kann. Der sicherste Standard ist, nichts zu enthüllen, bis ein bestimmter Datensatz, ein Feldsatz und eine Zugriffsregel jede Ergänzung rechtfertigen. Begrenzen Sie die Grenzen unten, bevor Sie eine private Quelle an den Assistenten senden:

• welche Datensätze der Assistent abfragen kann;
• welche Attribute das Quellsystem verlassen können;
• welche Benutzer und Mandanten auf jeden Datensatz zugreifen können;
• wie die Mieterisolierung durchgesetzt wird;
• welche Felder empfindlich sind;
• ob der Abruf durch das Host-Backend verläuft;
• was protokolliert wird und wie lange;
• wie die Quellenattribution erhalten bleibt;
• welche regionalen, vertraglichen oder Aufbewahrungspflichten gelten;
• Welche Operationen erfordern eine menschliche Bestätigung.

Kaleidr Enterprise beschreibt Inferenz-APIs, Ranking-Systeme, Analyse- und Bereitstellungsunterstützung für standortbezogene Produkt-Stacks, aber die öffentliche Dokumentation stellt nicht für jede private Datenbank einen universellen Konnektor her. Der Abrufpfad hängt von Ihren eigenen Systemen, dem Berechtigungsmodell und den Compliance-Beschränkungen ab, die kein generischer Connector in Ihrem Auftrag annehmen kann. Behandeln Sie den Private-Data-Pfad als implementierungsspezifische oder unternehmensspezifische Integration, bis der genaue Quell-, Autorisierungs- und Abrufmechanismus für Ihre Umgebung dokumentiert ist.

UX-Muster für hilfreichen Kartenchat

Eine technisch korrekte Integration kann immer noch fehlgeschlagen sein, wenn der Chat und die Karte um Aufmerksamkeit konkurrieren, anstatt zu kooperieren. Ein Panel, das die Karte versteckt, oder eine Karte, die ohne Erklärung springt, lässt den Benutzer unsicher, welcher Oberfläche er vertrauen soll. Die folgenden Muster halten die beiden als eine Antwort, und jedes adressiert eine bestimmte Art und Weise, wie die Paarung dazu neigt, zu brechen.

Karte sichtbar halten

Die Karte ist Teil der Antwort, nicht eine Kulisse, die der Chat abdecken kann. Vermeiden Sie auf dem Desktop, es hinter einer Vollbild-Chatoberfläche zu verstecken, und verwenden Sie auf dem Handy ein anpassbares Blatt oder einen kompakten Chat-Modus, der genügend Kartenkontext bewahrt, um das Ergebnis zu verstehen. Ein Benutzer, der die Pins nicht sehen kann, kann nicht beurteilen, ob die Antwort richtig ist.

Vom Assistenten ausgelöste Änderungen anzeigen

Wenn der Assistent Markierungen hinzufügt, die Kamera ändert, einen Bereich hervorhebt oder eine Route beginnt, machen Sie die Aktion wahrnehmbar. Ein plötzlicher Sprung im Kartenzustand ohne sichtbare Ursache liest sich als Fehler, also animieren oder kommentieren Sie die Änderung. Der Benutzer sollte immer verstehen, warum die Karte verschoben wurde.

Manuelle Steuerelemente beibehalten

Benutzer benötigen weiterhin eine Schwenk-, Zoom-, Reset-, Suche-, Filter- und direkte Markierungsauswahl, nachdem der Assistent handelt. KI sollte einen Interaktionspfad hinzufügen und nicht die vorhandenen Wiederherstellungspfade entfernen, auf die sich ein Benutzer bereits verlässt. Behandeln Sie das Gespräch als eine weitere Kontrolle, neben den Standard-Konserversionen, anstatt als Ersatz für sie.

Rückgängig machen und Zurücksetzen unterstützen

Geben Sie einen klaren Weg, um Assistentenmarkierungen zu löschen, die vorherige Kamera wiederherzustellen und die Konversation neu zu starten. Ein irreversibler Kartenzustand schafft Verwirrung bei explorativen Fragen, bei denen ein Benutzer oft eine Antwort mit der letzten vergleichen möchte. Ein einziges Reset-Bereitschaft verwandelt eine Sackgasse wieder in eine Erkundung.

Vorgeschlagene Fragen anbieten

Vorschläge zeigen den Benutzern, was das System tun kann, und reduzieren leere oder nicht unterstützte Anforderungen. Basieren Sie die Beispiele auf dem realen Produkt-Workflow und nicht auf generischen Tourismus-Aufforderungen, da ein Vorschlag, der eine tatsächliche Aufgabe widerspiegelt, sowohl den Wert demonstriert als auch das Modell in Richtung Fragen steuert, die es gut beantworten kann. Drehen Sie sie, wenn das Produkt wächst, so dass das Panel die aktuellen Funktionen und nicht ein gefrorenes Starter-Set bewirbt.

Ergebnislose Suchen und Fehlerzustände gestalten

Unterscheiden Sie ein No-Match-Ergebnis von einem mehrdeutigen Ort, einer abgelaufenen Sitzung, einem nicht zulässigen Ursprung, einem Anbieterfehler, einer Kontingentsbedingung und einer nicht unterstützten Anfrage."Etwas schief gelaufen" ist nicht umsetzbar genug für einen Karten-Workflow, bei dem sich der Wiederherstellungsschritt zwischen, sagen wir, einem schlechten Ursprung und einem leeren Ergebnissatz unterscheidet. Nennen Sie die Bedingung und bieten Sie den nächsten Schritt an.

Barrierefrei gestalten

Beschriften Sie die Chat-Region und die Karte, bewahren Sie die Tastaturreihenfolge bei und kündigen Sie den Streaming-Status an, ohne eine Bildschirmlesere zu überwältigen. Alle Informationen, die nur durch Markerfarbe übermittelt werden, müssen auch als Text verfügbar sein, so dass ein Benutzer, der die Farben nicht unterscheiden kann, immer noch die vollständige Antwort erhält. Barrierefreiheit ist hier die gleiche Disziplin wie die Fundierung: Die Antwort muss überleben, wenn man sie auslesen und nicht nur betrachtet.

Zu erfassende Ereignisse und Kennzahlen

Raw-Chat-Offens beweisen keinen Wert, also instrumentieren Sie den Assistenten, um zu messen, ob es den Benutzern tatsächlich hilft, eine Kartenaufgabe zu beenden. Die unten aufgeführten Ereignisnamen sind eher redaktionelle Empfehlungen als ein Anspruch auf automatisch ausgesandte Kaleidr Analytics-Ereignissen. Passen Sie sie an Ihr eigenes Schema an, aber halten Sie die Aufteilung zwischen Versuch, Erfolg und Misserfolg, von dem die Metriken später abhängen. Beginnen Sie mit einem Event-Set wie diesem:

map_chat_opened
map_chat_question_submitted
map_chat_answer_returned
map_chat_no_result
map_chat_error
map_action_applied
map_result_selected
map_marker_opened
map_chat_followup_submitted
map_chat_shared
map_chat_to_editor

Aus diesen Ereignissen sind die Metriken, die tatsächlich die Vernützlichkeit widerspiegeln, Abschluss- und Ergebnismaße anstelle von Volumen. Offene und Fragezählungen beschreiben den Verkehr, aber sie sagen nichts darüber aus, ob der Assistent die Aufgabe gelöst hat. Ein nützliches Dashboard kombiniert daher jede Aktivitätszahl mit dem Ergebnis, das sie produzieren sollte. Belasten Sie es gegenüber den Maßnahmen, die einen fertigen Job verfolgen, wie diese:

• Abschlussquote der Frage;
• Antworterfolgsquote;
• No-Result Rate;
• technische Fehlerquote;
• Erfolgsquote der Kartenaktionen;
• Ergebnis-Auswahl-Rate;
• Marker-Open-Rate;
• Folge-up-Fragesatz;
• Zeit für nützliche Ergebnisse;
• Speicher- oder Aktienkurs;
• nachgelagerte Umwandlung;
• Sieben-Tage-Rücklaufquote unter Benutzern, die eine Chat-gesteuerte Kartenaktion abgeschlossen haben.

Segmentieren Sie die Ergebnisse nach Anbieter, Gerät, Abfragetyp, Kundenkonto und aktiviertem Workflow, da eine aggregierte Zahl dort verbirgt, wo der Assistent arbeitet und wo nicht. Eine hohe Öffnungsrate gepaart mit einer niedrigen Ergebnisauswahlrate signalisiert normalerweise eher Neugier als Produktwert, was genau das Missverstanden ist, das das Tracking allein fördert. Das gemeinsame Lesen der Segmente sagt Ihnen, welche Oberflächen mehr Investitionen verdienen und welche umgedacht werden müssen.

Checkliste für Produktionstests

Interne Demo-Eingaben sind in der Regel sauberer und spezifischer als die Fragen, die Produktionsbenutzer tatsächlich tippen. Das Testen nur gegen aufgeräumte Eingaben verbirgt die Fehlerzustände, die am wichtigsten sind, von einem falsch geschriebenen Ort bis zu einer abgelaufenen Sitzung. Die folgende Liste vermischt bewusst vage Sprache, Anbieterfehler und Lebenszyklusereignisse, da jeder einen anderen Teil der Integration ausübt. Trainieren Sie den Assistenten gegen diese chaotischen Eingaben und Fehlerbedingungen, bevor Sie versenden:

• vage Fragen;
• falsch geschriebene Standorte;
• doppelte Ortsnamen in verschiedenen Regionen;
• eine leere Ergebnissatz;
• einen ungültigen Veröffentlichungsschlüssel;
• eine verbotene Herkunft;
• eine abgelaufene Browsersitzung;
• einen fehlenden Fähigkeitsumfang;
• eine 429-Quoten- oder Konkurrenzreaktion;
• ein langsames oder unterbrochenes Netzwerk;
• ein Anbieterkontingent oder Authentifizierungsfehler;
• ein Kartenstil-Reload;
• Mobile Größenänderung und Orientierungsänderungen;
• Tastatur-only Navigation;
• Screen-Reader-Labels und Live-Updates;
• eine nicht unterstützte Anfrage;
• eine unbefugte Private-Data-Anforderung;
• Chat-Montage vor Kartenbereitschaft;
• mehrere Karten-Instanzen auf einer Seite;
• Routenänderungen und Komponentenentmounting;
• Benutzer-, Organisations- oder Mandantenwechsel.

Häufige Implementierungsfehler

Die folgenden Fehler werden über Integrationen hinweg wieder auftreten, und jeder hat eine saubere Korrektur. Keiner ist exotisch, weshalb sie einfach zu versenden sind. Lesen Sie die Tabelle als Checkliste, was kaputt geht, warum sie kaputt geht und was stattdessen zu tun ist.

Mapbox, Google Maps oder MapLibre: Welche Lösung passt?

Kaleidr ist die KI-Interaktionsschicht, daher gehört die Entscheidung des Renderers immer noch eher zum Host-Produkt als zum Assistenten. Der richtige Renderer hängt von Ihrem vorhandenen Werkzeug, Ihrer Styling-Kontrolle und Ihrem Infrastruktur-Appetit ab, von dem sich die Chat-Schicht nicht ändert. Die folgende Tabelle fasst zusammen, wo jeder Renderer passt und was das Host-Team weiterhin besitzt, wobei Kaleidr als konsistente Gesprächsebene über alle drei hinweg hinzugefügt wurde.

Wechseln Sie nicht nur um, um Chat hinzuzufügen, wenn die aktuelle Karte bereits die Rendering-Anforderungen der Anwendung erfüllt. Geben Sie stattdessen die vorhandene Live-Map-Instanz an Kaleidr weiter und messen Sie, ob die Gesprächsebene eine bestimmte, definierte Benutzeraufgabe verbessert. Eine Renderer-Migration ist eine große, separate Entscheidung, und sie sollte für ihre eigenen Rendering- und Infrastrukturverdienste und nicht auf der Chat-Funktion stehen.

Abschließende Implementierungscheckliste

• Vorhendes Karten-Workflow bestätigt
• Unterstützter Renderer bestätigt
• Anbieter-Map-Laden erfolgreich
• Anbieter-Proferenz eingeschränkt
• Kaleidr-Plan und Zugang bestätigt
• Publishable key erstellt
• ai-Bereich bestätigt
• Zulässige Origins konfiguriert
• Serverschlüssel vom Browsercode ausgeschlossen
• kaleidr.js einmal geladen
• Live-Karten-Instanz an Kaleidr.mount übergeben
• Chat-Lebenszyklus, der an den Anwendungslebenszyklus gebunden sey
• Unterstützte Kartenaktionen bestätigt
• Quellen-der-Wahrheit-Systeme dokumentiert
• No-Result- und Fehlerzustände implementiert
• Quota-Handling implementiert
• Analytics-Veranstaltungen hinzugefügt
• Sicherheit und Datenschutzprüfung abgeschlossen
• Barrierefreiheit getestet
• Mobiles Verhalten getestet
• Echte Benutzerfragen getestet

Fazit

Mapbox, Google Maps und MapLibre müssen nicht ersetzt werden, um kartenbewussten KI-Chat hinzuzufügen, da der Renderer weiterhin eigene Kartenanzeige und anbieterspezifisches Verhalten besitzt. Die Host-Anwendung besitzt weiterhin Benutzer, Berechtigungen, Geschäftslogik und Daten-Governance, während Kaleidr die Konversationsebene hinzufügt, die Ortsabsicht auflöst, strukturierte Standortergebnisse streamt, Orte diagrammiert und unterstützte Kartenaktionen koordiniert. Die beiden Verantwortlichkeiten bleiben unterschiedlich, was die Integration debuggbar und die Antworten auf Grund hält.

Die Integration verdient ihren Platz, wenn die natürliche Sprache sinnvolle Reibung in einem Standort-Workflow reduziert, nicht wenn sie nur eine Chat-Box zu einer Seite hinzufügt. Es gelingt nur, wenn die Antwort geerdet bleibt, Browser- und Serveranmeldeinformationen getrennt bleiben, die Verantwortlichkeiten der Anbieter explizit bleiben und die Analyse abgeschlossene Kartenaufgaben und nicht nur die Chat-Aktivität messen. Bauen Sie gegen diese vier Bedingungen auf, und der Assistent wird zu einem echten Interaktionspfad und nicht zu einer Neuheit. Teams, die auch ein prompt-erstes Kartenautoring benötigen (nicht nur auf einer vorhandenen Karte chatten) können von Kaleidr Studio aus starten.

KI-Interaktion zur vorhandenen Karte hinzufügen

Verbinden Sie den Kaleidr-Chat mit einer Mapbox-, Google Maps- oder MapLibre-Karte, die Sie bereits ausführen, ohne Ihren Renderer zu tauschen. Das aktuelle SDK benötigt nur die Live-Map-Instanz und einen ursprungsbeschränkten veröffentlichbaren Schlüssel, und der mount-Aufruf ist über alle drei hinweg identisch. Erstellen Sie einen Schlüssel mit dem ai-Scope, fügen Sie Ihre zulässigen Ursprünge hinzu und übergeben Sie die Karte an Kaleidr.mount.

Holen Sie sich einen Kaleidr API-Schlüssel

Vollständige Implementierung prüfen

Die Entwicklerdokumentation von Kaleidr deckt die Stücke ab, die dieser Leitfaden in der Tiefe eines Produktionsbaubedarfs zusammenfasst. Das SDK-Schnellstart-, anbieterspezifische Guides und das Authentifizierungsmodell befinden sich neben den Referenzen Viewer, Editor, Kachel und Plattform-API. Beginnen Sie dort, wenn Sie von einem funktionierenden Prototypen zu einer gehärteten Integration wechseln.

Lesen Sie die Entwicklerdokumentation

Häufig gestellte Fragen

Kann ich einer vorhandenen Karte KI-Chat hinzufügen?

Ja. Das Chat-Produkt von Kaleidr akzeptiert eine Live-Karteninstanz und dokumentiert derzeit Mapbox, Google Maps, MapLibre und Leaflet-Anhang. Der vorhandene Renderer bleibt für die Anzeige der Karte verantwortlich, und Kaleidr fügt die Konversationsebene hinzu.

Muss ich Mapbox, Google Maps oder MapLibre ersetzen?

Nein. Die Host-Anwendung kann ihren vorhandenen Renderer beibehalten, und Kaleidr fungiert als KI-Interaktionsschicht, die an die Live-Karteninstanz angeschlossen ist. Das Übergeben der Karteninstanz an Kaleidr.mount reicht aus – es ist keine Renderer-Migration erforderlich.

Wie verbindet sich Kaleidr mit einer Live-Karte?

Laden Sie kaleidr.js, erstellen oder erhalten Sie das Live-Map-Objekt des Anbieters und rufen Sie Kaleidr.mount mit product: "chat", einem veröffentlichbaren Schlüssel, und der Karteninstanz auf. Kaleidr erkennt automatisch den unterstützten Renderer und koordiniert Marker und Kamera durch ihn hindurch.

Sollte ich einen veröffentlichbaren Schlüssel oder einen Server-Schlüssel verwenden?

Verwenden Sie einen Veröffentlichungsschlüssel über das Browser-SDK für Chat-, Editor- oder Kacheleinbettungen und verwenden Sie einen Serverschlüssel nur für Backend-Plattform-API-Anfragen. Der Veröffentlichungsschlüssel ist so konzipiert, dass er in der Seitenquelle angezeigt wird; der Serverschlüssel darf dies niemals tun.

Wie verhindere ich erfundene Ortsangaben?

Lösen Sie Orte durch autoritative Standortdienste auf, nutzen Sie den strukturierten Ort und die Fundierungsereignisse und behalten Sie Geschäftssysteme als Quelle der Wahrheit. Listen Sie die Kartenaktionen, die der Assistent ergreifen kann, zu, und geben Sie explizite No-Result- und Mehrdeutigkeitszustände an, so dass eine unsichere Antwort auftaucht, anstatt einen Ort zu erfinden.

Übernimmt Kaleidr die Kosten für Mapbox oder Google Maps?

Nein. Das Anbieterkonto und das Kaleidr-Konto sind getrennt: Mapbox oder Google berechnet dem Rederer und den zugehörigen Anbieterdiensten, und Kaleidr berechnet die KI-Fähigkeit gegen die Kaleidr-Organisation. Jeder Anbieter wendet seine eigenen Beschränkungen und Quoten unabhängig an.

Eignet sich KI-Chat für jede Karte?

Nein. Ein festes Suchfeld, Filter oder direkte Kartensteuerung eignet sich oft besser für einfache deterministische Aufgaben, wie das Öffnen eines bekannten Stores oder die Auswahl einer Kategorie. AI-Chat ist am nützlichsten, wenn Benutzer kontextbezogene, sich ändernde oder mehrvariable Standortabsichten ausdrücken müssen, die feste Filter nicht erfassen können.

Quellen

• Google. Load the Maps JavaScript API. Google Maps Platform documentation. Accessed 24 July 2026. https://developers.google.com/maps/documentation/javascript/load-maps-js-api
• Google. Google Maps Platform security guidance. Google Maps Platform documentation. Accessed 24 July 2026. https://developers.google.com/maps/api-security-best-practices
• Kaleidr. Attach Kaleidr AI to a Google map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/guides/attach-ai-to-google-maps
• Kaleidr. Attach Kaleidr AI to a Mapbox map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/guides/attach-ai-to-mapbox
• Kaleidr. Attach Kaleidr AI to a MapLibre map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/guides/attach-ai-to-maplibre
• Kaleidr. Auth & scopes. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes
• Kaleidr. Chat — attach AI to your map. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/sdk/chat-attach
• Kaleidr. CORS & allowed origins. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins
• Kaleidr. Get an API key. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/get-an-api-key
• Kaleidr. Pricing & Plans. kaleidr.com. Accessed 24 July 2026. https://kaleidr.com/pricing
• Kaleidr. Quickstart. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/quickstart
• Kaleidr. SSE wire contract. Kaleidr Developer Docs. Accessed 24 July 2026. https://docs.kaleidr.com/platform-api/sse-wire-contract
• Mapbox. Get started with Mapbox GL JS using a CDN. Mapbox GL JS documentation. Accessed 24 July 2026. https://docs.mapbox.com/mapbox-gl-js/guides/get-started/use-with-cdn/
• Mapbox. How to use Mapbox securely. Mapbox Help. Accessed 24 July 2026. https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/
• MapLibre. Display a map. MapLibre GL JS documentation. Accessed 24 July 2026. https://maplibre.org/maplibre-gl-js/docs/examples/display-a-map/
• MapLibre. Map event types. MapLibre GL JS API documentation. Accessed 24 July 2026. https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapEventType/

@misc{kaleidr_chat_attach,
  title  = {Chat — attach AI to your map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/sdk/chat-attach}
}

@misc{kaleidr_auth_scopes,
  title  = {Auth \& scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{kaleidr_mapbox_guide,
  title  = {Attach Kaleidr AI to a Mapbox map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/guides/attach-ai-to-mapbox}
}

@misc{kaleidr_google_maps_guide,
  title  = {Attach Kaleidr AI to a Google map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/guides/attach-ai-to-google-maps}
}

@misc{kaleidr_maplibre_guide,
  title  = {Attach Kaleidr AI to a MapLibre map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 24 July 2026},
  url    = {https://docs.kaleidr.com/guides/attach-ai-to-maplibre}
}

@misc{mapbox_cdn_guide,
  title  = {Get started with Mapbox GL JS using a CDN},
  author = {{Mapbox}},
  note   = {Mapbox GL JS documentation; accessed 24 July 2026},
  url    = {https://docs.mapbox.com/mapbox-gl-js/guides/get-started/use-with-cdn/}
}

@misc{google_maps_js_loader,
  title  = {Load the Maps JavaScript API},
  author = {{Google}},
  note   = {Google Maps Platform documentation; accessed 24 July 2026},
  url    = {https://developers.google.com/maps/documentation/javascript/load-maps-js-api}
}

@misc{maplibre_display_map,
  title  = {Display a map},
  author = {{MapLibre}},
  note   = {MapLibre GL JS documentation; accessed 24 July 2026},
  url    = {https://maplibre.org/maplibre-gl-js/docs/examples/display-a-map/}
}