RAG 进阶：零成本 chat_with_readthedocs

Readthedocs 这个平台，做技术文档托管的朋友应该都不陌生，GitHub、GitLab 上的项目文档免费往上一放，省心又省力。不过，当文档量堆起来之后，靠站内搜索翻来翻去就不是那么顺手了。尤其是在 AI 时代，用户已经习惯“直接问答案”，而不是亲自去翻目录。

这篇文章就聊聊——如何借助 HuixiangDou 这个开源的群聊知识助手，在 readthedocs 上实现源码级检索问答。而且重点是：

最终的效果大概是这样：打开 readthedocs 页面，右下角会有一个 “Chat with AI” 按钮，点击进去，你可以问它“如何安装 HuixiangDou？”或者“llm_client.py 是干啥用的？”，它会先检索项目文档和源码，然后流式作答。

那么，这套零成本方案是怎么搭起来的？我们一步步来看。

1. 服务部署方法

整体架构很清晰，三个关键角色：

• readthedocs
  ：托管中英文文档

• OpenXLab
  ：提供 https 入口——readthedocs 是 https 服务，没法直接内嵌 http 网页

• SiliconCloud
  ：提供 text2vec、reranker 和 LLM 模型的远程 API

补充一句：SiliconCloud 的 bce 行为跟 GitHub 并非完全一致，如果条件允许，自备 GPU 机器跑模型，精度会更高。

1.1 准备代码和文档

假设我们以 mmpose 的代码和文档作为知识库——实际操作时，完全替换成你自己的专业文档即可。

cd HuixiangDou
mkdir repodir
git clone https://github.com/open-mmlab/mmpose --depth=1
# 移除 .git 方便提交
rm -rf .git

然后调整 gradio_ui.py 的默认配置，指定使用 config-cpu.ini：

# huixiangdou/gradio_ui.py
parser.add_argument(
    '--config_path',
    default='config-cpu.ini',
    type=str,
...

把你的知识库连同 HuixiangDou 源码，一起提交到 GitHub 的一个分支。例如 huixiangdou-readthedocs 的 for-openxlab-readthedocs 分支。

1.2 创建 OpenXLab 应用

打开 OpenXLab，创建一个 Gradio 类型的应用。需要做的操作：

1. 填入上一步的 GitHub 仓库地址和分支名称
2. 服务器类型选择

   CPU

确认创建后，修改应用设置：

• 自定义启动文件改为 huixiangdou/gradio_ui.py
• 配置环境变量。HuixiangDou 会优先使用 config 里的 token，如果找不到，会尝试查找 SILICONCLOUD_TOKEN 和 LLM_API_TOKEN

同步代码、启动应用。

https://openxlab.org.cn/apps/detail/tpoisonooo/HuixiangDou-readthedocs

在浏览器按 F12，检查源码，可以得到服务对应的 https 地址：

src="https://g-app-center-000704-0786-wrbqzpv.openxlab.space"

只要不在 OpenXLab 中点击“删除应用数据”，这个地址就会保持不变。

1.3 使用 readthedocs 自定义主题

假设你已经熟悉 readthedocs 的基本用法。可以直接拷贝 HuixiangDou 的 docs 目录。zh 或 en 目录都可以。

在 requirements/doc.txt 中设置自定义主题。我们使用的是一个自定义主题实现：

• 在 layout.html 里创建了一个 chatButton 和空白 container
• 为按钮绑定事件：点击时，空白 container 会加载前面得到的 https 地址
• 在 theme.css 中，你可以按喜好修改样式

最后，在 readthedocs.io 上配置你的项目，执行 Build Version 即可。

2. 代码检索方案

这套方案在代码检索上使用的是稀疏方法。具体来说：

1. 魔改了一个 bm25 实现，完整源码只有 189 行
2. 特征库建立阶段：对项目中的 python 文件，用文件名、ast 抽取的类名、函数名和注释作为 chunk
3. 将 chunk 分词后，建立稀疏特征

检索阶段：

1. query 分词后，参与稀疏查询
2. 稀疏和稠密结果共同参与 rerank

这么设计的理由有两个：

• readthedocs 中的响应要尽量快，所以稀疏、稠密、网络搜索必须并行执行，共同参与 rerank、减少 LLM 调用，才能缩短 pipeline 延迟
• bm25 的输入要避免噪音，所以只用函数名、类名、文件名这类有签名意义的干净数据

3. 总结

这篇文章介绍了如何基于 HuixiangDou、OpenXLab 和 SiliconCloud，在 readthedocs 上零成本搭建一个能够检索代码和文档的问答助手。同时，也说明了 HuixiangDou 中用于代码检索的稀疏方法。

需要提醒的是：这套方案为了控制成本，并没有开启图文混合检索；此外，远程 bce 接口的行为与 GitHub 不完全一致，会对服务精度产生轻微影响。