🎚️ 升级

HuixiangDou2(ACL25) 是一种 GraphRAG 解决方案，在植物科学领域已证明其有效性，并为《Molecular Plant》杂志的封面论文 做出了贡献。如果您从事计算机科学以外的工作，不妨试用一下这个新版本。

---

英语 | 简体中文

HuixiangDou1 是一款基于 LLM 的专业知识助手。

优势：

1. 设计了预处理、拒绝和响应三阶段流水线
   • chat_in_group 适用于群聊场景，在不造成消息刷屏的情况下回答用户问题，详见 2401.08772、2405.02817、混合检索 和 精确度报告
   • chat_with_repo 用于实时流式聊天
2. 无需训练，支持仅 CPU、2G、10G 等配置
3. 提供完整的 Web、Android 和流水线源代码套件，具备工业级标准且可商业化

请查看 HuixiangDou 运行的场景 以及当前的公共服务状态：

• readthedocs ChatWithAI（仅 CPU）现已可用
• OpenXLab 使用 GPU 并持续维护中
• 微信机器人 需要支付微信接入的相关费用。所有代码均已验证一年内功能正常。请根据您的需求自行部署免费版或商业版。

如果对您有所帮助，请给它点个赞 ⭐

🔆 新特性

我们的 Web 版本已发布至 OpenXLab，您可以在其中创建知识库、更新正负样本、开启网页搜索、测试聊天功能，并将其集成到飞书/微信群中。详情请参见 BiliBili 和 YouTube！

Web 版本的 Android API 也支持其他设备。详情请参阅 Python 示例代码。

• [2025/03] 简化部署并移除 --standalone
• [2025/03] 转发多条微信群消息
• [2024/09] 倒排索引 让 LLM 更倾向于使用知识库🎯
• [2024/09] 代码检索
• [2024/08] chat_with_readthedocs，详情请参阅 如何集成 👍
• [2024/07] 图像与文本检索及移除 langchain 👍
• [2024/07] 混合知识图谱与密集检索，将 F1 分数提升了 1.7% 🎯
• [2024/06] 评估 chunksize、分词器和 text2vec 模型 🎯
• [2024/05] wkteam 微信接入，支持解析图片与 URL，并实现共指消解
• [2024/05] 针对 NLP 任务的 SFT LLM，F1 提升 29% 🎯

  🤗

  LoRA-Qwen1.5-14B

  LoRA-Qwen1.5-32B

  alpaca 数据

  arXiv

• [2024/04] RAG 注释 SFT Q&A 数据和示例
• [2024/04] 发布 Web 前后端服务源代码 👍
• [2024/03] 新增 个人微信集成 和 预编译 APK！
• [2024/02] [实验性功能] 微信群 集成多模态技术以实现 OCR

📖 支持状态

LLM	文件格式	检索方法	集成	预处理
DeepSeek InternLM GLM KIMI StepFun vLLM Silicon🏷️ PPIO🏷️ Xi-Api	excel html markdown pdf ppt txt word	针对文档的密集向量检索 针对代码的稀疏向量检索 知识图谱 互联网搜索 SourceGraph 图像与文本	微信（安卓/wkteam) Lark OpenXLab Web Gradio Demo HTTP 服务器 Read the Docs	指代消解

📦 硬件要求

以下是不同功能所需的显存要求，区别仅在于是否启用了相关选项。

配置示例	显存需求	描述	在 Linux 上验证过
config-cpu.ini	-	仅使用 siliconcloud API 处理文本
[标准版]config.ini	2GB	使用 OpenAI API（如 kimi、deepseek 和 stepfun）进行纯文本检索
config-multimodal.ini	10GB	使用 OpenAI API 进行 LLM、图像和文本检索

🔥 运行标准版

我们以标准版（本地运行 LLM，文本检索）为例进行介绍。其他版本只是配置选项有所不同。

I. 下载并安装依赖项

点击同意 BCE 模型协议，登录 Hugging Face：

huggingface-cli login

安装依赖项：

# 解析 `word` 格式所需软件
apt update
apt install python-dev libxml2-dev libxslt1-dev antiword unrtf poppler-utils pstotext tesseract-ocr flac ffmpeg lame libmad0 libsox-fmt-mp3 sox libjpeg-dev swig libpulse-dev
# Python 所需库
pip install -r requirements.txt
# 对于 Python 3.8，请安装 faiss-gpu 而不是 faiss

