---
title: "AI建议扩展配置选项"
description: "使用规则、初始建议和自定义样式配置AI建议扩展。"
canonical_url: "https://tiptap.zhcndoc.com/content-ai/capabilities/suggestion/configure"
---

# AI建议扩展配置选项

使用规则、初始建议和自定义样式配置AI建议扩展。

Tiptap 的 AI 建议扩展接受不同的设置来配置扩展和命令的全局行为。

## 规则

一组在校对过程中应用的规则数组。每条规则包含：

- 唯一的 `id`
- `prompt` 属性，一个文本，将被 AI 模型读取以生成建议
- 决定规则在 UI 中如何显示的一些参数，如 `title`、`color` 和 `backgroundColor`

你可以随时通过使用 `setAiSuggestionRules` 命令修改规则，无需重新加载编辑器。

```ts
AiSuggestion.configure({
  rules: [
    {
      id: '1',
      title: '拼写检查',
      prompt: '识别并纠正任何拼写错误',
      color: '#DC143C',
      backgroundColor: 'FFE6E6',
    },
  ],
})
```

你可以在此指南中了解更多关于规则的内容：[定义规则](https://tiptap.zhcndoc.com/content-ai/capabilities/suggestion/features/define-rules.md)

## 初始建议

一个在任何校对开始前显示的初始建议数组。可用作性能优化，避免等待首批建议生成。

```ts
export const suggestions: Suggestion[] = [
  {
    id: '1',
    deleteRange: { from: 1, to: 5 },
    deleteText: 'Mistaek',
    replacementOptions: [
      {
        id: '1',
        addText: 'Mistake',
      },
    ],
    rule: {
      id: '1',
      title: '拼写检查',
      prompt: '识别并纠正任何拼写错误',
      color: '#DC143C',
      backgroundColor: 'FFE6E6',
    },
    isRejected: false,
  },
]

AiSuggestion.configure({
  initialSuggestions: suggestions,
})
```

更多关于建议对象应包含的数据，请查看[API参考](https://tiptap.zhcndoc.com/content-ai/capabilities/suggestion/api-reference.md#proofreading-suggestions)。

## 自定义建议样式

`getCustomSuggestionDecoration` 函数允许你控制建议的外观并为用户提供视觉提示。你可以给建议添加自定义的CSS类，并在建议前后添加自定义元素。适用于为建议添加弹出框、工具提示或图标。

自定义样式和元素基于 [Prosemirror Decorations API](https://prosemirror.net/docs/ref/#view.Decorations) 实现。

想了解如何在选择建议时显示弹出框，请参阅[本指南](https://tiptap.zhcndoc.com/content-ai/capabilities/suggestion/features/display-suggestions.md#show-a-popover-when-you-select-a-suggestion)。

```ts
AiSuggestion.configure({
  getCustomSuggestionDecoration({ suggestion, isSelected, getDefaultDecorations }) {
    // 你可以将AI建议扩展的默认装饰与自定义装饰结合使用
    const decorations = getDefaultDecorations()

    // 在建议文本前添加自定义元素
    Decoration.widget(suggestion.deleteRange.from, () => {
      const element = document.createElement('span')
      element.textContent = '⚠️'
      return element
    })
    return decorations
  },
})
```

## 自定义何时加载建议

By default, the AI suggestion extension automatically loads suggestions when the editor is ready. You can disable this behavior with the `loadOnStart` option.

```ts
AiSuggestion.configure({
  loadOnStart: false,
})
```

By default, the AI suggestion extension reloads suggestions when the editor content changes. You can disable this behavior with the `reloadOnUpdate` option.

```ts
AiSuggestion.configure({
  reloadOnUpdate: false,
})
```

You can learn how to configure when suggestions are loaded in [this guide](https://tiptap.zhcndoc.com/content-ai/capabilities/suggestion/features/configure-when-to-load-suggestions.md).

## 自定义防抖超时时间

默认情况下，AI建议扩展会在用户停止输入后等待800毫秒再重新加载建议，以避免API调用过于频繁。你可以通过 `debounceTimeout` 选项配置此超时时间。

```ts
AiSuggestion.configure({
  debounceTimeout: 1000,
})
```

## 处理加载建议时的错误

你可以提供一个回调函数来处理加载建议时的错误。这允许你记录错误、向用户显示错误信息或在发生错误时执行其他操作。

关于如何在 UI 中处理加载和错误状态的完整指南见下：

```ts
AiSuggestion.configure({
  onLoadSuggestionsError(error) {
    console.error('加载建议时发生错误', error)
  },
})
```

## Tiptap 内容 AI 云选项

如果你不[提供自己的后端](https://tiptap.zhcndoc.com/content-ai/capabilities/suggestion/custom-llms.md)，AI 建议扩展将使用 Tiptap 内容 AI 云来生成建议。

你可以通过 `model` 选项配置用于生成建议的 OpenAI 模型。默认模型为 `gpt-4o-mini`。我们推荐它用于大多数用例，因其在速度、成本与准确性之间取得了良好平衡。

```ts
AiSuggestion.configure({
  // 这需要是你生成的 JWT，且绝不能是 OpenAI API 密钥！
  token: 'YOUR_TOKEN',
  // 用于生成建议的模型，默认为"gpt-4o-mini"
  model: 'gpt-4o',
})
```

目前支持的 OpenAI 模型包括：

- `gpt-5`
- `gpt-5-2025-08-07`
- `gpt-5-mini`
- `gpt-5-mini-2025-08-07`
- `gpt-5-nano`
- `gpt-5-nano-2025-08-07`
- `gpt-5-chat`
- `gpt-5-chat-2025-08-07`
- `gpt-4.1`
- `gpt-4.1-2025-04-14`
- `gpt-4.1-mini`
- `gpt-4.1-mini-2025-04-14`
- `gpt-4.1-nano`
- `gpt-4.1-nano-2025-04-14`
- `chatgpt-4o-latest`
- `gpt-4o-mini`
- `gpt-4o-mini-2024-07-18`
- `gpt-4o`
- `gpt-4o-2024-11-20`
- `gpt-4o-2024-08-06`
- `gpt-4o-2024-05-13`
- `gpt-4-turbo`
- `gpt-4-turbo-2024-04-09`
- `gpt-4-turbo-preview`
- `gpt-4`
- `gpt-4-0125-preview`
- `gpt-4-1106-preview`
- `gpt-4-0613`
- `gpt-4-0314`
- `gpt-4-32k`
- `gpt-4-32k-0613`
- `gpt-3.5-turbo-0125`
- `gpt-3.5-turbo`
- `gpt-3.5-turbo-1106`
- `gpt-3.5-turbo-16k`

## 集成你自己的后端和大型语言模型（LLMs）

如果你想使用自己的后端和LLM来生成建议，可以提供一个自定义的 `resolver` 函数。该函数应根据编辑器内容和规则返回建议数组。

关于如何集成自己的后端和LLMs，你可以参考[此指南](https://tiptap.zhcndoc.com/content-ai/capabilities/suggestion/custom-llms.md)。

```ts
AiSuggestion.configure({
  resolver: async ({ content, rules }) => {
    // 你的自定义逻辑以生成建议
    return suggestions
  },
})
```

## 向LLM提供额外上下文

如果你想向LLM提供额外信息，可以使用 `context` 选项。此选项允许你传递附加数据，以改善建议的质量。

`context` 选项是一个字符串，会作为提示的一部分添加给LLM。它将应用于所有规则。

```ts
AiSuggestion.configure({
  context: '语气应正式且专业。',
})
```

你可以在[此指南](https://tiptap.zhcndoc.com/content-ai/capabilities/suggestion/features/provide-llm-context.md)了解更多关于提供上下文的信息。

## 配置缓存

AI建议扩展会缓存建议以减少API调用。它将编辑器内容拆分成多个块，并存储每个块生成的建议。重新加载建议时，仅重新获取已修改的块。该行为默认启用，但你可以自定义。

你可以通过将 `enableCache` 设为 `false` 来禁用缓存。此时编辑器内容变更时，AI建议扩展会对所有块调用API。

```ts
AiSuggestion.configure({
  // 禁用缓存
  enableCache: false,
})
```

你可以通过 `chunkSize` 选项配置每个块包含的顶级节点数。默认值是 `2`，意味着对于包含10段的文档，AI建议会创建5个每块包含2段的块。

```ts
AiSuggestion.configure({
  // 每个块包含3个顶级HTML节点
  chunkSize: 3,
})
```

你可以通过重写 `chunkHtml` 函数来自定义块的生成。该函数接收编辑器内容，并应返回一个HTML字符串数组，每个字符串代表一个块。这让你能够精细控制内容如何切分成块。

```ts
AiSuggestion.configure({
  chunkHtml: customChunkHtmlFunction,
})
```