@embeddable.com/ai-chat (英语)

一个框架不可知的Web组件,它使一个流动的 AI 聊天部件在 STOMP WebSocket 上连接到一个可嵌入的管弦乐后端.

与 斯坦西尔 ——在平版HTML,React,Vue,Angular或任何其他框架中工作.

快开始

1. 配置您的 LLM

在ai-chat回复之前,您的工作空间需要配置在管弦乐后端的LLM. 发送一个 POST 改为 /api/v1/llm-config,用您的可嵌入的 API 密钥认证 (Authorization: Bearer <api-key>) (中文(简体) ). 这是一个一次性的,每个工作空间的设置——配置被加密存储,每一次聊天都重复使用.

curl -X POST https://api.[us|eu].embeddable.com/api/v1/llm-config \
  -H "Authorization: Bearer YOUR_EMBEDDABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "model": "claude-sonnet-4-5",
    "apiKey": "sk-ant-...",
    "temperature": 0.7,
    "maxTokens": 2048,
    "systemPrompt": "You are a helpful analytics assistant."
  }'

LLM 配置字段

获取当前配置( 用 API 密钥遮盖) GET /api/v1/llm-config。如果没有设置,则返回 404。 。 。 .

2. 薄荷证券

每个用户都需要一个安全标志,用您嵌入的 API 密钥将服务器侧刻出并传递到 embeddable-tokens 道具 (英语). 见 安全标志 用于请求及其选项(包括使画布只读).

3. 装入交流

添加此脚本以从 unpkg 装入组件最新版本( 不需要构建步骤) :

<script type="module" src="https://unpkg.com/@embeddable.com/[email protected]/dist/ai-chat/ai-chat.esm.js"></script>

4. 在您的页面上添加 ai-chat

在模式(浮动面板)或内线(装入容器)之间选择:

1. 模式 - 触发时在浮动面板中打开聊天

<em-ai-chat mode="modal" placement="bottom-right" orchestrator-url="wss://api.[us|eu].embeddable.com/ws" embeddable-tokens='["your-security-token"]'>
  <button slot="trigger">Open chat</button>
</em-ai-chat>

2. 内入模式 - 聊天充满了它的容器

<div style="width: 420px; height: 600px;">
  <em-ai-chat mode="inline" orchestrator-url="wss://api.[us|eu].embeddable.com/ws" embeddable-tokens='["your-security-token"]'></em-ai-chat>
</div>

见 演示.html 对于一个完整的例子.

安全标志

空谈提出的每一项请求 都用安全标志认证 每个用户使用薄荷一 POST /api/v1/security-token (用可嵌入的 API 密钥认证),然后传递给 embeddable-tokens 道具作为JSON-编码阵列——第一个道具被用作"熊克"证书.

curl -X POST https://api.[us|eu].embeddable.com/api/v1/security-token \
  -H "Authorization: Bearer YOUR_EMBEDDABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "embeddableId": "your-embeddable-id",
    "user": "user-123",
    "securityContext": {},
    "expiryInSeconds": 3600
  }'

与页面上的仪表板匹配符号

如果页面还制作出一个或多个可嵌入式仪表板(<em-beddable token="...">),建议将同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同一种同 embeddable-tokens 打开 <em-ai-chat>聊天时只看 <em-beddable> 其符号与它得到的匹配的元素 – 匹配就是它允许它读取当前屏幕上的仪表板(它所装入的部件,查询和数据)并读取自定义画布的当前布局(例如它有多少列),所以它可以像新生成的图表那样明智地大小和定位添加.

部件仍然使用不同的或独立的符号工作——它仍然可以在画布上添加一个图表——但是没有匹配,它不会在页面上的仪表盘数据或其布局中具有能见度,因此它不能调整大小或定位它有效添加的内容.

这种匹配符符的要求是暂时的——未来的发布会消除AI-chat符符符与仪表盘相匹配的需要,所以这些能力不管怎样都有效.

取消自定义画布突变

AI可以改变仪表板自定义画布(例如,添加它刚刚生成的图表). 添加 "customCanvasReadOnly": true 答复上述请求。 设定时,管弦乐团拒绝为该指使书写画布,而AI-chat的工具被标记为只读——助手仍然可以回答问题并预览图表,但不能添加或以其他方式修改画布. 旗帜默认为 false 省略时(允许的更改)。 由于它活在符上,不同的用户可以用相同的嵌入式部件获得不同的访问级别.