II. 创建知识库

我们使用一些小说来构建知识库，并筛选问题。如果你有自己的文档，只需将其放入 repodir 目录下即可。

复制并执行以下所有命令（包括 # 符号）：

# 下载知识库，这里仅以部分文档为例。你可以将任何自己的文档放入 `repodir` 目录中。
cd HuixiangDou
mkdir repodir
cp -rf resource/data* repodir/

# 构建知识库，这会将 `repodir` 中的内容特征保存到 `workdir`，并将正负样本阈值更新到 `config.ini` 文件中。
mkdir workdir
python3 -m huixiangdou.services.store

# 你也可以从 QA 对（CSV 或 JSON 格式）构建知识库。
# CSV：第一列是问题，第二列是答案。
# JSON：{"question1": "answer1", "question2": "answer2", ...}
# python3 -m huixiangdou.services.store --qa-pair resource/data/qa_pair.csv

III. 设置 LLM API 并测试

在 config.ini 文件中设置模型和 api-key。如果要在本地运行 LLM，建议使用 vllm。

vllm serve /path/to/Qwen-2.5-7B-Instruct --served-model-name vllm --enable-prefix-caching --served-model-name Qwen-2.5-7B-Instruct

以下是已配置的 config.ini 示例：

[llm.server]
remote_type = "kimi"
remote_api_key = "sk-dp3GriuhhLXnYo0KUuWbFUWWKOXXXXXXXXXX"
remote_llm_model = "auto"

# remote_type = "step"
# remote_api_key = "5CpPyYNPhQMkIzs5SYfcdbTHXq3a72H5XXXXXXXXXXXXX"
# remote_llm_model = "auto"

# remote_type = "deepseek"
# remote_api_key = "sk-86db9a205aa9422XXXXXXXXXXXXXX"
# remote_llm_model = "deepseek-chat"

# remote_type = "vllm"
# remote_api_key = "EMPTY"
# remote_llm_model = "Qwen2.5-7B-Instruct"

# remote_type = "siliconcloud"
# remote_api_key = "sk-xxxxxxxxxxxxx"
# remote_llm_model = "alibaba/Qwen1.5-110B-Chat"

# remote_type = "ppio"
# remote_api_key = "sk-xxxxxxxxxxxxx"
# remote_llm_model = "thudm/glm-4-9b-chat"

然后运行测试：

# 回答与百草园相关的问题（基于知识库），但不回答天气问题。
python3 -m huixiangdou.main

+-----------------------+---------+--------------------------------+-----------------+
|         Query         |  State  |         Reply                  |   References    |
+=======================+=========+================================+=================+
| 百草园里有什么？ | success | 百草园拥有丰富多样的自然景观和生物…… | installation.md |
--------------------------------------------------------------------------------------
| 今天天气怎么样？         | Init state| ..                           |                 |
+-----------------------+---------+--------------------------------+-----------------+
🔆 在这里输入你的问题，输入 `bye` 退出：
..

💡 同时也可以使用 gradio 运行一个简单的 Web UI：

python3 -m huixiangdou.gradio_ui

或者启动一个监听 23333 端口的服务器，默认管道为 chat_with_repo：

python3 -m huixiangdou.api_server

# 测试异步 API 
curl -X POST http://127.0.0.1:23333/huixiangdou_stream  -H "Content-Type: application/json" -d '{"text": "如何安装 mmpose","image": ""}'
# cURL 同步 API
curl -X POST http://127.0.0.1:23333/huixiangdou_inference  -H "Content-Type: application/json" -d '{"text": "如何安装 mmpose","image": ""}'

请更新 repodir 文档、good_questions 和 bad_questions，并尝试应用到你自己的领域知识中（如医疗、金融、电力等）。

IV. 集成

至飞书、微信群

• 单向 发送至飞书群
• 双向 飞书群收发消息、召回
• 个人微信 Android 接入 和 Android 工具
• 个人微信 wkteam 接入

至 Web 前后端

我们提供了 typescript 前端和 python 后端源代码：

• 支持多租户管理
• 无需编程即可接入飞书和微信
• 对 k8s 友好

与 OpenXlab APP 类似，请阅读 Web 部署文档。

至 readthedocs.io

