[opensourcedex]

HuixiangDou is a free, open source ai interaction & interfaces project written in Python and released under BSD-3-Clause. It has 2,499 GitHub stars, 181 forks and 37 open issues, and was last pushed 11 months ago. On this registry it ranks #97 of 156 tracked projects in AI Interaction & Interfaces, with 5 head-to-head comparisons available.

What is HuixiangDou?

HuixiangDou is a Python, BSD-3-Clause licensed LLM-based professional knowledge assistant that answers technical questions inside group chats such as WeChat and Feishu/Lark without flooding the channel with messages, and it is built for teams that maintain an internal or public-facing support knowledge base.

What it is

HuixiangDou is a professional knowledge assistant built on LLMs, distributed as the InternLM/HuixiangDou repository under the BSD-3-Clause licence. It has 2501 stars, 179 forks and 37 open issues, and the last push was on 2025-11-24. The project lives in the Python RAG and LLM pipeline ecosystem and carries the topics rag, pipeline, multimodal, image-retrieval, group-chat, chatbot, lark and wechat. Backend model support covers DeepSeek, InternLM, GLM, KIMI and StepFun, and the codebase ships a web front end and back end, an Android client and pipeline source code.

The concrete problem it solves is message flooding in group chats. A general chatbot answers everything it is asked; HuixiangDou instead runs a three-stage pipeline of preprocess, rejection and response, where the rejection stage decides whether a question should be answered at all before any reply is produced. The behaviour is documented in the papers 2401.08772 and 2405.02817, along with a Hybrid Retrieval document and a precision report under evaluation/. It also removed its langchain dependency in July 2024 and replaced it with its own pipeline.

Key capabilities

  • chat_in_group handles the group chat scenario through the preprocess, rejection and response stages, answering user questions without message flooding.
  • chat_with_repo provides real-time streaming chat.
  • Hybrid knowledge graph combined with dense retrieval improves the F1 score by 1.7%, per docs/en/doc_knowledge_graph.md.
  • An inverted indexer, added in pull request 387, makes the LLM prefer the knowledge base, and code retrieval lives in huixiangdou/services/parallel_pipeline.py.
  • Image and text retrieval are supported, including multimodal OCR in WeChat groups, plus image and URL parsing with coreference resolution through wkteam WeChat access.
  • No training is required, and the project runs on CPU-only machines with 2G and 10G configurations.
  • The repository offers Web, Android and pipeline source code, with a prebuilt Android package at huixiangdou-20240508.apk.

Who uses it and how

  • Group chat operators on WeChat and Feishu/Lark use it as an in-channel support assistant; the March 2025 work added forwarding of messages from multiple WeChat group messages.
  • The readthedocs ChatWithAI service runs CPU-only as a public deployment, while the OpenXLab web application uses a GPU and is under continuous maintenance.
  • Teams that need another client shape use the web version API for Android, with sample code in tests/test_openxlab_android_api.py.
  • Groups tuning retrieval quality fine-tune models on their own data: supervised fine-tuning produced LoRA-Qwen1.5-14B and LoRA-Qwen1.5-32B and raised F1 by 29%, and RAG annotation SFT question-and-answer data is provided.
  • Small teams deploy on a single CPU-only machine at the 2G configuration, since no training step is needed.

Getting started

The quickest path is the hosted web version on OpenXLab, where a knowledge base can be created, positive and negative examples updated, web search turned on, chat tested and the assistant integrated into Feishu or WeChat groups. To self-host, take the pipeline source from InternLM/HuixiangDou; the March 2025 change simplified deployment by removing the --standalone flag, and a prebuilt Android client is published in the releases.

How it compares

The supplied facts name no paid products that this project replaces, and they name no directly comparable open-source assistant either. On the available record, HuixiangDou stands alone in this registry as an LLM knowledge assistant aimed specifically at group chat traffic control.

When to use it — and when not to

Self-hosting means running the pipeline yourself, and the README notes that WeChat integration carries a cost, with separate free and commercial access paths documented. The documentation set is Chinese-first, with README_zh.md as the primary file and English companions alongside it, so an English-only team will need to read across both. If the intended work sits outside computer science, the upstream project points to HuixiangDou2, a GraphRAG solution demonstrated in the plant-science domain, rather than this release.

