🎚️ 版本升级

HuixiangDou2(ACL25) 是在植物领域验证有效的 GraphRAG 方案，已经为Cell MP封面论文做出了贡献。如果你关注非计算机领域，试试新版。

---

English | 简体中文

HuixiangDou 是一个基于 LLM 的专业知识助手，优势：

1. 设计预处理、拒答、响应三阶段 pipeline：
   • chat_in_group 群聊场景，解答问题时不会消息泛滥。见 2401.08772，2405.02817，混合检索和业务数据精度测试
   • chat_with_repo 实时聊天场景，响应更快
2. 无需训练适用各行业，提供 CPU-only、2G、10G 规格配置
3. 提供一整套前后端 web、android、算法，工业级开源可商用

查看茴香豆已运行在哪些场景，当前公共服务状况：

• readthedocs ChatWithAI cpu-only 可用
• OpenXLab 使用 GPU，持续维护
• 微信群 有接入成本。所有代码已运行一年验证可用，请自行部署 免费 或 商业 版

如果对你有用，麻烦 star 一下⭐

🔆 新功能

Web 版已发布到 OpenXLab，可以创建自己的知识库、更新正反例、开关网络搜索，聊天测试效果后，集成到飞书/微信群。

Web 版视频教程见 BiliBili 和 YouTube。

Web 版给 android 的接口，也支持非 android 调用，见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，splitter 和 text2vec 模型 🎯
• [2024/05] wkteam 微信接入，整合图片&公众号解析、集成指代消歧
• [2024/05] SFT LLM 处理 NLP 任务，F1 提升 29% 🎯

  🤗

  LoRA-Qwen1.5-14B

  LoRA-Qwen1.5-32B

  alpaca 数据

  arXiv

• [2024/04] 实现 RAG 标注 SFT 问答数据和样例
• [2024/04] 发布 web 前后端服务源码 👍
• [2024/03] 新的个人微信集成方法和预编译 apk !
• [2024/02] [实验功能] 微信群 集成多模态以实现 OCR

📖 支持情况

LLM	文件格式	检索方法	接入方法	预处理
DeepSeek InternLM GLM KIMI-k2 StepFun vLLM Silicon🏷️ PPIO🏷️ Xi-Api	excel html markdown pdf ppt txt word	文档用稠密，代码用稀疏 知识图谱 联网搜索 SourceGraph 图文混合	微信（android/wkteam） 飞书 OpenXLab Web Gradio Demo HTTP Server 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，纯文本检索）为例，介绍 HuixiangDou 功能。其他版本仅仅是配置选项不同。我们推荐 Python3.10

一、下载模型，安装依赖

首先点击同意 BCE 模型协议，命令行登录 huggingface

huggingface-cli login

安装依赖

# parsing `word` format requirements
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 requirements
pip install -r requirements.txt
# python3.8 安装 faiss-gpu 而不是 faiss

二、创建知识库

我们将用《朝花夕拾》的文章构建知识库。如有自己的文档，放入 repodir 下即可。

复制下面所有命令（包含 '#' 符号）建立知识库。

# 下载知识库，我们仅以《朝花夕拾》两篇文章为例。repodir下可以放任何自己的文档
cd HuixiangDou
mkdir repodir
cp -rf resource/data* repodir/

# 建立知识库，repodir 的特征会保存到 workdir，拒答阈值也会自动更新进 `config.ini`
mkdir workdir
python3 -m huixiangdou.services.store

# 你也可以从问答对（QA pairs）构建知识库（支持 CSV 或 JSON 格式）
# CSV 格式：第一列为问题（key），第二列为答案（value）
# JSON 格式：{"问题1": "答案1", "问题2": "答案2", ...}
# python3 -m huixiangdou.services.store --qa-pair resource/data/qa_pair.csv

三、配置 LLM，运行测试

设置 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| ..                           |                 |
+-----------------------+---------+--------------------------------+-----------------+
🔆 Input your question here, type `bye` for exit:
..

💡 也可以启动 gradio 搭建一个简易的 Web UI，默认绑定 7860 端口：

python3 -m huixiangdou.gradio_ui

或者启动服务端，监听 23333 端口。默认使用 chat_with_repo pipeline：

python3 -m huixiangdou.api_server

