开始使用 BlockNote AI

本指南将引导你完成为 BlockNote 富文本编辑器添加 AI 功能的步骤。

首先，安装 @blocknote/xl-ai 包：

npm install @blocknote/xl-ai

创建模型

BlockNote AI 使用 AI SDK 来标准化集成来自支持的提供商的人工智能（AI）模型。

第一步，你需要在 AI SDK 中注册一个新的模型。例如，针对 Groq 托管的 Llama：

npm install @ai-sdk/groq

import { createGroq } from "@ai-sdk/groq";

const provider = createGroq({
  apiKey: "YOUR_GROQ_API_KEY",
});

const model = provider("llama-3.3-70b-versatile");

请注意，这种设置是直接在客户端调用提供商，并将你的 API 密钥暴露在客户端。对于生产环境，更常见的做法是由你自己的服务器处理身份验证并代理请求到提供商。请参阅我们的演示 AI 服务器了解 Node.js 示例，或查阅 AI SDK 最佳实践。

配置编辑器

现在，你可以创建启用 AI 扩展的编辑器了：

import { createBlockNoteEditor } from "@blocknote/core";
import { BlockNoteAIExtension } from "@blocknote/xl-ai";
import { en } from "@blocknote/core/locales";
import { en as aiEn } from "@blocknote/xl-ai/locales";
import { AIExtension } from "@blocknote/xl-ai";
import "@blocknote/xl-ai/style.css"; // 添加 AI 样式表

const editor = createBlockNoteEditor({
  dictionary: {
    ...en,
    ai: aiEn, // 添加 AI 扩展的默认翻译
  },
  extensions: [
    AIExtension({
      transport: new DefaultChatTransport({
        api: `/api/chat`,
      }),
    }),
  ],
  // ... 其他编辑器选项
});

有关 AIExtension 选项的更多信息，请参阅 API 参考。

添加 AI UI 元素

现在，只剩下一步就是自定义编辑器的 UI 元素。
我们希望：

在格式工具栏（选中文本时显示）中添加一个 AI 按钮
在斜杠菜单（输入 / 时显示）中添加一个 AI 选项

我们通过禁用默认的 FormattingToolbar 和 SuggestionMenu 并添加自定义的实现来完成此操作。详见更改 UI 元素。

<BlockNoteView
  editor={editor}
  // 我们禁用了部分默认 UI 元素
  formattingToolbar={false}
  slashMenu={false}
>
  {/* 将 AI 命令菜单添加到编辑器 */}
  <AIMenuController />

  {/* 创建带有 AI 按钮的自定义格式工具栏
    (完整示例代码见下方) */}
  <FormattingToolbarWithAI />

  {/* 创建带有 AI 选项的自定义斜杠菜单
    (完整示例代码见下方) */}
  <SuggestionMenuWithAI editor={editor} />
</BlockNoteView>

后端设置

接下来，我们将设置后端路由来处理转发到你的大型语言模型（LLM）提供商的 AI 请求。

这个示例使用了 Next.js 和 AI SDK 中的基础示例：

import { openai } from "@ai-sdk/openai";
import { convertToModelMessages, streamText } from "ai";
import {
  aiDocumentFormats,
  injectDocumentStateMessages,
  toolDefinitionsToToolSet,
} from "@blocknote/xl-ai/server";

// 允许最长 30 秒的流式响应
export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages, toolDefinitions } = await req.json();

  const result = streamText({
    model: openai("gpt-4.1"), // 参考 https://ai-sdk.dev/docs/foundations/providers-and-models
    system: aiDocumentFormats.html.systemPrompt,
    messages: convertToModelMessages(injectDocumentStateMessages(messages)),
    tools: toolDefinitionsToToolSet(toolDefinitions),
    toolChoice: "required",
  });

  return result.toUIMessageStreamResponse();
}

这遵循了 AI SDK 的常规 streamText 模式，但有三个例外：

BlockNote 文档状态从消息元数据中提取，并通过 injectDocumentStateMessages 注入到消息中
BlockNote 客户端工具定义从请求体中提取，并通过 toolDefinitionsToToolSet 传递给 LLM
系统提示词设置为默认的 BlockNote 系统提示词（aiDocumentFormats.html.systemPrompt）。你可以覆盖或扩展系统提示词。如果你这样做，请确保你修改后的系统提示词仍然能够向 AI 解释如何修改 BlockNote 文档。

更多关于如何将 BlockNote AI 与你的后端集成的信息，请参阅后端集成。

完整示例

查看完整示例代码和在线演示。选择一些文本并点击 AI（星星）按钮，或在编辑器的任意位置输入 /ai 以访问 AI 功能。

GitHub

StackBlitz

import { BlockNoteEditor } from "@blocknote/core";
import { filterSuggestionItems } from "@blocknote/core/extensions";
import "@blocknote/core/fonts/inter.css";
import { en } from "@blocknote/core/locales";
import { BlockNoteView } from "@blocknote/mantine";
import "@blocknote/mantine/style.css";
import {
  FormattingToolbar,
  FormattingToolbarController,
  getDefaultReactSlashMenuItems,
  getFormattingToolbarItems,
  SuggestionMenuController,
  useCreateBlockNote,
} from "@blocknote/react";
import {
  AIExtension,
  AIMenuController,
  AIToolbarButton,
  getAISlashMenuItems,
} from "@blocknote/xl-ai";
import { en as aiEn } from "@blocknote/xl-ai/locales";
import "@blocknote/xl-ai/style.css";

