AI 聊天
Docsbook AI 聊天是文档网站上的一个小组件，可以根据文档内容回答读者的问题。读者提出问题，服务器搜索页面，获取匹配的页面，并流式返回引用这些页面的答案。
任何文档助手真正值得关注的，并不是它能够回答问题，而是它在无法回答时的表现。本页面是双方共同遵循的契约。整个流程请参阅答案质量。
你将获得#
- 页面中的答案，而不是工单。 即使读者提出的问题措辞与标题不同，也仍然能找到解答该问题的页面。
- 清晰可见的踪迹。 小组件会打印
Found N results，然后每打开一个页面就打印一行Reading <page>。每一行都是一个链接，因此持怀疑态度的读者可以自行前往核查来源。 - 答案下方的引用。 只有当服务器确实为这个问题获取了该页面，或答案在行内引用了该页面路径时，引用才会保留。模型既未读取也未引用的路径，会在读者看到之前被删除。
- 后续问题。 系统会根据答案生成三个简短的后续问题，并将其作为按钮提供。
- 失败记录。 助手无法回答的问题会成为“未回答问题”报告，并触发一个
chat.no_answerwebhook，其中列出你尚未编写的页面。
助手不会做什么#
| 不会做 | 原因 |
|---|---|
| 根据模型自身的预训练知识作答 | 指令块禁止依赖常识来定义术语，或填补文档未涵盖的信息空白 |
| 引用它既未阅读也未引用的页面 | 只有当路径在答案中以内联方式引用或该页面确实由服务器获取时，引用才会保留。通过获取的部分从构造上具有依据；内联部分则不然——请参阅答案质量 |
| 编造设置流程 | 对于“如何设置 X”，它必须指向内容中明确具体菜单路径、按钮或步骤的句子。仅仅提及 X 并不构成设置流程，并且系统会指示它说明这一点 |
| 省略已声明的前置条件 | 如果页面声明了所需的套餐、角色、前置步骤、版本或配额，答案必须包含这些要求——即使该要求只在页面简介中声明 |
| 将免费功能与其付费升级版混为一谈 | 描述相关但不同事物的页面会被有意区分开来 |
| 猜测锚点 | 引用标题的链接目标由服务器使用与渲染页面相同的 slugify 程序计算得出，而不是由模型提供 |
答案是如何生成的？#
简而言之；详细信息请参阅答案质量。
- 可选的预处理钩子。 如果你注册了预处理钩子，你的端点会先接收问题，并可以阻止问题或注入上下文。请参阅聊天钩子。
- 检索。 向量搜索和 Postgres 全文搜索都会运行，搜索结果会合并——总数上限为五个页面。两个词法回退机制可覆盖没有向量索引的语料库。
- 获取。 每个选定的页面都会从你的代码库默认分支中读取，并截取至 12,000 个字符，同时保留开头和结尾。
- 生成。 页面内容、你的系统提示词和基础规则会发送给模型；答案会以 Markdown 和引用数组的形式流式返回。
- 引用过滤。 系统会根据实际读取的页面检查引用，并在服务器端重新计算锚点。
- 记录。 Token 数量和提供商费用会写入使用情况账本；
chat.question_asked会触发，而当答案承认自己不知道时，chat.no_answer也会触发。
您可以配置的内容#
| 控制项 | 更改内容 | 位置 |
|---|---|---|
| 系统提示词 | 用您的表达方式和规则替换默认指令。它会与基础规则一同添加，而不是取代基础规则 | 聊天设置 |
| 建议问题 | 空状态下显示的起始提示词——这是小组件中影响力最大的文本，因为它们会告诉读者助手的用途 | 聊天设置 |
| 行动号召 URL | 助手会先回答问题，然后用一句话指向该链接——仅当读者在评估、比较或询问限制、价格或方案时才会这样做，并且每次回复最多一次 | 聊天设置 |
| 模型 | 用于回答读者问题的模型。所有方案均免费提供 | 聊天设置 |
| 前置 / 后置 / 流式处理钩子 | 围绕每个回答调用您自己的 HTTPS 端点 | 聊天钩子 |
| 语义索引 | 在关键词匹配之上进行基于语义的检索 | 浮动小组件 → AI 聊天 → 语义搜索 |
如果助手在每个回答末尾都附上价格链接，就会失去用户的信任，这带来的转化损失超过了它赢得的转化——因此，行动号召的措辞是限制何时提供该链接，而不是作为一项持续性的宣传指令。
聊天使用哪个模型？#
读者聊天通过 OpenRouter 管理的默认模型是 openai/gpt-4o-mini：根据 OpenAI 的模型参考，其上下文窗口为 128,000 个 token，输出上限为 16,384 个 token。你也可以在任何方案中改为从聊天目录中选择任意模型，模型选择器会在每个模型旁显示其每百万个 token 的价格。
之所以存在两个模型设置，是因为有两个不同的助手在工作，并且它们分别进行计量：
- AI 访客聊天模型 — 用于回答读者问题。
- 管理员 & AI 代理模型 — 用于运行控制面板内的助手，该助手会调用工具并编辑文档。
它们有意不是同一个设置。Docsbook 曾经发布过一个版本，其中管理员循环因某个参数未传递而悄悄使用了读者聊天的默认模型，导致从外部看这两个界面连续数周都完全相同。针对工具调用进行评估的模型并不自动适合读者问答，反之亦然；将这些常量分开，才能让每个选择都可核查。
Docsbook 的密钥只接受已发布目录中的模型，因为费用会按模型的实际价格计费——无法识别的模型会按照你从未看到过的费率收费。如果你携带自己的提供商密钥，则可以指定提供商提供的任意模型，使用量会计入你的密钥，并按照提供商的价格计费，而不是从 Docsbook 余额中扣除。
可用性和费用#
面向读者的 AI 聊天是 Pro 功能。 在免费项目中，访客的问题会在调用任何模型之前被拒绝，无论项目持有什么密钥——这是套餐层级决策，而不是费用决策，因此使用自己的密钥也不会重新开放该功能。所有套餐都不会限制项目所有者本人在管理后台聊天中的提问。当前套餐请参阅定价页面。
聊天中有三项会从项目余额中计量扣费：向读者提供答案、构建或重建语义索引（以及对每个传入问题生成嵌入），还有从聊天中启动的一次代理运行。托管小组件、提供页面、关键词搜索、页面反馈和钩子调用均不计量。
计量项目与调用模型并不是同一份清单，了解每项属于哪一类很重要。在读者流程中，有两次模型调用目前不会计费：答案下方的三个后续问题，以及仅在所有检索器都返回空结果时才运行的代理搜索循环。还有一次不属于读者流程的模型调用会计费：用于填充 Chat 标签页中已回答列的评判器，该调用按所有者一侧的 AI 工作计费。
余额用尽后，聊天会停止，而不会继续产生费用。服务器的响应会区分套餐限制和你自行设置的上限，且只有前者会计为一次付费墙命中——因此，自行设置的来源上限绝不会在你的转化漏斗中显示为需要升级的需求。无论是哪种情况，读者都会收到聊天已暂停的提示。
发生故障时读者看到的内容#
| 情况 | 读者看到的内容 |
|---|---|
| 此网站未连接 AI 聊天 | 一段简单的说明，请读者联系网站所有者。绝不会显示堆栈跟踪 |
| 项目处于 Free 计划 | 什么也没有。聊天界面完全不会渲染，因此既没有按钮也没有消息——读者看到的是一个没有助手的文档网站 |
| 余额耗尽 | 聊天会暂停并说明原因 |
| 未检索到任何内容 | 明确说明文档未涵盖该问题的答案——同时该问题会出现在“未回答问题”报告中 |
| 您的预处理钩子阻止了该问题 | 一条通用错误消息。请参阅下面的限制 |
| 模型或网络故障 | “出了点问题。请重试。”，并以读者的语言显示 |
限制#
- 被阻止的问题不会向读者显示原因。 预钩子的
reason字符串会在响应流中发送，但文档站点小组件会改为显示通用错误消息。对于问题而言：该字段会被传递，自定义前端可以读取它，但随附的小组件不会读取。在此问题修复之前，请将reason作为供你自己的日志使用的值。 - 多人聊天已构建完成，但尚未启用。 邀请界面、在线状态按钮和 API 路由都已存在；但传输功能尚未实现，因此激活共享会话会返回“暂时不可用”。请不要据此进行规划。
- 无答案检测器使用英语模式匹配。 使用其他语言编写的拒答不会被识别，因此
chat.no_answer和“未回答的问题”报告会低估非英语网站中的数量。 - 答案反馈和页面反馈是不同的系列。 对答案点踩与对页面点踩不是同一事件；请参阅页面反馈，了解每种反馈会到达哪里。
- 没有已发布的准确率数据。 Docsbook 不声称答案准确率百分比。答案质量说明了实际测量的内容，以及我们不提供具体数字的原因。
- 默认读者模型由提供商负责更改。 上下文窗口、拒答行为和价格由他们决定；检索和引用机制由我们负责。