Table of Contents
Shortcuts

🎚️ 版本升级

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

English | 简体中文

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

  1. 设计预处理、拒答、响应三阶段 pipeline：

  2. 无需训练适用各行业，提供 CPU-only、2G、10G 规格配置

  3. 提供一整套前后端 web、android、算法，工业级开源可商用

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

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

🔆 新功能

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

Web 版视频教程见 BiliBili 和 YouTube。

Web 版给 android 的接口，也支持非 android 调用，见python 样例代码。

📖 支持情况

LLM 文件格式 检索方法 接入方法 预处理

  • excel

  • html

  • markdown

  • pdf

  • ppt

  • txt

  • word

📦 硬件要求

以下是不同特性所需显存，区别仅在配置选项是否开启。

配置示例

显存需求

描述

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，尝试自己的领域知识（医疗，金融，电力等）。

四、集成

到飞书、微信群

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"

需要注意：

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

python3 tests/test_query_gradio.py

更多

请阅读以下话题：

🛠️ 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 过低。

🍀 致谢

📝 引用

@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}, 
}