HuixiangDou

环境要求

• Debian/Ubuntu 等可使用 apt 的 Linux 环境
• Python 环境（README 提到 Python 3.8 需改用 faiss-gpu 而非 faiss）
• 已注册 HuggingFace 账号并同意 bce-embedding-base_v1 模型协议
• 一个可用的 LLM 服务：远程 API key（如 kimi）或本地 vllm 部署的模型

安装与启动步骤

1. 1登录 HuggingFace

   先点击 README 中的链接同意 BCE 模型的用户协议，再用命令行登录 HuggingFace 账号，否则后续无法下载嵌入模型。

   huggingface-cli login

   复制

2. 2安装系统依赖

   安装文档解析、OCR、音视频处理所需的系统库，需 root 或 sudo 权限，命令来自 README 的 Other Configurations 部分。

   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

   复制

3. 3安装 Python 依赖

   在项目根目录执行，安装 CPU 版依赖清单；README 中另有针对 Python 3.8 使用 faiss-gpu 的提示。

   python3 -m pip install -r requirements-cpu.txt

   复制

4. 4启动本地 LLM

   若选择本地运行大模型，README 推荐用 vllm 部署，把路径换成你实际的模型目录。用远程 API 时可跳过此步。

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

   复制

5. 5配置 config.ini

   在 config.ini 的 [llm.server] 段填写模型类型、API key 和模型名，这是连接 LLM 的关键配置。

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

   复制

关键配置

如何确认成功

README 未给出统一的启动验证命令；配置完 config.ini 并启动服务后，在群聊中 @ 机器人提问，能返回带文档引用的答案即表示正常。

常见问题

注意事项

• 本项目有三阶段流水线：预处理、拒答、回答，群聊场景对应 chat_in_group。
• README 节选中 Python 依赖安装命令未完整展示，实际安装请以官方文档 huixiangdou.readthedocs.io 为准。
• 官方已发布 HuixiangDou2（GraphRAG 方案），非计算机领域用户可优先尝试新版本。
• API key 等敏感信息不要提交到公开仓库。