@llamaindex/chat-ui

用于 LLM 应用的聊天 UI 组件

概述

@llamaindex/chat-ui 是一个 React 组件库，为构建 LLM（大型语言模型）应用中的聊天界面提供了开箱即用的 UI 元素。该包旨在简化基于聊天的 AI 驱动应用程序用户界面的开发。

快速开始

您可以通过使用 Shadcn CLI 命令快速将聊天机器人添加到您的项目中：

npx shadcn@latest add https://ui.llamaindex.ai/r/chat.json

手动安装

要在您的项目目录中安装该包，请运行以下命令：

npm install @llamaindex/chat-ui

功能特性

• 预建的聊天组件（例如消息气泡、输入框）
• 极简样式，可使用 Tailwind CSS 完全自定义
• 自定义小部件以扩展组件（例如用于渲染生成或检索的文档）
• TypeScript 支持，确保类型安全
• 易于与 Vercel Ai 等 LLM 后端集成
• 使用 highlight.js 和 katex 进行代码和 LaTeX 渲染

使用方法

1. 安装包

npm install @llamaindex/chat-ui

2. 配置 Tailwind CSS 以包含 chat-ui 组件

对于 Tailwind CSS 4.x 版本，请更新 globals.css 文件以包含 chat-ui 组件（如有必要，请更新指向 node_modules 的相对路径）：

@source '../node_modules/@llamaindex/chat-ui/**/*.{ts,tsx}';

对于 Tailwind CSS 3.x 版本，您需要在 tailwind.config.ts 文件中添加以下内容：

module.exports = {
  content: [
    'app/**/*.{ts,tsx}',
    'node_modules/@llamaindex/chat-ui/**/*.{ts,tsx}',
  ],
  // ...
}

3. 导入组件并使用

最简单的入门方式是将整个 ChatSection 组件与来自 vercel/ai 的 useChat 钩子连接起来：

import { ChatSection } from '@llamaindex/chat-ui'
import { useChat } from '@ai-sdk/react'

const ChatExample = () => {
  const handler = useChat()
  return <ChatSection handler={handler} />
}

这个简单示例的效果如下所示：

组件组合

组件被设计为可组合的。您可以直接使用它们：

import { ChatSection } from '@llamaindex/chat-ui'
import { useChat } from '@ai-sdk/react'

const ChatExample = () => {
  const handler = useChat()
  return <ChatSection handler={handler} />
}

或者您也可以通过自己的子组件来扩展它们：

import { ChatSection、ChatMessages、ChatInput } from '@llamaindex/chat-ui'
import LlamaCloudSelector from './components/LlamaCloudSelector' // 您的自定义组件
import { useChat } from '@ai-sdk/react'

const ChatExample = () => {
  const handler = useChat()
  return (
    <ChatSection handler={handler}>
      <ChatMessages />
      <ChatInput>
        <ChatInput.Form className="bg-lime-500">
          <ChatInput.Field type="textarea" />
          <ChatInput.Upload />
          <LlamaCloudSelector /> {/* 自定义组件 */}
          <ChatInput.Submit />
        </ChatInput.Form>
      </ChatInput>
    </ChatSection>
  )
}

您的自定义组件可以使用 useChatUI 钩子向聊天 API 端点发送额外的数据：

import { useChatInput } from '@llamaindex/chat-ui'

const LlamaCloudSelector = () => {
  const { requestData、setRequestData } = useChatUI()
  return (
    <div>
      <select
        value={requestData?.model}
        onChange={e => setRequestData({ model: e.target.value })}
      >
        <option value="llama-3.1-70b-instruct">Pipeline 1</option>
        <option value="llama-3.1-8b-instruct">Pipeline 2</option>
      </select>
    </div>
  )
}

样式

组件

chat-ui 组件基于 shadcn 组件，并使用 Tailwind CSS 实现。

您可以通过更改 Tailwind CSS 配置中 globals.css 文件中的 CSS 变量来覆盖默认样式。例如，要更改背景色和前景色：

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
}

有关所有可用 CSS 变量的列表，请参阅 Shadcn 主题配置。

此外，您还可以通过在 className 属性中设置自定义类来覆盖每个组件的样式。例如，设置 ChatInput.Form 组件的背景颜色：

import { ChatSection、ChatMessages、ChatInput } from '@llamaindex/chat-ui'
import { useChat } from '@ai-sdk/react'

const ChatExample = () => {
  const handler = useChat()
  return (
    <ChatSection handler={handler}>
      <ChatMessages />
      <ChatInput>
        <ChatInput.Preview />
        <ChatInput.Form className="bg-lime-500">
          <ChatInput.Field type="textarea" />
          <ChatInput.Upload />
          <ChatInput.Submit />
        </ChatInput.Form>
      </ChatInput>
    </ChatSection>
  )
}

