VitePress 文档站支持 AI 对话能力

将教你如何使用一个开源工具 Documate 快速让你的 VitePress 文档站拥有 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 对话能力,可以使用下面的命令:

sql 复制代码
 npm create documate@latest --template vitepress

创建完成后可直接跳到第 3 步「构建上传和搜索后端 API」继续配置。

如果要给已有的 VitePress 项目添加 AI 对话能力,则按照以下步骤进行。

1. 初始化

在你的 VitePress 项目根目录下使用以下命令进行初始化:

kotlin 复制代码
 npx @documate/documate init --framework vue

该命令会创建一个 documate.json 配置文件。

json 复制代码
 {
   "root": ".",
   "include": [
     "**/*.md"
   ],
   "backend": ""
 }

并且添加了一个 documate:upload 命令用于上传文档生成知识库,后面会介绍到具体用法。

perl 复制代码
 {
   "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 文档中介绍了如何定制自己的主题。

javascript 复制代码
 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 值。

javascript 复制代码
 // .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. 运行项目

通过下面的命令将内容上传到后端,生成文档知识库:

arduino 复制代码
 npm run documate:upload

命令完成后,本地启动项目,点击左上角 Ask AI 按钮,在弹出对话框后输入问题就可以得到基于你文档内容的回答。

arduino 复制代码
 npm run docs:dev

更多的使用和配置方式可以参考 Documate 项目的 GitHub:github.com/AirCodeLabs... 欢迎留言讨论。

相关推荐
科研邪修法4 小时前
PDF新增页面文字与文本批注怎么区分?以双版本培训讲义为例
前端·css·pdf
Lanwarf-前端开发5 小时前
Vue3 + Canvas/WebGL 雷达扫描可视化实战:PPI、RHI、VOL、SVOL 四种模式原理与实现
前端·javascript·vue.js·webgl
FRing036 小时前
vue3干货总结2(vue3生命周期、父子通信、模版引用、provide和inject)
开发语言·前端·vue.js·vue3
锋行天下8 小时前
langgraph 全栈项目(三)
前端·人工智能·后端
锋行天下9 小时前
langgraph 全栈项目(二)
前端·人工智能·后端
锋行天下10 小时前
langgraph全栈项目(一)
前端·人工智能·后端
叼烟扛炮10 小时前
[LangChain] 学习笔记(15):为什么你的重试没用——429、抖动、fallback 与熔断
java·服务器·前端
小码哥06810 小时前
智慧物业系统源码定制:公告发布范围与住户阅读记录设计
前端·javascript·vue.js·物业管理·物业系统·物业软件
泯泷13 小时前
Cloudflare 出手抢 Astro:前端框架之战,底层逻辑变了
前端·javascript·前端框架