import { DefaultChatTransport } from "ai";
import { useEffect } from "react";
import { getEnv } from "./getEnv";

const BASE_URL =
  getEnv("BLOCKNOTE_AI_SERVER_BASE_URL") || "https://localhost:3000/ai";

export default function App() {
  // Creates a new editor instance.
  const editor = useCreateBlockNote({
    dictionary: {
      ...en,
      ai: aiEn, // add default translations for the AI extension
    },
    // Register the AI extension
    extensions: [
      AIExtension({
        transport: new DefaultChatTransport({
          // URL to your backend API, see example source in `packages/xl-ai-server/src/routes/regular.ts`
          api: `${BASE_URL}/regular/streamText`,
        }),
      }),
    ],
    // We set some initial content for demo purposes
    initialContent: [
      {
        type: "heading",
        props: {
          level: 1,
        },
        content: "Open source software",
      },
      {
        type: "paragraph",
        content:
          "Open source software refers to computer programs whose source code is made available to the public, allowing anyone to view, modify, and distribute the code. This model stands in contrast to proprietary software, where the source code is kept secret and only the original creators have the right to make changes. Open projects are developed collaboratively, often by communities of developers from around the world, and are typically distributed under licenses that promote sharing and openness.",
      },
      {
        type: "paragraph",
        content:
          "One of the primary benefits of open source is the promotion of digital autonomy. By providing access to the source code, these programs empower users to control their own technology, customize software to fit their needs, and avoid vendor lock-in. This level of transparency also allows for greater security, as anyone can inspect the code for vulnerabilities or malicious elements. As a result, users are not solely dependent on a single company for updates, bug fixes, or continued support.",
      },
      {
        type: "paragraph",
        content:
          "Additionally, open development fosters innovation and collaboration. Developers can build upon existing projects, share improvements, and learn from each other, accelerating the pace of technological advancement. The open nature of these projects often leads to higher quality software, as bugs are identified and fixed more quickly by a diverse group of contributors. Furthermore, using open source can reduce costs for individuals, businesses, and governments, as it is often available for free and can be tailored to specific requirements without expensive licensing fees.",
      },
    ],
  });

  // Renders the editor instance using a React component.
  return (
    <div>
      <BlockNoteView
        editor={editor}
        // We're disabling some default UI elements
        formattingToolbar={false}
        slashMenu={false}
        style={{ paddingBottom: "300px" }}
      >
        {/* Add the AI Command menu to the editor */}
        <AIMenuController />

        {/* We disabled the default formatting toolbar with `formattingToolbar=false` 
        and replace it for one with an "AI button" (defined below). 
        (See "Formatting Toolbar" in docs)
        */}
        <FormattingToolbarWithAI />

        {/* We disabled the default SlashMenu with `slashMenu=false` 
        and replace it for one with an AI option (defined below). 
        (See "Suggestion Menus" in docs)
        */}
        <SuggestionMenuWithAI editor={editor} />
      </BlockNoteView>
    </div>
  );
}

// Formatting toolbar with the `AIToolbarButton` added
function FormattingToolbarWithAI() {
  return (
    <FormattingToolbarController
      formattingToolbar={() => (
        <FormattingToolbar>
          {...getFormattingToolbarItems()}
          {/* Add the AI button */}
          <AIToolbarButton />
        </FormattingToolbar>
      )}
    />
  );
}

// Slash menu with the AI option added
function SuggestionMenuWithAI(props: {
  editor: BlockNoteEditor<any, any, any>;
}) {
  return (
    <SuggestionMenuController
      triggerCharacter="/"
      getItems={async (query) =>
        filterSuggestionItems(
          [
            ...getDefaultReactSlashMenuItems(props.editor),
            // add the default AI slash menu items, or define your own
            ...getAISlashMenuItems(props.editor),
          ],
          query,
        )
      }
    />
  );
}

// helper function to get env variables across next / vite
// only needed so this example works in BlockNote demos and docs
export function getEnv(key: string) {
  const env = (import.meta as any).env
    ? {
        BLOCKNOTE_AI_SERVER_API_KEY: (import.meta as any).env
          .VITE_BLOCKNOTE_AI_SERVER_API_KEY,
        BLOCKNOTE_AI_SERVER_BASE_URL: (import.meta as any).env
          .VITE_BLOCKNOTE_AI_SERVER_BASE_URL,
      }
    : {
        BLOCKNOTE_AI_SERVER_API_KEY:
          process.env.NEXT_PUBLIC_BLOCKNOTE_AI_SERVER_API_KEY,
        BLOCKNOTE_AI_SERVER_BASE_URL:
          process.env.NEXT_PUBLIC_BLOCKNOTE_AI_SERVER_BASE_URL,
      };

  const value = env[key as keyof typeof env];
  return value;
}