--- title: 向 AI 提问 description: 一个由 AI 提供支持的聊天助手，通过上下文感知的回答帮助用户理解您的文档 type: conceptual summary: 具有上下文感知搜索、持久历史记录和建议提示的 AI 聊天助手。 prerequisites: - /docs/env related: - /docs/open-in-chat - /docs/llms-txt - /docs/configuration --- The Ask AI feature provides an intelligent chat assistant built directly into your documentation. Users can ask questions about your docs and get instant, context-aware answers powered by AI. The assistant can search through your documentation, understand context, and provide helpful responses. ## 工作原理 The AI chat assistant is available in two ways: ### 1. 每页快速访问 每个文档页面的标题旁的页面操作菜单中都有 "Ask AI about this page" 操作，在移动端则位于描述下方的操作行中。读者选择该操作后，Ask AI 会： 1. 清除当前对话（包括浏览器中存储的历史记录）并打开聊天 2. 在输入框上方显示一张标明该页面的卡片。读者可以移除卡片，在不附带页面的情况下提问 3. 将该页面随读者的下一条消息一起发送，然后用该消息上标明页面的标签替换卡片 Ask AI 只发送页面路径。聊天路由会从站点自身的内容中读取该页面的完整 Markdown，并以此为依据回答，因此读者无需粘贴任何内容就能询问"这个页面讲了什么？"。只有下一条消息会附带该页面，重新加载后该消息上的标签仍会保留。 聊天路由只读取 Ask AI 可见的页面。如果路径指向通过 `excludeFrom: [chat]` 或 `internal: true` 隐藏的页面、被路由的 `filterPage` 选项移除的页面，或者不指向任何页面，路由会忽略该页面并正常回答问题。 更新日志条目不属于聊天路由的内容来源，因此在更新日志页面上，"Ask AI about this page" 保持原有行为：打开聊天并预填一条请 Ask AI 阅读该条目 URL 的提示，读者可以在发送前编辑。 同一菜单中的 "Open in ChatGPT"、"Open in Claude" 等外部提供商仍会使用链接到该页面的提示打开对应的提供商。 ### 2. 全局聊天界面 Users can open the chat interface at any time by: - Clicking the "Ask AI" button in the navbar - Using the keyboard shortcut: `⌘I` (Mac) or `Ctrl+I` (Windows/Linux) Once open, users can: - Ask questions about any part of your documentation - View the documentation pages used as sources for each answer - Copy an answer as Markdown - Get step-by-step guidance on complex topics ## 功能 ### 上下文感知搜索 The AI assistant includes a built-in `search_docs` tool that: 1. Searches through your documentation content 2. Finds relevant pages based on the user's question 3. Shows source citations with links to the referenced pages 4. Uses the content to provide accurate, contextual answers ### 持久化聊天历史 Ask AI 会将对话保存到浏览器的 IndexedDB 中，因此用户可以： - 在页面重新加载和导航后保留对话 - 在之后访问时继续之前的对话 - 从聊天标题栏复制或删除对话 Geistdocs 会在对话的最近一条消息之后保留该对话 30 天。每条新消息都会重新开始计时，重新加载页面则不会。当 Ask AI 加载超过保留期的对话时，会清除该对话并以空白状态开始。 设置 `ai.history.retentionDays` 可以更改保留期： ```tsx title="geistdocs.tsx" export const ai = { history: { retentionDays: 7, }, }; ``` | 值 | 行为 | | ------------------------------- | ---------------------------------------------------------- | | 未设置 | 在最近一条消息之后保留对话 30 天。 | | 正数 | 保留对话指定的天数。`0.5` 表示 12 小时。 | | `0` | 不保存历史。Ask AI 加载时会清除已存储的对话。 | | `Infinity` | 已存储的对话永不过期。 | | 负数、`NaN` 或 `-Infinity` | 使用 30 天的默认值，并在浏览器控制台中输出警告。 | 聊天历史按站点存储，并以站点 `title` 作为键，因此更改 `ai.title` 不会影响已有的历史。 ### 交互功能 - **建议**：聊天为空时，用户最多会看到四个建议的问题 - **支持 Markdown**：响应以正确的 Markdown 格式呈现 - **代码语法高亮**：响应中的代码块包含语法高亮 - **活动指示**：响应流式传输时，模型推理期间显示 "Thinking..."，工具运行时显示活动标签 Ask AI 仅接受文本问题，不支持文件或图片附件。 ### 移动响应式 The chat interface adapts to different screen sizes: - **桌面**：作为侧边栏面板从右侧滑入 - **移动端**：以底部抽屉的形式打开，便于访问 ## 从您自己的组件控制 Ask AI `@vercel/geistdocs/controls` 中的 `useGeistdocsChat` 可以从您自己的客户端组件中打开、关闭 Ask AI 聊天并向其发送消息。可以在 `GeistdocsProvider` 内渲染的任何组件中调用它，例如自定义页眉、提示框或 MDX 组件。 | 属性 | 类型 | 说明 | | -------------- | -------------------------------------------------- | -------------------------------------------------------------------------- | | `enabled` | `boolean` | 当 `ai.enabled` 为 `false` 时为 `false`，此时所有操作都不会生效。 | | `isOpen` | `boolean` | 聊天面板是否已打开。 | | `open` | `() => void` | 打开聊天。 | | `close` | `() => void` | 关闭聊天。 | | `toggle` | `() => void` | 聊天关闭时打开，打开时关闭。 | | `openWithPage` | `(page?: { url: string; title?: string }) => void` | 开始关于某个页面的新对话，与 "Ask AI about this page" 相同。默认为当前页面。 | | `ask` | `(text: string) => void` | 打开聊天并将 `text` 作为用户消息发送。 | ### 在自定义页眉中添加"询问此页面"按钮 `openWithPage` 的行为与 "Ask AI about this page" 操作相同：清除对话、打开聊天，并将页面附加到读者的下一条消息。 ```tsx title="components/ask-about-page-button.tsx" "use client"; import { useGeistdocsChat } from "@vercel/geistdocs/controls"; export const AskAboutPageButton = () => { const { enabled, openWithPage } = useGeistdocsChat(); if (!enabled) { return null; } return ( ); }; ``` 不传参数时，`openWithPage` 会按路径附加当前页面，卡片显示该路径。传入 `title` 可以改为显示页面标题，例如 `openWithPage({ url: "/docs/getting-started", title: "Getting Started" })`。`url` 是站点内路径，可以包含也可以不包含 `basePath`。对于绝对 URL，Ask AI 只发送其路径，因此生产环境 URL 在预览部署中同样可以解析。 ### 使用 `ask` 发送问题 `ask` 会打开聊天并像读者输入一样发送文本。可以用它创建开启特定对话的按钮： ```tsx title="components/ask-button.tsx" "use client"; import { useGeistdocsChat } from "@vercel/geistdocs/controls"; export const AskButton = ({ question }: { question: string }) => { const { ask, enabled } = useGeistdocsChat(); if (!enabled) { return null; } return ( ); }; ``` `ask` 会去除文本首尾空白并忽略空字符串。聊天尚未加载时，Ask AI 会先加载聊天、恢复已存储的对话，然后发送消息。正在流式传输响应时，消息会等到响应结束后再发送，多次调用 `ask` 会按顺序发送。 先调用 `openWithPage` 再调用 `ask`，即可在新对话中发送关于某个页面的问题： ```tsx const { ask, openWithPage } = useGeistdocsChat(); const summarize = () => { openWithPage(); ask("用三个要点总结此页面。"); }; ``` ## 重命名聊天面板 设置 `ai.title` 可以更改聊天面板的标题、无障碍标签，以及面板加载失败时显示的错误信息。默认值为 "Ask AI"，空白值会回退到默认值。 ```tsx title="geistdocs.tsx" export const ai = { title: "Ask Acme AI", }; ``` `ai.title` 只影响聊天面板。导航栏中的 "Ask AI" 按钮和 "Ask AI about this page" 页面操作保持原有标签。 ## 从其他路由提供聊天服务 Ask AI 默认将聊天请求发送到 `/api/chat`。当站点必须从其他路径提供聊天服务时（例如拥有 `/api/ai-chat` 并对其应用机器人防护或防火墙规则的微前端），请设置 `ai.endpoint`： ```tsx title="geistdocs.tsx" export const ai = { endpoint: "/api/ai-chat", }; ``` 然后将聊天路由适配器移动到对应的 App Router 路径，例如 `app/api/ai-chat/route.ts`。适配器代码保持不变。 `ai.endpoint` 是应用内路径。聊天客户端会自动添加 `basePath`，因此设置了 `basePath: "/help"` 和 `endpoint: "/api/ai-chat"` 的站点会调用 `/help/api/ai-chat`。eve agent 预热请求使用相同的 URL，`createOpenApiRoute` 生成的 OpenAPI 文档也会在配置的路径下列出聊天操作。 该值必须以单个 `/` 开头，且不能包含查询字符串、片段、空白字符、反斜杠、`.` 或 `..` 路径段（包括百分号编码形式）或末尾斜杠，也不能是其他 Geistdocs 路由已使用的路径，包括 `/api/search`、`/agents.md`、`/llms.txt`、`/sitemap.md`、`/.well-known/mcp.json` 以及站点 OpenAPI 文档路径。无效的 `ai.endpoint` 会在 `createOpenApiRoute` 运行时抛出错误，并让聊天面板显示错误状态，而不会向意外的 URL 发送请求。 ## 复制回答 每个已完成的 Ask AI 回答下方都有一个复制按钮，用于将回答的文本复制为 Markdown。复制的文本不包含 "Thinking..." 和工具活动指示，也不包含来源列表。该按钮在回答流式传输完成后出现，没有文本的回答不显示该按钮，且无需任何配置。 要复制整个对话，请使用聊天标题栏中的复制按钮。 ## 收集对回答的反馈 将 `ai.messageFeedback` 设置为 `true`，即可在每个已完成回答的复制按钮旁显示"赞"和"踩"按钮。`ai.messageFeedback` 默认为 `false`。 ```tsx title="geistdocs.tsx" export const ai = { messageFeedback: true, }; ``` 投票会发送到接收[页面反馈](/docs/feedback)的同一个 Geistdocs 反馈服务，该服务会创建一个带有您的 `siteId` 标签的 GitHub issue。请求包含以下字段： | 字段 | 内容 | | ---------- | ------------------------------------------------------------------------------------------------------ | | `note` | 以 `[Ask AI]`、投票表情和问题的单行摘要开头，随后列出投票结果、完整问题、回答所显示的来源 URL，以及 Markdown 格式的回答。 | | `thumbs` | `"up"` 或 `"down"`。反馈服务会为 issue 添加 `thumbs-up` 或 `thumbs-down` 标签。 | | `url` | 读者投票时所在的页面。 | | `label` | 您的 `siteId`。 | | `ua`、`ip` | 读者的用户代理和 IP 地址，与页面反馈相同。 | 问题是该回答之前读者发送的最近一条消息。超过 4,000 个字符的问题和回答会被截短，最多发送 10 个来源 URL。由于 `note` 包含读者输入的原始问题，请在启用 `ai.messageFeedback` 之前确认您站点的隐私要求。 每个回答只能投票一次。反馈服务接受投票后，所选按钮保持选中状态，两个按钮都会被禁用，并显示 "Thanks for your feedback" 提示。如果请求失败，会显示错误提示，读者可以再次投票。 Ask AI 会将投票与对话一起保存在浏览器中，因此重新加载后所选按钮仍保持选中，直到聊天历史被清除。投票存储在回答的消息元数据中，`createChatRoute` 会忽略该元数据，因此投票不会改变之后的聊天请求。 ## 显示已登录读者的头像 从 `@vercel/geistdocs/controls` 渲染 `AskAIUser`，即可在 Ask AI 中读者的消息旁显示其头像。Geistdocs 不知道谁登录了您的站点，因此需要您在运行时从自己的身份验证中传入读者信息。 `AskAIUser` 本身不会在页面上渲染任何内容。当它在 `GeistdocsProvider` 内挂载并带有 `avatarUrl` 时，每条用户消息都会显示一个 24px 的圆形头像。当 `AskAIUser` 卸载或未收到 `avatarUrl` 时（例如读者退出登录后），用户消息会恢复为不显示头像。 | 属性 | 类型 | 说明 | | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `avatarUrl` | `string \| null` | 读者头像的 URL。只会渲染 `https://` 和 `http://` URL 以及根相对路径（例如 `/api/avatar`）。其他值（包括 `data:` URL）会被忽略。 | | `name` | `string \| null` | 读者的姓名，用作头像的替代文本。未提供姓名时，头像为装饰性图片，替代文本为空。 | 创建一个客户端组件，从您的身份验证库读取读者信息并渲染 `AskAIUser`。以下示例使用 `useSession` hook，请替换为您所用库的客户端会话 hook： ```tsx title="components/ask-ai-user.tsx" "use client"; import { AskAIUser } from "@vercel/geistdocs/controls"; import { useSession } from "@/lib/auth-client"; export const SignedInAskAIUser = () => { const { data: session } = useSession(); if (!session?.user.image) { return null; } return ( ); }; ``` 然后在根布局的 `GeistdocsProvider` 内渲染一次： ```tsx title="app/[lang]/layout.tsx" {children}