project readme (upstream, from github) — read inline

🎚️ Upgrade

HuixiangDou2(ACL25) is a GraphRAG solution whose effectiveness has been demonstrated in the plant-science domain and that contributed to the cover paper in Cell Molecular Plant. If you work outside computer science, give the new release a try.

English | 简体中文

Wechat Readthedocs YouTube BiliBili discord Arxiv Arxiv

HuixiangDou1 is a professional knowledge assistant based on LLM.

Advantages:

  1. Design three-stage pipelines of preprocess, rejection and response
  2. No training required, with CPU-only, 2G, 10G configuration
  3. Offers a complete suite of Web, Android, and pipeline source code, industrial-grade and commercially viable

Check out the scenes in which HuixiangDou are running and current public service status:

  • readthedocs ChatWithAI (cpu-only) is available
  • OpenXLab is using GPU and under continuous maintenance
  • WeChat bot has a cost associated with WeChat integration. All code has been verified to be functional for one year. Please deploy it on your own for either the free or commercial version.

If this helps you, please give it a star ⭐

🔆 New Features

Our Web version has been released to OpenXLab, where you can create knowledge base, update positive and negative examples, turn on web search, test chat, and integrate into Feishu/WeChat groups. See BiliBili and YouTube !

The Web version's API for Android also supports other devices. See Python sample code.