尝试页面右下角按钮 和 文档。

🍴 其他配置

仅 CPU 版本

如果没有 GPU，可以使用 siliconcloud 的 API 完成模型推理。

以 docker miniconda+Python3.11 为例，安装 CPU 依赖并运行：

# 启动容器
docker run -v /path/to/huixiangdou:/huixiangdou -p 7860:7860 -p 23333:23333 -it continuumio/miniconda3 /bin/bash
# 安装依赖
apt update
apt install python-dev libxml2-dev libxslt1-dev antiword unrtf poppler-utils pstotext tesseract-ocr flac ffmpeg lame libmad0 libsox-fmt-mp3 sox libjpeg-dev swig libpulse-dev
python3 -m pip install -r requirements-cpu.txt
# 构建知识库
python3 -m huixiangdou.services.store --config_path config-cpu.ini
# 问答测试
python3 -m huixiangdou.main --config_path config-cpu.ini
# gradio UI
python3 -m huixiangdou.gradio_ui --config_path config-cpu.ini

如果觉得安装太慢，可以在 Docker Hub 上找到预装镜像，启动时直接替换即可。

10G 多模态版本

如果你有 10G 显存的 GPU，可以进一步支持图像和文本检索。只需修改 config.ini 中使用的模型。

# config-multimodal.ini
# !!! 下载 `https://huggingface.co/BAAI/bge-visualized/blob/main/Visualized_m3.pth`    到 `bge-m3` 文件夹 !!!
embedding_model_path = "BAAI/bge-m3"
reranker_model_path = "BAAI/bge-reranker-v2-minicpm-layerwise"

注意：

• 需要手动下载 Visualized_m3.pth 到 bge-m3 目录
• 安装主分支上的 FlagEmbedding，我们已经修复了 bugfix。这里可以下载 bpe_simple_vocab_16e6.txt.gz
• 安装 requirements/multimodal.txt

运行 gradio 测试，查看图像和文本检索结果 这里。

python3 tests/test_query_gradio.py

进一步说明

请阅读以下主题：

• 混合知识图谱与密集检索
• 参考 config-advanced.ini 配置以提升效果
• 群聊场景中的指代消解训练
• 使用 wkteam 微信接入，集成图片、公众号解析和指代消解
• 使用 rag.py 标注 SFT 训练数据

🛠️ 常见问题解答

1. 如果机器人过于冷淡/过于健谈怎么办？

   • 将实际场景中需要回答的问题填入 resource/good_questions.json，将应被拒绝的问题填入 resource/bad_questions.json。
   • 调整 repodir 中的主题内容，确保主库中的 markdown 文档不包含无关内容。

   重新运行 feature_store 更新阈值和特征库。

   ⚠️ 你也可以直接修改 config.ini 中的 reject_throttle。一般来说，0.5 是较高的值；0.2 则过低。

2. 启动正常，但在运行时出现内存不足？

   基于 transformer 结构的 LLM 长文本处理需要更多内存。此时需要对模型进行 kv 缓存量化，例如 lmdeploy 量化说明。然后使用 docker 独立部署 Hybrid LLM Service。

3. No module named 'faiss.swigfaiss_avx2'

   找到已安装的 faiss 包

   import faiss
   print(faiss.__file__)
   # /root/.conda/envs/InternLM2_Huixiangdou/lib/python3.10/site-packages/faiss/__init__.py
   

   添加软链接

   # cd your_python_path/site-packages/faiss
   cd /root/.conda/envs/InternLM2_Huixiangdou/lib/python3.10/site-packages/faiss/
   ln -s swigfaiss.py swigfaiss_avx2.py
   

🍀 致谢

• KIMI：长文本大模型，支持直接上传文件
• FlagEmbedding：BAAI RAG 团队
• BCEmbedding：中英双语特征模型
• Langchain-ChatChat：Langchain 与 ChatGLM 的应用
• GrabRedEnvelope：微信红包领取工具

📝 引用

@misc{kong2024huixiangdou,
      title={HuiXiangDou：基于 LLM 的技术辅助克服群聊场景},
      author={孔焕钧、张松阳、李佳颖、肖敏、徐俊、陈凯},
      year={2024},
      eprint={2401.08772},
      archivePrefix={arXiv},
      primaryClass={cs.CL}
}

