AI Elements 快速入门与安装指南

AI Elements 是 Vercel 推出的基于 shadcn/ui 构建的 AI 组件库和自定义注册表，帮助开发者更快地构建 AI 原生应用。它提供了预构建的组件，如对话、消息等，与 AI SDK 深度集成，支持流式传输、状态管理和类型安全。

核心特性

完全可组合

每个组件都是一个构建块。组合小而专注的部件来创建你需要的精确 UI。

AI SDK 集成

与 AI SDK 深度集成。内置流式传输、状态状态和类型安全。

shadcn/ui 基础

基于 shadcn/ui 约定构建。你现有的主题和设置会自动应用。

环境要求

在安装 AI Elements 之前，确保你的环境满足以下要求：

Node.js 18 或更高版本
React 19
Next.js 14+（推荐使用 App Router）
AI SDK 已安装并配置
shadcn/ui 已在项目中初始化
Tailwind CSS 4

如果你没有安装 shadcn/ui，运行任何 AI Elements 安装命令都会自动为你设置。

AI Gateway（推荐）

推荐使用 AI Gateway 来访问模型，因为它提供了：

单一 API 密钥支持多个模型提供商
内置回退支持
统一计费
每月提供 5 美元的使用额度用于实验

将 AI_GATEWAY_API_KEY 添加到你的 .env.local 文件中。你可以在 Vercel AI Gateway 获取 API 密钥。

安装组件

使用 AI Elements CLI

bash

# 使用 npm
npx ai-elements@latest add message

# 使用 pnpm
pnpm dlx ai-elements@latest add message

# 使用 yarn
yarn dlx ai-elements@latest add message

# 使用 bun
bunx ai-elements@latest add message

使用 shadcn CLI

bash

# 使用 npm
npx shadcn@latest add @ai-elements/message

# 使用 pnpm
pnpm dlx shadcn@latest add @ai-elements/message

# 使用 yarn
yarn dlx shadcn@latest add @ai-elements/message

# 使用 bun
bunx shadcn@latest add @ai-elements/message

组件默认会添加到 @/components/ai-elements/ 目录下。

验证安装

安装组件后，验证它是否正常工作：

检查组件文件是否存在于你的组件目录中
在页面中导入并使用它：

tsx

import {
  Message,
  MessageContent,
  MessageResponse,
} from "@/components/ai-elements/message";

export default function Page() {
  return (
    <Message from="assistant">
      <MessageContent>
        <MessageResponse>Hello, world!</MessageResponse>
      </MessageContent>
    </Message>
  );
}

运行开发服务器并确认组件渲染正常

可用组件

AI Elements 提供了丰富的组件来构建 AI 应用：

Conversation - 对话容器组件
Message - 消息展示组件
PromptInput - 提示输入组件
Reasoning - 推理过程展示
Sources - 来源引用展示
Suggestion - 建议提示组件
Queue - 任务队列展示
Task - 任务项组件
Terminal - 终端输出展示
CodeBlock - 代码块展示
FileTree - 文件树组件
Checkpoint - 检查点组件
Plan - 计划步骤展示

快速开始示例

聊天界面

AI Elements 可以用来构建类似 ChatGPT、Claude 或 Grok 的聊天界面：

tsx

"use client";

import { Conversation, ConversationContent } from "@/components/ai-elements/conversation";
import { Message, MessageContent, MessageResponse } from "@/components/ai-elements/message";
import { PromptInput, PromptInputFooter, PromptInputTextarea } from "@/components/ai-elements/prompt-input";

export default function ChatPage() {
  return (
    <div className="flex flex-col h-screen">
      <Conversation>
        <ConversationContent>
          <Message from="user">
            <MessageContent>
              <MessageResponse>你好，请解释 React Hooks 的使用方法</MessageResponse>
            </MessageContent>
          </Message>
          <Message from="assistant">
            <MessageContent>
              <MessageResponse>
                React Hooks 是 React 16.8 引入的特性，它允许你在函数组件中使用状态和其他 React 特性...
              </MessageResponse>
            </MessageContent>
          </Message>
        </ConversationContent>
      </Conversation>
      <PromptInput>
        <PromptInputTextarea placeholder="输入消息..." />
        <PromptInputFooter>
          <button>发送</button>
        </PromptInputFooter>
      </PromptInput>
    </div>
  );
}

与 AI SDK 集成

AI Elements 与 Vercel AI SDK 无缝集成：

tsx

import { useChat } from "ai/react";

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat();

  return (
    <Conversation>
      <ConversationContent>
        {messages.map((message) => (
          <Message key={message.id} from={message.role}>
            <MessageContent>
              <MessageResponse>{message.content}</MessageResponse>
            </MessageContent>
          </Message>
        ))}
      </ConversationContent>
    </Conversation>
  );
}

下一步

学习如何在应用中使用组件
浏览可用的组件以找到你需要的
如果遇到问题，查看故障排除指南

字节笔记本