🤗 LoRA-Qwen1.5-14B LoRA-Qwen1.5-32B alpaca data arXiv
- \[2024/04\] [RAG Annotation SFT Q&A Data and Examples](./docs/zh/doc_rag_annotate_sft_data.md) - \[2024/04\] Release [Web Front and Back End Service Source Code](./web) 👍 - \[2024/03\] New [Personal WeChat Integration](./docs/zh/doc_add_wechat_accessibility.md) and [**Prebuilt APK**](https://github.com/InternLM/HuixiangDou/releases/download/v0.1.0rc1/huixiangdou-20240508.apk) ! - \[2024/02\] \[Experimental Feature\] [WeChat Group](https://cdn.vansin.top/internlm/dou.jpg) Integration of multimodal to achieve OCR

📖 Support Status

LLM File Format Retrieval Method Integration Preprocessing
  • excel
  • html
  • markdown
  • pdf
  • ppt
  • txt
  • word

📦 Hardware Requirements

The following are the GPU memory requirements for different features, the difference lies only in whether the options are turned on.

Configuration Example GPU mem Requirements Description Verified on Linux
config-cpu.ini - Use siliconcloud API
for text only
[Standard Edition]config.ini 2GB Use openai API (such as kimi, deepseek and stepfun to search for text only
config-multimodal.ini 10GB Use openai API for LLM, image and text retrieval

🔥 Running the Standard Edition

We take the standard edition (local running LLM, text retrieval) as an introduction example. Other versions are just different in configuration options.

I. Download and install dependencies

Click to agree to the BCE model agreement, log in huggingface

huggingface-cli login

Install dependencies

# 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
# For python3.8, install faiss-gpu instead of faiss

II. Create knowledge base

We use some novels to build knowledge base and filtering questions. If you have your own documents, just put them under repodir.

Copy and execute all the following commands (including the '#' symbol).

# Download the knowledge base, we only take the some documents as example. You can put any of your own documents under `repodir`
cd HuixiangDou
mkdir repodir
cp -rf resource/data* repodir/

# Build knowledge base, this will save the features of repodir to workdir, and update the positive and negative example thresholds into `config.ini`
mkdir workdir
python3 -m huixiangdou.services.store

# You can also build knowledge base from QA pairs (CSV or JSON format)
# CSV: First column is key (question), second column is value (answer)
# JSON: {"question1": "answer1", "question2": "answer2", ...}
# python3 -m huixiangdou.services.store --qa-pair resource/data/qa_pair.csv

III. Setup LLM API and test

Set the model and api-key in config.ini. If running LLM locally, we recommend using 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

Here is an example of the configured 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"

Then run the test:

# Respond to questions related to the Hundred-Plant Garden (related to the knowledge base), but do not respond to weather questions.
python3 -m huixiangdou.main

+-----------------------+---------+--------------------------------+-----------------+
|         Query         |  State  |         Reply                  |   References    |
+=======================+=========+================================+=================+
| What is in the Hundred-Plant Garden? | success | The Hundred-Plant Garden has a rich variety of natural landscapes and life... | installation.md |
--------------------------------------------------------------------------------------
| How is the weather today?         | Init state| ..                           |                 |
+-----------------------+---------+--------------------------------+-----------------+
🔆 Input your question here, type `bye` for exit:
..

💡 Also run a simple Web UI with gradio:

python3 -m huixiangdou.gradio_ui

Or run a server to listen 23333, default pipeline is chat_with_repo:

python3 -m huixiangdou.api_server

# test async API 
curl -X POST http://127.0.0.1:23333/huixiangdou_stream  -H "Content-Type: application/json" -d '{"text": "how to install mmpose","image": ""}'
# cURL sync API
curl -X POST http://127.0.0.1:23333/huixiangdou_inference  -H "Content-Type: application/json" -d '{"text": "how to install mmpose","image": ""}'

Please update the repodir documents, good_questions and bad_questions, and try your own domain knowledge (medical, financial, power, etc.).

IV. Integration

To Feishu, WeChat group

To web front and backend

We provide typescript front-end and python back-end source code:

  • Multi-tenant management supported
  • Zero programming access to Feishu and WeChat
  • k8s friendly

Same as OpenXlab APP, please read the web deployment document.

To readthedocs.io

Try right-bottom button on the page and document.

🍴 Other Configurations

CPU-only Edition

If there is no GPU available, model inference can be completed using the siliconcloud API.

Taking docker miniconda+Python3.11 as an example, install CPU dependencies and run:

# Start container
docker run -v /path/to/huixiangdou:/huixiangdou -p 7860:7860 -p 23333:23333 -it continuumio/miniconda3 /bin/bash
# Install dependencies
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
# Establish knowledge base
python3 -m huixiangdou.services.store --config_path config-cpu.ini
# Q&A test
python3 -m huixiangdou.main --config_path config-cpu.ini
# gradio UI
python3 -m huixiangdou.gradio_ui --config_path config-cpu.ini

If you find the installation too slow, a pre-installed image is provided in Docker Hub. Simply replace it when starting the docker.

10G Multimodal Edition

If you have 10G GPU mem, you can further support image and text retrieval. Just modify the model used in 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"

Note:

Run gradio to test, see the image and text retrieval result here.

python3 tests/test_query_gradio.py

Furthermore

Please read the following topics:

🛠️ FAQ

  1. What if the robot is too cold/too chatty?

    • Fill in the questions that should be answered in the real scenario into resource/good_questions.json, and fill the ones that should be rejected into resource/bad_questions.json.
    • Adjust the theme content in repodir to ensure that the markdown documents in the main library do not contain irrelevant content.

    Re-run feature_store to update thresholds and feature libraries.

    ⚠️ You can directly modify reject_throttle in config.ini. Generally speaking, 0.5 is a high value; 0.2 is too low.

  2. Launch is normal, but out of memory during runtime?

    LLM long text based on transformers structure requires more memory. At this time, kv cache quantization needs to be done on the model, such as lmdeploy quantization description. Then use docker to independently deploy Hybrid LLM Service.

  3. No module named 'faiss.swigfaiss_avx2'

    locate installed faiss package

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

    add soft link

    # 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

🍀 Acknowledgements

📝 Citation

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

Frequently asked questions

Is HuixiangDou free to use?

HuixiangDou is open source under the BSD-3-Clause licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does HuixiangDou do?

HuixiangDou: Overcoming Group Chat Scenarios with LLM-based Technical Assistance

What is HuixiangDou written in?

HuixiangDou is primarily written in Python. Its source is publicly available at https://github.com/InternLM/HuixiangDou, and it has 2,499 GitHub stars.