@misc{kong2024labelingsupervisedfinetuningdata,
      title={利用规模定律标注监督微调数据}, 
      author={孔焕钧},
      year={2024},
      eprint={2405.02817},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2405.02817}, 
}

@misc{kong2025huixiangdou2robustlyoptimizedgraphrag,
      title={HuixiangDou2：一种鲁棒优化的 GraphRAG 方法}, 
      author={孔焕钧、王哲凡、王晨阳、马哲、董南青},
      year={2025},
      eprint={2503.06474},
      archivePrefix={arXiv},
      primaryClass={cs.IR},
      url={https://arxiv.org/abs/2503.06474}, 
}

HuixiangDou 快速上手指南

HuixiangDou 是一款基于大语言模型（LLM）的专业知识助手，专为群聊场景和实时流式对话设计。它无需训练，支持纯 CPU 或低显存 GPU 运行，提供完整的 Web、Android 及后端源码。

1. 环境准备

系统要求

• 操作系统：推荐 Linux (x86_64)
• 硬件配置：
  • 纯 CPU 版：无 GPU 要求，需调用云端 API（如 SiliconCloud）。
  • 标准版（文本检索）：仅需 2GB 显存（如 GTX 1660 Ti），或使用云端 API。
  • 多模态版（图文检索）：需 10GB+ 显存（如 RTX 3090）。
• Python 版本：推荐 Python 3.8+

前置依赖安装

在安装 Python 依赖前，需先安装系统级工具以支持文档解析（Word, PDF, OCR 等）：

# 更新源并安装系统依赖
apt update
apt install python-dev libxml2-dev libxslt1-dev antiword unrtf poppler-utils pstotext tesseract-ocr flac ffmpeg lame libmad0 libsox-fmt-mp3 sox libjpeg-dev swig libpulse-dev

# 安装 Python 依赖
pip install -r requirements.txt

# 注意：若使用 Python 3.8，请安装 faiss-gpu 替代 faiss
# pip install faiss-gpu

2. 安装与知识库构建

步骤一：获取模型与代码

首先同意 BCE Embedding 模型协议并登录 HuggingFace（国内用户若访问受限，可配置镜像或使用代理）：

huggingface-cli login

克隆项目代码并进入目录：

git clone https://github.com/InternLM/HuixiangDou.git
cd HuixiangDou

步骤二：创建知识库

将您的文档（支持 pdf, word, markdown, txt 等格式）放入 repodir 目录。以下示例使用项目自带的测试数据：

# 创建文档目录并复制示例数据
mkdir repodir
cp -rf resource/data* repodir/

# 创建工作目录并构建知识库
# 此步骤会提取特征并自动更新 config.ini 中的阈值
mkdir workdir
python3 -m huixiangdou.services.store

提示：您也可以直接使用问答对（CSV 或 JSON 格式）构建知识库： python3 -m huixiangdou.services.store --qa-pair resource/data/qa_pair.csv

3. 基本使用

步骤一：配置模型

编辑 config.ini 文件，配置 LLM 服务。您可以选择本地部署（推荐 vLLM）或云端 API（如 Kimi, DeepSeek, SiliconCloud 等）。

示例：使用云端 Kimi API

[llm.server]
remote_type = "kimi"
remote_api_key = "sk-your-actual-api-key-here"
remote_llm_model = "auto"

示例：使用本地 vLLM 部署 先在终端启动本地服务：

vllm serve /path/to/Qwen-2.5-7B-Instruct --served-model-name Qwen-2.5-7B-Instruct --enable-prefix-caching

然后在 config.ini 中配置：

[llm.server]
remote_type = "vllm"
remote_api_key = "EMPTY"
remote_llm_model = "Qwen-2.5-7B-Instruct"

步骤二：运行测试

启动主程序进行测试。系统将自动判断问题是否与知识库相关：若相关则回答，若不相关（如询问天气）则拒绝回答，避免群聊消息泛滥。

python3 -m huixiangdou.main

运行成功后，您将看到类似以下的交互输出，表明助手已准备好处理基于知识库的问答。

---

更多集成：

• Web 界面：参考 web 目录源码或体验 OpenXLab 在线版。
• 微信/飞书集成：参考 docs/zh/ 目录下的详细接入文档。
• API 服务：运行 python3 -m huixiangdou.api_server 开启 HTTP 服务供其他应用调用。