爱聊天道具

标签

所有介绍用户的文本都通过 labels 属性( 类型) ChatLabels) (中文(简体) ). 提供以下密钥的任何子集; 省略密钥返回默认值 .

const chat = document.querySelector('em-ai-chat');
chat.labels = {
  welcomeMessage: 'Hi! Ask me anything about your dashboard.',
  inputPlaceholder: 'Type a question…',
};

槽数

他们

组件的视觉属性被定义为 --em-ai-chat-* CSS自定义属性. 默认情况下,这些决心是来自 难得一见 设计系统 --em-sem-* (语义)和 --em-core-* (原始内容) 符号层. 你可以看到完整的地图 src/em-ai-chat/em-ai-chat.tokens.css (中文(简体) )。 。 。 .

如果一个 <em-beddable> 已经在您的应用程序中, 符号中 --em-sem-* (语义)和 --em-core-* (原始内容)将自动注入 :root,样式将自动应用.

若无 <em-beddable> ,或者如果聊天需要特定的样式,设置 --em-ai-chat-* 变量直接打开 em-ai-chat 匹配您自己的设计 :

em-ai-chat {
  /* Shell */
  --em-ai-chat-shell-background: #ffffff;
  --em-ai-chat-shell-border-color: #e4e4ea;

  /* Input composer */
  --em-ai-chat-composer-input-border-color: #e4e4ea;
  --em-ai-chat-composer-input-border-color--focus: #2d52cc;

  /* Primary icon button (send / cancel) */
  --em-ai-chat-icon-button-primary-background: #2d52cc;
  --em-ai-chat-icon-button-primary-color: #ffffff;

  /* Panel size (modal mode) */
  --em-ai-chat-panel-width: 23.75rem;
  --em-ai-chat-panel-height: 32.5rem;

  ...;
}

现有变量的完整列表在 src/em-ai-chat/em-ai-chat.tokens.css (中文(简体) )。 。 。 .

框架整合

反应 / Vue / 角 (ESM 导入)

import { defineCustomElements } from '@embeddable.com/ai-chat/loader';
defineCustomElements();

然后使用 <em-ai-chat> 和其他 HTML 元素一样 :

return (
  <em-ai-chat embeddable-tokens={JSON.stringify([token])} orchestrator-url="wss://..." mode="modal">
    <button slot="trigger">Chat</button>
  </em-ai-chat>
);

虚拟用户 - 把这个添加到 vite.config.ts 防止Vite预装装入器(它打破了Stencil的懒散块分辨率):

export default defineConfig({
  optimizeDeps: {
    exclude: ['@embeddable.com/ai-chat'],
  },
});

地方发展

npm install
npm start        # dev server with hot reload at http://localhost:3333

编辑 src/index.html (中文(简体) ) 在本地开发时更改道具或令牌。 乐团后端预计在 ws://localhost:8080/ws 默认.

npm run build    # production build → dist/

建筑

em-ai-chat 是根组件。 它拥有STOMP WebSocket连接,持有所有消息状态,并协调下面的儿童组件.

em-ai-chat
│   Root. Manages the STOMP WebSocket lifecycle, accumulates streaming
│   events into a display list, and switches between modal and inline modes.
│
├── em-ai-chat-modal-shell   (modal mode only)
│   Floating panel with trigger-based open/close, drag-to-reposition,
│   and mouse/keyboard resize. Persists panel size and position across toggles.
│
├── em-ai-chat-messages
│   Scrolling feed of user messages, assistant responses, tool calls, errors,
│   and injected components. Groups tool calls under their parent message
│   and auto-scrolls to the latest entry.
│
│   ├── em-ai-chat-message-feedback
│   │   Thumbs up/down rating attached to each assistant message.
│   │
│   └── em-ai-chat-component
│       Sandboxed host for Embeddable component bundles injected by the AI.
│       Injects theme tokens, scales height via ResizeObserver, and proxies
│       data-fetch requests to the orchestrator.
│
└── em-ai-chat-input
    Textarea composer. Enter sends, Shift+Enter adds a newline. Auto-focuses
    on visibility and toggles the action button between send and cancel
    while a response is streaming.

服务器事件由处理 reduceEvent() 内 src/utils/messages.utils.ts (中文(简体) )它保持 Map<id, message> 用于 O(1) 流出更新,并返回每个变化上的新数组引用,以触发 Stencil 重报.