# cURL 测试状态回调接口
curl -X POST http://127.0.0.1:23333/huixiangdou_stream  -H "Content-Type: application/json" -d '{"text": "how to install mmpose","image": ""}'
# cURL 测试同步接口
curl -X POST http://127.0.0.1:23333/huixiangdou_inference  -H "Content-Type: application/json" -d '{"text": "how to install mmpose","image": ""}'

请调整 repodir 文档、good_questions 和 bad_questions，尝试自己的领域知识（医疗，金融，电力等）。

四、集成

到飞书、微信群

• 单向发送到飞书群
• 双向飞书群收发、撤回
• 免费个微 android 接入 和 基于系统 API 的 android 工具 控制手机 UI（不只是微信）
• 商业个微 wkteam 接入

WEB 前后端部署，零编程集成飞书微信

我们提供了完整的 typescript 前端和 python 后端服务源码：

• 支持多租户管理
• 零编程接入飞书、微信群
• 架构松散，适合 k8s

效果同 OpenXlab APP ，请阅读 web 部署文档。

到 readthedocs.io

点这个页面的右下角按钮 and 部署文档

🍴 其他配置

纯 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

如果装依赖太慢，dockerhub 里提供了安装好依赖的镜像，docker 启动时替换即可。

10G 多模态版

如果你有 10G 显存，那么可以进一步支持图文检索。仅需修改 config.ini 使用的模型。

# config-multimodal.ini
# !!! Download `https://huggingface.co/BAAI/bge-visualized/blob/main/Visualized_m3.pth` to `bge-m3` folder !!!
embedding_model_path = "BAAI/bge-m3"
reranker_model_path = "BAAI/bge-reranker-v2-minicpm-layerwise"

需要注意：

• 先下载 bge-m3，然后把 Visualized_m3.pth 放进 bge-m3 目录
• FlagEmbedding 需要安装 master 最新版，我们做了 bugfix；这里可以下载 BGE 打包漏掉的 bpe_simple_vocab_16e6.txt.gz
• 安装 requirements/multimodal.txt

运行 gradio 测试，图文检索效果见这里.

python3 tests/test_query_gradio.py

更多

请阅读以下话题：

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

🛠️ FAQ

1. 对于通用问题（如 “番茄是什么” ），我希望 LLM 优先用领域知识（如 “普罗旺斯番茄”）怎么办？

   参照 PR，准备实体列表，构建特征库时传入列表，ParallelPipeline检索会基于倒排索引增大召回

2. 机器人太高冷/太嘴碎怎么办？

   • 把真实场景中，应该回答的问题填入resource/good_questions.json，应该拒绝的填入resource/bad_questions.json
   • 调整 repodir 中的文档，确保不包含场景无关内容

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

   ⚠️ 如果你足够自信，也可以直接修改 config.ini 的 reject_throttle 数值，一般来说 0.5 是很高的值；0.2 过低。

🍀 致谢

• KIMI: 长文本 LLM，支持直接上传文件
• FlagEmbedding: BAAI RAG 组
• BCEmbedding: 中英双语特征模型
• Langchain-ChatChat: Langchain 和 ChatGLM 的应用
• GrabRedEnvelope: 微信抢红包

📝 引用

@misc{kong2024huixiangdou,
      title={HuiXiangDou: Overcoming Group Chat Scenarios with LLM-based Technical Assistance},
      author={Huanjun Kong and Songyang Zhang and Jiaying Li and Min Xiao and Jun Xu and Kai Chen},
      year={2024},
      eprint={2401.08772},
      archivePrefix={arXiv},
      primaryClass={cs.CL}
}

@misc{kong2024labelingsupervisedfinetuningdata,
      title={Labeling supervised fine-tuning data with the scaling law}, 
      author={Huanjun Kong},
      year={2024},
      eprint={2405.02817},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2405.02817}, 
}

@misc{kong2025huixiangdou2robustlyoptimizedgraphrag,
      title={HuixiangDou2: A Robustly Optimized GraphRAG Approach}, 
      author={Huanjun Kong and Zhefan Wang and Chenyang Wang and Zhe Ma and Nanqing Dong},
      year={2025},
      eprint={2503.06474},
      archivePrefix={arXiv},
      primaryClass={cs.IR},
      url={https://arxiv.org/abs/2503.06474}, 
}