mintlify__docs/zh/ai/assistant.mdx

---
title: "AI 助手"
description: "为你的文档添加 AI 驱动的聊天功能，能够回答问题、标注来源并生成代码示例。"
keywords: ["chat", "RAG", "user support", "mulitmodal"]
---

<Info>
  AI 助手会在 [Pro 和 Enterprise 方案](https://mintlify.com/pricing?ref=assistant) 中自动启用。
</Info>

<div id="about-the-assistant">
  ## 关于 AI 助手
</div>

AI 助手通过自然语言查询回答与你的文档相关的问题。用户可以在你的文档站点中使用 AI 助手，即使他们不知道从哪里查起，也能快速找到答案，更顺利地使用你的产品。

AI 助手使用 agentic RAG (检索增强生成) 和工具调用功能。当用户提问时，AI 助手会：

* **搜索和检索** 文档中的相关内容，以提供准确的回答。
* **基于用户在提问时正在查看的页面构建上下文**。
* **引用来源** 并提供可点击的链接，将用户直接带到被引用的页面。
* **在回答与你的 API 相关的问题时返回详细的 API 信息**，包括来自 OpenAPI 规范的方法、参数、请求体和响应模式。
* **生成可复制的代码示例**，帮助用户基于你的文档实现解决方案。
* **支持多模态输入**，允许用户添加文本、图片和其他文件作为上下文。

你可以在控制台查看 AI 助手的使用情况，以了解用户行为和文档效果。你还可以导出并分析查询数据，以帮助识别：

* 可能需要更好覆盖的常见问题。
* 用户难以找到答案的内容空白。
* 可以通过补充内容获益的热门主题。

<div id="how-indexing-works">
  ### 索引的工作原理
</div>

AI 助手会自动为你已发布的文档和 API 规范建立索引，以便准确回答问题。当你发布变更时，AI 助手会立即为新增、更新或删除的内容建立或更新索引。AI 助手不会为草稿 branch 或预览部署建立索引。

默认情况下，AI 助手不会为隐藏页面建立索引。要将隐藏页面包含在 AI 助手的索引中，请在你的 `docs.json` 中设置 `seo.indexing: "all"`。更多信息请参见 [Hidden pages](/zh/organize/hidden-pages#search-seo-and-ai-indexing)。

<div id="how-the-assistant-handles-unknown-questions">
  ### AI 助手如何处理无法解答的问题
</div>

AI 助手只会根据你的文档中的信息来回答问题。如果在搜索后仍然找不到相关信息，它会回应自己没有足够的信息来作答。

你可以[设置分流邮箱](/zh/ai/assistant#set-deflection-email)，让 AI 助手在无法回答用户问题时，向用户提供你的支持邮箱。即使文档没有覆盖他们的具体问题，这也为用户提供了一个后续解决途径。

<div id="configure-the-assistant">
  ## 配置 AI 助手
</div>

在 Pro 和 Enterprise 方案中，AI 助手默认启用。

在控制台的 [Assistant](https://dashboard.mintlify.com/products/assistant) 页面配置 AI 助手并管理计费。启用或停用 AI 助手、配置响应处理方式、添加默认问题，并管理你的消息额度。

<div id="enable-or-disable-the-assistant">
  ### 启用或停用 AI 助手
</div>

在文档站点上切换 AI 助手的状态，以启用或停用 AI 助手。

<Frame>
  <img src="/images/assistant/status-light.png" alt="控制台中的 AI 助手状态开关。" className="block dark:hidden" />

  <img src="/images/assistant/status-dark.png" alt="控制台中的 AI 助手状态开关。" className="hidden dark:block" />
</Frame>

<div id="set-deflection-email">
  ### 设置分流邮箱
</div>

在响应处理部分，启用 AI 助手将未解答的问题转交给你的支持团队。指定一个电子邮箱地址，当 AI 助手无法回答用户的问题时会提供给用户。你也可以启用在 AI 助手聊天面板中显示“Contact support”按钮。

<Frame>
  <img src="/images/assistant/deflection-light.png" alt="控制台中的 AI 助手分流面板。助手分流已开启，且将 support@mintlify.com 设为分流邮箱。" className="block dark:hidden" />

  <img src="/images/assistant/deflection-dark.png" alt="控制台中的 AI 助手分流面板。助手分流已开启，且将 support@mintlify.com 设为分流邮箱。" className="hidden dark:block" />
</Frame>

<div id="search-domains">
  ### 搜索域名
</div>

在响应处理部分中，配置 AI 助手在回答问题时可以用于网页搜索的域名，以获取更多上下文。

* 域名必须是公开可访问的。
* 依赖 JavaScript 才能加载内容的域名不受支持。

<Frame>
  <img src="/images/assistant/search-domains-light.png" alt="控制台中启用的 AI 助手搜索域名面板。AI 助手被配置为搜索 mintlify.com/pricing 这个域名。" className="block dark:hidden" />

  <img src="/images/assistant/search-domains-dark.png" alt="控制台中启用的 AI 助手搜索域名面板。AI 助手被配置为搜索 mintlify.com/pricing 这个域名。" className="hidden dark:block" />
</Frame>

若要更精细地控制 AI 助手可以搜索的内容，请使用过滤语法。

* **域级过滤**
  * `example.com`：仅搜索 `example.com` 这个域名
  * `docs.example.com`：仅搜索 `docs.example.com` 这个子域
  * `*.example.com`：搜索 `example.com` 的所有子域
* **路径级过滤**
  * `docs.example.com/api`：搜索 `/api` 子路径下的所有页面
* **多个匹配模式**
  * 添加多个条目，以针对站点的不同部分

<div id="add-sample-questions">
  ### 添加示例问题
</div>

通过添加示例问题，帮助用户借助 AI 助手开始对话。

AI 助手可以根据用户正在查看的页面生成该页面特有的问题，你也可以添加在所有页面中都可用的常驻问题。

最多可添加 3 个示例问题。点击 **Ask AI**，即可根据你的文档获取推荐问题。

<Frame>
  <img src="/images/assistant/search-suggestions-light.png" alt="控制台中的搜索建议面板，已启用上下文相关的示例问题。" className="block dark:hidden" />

  <img src="/images/assistant/search-suggestions-dark.png" alt="控制台中的搜索建议面板，已启用上下文相关的示例问题。" className="hidden dark:block" />
</Frame>

<div id="customize-assistant-behavior">
  ## 自定义 AI 助手行为
</div>

在你的项目中添加一个 `Assistant.md` (或 `ASSISTANT.md`) 文件，为 AI 助手提供自定义指令，以影响它的回答方式。AI 助手会将这些指令作为每条回复的系统级上下文。

在项目根目录下的 `.mintlify/Assistant.md` (或 `.mintlify/ASSISTANT.md`) 路径创建该文件。

`Assistant.md` 文件中的指令会追加到 AI 助手的系统提示中。它们不会替换或覆盖 AI 助手的默认指令。

要移除自定义指令，只需删除 `Assistant.md` 文件。

使用 `Assistant.md` 可以：

* 调整 AI 助手的人设和语气
* 提供特定于产品的上下文信息
* 定义支持升级路径/流程
* 指定术语偏好
* 限制或限定 AI 助手的关注范围
* 提供特定版本的使用指引

```markdown Example Assistant.md
您是 Acme Corp 开发者平台的 AI 助手。

## 语气
- 简洁直接。直奔主题比详尽阐述更有帮助。
- 使用适合软件开发者的技术语言。大多数向您提问的人都熟悉 Acme 的产品。

## 产品背景
- Acme SDK v3 是当前稳定版本。v2 已废弃。如果有人询问 v2,请提醒他们该版本已废弃,但仍需回答他们的问题。
- 将账单相关问题引导至 support@acme.com。

## 术语
- 使用"工作区"而非"项目"或"组织"。
- 使用"访问令牌"而非"API 密钥"。
```

<div id="manage-billing">
  ## 管理计费
</div>

AI 助手使用分级消息额度。一次消息是指任何与 AI 助手的用户交互且收到了正确回复的情况。如果你有未使用的消息额度，最多可将当前消息额度的一半结转到下一个账单周期。例如，如果你的消息额度为 1,000 条且只使用了 300 条，则有 500 条消息会结转到下一个账单周期，使你在下一个账单周期总共有 1,500 条消息额度。

默认情况下，AI 助手允许超额使用。你可以禁用超额，以避免因超出当前等级的使用量而产生额外费用。如果你用尽消息额度并禁用了超额，AI 助手将在消息额度重置前不可用。当启用超额时，每一条超出额度的消息都会产生超额费用，但根据你的使用情况，偶尔的超额有时可能比升级到更高等级更便宜。

<div id="change-your-assistant-tier">
  ### 更改你的 AI 助手等级
</div>

AI 助手等级决定你的每月消息配额和定价。

在控制台的 AI 助手页面中，通过 [Billing 标签页](https://dashboard.mintlify.com/products/assistant?tab=billing) 查看并更改你当前的等级。

在 **Spending Controls** 部分，从下拉菜单中选择你所需的等级。

**升级等级：**

* 新的消息配额会立即生效。
* 你需要为当前计费周期支付按比例计算的差额。

**降级等级：**

* 新的消息配额会立即生效。
* 价格变更将在下一个计费周期开始时生效。
* 当前等级中未使用的消息**不会**结转。

<div id="allow-overages">
  ### 允许超额使用
</div>

如果你希望不允许超额使用，可以在控制台的 AI 助手页面中 [Billing 标签页](https://dashboard.mintlify.com/products/assistant?tab=billing) 里的 **Billing Controls** 部分将其禁用。

<div id="set-usage-alerts">
  ### 设置用量提醒
</div>

在 Billing Controls 部分设置用量提醒，当你的消息配额使用达到某一百分比时，通过电子邮件收到通知。

<div id="connect-apps">
  ## 连接应用
</div>

在“连接应用”部分，将 AI 助手添加到你的 [Discord](/zh/ai/discord) 服务器和 [Slack](/zh/ai/slack-bot) 工作区，让用户可以在这些平台上基于你的文档获得解答。

<div id="assistant-insights">
  ## AI 助手洞察
</div>

使用 AI 助手洞察来了解用户如何与您的文档交互，并识别改进机会。

[assistant 页面](https://dashboard.mintlify.com/products/assistant) 显示本月至今的使用趋势。您可以在 [Analytics](/zh/optimize/analytics#assistant) 页面查看更详细的洞察。

<div id="make-content-ai-ingestible">
  ## 让内容便于 AI 读取与理解
</div>

合理组织文档结构，以帮助 AI 助手提供准确、相关的答案。清晰的组织和完整的上下文信息既有利于人工读者，也能提升 AI 的理解。

<Card title="结构与组织">
  * 使用语义化标记。
  * 为各个部分撰写有描述性的标题。
  * 建立合理的信息层级结构。
  * 在整个文档中使用一致的格式。
  * 在页面 frontmatter 中包含完整的 metadata。
  * 使用语义化标记。
</Card>

<Card title="上下文">
  * 在术语和缩写首次出现时进行明确定义。
  * 提供足够的功能和流程概念性介绍内容。
  * 包含示例和使用场景。
  * 交叉引用相关主题。
  * 添加带有额外 context 的[隐藏页面](/zh/organize/hidden-pages)，这些内容用户不需要查看，但 AI 助手可以引用。
</Card>

<div id="use-the-assistant">
  ## 使用 AI 助手
</div>

用户有多种方式可以与 AI 助手开始对话。每种方式都会在文档页面右侧打开一个聊天面板。用户可以提出任何问题，AI 助手会在你的文档中搜索答案。如果 AI 助手无法检索到相关信息，AI 助手会告知无法回答该问题。

将 AI 助手作为机器人添加到你的 [Slack 工作区](/zh/ai/slack-bot) 或 [Discord 服务器](/zh/ai/discord)，这样你的社区成员就可以在自己偏好的平台上直接提问，而无需离开该平台。

<div id="ui-placement">
  ### UI 放置方式
</div>

AI 助手会出现在两个位置：搜索栏旁边的按钮，以及页面底部的工具栏。

<Columns cols={2}>
  <Frame caption="搜索栏旁边的 AI 助手按钮。">
    <img
      src="/images/assistant/assistant-button-light.png"
      className="block dark:hidden"
      style={{
  width: '268px',
  height: 'auto',
}}
      alt="亮色模式下的搜索栏和 AI 助手按钮。"
    />

    <img
      src="/images/assistant/assistant-button-dark.png"
      className="hidden dark:block"
      style={{
  width: '268px',
  height: 'auto',
}}
      alt="暗色模式下的搜索栏和 AI 助手按钮。"
    />
  </Frame>

  <Frame caption="页面底部的 AI 助手按钮。">
    <img
      src="/images/assistant/assistant-bar-light.png"
      className="block dark:hidden"
      style={{
  width: '268px',
  height: 'auto',
}}
      alt="亮色模式下的 AI 助手工具栏。"
    />

    <img
      src="/images/assistant/assistant-bar-dark.png"
      className="hidden dark:block"
      style={{
  width: '268px',
  height: 'auto',
}}
      alt="暗色模式下的 AI 助手工具栏。"
    />
  </Frame>
</Columns>

<div id="keyboard-shortcut">
  ### 键盘快捷键
</div>

在 macOS 上使用快捷键 <kbd>Command</kbd> + <kbd>I</kbd>，在 Windows 上使用 <kbd>Ctrl</kbd> + <kbd>I</kbd> 打开 AI 助手对话面板。

<div id="highlight-text">
  ### 高亮文本
</div>

在页面上选中一段文本，然后点击弹出的 **Add to assistant** 按钮，打开 AI 助手聊天面板，并将选中文本添加为 context。你可以将多个文本片段或代码块添加到 AI 助手的 context 中。

<Frame>
  <img src="/images/assistant/highlight-light.png" alt="浅色模式下，高亮文本上方的 Add to assistant 按钮。" className="block dark:hidden" />

  <img src="/images/assistant/highlight-dark.png" alt="深色模式下，高亮文本上方的 Add to assistant 按钮。" className="hidden dark:block" />
</Frame>

<div id="code-blocks">
  ### 代码块
</div>

点击代码块中的 **Ask AI** 按钮，打开 AI 助手聊天面板，并将该代码块作为上下文添加。你可以将多个代码块或文本片段添加到 AI 助手的上下文中。

<Frame>
  <img src="/images/assistant/code-block-light.png" alt="浅色模式下代码块中的 Ask AI 按钮。" className="block dark:hidden" />

  <img src="/images/assistant/code-block-dark.png" alt="深色模式下代码块中的 Ask AI 按钮。" className="hidden dark:block" />
</Frame>

<div id="file-attachments">
  ### 文件附件
</div>

在发送给 AI 助手的消息中附加文件，以提供更多上下文信息。

支持的文件类型包括：

* **图片**：JPEG、PNG、GIF、WebP、SVG
* **文档**：PDF
* **代码和文本文件**：JavaScript (`.js`, `.jsx`, `.mjs`, `.cjs`)、TypeScript (`.ts`, `.tsx`)、Python、HTML、CSS、Markdown、MDX、JSON、YAML、XML、SQL、CSV、纯文本、shell 脚本 (`.sh`, `.bash`, `.env`)、GraphQL、TOML、Go、Rust、Ruby、Java、Kotlin、Swift、C (`.c`, `.h`)、C++ (`.cpp`, `.hpp`)、C#、PHP、Lua、R、Scala

限制：

* 单个附件的最大文件大小：5 MB
* 每条消息允许的最大附件数量：10

<Frame>
  <img src="/images/assistant/image-attach-light.png" alt="在 AI 助手聊天面板中作为上下文添加的一张图片。" className="block dark:hidden" />

  <img src="/images/assistant/image-attach-dark.png" alt="在 AI 助手聊天面板中作为上下文添加的一张图片。" className="hidden dark:block" />
</Frame>

<div id="urls">
  ### URLs
</div>

通过在 URL 中添加查询参数打开 AI 助手，可以创建指向特定信息的深度链接，或分享带有预填问题的 AI 助手会话。

* **打开 AI 助手**：在 URL 末尾添加 `?assistant=open`，即可在页面加载时打开 AI 助手对话面板。
  * 示例：[https://mintlify.com/docs?assistant=open](https://mintlify.com/docs?assistant=open)
* **通过预填问题打开**：在 URL 末尾添加 `?assistant=YOUR_QUERY`，打开 AI 助手并自动提交问题。
  * 示例：[https://mintlify.com/docs?assistant=explain webhooks](https://mintlify.com/docs?assistant=explain%20webhooks)

<div id="troubleshooting">
  ## 故障排查
</div>

<Accordion title="看不到 AI 助手聊天栏">
  如果在特定浏览器中看不到 AI 助手的界面，您可能需要向 [EasyList](https://easylist.to) 提交误判报告。使用 EasyList Cookies List 的浏览器 (如 Brave 和 Comet) 有时会屏蔽 AI 助手或其他界面元素。EasyList Cookies List 包含一条按域名生效的规则，会在特定域名上隐藏固定元素以拦截 Cookie 横幅，而该规则会误伤合法的界面组件。

  请向 [EasyList](https://github.com/easylist/easylist) 提交误判报告，请求移除该规则。过滤列表更新后，问题将对所有用户一并解决。
</Accordion>