Readthedocs 是知名的文档托管平台，通常用于免费存放 GitHub 和 GitLab 的项目文档。当项目文档较多时，简单的搜索难以满足读者需求，此外在 AI 2.0 时代，“主动寻找答案”这类用户体验已经逐渐落后。

本文将介绍如何基于 HuixiangDou 在 readthedocs 中做源码检索，同时不需要自备 GPU 服务器和域名。

HuixiangDou ——开源的适合群聊场景的 LLM 知识助手 GitHub 链接：(欢迎 star) https://github.com/internlm/huixiangdou

最终效果见下图，HuixiangDou 会先检索项目文档和 python 源码，然后流式作答。点击右下角 “Chat with AI” 即可体验，可尝试问它这些问题：

• 如何安装 HuixiangDou？

• llm_client.py 是干啥用的？

1. 服务部署方法

chat_with_readthedocs 的零成本部署结构如下图所示：

添加图片注释，不超过 140 字（可选）

其中，

• readthedocs 用于托管中英文文档

• OpenXLab 提供 https 入口，这是因为 readthedocs 作为 https 服务，无法内嵌 http 网页

• SiliconCloud 提供 text2vec、reranker 和 LLM 模型的远程 API。考虑到 siliconcloud bce 行为和 GitHub 并未完全对齐，若自备 GPU 机器运行模型，精度会更高

以下是具体操作步骤。

1.1 准备代码和文档

假设我们用 mmpose 所有文档做知识库，把知识库放入 repodir。这里可替换自己的专业知识文档。

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,
..

连同自己的知识库和 Huixiangou 源码，一起提交到 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，如图：

添加图片注释，不超过 140 字（可选）

同步代码、启动应用。首次运行需要 10min 左右建立稠密和稀疏特征库，结束后应该能看到一个 gradio 应用。例如:

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

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

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

只要不在 OpenXLab 中点击 “删除应用数据”，这个地址就是固定的。

1.3 使用 readthedocs 自定义主题

假设你已经熟悉 readthedocs 基本用法，可以直接拷贝 HuixiangDou docs 目录

• zh 或 en 目录皆可

• 在 requirements/doc.txt 设置自定义主题

https://github.com/tpoisonooo/pytorch_sphinx_theme 是我们的自定义主题实现，主要是：

1. 在 layout.html 创建了一个 chatButton 和空白 container

2. 为 chatButton 绑定事件。按钮点击时，空白 container 将加载 https 地址，也就是前面的：

bash https://g-app-center-000704-0786-wrbqzpv.openxlab.space 在 theme.css 中，您可修改自己喜欢的样式。

最后，在 readthedocs.io 配置自己的项目，Build Version 即可。

2. 代码检索方案

本文使用稀疏方法实现代码检索。

添加图片注释，不超过 140 字（可选）

具体来说：

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 不一致，会轻微影响服务精度。