使用 BlockNote AI 进行后端集成

将 BlockNote AI 与大型语言模型（LLM）集成的最常见（且推荐）的方式是让 BlockNote AI 调用您的后端，然后后端使用 Vercel AI SDK 调用您选择的 LLM。本文档介绍了默认的集成方式，同时也提供了多种替代方案。

默认设置（Vercel AI SDK）

下面的示例紧跟 Next.js 的 Vercel AI SDK 基础示例。唯一的区别是，我们从请求体中获取 BlockNote 工具，并使用 toolDefinitionsToToolSet 函数将工具定义转换为 AI SDK 工具。我们还通过调用 injectDocumentStateMessages 转发了 BlockNote 附加到每条用户消息中的序列化文档状态（选择、光标、区块 ID）。现在 LLM 可以调用这些工具，以便根据用户请求修改 BlockNote 文档。工具调用被转发至客户端应用，由 AI 扩展自动处理。

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: await convertToModelMessages(
      injectDocumentStateMessages(messages),
    ),
    tools: toolDefinitionsToToolSet(toolDefinitions),
    toolChoice: "required",
  });

  return result.toUIMessageStreamResponse();
}

不同的 JavaScript 框架设置非常相似。例如，请参见我们的 Hono 示例。

如果您的后端使用其他语言，无法使用 Vercel AI SDK，或根本无法搭建后端——也有多种替代方案可以集成 BlockNote AI：

数据流协议

BlockNote AI 期望您的后端根据数据流协议返回服务器发送事件（SSE）数据流。该协议由 Vercel AI SDK 指定。您可以利用此信息为您的应用场景开发自定义后端接口。例如，提供以 Python 等其他语言实现的兼容 API 端点。

这是一个使用 Python FastAPI 作为后端的示例（注意此处的未解决问题）。

自定义传输

您也可以不修改后端支持数据流协议，而是在客户端应用中实现自定义的传输层。传输层负责将 AI SDK 请求发送到后端并接收 LLM 响应。

ClientSideTransport

BlockNote AI 还提供了一个 ClientSideTransport 类，可用于直接连接 LLM，无需通过后端路由。使用此传输层，您可以在客户端直接创建 Vercel AI SDK Provider 和 LanguageModel，再用它实例化传输层，并传递给 AI 扩展。

下面的示例使用了 OpenAI 兼容供应商，但您可以使用任意供应商 / 模型。

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { ClientSideTransport } from "@blocknote/xl-ai";

const model = createOpenAICompatible({
  apiKey: 'your-api-key',
  baseURL: 'https://your-provider',
})('model-id');

// ...
 AIExtension({
    transport: new ClientSideTransport({
        model,
    }),
}),
// ...

使用代理服务器

通常您无法在客户端应用中使用 ClientSideTransport 直接调用您的 LLM 供应商，因为您需要隐藏 API 密钥或避免跨源资源共享（CORS）问题。为此，您可以使用代理服务器，将请求路由到您的 LLM 供应商。该代理服务器可以注入 API 密钥并转发请求。

BlockNote AI 提供了 fetchViaProxy 函数，可用于创建将请求通过代理服务器路由的 fetch 函数（下面示例使用 Groq 作为 LLM 供应商）：

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

const model = createGroq({
  fetch: fetchViaProxy(
    (url) => `${BASE_URL}/proxy?provider=groq&url=${encodeURIComponent(url)}`,
  ),
  apiKey: "fake-api-key", // API 密钥未直接使用，实际注入在代理服务器中
})("llama-3.3-70b-versatile");

参见完整示例，演示如何结合代理服务器使用 ClientSideTransport。

高级模式

您可以将 BlockNote AI 功能与更高级的 AI 流水线连接起来。可以集成诸如 Agent、RAG（检索增强生成）、多步 LLM 调用等概念。务必确保始终将 BlockNote 工具（通过请求体 toolDefinitions 传递）暴露给 LLM，并把工具调用转发到客户端。

我们热切期待了解您的集成方案并与您协作开发高级 AI 模式。如需关于将您的流水线和应用程序与 BlockNote AI 集成的专属支持，请联系我们。

默认情况下，BlockNote AI 会将整个 LLM 聊天记录发送到后端。有关后端存储聊天且仅将最新消息发送到后端的模式，请参见服务器持久化示例。