这篇文章将教你如何使用一个开源工具 Documate（github.com/AirCodeLabs…）快速让你的 VitePress（vitepress.dev/） 文档站拥有 AI 对话能力，基于你的文档内容来解答用户问题。
通过简单的配置，就可以将能力接入到你的网站之中。有了大模型的加持，用户上来几乎可以不读文档，直接与 AI 对话就可以完成自己的需求，对技术类产品文档来说，价值很高。支持流式输出，回答速度很快，并且开源，随时可以贡献和调整代码。
技术原理
仔细阅读了这个项目的源码，整体实现还是比较简单和清晰的。它由三部分构成：
第一部分：一个将文档提交到数据库的 CLI 工具，只需要在项目中配置下 documate.json 就行了。
document.json配置文件非常简单，只有三个配置项：
- root 描述使用项目的哪个目录下的文件生成内容，默认是根目录
- include 描述哪些是需要处理的文档文件，默认是Markdown文本。
- backend 指定上传文档内容到后端保存的接口，OpenAI根据这些内容来提供回答。
第二部分：一个封装好的拿来即用的问答 UI 组件，直接 import 组件就可以使用，目前提供了 Vue 组件以及不依赖任何框架的原生 JavaScript 的 UI。看 issue 规划，React 版本社区已经在支持中了，相信很快就会发布；
第三部分：一个提供问答服务、可一键完成部署的 AI Ask Server，可以在 AirCode 直接完成部署，也可以在自己的服务器上部署；
问答服务有了，UI 组件有了，数据也有了，那就可以尝试着玩耍了，整个配置过程大概可以在 15min 内完成。
如何接入
如果你想创建一个全新的 VitePress 项目并包含 AI 对话能力，可以使用下面的命令：
bash复制代码npm create documate@latest --template vitepress
创建完成后可直接跳到第 3 步「构建上传和搜索后端 API」继续配置。
如果要给已有的 VitePress 项目添加 AI 对话能力，则按照以下步骤进行。
1. 初始化
在你的 VitePress 项目根目录下使用以下命令进行初始化：
bash复制代码npx @documate/documate init --framework vue
该命令会创建一个 documate.json 配置文件。
json复制代码{
"root": ".",
"include": [
"**/*.md"
],
"backend": ""
}
并且添加了一个 documate:upload 命令用于上传文档生成知识库，后面会介绍到具体用法。
json复制代码{
"scripts": {
"docs:dev": "vitepress dev",
"docs:build": "vitepress build",
"docs:preview": "vitepress preview",
"documate:upload": "documate upload"
},
"dependencies": {
"@documate/vue": "^0.2.3"
},
"devDependencies": {
"@documate/documate": "^0.1.0"
}
}
2. 给项目添加 UI 入口
在文件 .vitepress/theme/index.js 中添加如下代码，如果没有则需要先手动创建这个文件。VitePress 在 Extending the Default Theme 文档中介绍了如何定制自己的主题。
jsx复制代码import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
// Load component and style
import Documate from '@documate/vue'
import '@documate/vue/dist/style.css'
export default {
...DefaultTheme,
// Add Documate UI to the slot
Layout: h(DefaultTheme.Layout, null, {
'nav-bar-content-before': () => h(Documate, {
endpoint: '',
}),
}),
}
上面的代码会在导航栏中添加一个 AI 对话框的 UI。在本地使用 npm run docs:dev 启动服务后，你可以在左上角找到 Ask AI 的按钮。如果没有看到 Ask AI 按钮，可以检查下上面的代码是否都正确添加，并确保从 @documate/vue/dist/style.css 导入了 CSS 样式文件。
至此，你已经完成了 UI 的接入，接下来我们为对话框添加回答问题的接口能力。
3.构建上传和搜索后端 API
Documate 的后端代码用于上传文档内容生成知识库，以及接收用户的问题并返回流式的回答。
进入 GitHub 中的 backend 文件夹，点击其中的「Deploy to AirCode」，快速复制并部署一份自己的后端代码。
如果是第一次使用 AirCode（一个在线编写和部署 Node.js 应用的平台），会被重定向到登录页面。建议选择 GitHub 登录，会更快一些。
创建应用之后，在 Envrionments 标签页中设置 OPENAI_API_KEY 环境变量为你的 OpenAI Key 值。你可以在 OpenAI 控制台 中获取到 API Key。
点击顶部栏上的「Deploy」按钮，将所有的函数部署到线上，部署成功后可以得到每个函数的调用 URL。
这里会使用到 upload.js 和 ask.js两个函数，一个用于文档内容上传，另一个用于回答问题。
4.设置 API 接口
在 AirCode Dashboard 中，选择部署后的 upload.js 文件，复制 URL 并添加到 documate.json 的 backend 字段中：
json复制代码// documate.json
{
"root": ".",
"include": [ "**/*.md" ],
"backend": "替换为你的 upload.js 的 URL"
}
同上操作，在 AirCode 中选择已部署的 ask.js 文件，复制调用 URL，修改 .vitepress/theme/index.js 文件 endpoint 值。
jsx复制代码// .vitepress/theme/index.js
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import Documate from '@documate/vue'
import '@documate/vue/dist/style.css'
export default {
...DefaultTheme,
Layout: h(DefaultTheme.Layout, null, {
'nav-bar-content-before': () => h(Documate, {
// Replace the URL with your own one
endpoint: '替换为你的 ask.js 的 URL',
},
),
}),
}
5. 运行项目
通过下面的命令将内容上传到后端，生成文档知识库:
bash复制代码npm run documate:upload
命令完成后，本地启动项目，点击左上角 Ask AI 按钮，在弹出对话框后输入问题就可以得到基于你文档内容的回答。
bash复制代码npm run docs:dev
更多的使用和配置方式可以参考 Documate 项目的 GitHub：github.com/AirCodeLabs…。欢迎留言讨论。