代码和 LaTeX 样式

在 markdown 组件中，我们使用 highlight.js 处理代码块，katex 处理 LaTeX，以及 pdf-viewer 处理 PDF 文件。 如果您的应用涉及代码、LaTeX 或 PDF 文件，您需要导入相应的 CSS 文件：

import '@llamaindex/chat-ui/styles/markdown.css' // 代码、LaTeX 和自定义 Markdown 样式
import '@llamaindex/chat-ui/styles/pdf.css' // PDF 样式
import '@llamaindex/chat-ui/styles/editor.css' // 文档编辑器样式

code.css 文件默认使用 highlight.js 的 atom-one-dark 主题。还有许多其他主题可供选择：https://highlightjs.org/demo 您可以将其中任何一种的主题 CSS（位于 highlight.js 官方仓库）复制到您的项目中并导入使用。

语言渲染器支持（例如 mermaid）

对于 LLM 生成的任何语言，您可以指定自定义渲染器来呈现输出。 我们提供了一个示例，说明如何使用 自定义渲染器 将 mermaid 代码渲染为 SVG。

示例

请参阅 示例应用，以获取完整的示例。如果您想快速生成一个功能齐全的项目来开始使用，可以使用 create-llama。

许可证

@llamaindex/chat-ui 采用 MIT 许可证 发布。

支持

如果您遇到任何问题或有任何疑问，请在我们的 GitHub 仓库 中提交问题。

@llamaindex/chat-ui 快速上手指南

@llamaindex/chat-ui 是一个专为 LLM（大语言模型）应用设计的 React 组件库，提供开箱即用的聊天界面元素。它基于 Shadcn UI 和 Tailwind CSS，支持 TypeScript，并能轻松集成 Vercel AI 等后端。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• Node.js: 建议版本 18+
• 框架: React 项目 (支持 Next.js, Vite 等)
• 样式工具: 必须安装并配置 Tailwind CSS
• 包管理器: npm, yarn, pnpm 或 bun

安装步骤

你可以选择通过 Shadcn CLI 快速添加，或手动安装 npm 包。

方式一：使用 Shadcn CLI（推荐）

如果你正在使用 Shadcn UI，可以直接运行以下命令将组件添加到项目中：

npx shadcn@latest add https://ui.llamaindex.ai/r/chat.json

方式二：手动安装

在项目根目录下运行以下命令安装核心包：

npm install @llamaindex/chat-ui

注意：如果国内访问 npm 源较慢，可临时切换至淘宝镜像源： npm config set registry https://registry.npmmirror.com

配置 Tailwind CSS

安装完成后，需配置 Tailwind 以扫描 @llamaindex/chat-ui 中的样式文件。根据你的 Tailwind 版本选择对应配置：

Tailwind CSS v4.x 更新 globals.css 文件，添加 source 路径：

@source '../node_modules/@llamaindex/chat-ui/**/*.{ts,tsx}';

(注：请根据实际项目结构调整相对路径)

Tailwind CSS v3.x 更新 tailwind.config.ts (或 .js) 文件，在 content 数组中添加路径：

module.exports = {
  content: [
    'app/**/*.{ts,tsx}',
    'node_modules/@llamaindex/chat-ui/**/*.{ts,tsx}',
  ],
  // ...其他配置
}

基本使用

最简单的用法是将 ChatSection 组件与 @ai-sdk/react 提供的 useChat Hook 结合。

1. 安装 Vercel AI SDK (如果尚未安装):

   npm install @ai-sdk/react ai
   

2. 编写代码: 在你的 React 组件中引入并使用：

import { ChatSection } from '@llamaindex/chat-ui'
import { useChat } from '@ai-sdk/react'

const ChatExample = () => {
  const handler = useChat()
  return <ChatSection handler={handler} />
}

此代码将渲染一个包含消息气泡、输入框和提交按钮的完整聊天界面，并自动处理与后端的通信。

进阶：自定义样式与功能

如果需要渲染代码块、LaTeX 公式或 PDF 文件，请在入口文件（如 layout.tsx 或 main.tsx）中导入相应的样式文件：

import '@llamaindex/chat-ui/styles/markdown.css' // 代码高亮、LaTeX 及 Markdown 样式
import '@llamaindex/chat-ui/styles/pdf.css'     // PDF 预览样式
import '@llamaindex/chat-ui/styles/editor.css'  // 文档编辑器样式

你可以通过传递 className 属性覆盖默认样式，或通过组合子组件（如 ChatInput.Form, ChatInput.Field 等）构建完全自定义的聊天布局。