安装

首先，联系我们的团队以获取 Server AI 工具包的访问权限。

获取访问权限后，按照私有注册表指南配置您的包管理器。

然后，安装该包：

npm install @tiptap-pro/server-ai-toolkit

获取模式感知数据

首先，在编辑器中安装 ServerAiToolkit 扩展。这将修改您的编辑器架构，使您的文档与 Server AI 工具包兼容。

要使用 Server AI 工具包 API，您需要从 Tiptap 编辑器获取架构感知数据。这些数据描述了文档结构，并帮助 AI 理解哪些内容是有效的。

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { getSchemaAwarenessData, ServerAiToolkit } from '@tiptap-pro/server-ai-toolkit'

const editor = new Editor({
  extensions: [StarterKit, ServerAiToolkit],
})

// 从编辑器获取模式感知数据
const schemaAwarenessData = getSchemaAwarenessData(editor)

getSchemaAwarenessData 函数返回描述文档结构的模式感知数据，用于 Server AI 工具包 API。

保存模式感知数据

getSchemaAwarenessData 返回的模式感知数据是一个可序列化为 JSON 的对象，您可以将其存储在数据库中。无需每次都重新生成，仅在编辑器扩展或模式发生变化时更新即可。

使用自定义节点？

如果您的编辑器包含自定义节点或标记，请使用 addJsonSchemaAwareness 进行配置。请参阅自定义节点指南。

更多详情，请参阅模式感知 API 参考。

配置授权

Server AI 工具包是一个云端或本地服务。需认证后方可访问其 REST API。

在 Tiptap 云 AI 设置页面，获取您的 App ID 和密钥。
在文档服务器设置页面，获取您的文档服务器凭据（ID 和管理 API 密钥）。这些会作为 JWT 声明包含，方便 Server AI 工具包自动获取并保存您的 Tiptap 云文档。
使用诸如 jsonwebtoken 的库生成 JWT。生产环境中，请务必在服务器端创建 JWT，以保持密钥安全。
在 API 请求中使用 JWT。将其作为 Bearer token 放入 Authorization 头部，并在 X-App-Id 中传递 App ID。

环境变量

配置以下环境变量：

# .env
TIPTAP_CLOUD_AI_API_URL=https://api.tiptap.dev
TIPTAP_CLOUD_AI_SECRET=your-secret-key
TIPTAP_CLOUD_AI_APP_ID=your-app-id
TIPTAP_CLOUD_DOCUMENT_SERVER_ID=your-tiptap-cloud-document-server-id
TIPTAP_CLOUD_DOCUMENT_SERVER_MANAGEMENT_API_SECRET=your-tiptap-cloud-document-management-api-secret

TIPTAP_CLOUD_AI_API_URL：Server AI 工具包 API 的基础 URL。
TIPTAP_CLOUD_AI_SECRET：来自 Content AI 设置页面中的“Content AI Secret”。用于签名 JWT。
TIPTAP_CLOUD_AI_APP_ID：来自 Content AI 设置页面中的“Content AI App ID”。
TIPTAP_CLOUD_DOCUMENT_SERVER_ID：来自文档服务器设置页面中的 Tiptap Cloud Document Server ID。它会作为 experimental_document_server_id JWT 声明包含，以便 Server AI 工具包可以自动获取并保存文档。
TIPTAP_CLOUD_DOCUMENT_SERVER_MANAGEMENT_API_SECRET：您的文档服务器管理 API 密钥。它会作为 experimental_document_server_management_api_secret JWT 声明包含，用于文档访问。

创建 JWT 令牌

此函数会从 TIPTAP_CLOUD_AI_SECRET 生成一个 JWT，用于对 Server AI 工具包 API 进行身份验证。它包含文档服务器凭据，以便 Server AI 工具包可以自动获取并保存您的 Tiptap 云文档。

// lib/server-ai-toolkit/create-jwt-token.ts
import jwt from 'jsonwebtoken'

/**
 * 从 TIPTAP_CLOUD_AI_SECRET 生成一个 JWT，用于对 Server AI 工具包 API 进行身份验证
 */
export function createJwtToken(): string {
  return jwt.sign(
    {
      // 用于自动获取/保存文档的文档服务器凭据
      experimental_document_server_id: process.env.TIPTAP_CLOUD_DOCUMENT_SERVER_ID,
      experimental_document_server_management_api_secret:
        process.env.TIPTAP_CLOUD_DOCUMENT_SERVER_MANAGEMENT_API_SECRET,
    },
    process.env.TIPTAP_CLOUD_AI_SECRET,
    { expiresIn: '1h' },
  )
}

获取身份验证头

此函数返回所有 Server AI 工具包 API 请求所需的身份验证头。

// lib/server-ai-toolkit/get-auth-headers.ts
import { createJwtToken } from './create-jwt-token'

/**
 * 返回 Server AI 工具包 API 的身份验证头
 */
export function getAuthHeaders(): Record<string, string> {
  return {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${createJwtToken()}`,
    'X-App-Id': process.env.TIPTAP_CLOUD_AI_APP_ID,
  }
}

替代方案：直接提供文档

如果您管理文档的方式不是使用 Tiptap Cloud，而是自行存储，可以省略 JWT 中的 experimental_document_server_id 和 experimental_document_server_management_api_secret 声明，并直接通过 API 请求中的 document 字段传递文档。请参阅 REST API 参考。

调用 API 端点

完成身份验证后，使用 getAuthHeaders 函数调用 Server AI 工具包 API 端点：

import { getAuthHeaders } from './lib/server-ai-toolkit/get-auth-headers'

const apiBaseUrl = process.env.TIPTAP_CLOUD_AI_API_URL || 'https://api.tiptap.dev'

const response = await fetch(`${apiBaseUrl}/v3/ai/toolkit/tools`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    schemaAwarenessData,
  }),
})

const tools = await response.json()

完整的 API 文档请参见 REST API 参考。

后续步骤

现在您已配置好 Server AI 工具包，开始构建您的 AI 集成：

AI 代理聊天机器人

了解更多 →

构建一个能够通过聊天交互并编辑文档的对话式 AI。

Previously概述

Next up智能体