QAnything 腾讯云部署指南：国产知识库问答实战

QAnything 腾讯云部署完整指南

QAnything 是网易有道开源的企业级本地知识库问答系统。它在中文场景有个别人不好抄的优势：自研的 BCEmbedding——中英双语、跨语言检索的准确率是官方主打的卖点，再配合 BM25 + 向量的混合检索，召回率比纯向量方案高一档。

另外一个关键特性：支持全离线私有化部署，数据和推理全在本地，适合对数据出境有要求的企业。

代价是门槛不低。这篇先把门槛讲清楚，再带你一步步部署。

第一步：认清硬件门槛

官方文档标注的 Linux 环境要求：

机型对照

如果你现在只有 CPU 机器且内存不到 20GB，直接改用 MaxKB 腾讯云部署教程，别硬撑。

前往 腾讯云轻量应用服务器 选购页选大内存机型；需要 GPU 就在 腾讯云 GPU 机型页面 查看库存。

第二步：环境准备

2.1 安装 git-lfs（必做）

1sudo apt-get update
2sudo apt-get install -y git-lfs
3git lfs install

验证：

1git lfs version

2.2 安装 Docker

1sudo apt-get install -y ca-certificates curl gnupg lsb-release
2
3sudo install -m 0755 -d /etc/apt/keyrings
4curl -fsSL https://mirrors.cloud.tencent.com/docker-ce/linux/ubuntu/gpg \
5  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
6sudo chmod a+r /etc/apt/keyrings/docker.gpg
7
8echo \
9  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
10  https://mirrors.cloud.tencent.com/docker-ce/linux/ubuntu \
11  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
12
13sudo apt-get update
14sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
15
16sudo usermod -aG docker $USER
17newgrp docker

核对版本：

1docker --version          # 需 >= 20.10.5
2docker compose version    # 需 >= v2.23.3

2.3 配置镜像加速

腾讯云控制台「容器镜像服务 → 镜像加速器」里有专属地址，形如 https://xxxxxx.mirror.swr.myqcloud.com：

1sudo mkdir -p /etc/docker
2sudo tee /etc/docker/daemon.json <<'EOF'
3{
4  "registry-mirrors": [
5    "https://你的专属地址.mirror.swr.myqcloud.com"
6  ]
7}
8EOF
9sudo systemctl daemon-reload
10sudo systemctl restart docker

2.4 检查资源

1free -h     # 确认内存 >= 20GB
2df -h /     # 预留 >= 80GB（镜像 + 模型权重）
3nvidia-smi  # GPU 方案确认显卡可见

第三步：部署 QAnything

3.1 克隆仓库

1cd /opt
2git clone https://github.com/netease-youdao/QAnything.git
3cd QAnything

3.2 启动服务

Linux 用对应的 compose 文件：

1docker compose -f docker-compose-linux.yaml up -d

首次启动要拉多个镜像（含 milvus、mysql、minio、etcd 与业务服务），需要十几分钟，取决于带宽。

想看实时日志就用前台方式（调试时推荐）：

1docker compose -f docker-compose-linux.yaml up

3.3 确认启动完成

看到这条日志才算就绪：

查看日志：

1# 后台方式看日志
2docker compose -f docker-compose-linux.yaml logs -f
3
4# 或看项目日志文件
5tail -f logs/debug_logs/sanic_api.log

3.4 访问

浏览器打开：

注意路径末尾的 /qanything/ 不能少，直接访问 :8777 或 :8777/qanything 会打不开。

API 地址与前端相同：

3.5 关闭服务

1docker compose -f docker-compose-linux.yaml down

第四步：接入模型

4.1 用云端 API（最快）

在界面里配置对应厂商的 API Key 即可。适合先跑通流程。

4.2 接本地 Ollama（全离线关键一步）

如果你已经按 GLM 腾讯云部署教程 或 InternLM 腾讯云部署教程 在服务器上跑起了 Ollama，可以把它接进来，实现数据完全不出网。

核心思路：Ollama 提供 OpenAI 兼容接口，把它当成一个自定义的 OpenAI 服务填进配置。

1# 确认 Ollama 可访问
2curl http://127.0.0.1:11434/v1/models

4.3 关于 embedding 与 rerank

QAnything 自带 BCEmbedding（有道自研的 embedding + rerank），这是它中文检索效果好的根本原因。默认会随服务一起加载本地模型，通常不需要你额外配置。

如果你想单独使用 BCEmbedding（不含问答系统），官方也提供了独立的使用方式。

4.4 模型权重下载失败怎么办

自动下载失败时，手动从国内源拉：

• ModelScope：https://modelscope.cn/models/netease-youdao/QAnything
• 官方还列出了 wisemodel 等备用地址

1pip install modelscope
2python -c "
3from modelscope import snapshot_download
4snapshot_download('netease-youdao/QAnything', cache_dir='/data/qanything-models')
5"

下载完按项目要求的目录结构摆放，再重启服务。

第五步：构建知识库

5.1 新建知识库

界面里「新建知识库」，填名称与描述。支持的知识库类型按界面提示选择（通用问答 / FAQ 等）。

5.2 上传文档

支持的格式很全：doc、ppt、xls、pdf、docx、pptx、xlsx、txt、图片 等，其中对 docx / pptx / pdf 做了特别优化：

• 能解析出表格和图片
• 保留多级标题的层级结构

这个特性很重要——很多知识库工具把文档切成碎块，标题层级丢了，问答时上下文就断了。QAnything 会按层级标题 + 语义切分，保证每个切片是完整的语义单元。

5.3 混合检索怎么用起来

Docker 版默认支持 BM25 + embedding 混合检索（纯 Python 版不支持，这也是官方建议生产用 Docker 的原因）。

混合检索的价值：

• BM25 擅长精确关键词匹配（人名、型号、编号）
• embedding 擅长语义相近匹配（同义表述）

两者结合，召回率明显高于纯向量方案。中文场景尤其明显。

如果发现检索不准，优先检查：

1. 文档是否解析成功（看上传进度与状态）
2. 提问词是否过于口语化或与文档用词差异大
3. 是否被切分打断（看召回片段）

5.4 验收：问一个只有文档才知道的问题

别一上传完就上线。问一个文档里明确写了、但通用模型答不上来的问题，检查：

• 答案是否正确
• 是否给出了引用来源
• 引用片段是否真的来自你的文档

答案不带引用 = 检索没命中，必须回去排查，不要直接交付给用户。

第六步：API 对接

6.1 调用示例

1curl -X POST http://服务器IP:8777/qanything/ \
2  -H "Content-Type: application/json" \
3  -d '{
4    "question": "年假怎么申请",
5    "kb_id": "你的知识库ID"
6  }'

详细的接口字段以官方 API 文档为准（版本间会有变化）。

6.2 挂进内部工具

知识库建好之后，真正的价值在于被用起来。把它接到内部聊天工具里，比单独一个网址有用得多——员工不会主动打开新系统。

自建机器人的话可以参考 chatgpt-on-wechat + NoneBot 腾讯云部署教程。

第七步：运维

7.1 备份

QAnything 的数据分布在 MySQL（元数据）与 Milvus（向量）里，生产环境建议：

• 定期备份 MySQL
• 对数据卷做快照：docker volume ls 查看相关卷

7.2 更新

1cd /opt/QAnything
2git pull
3docker compose -f docker-compose-linux.yaml pull
4docker compose -f docker-compose-linux.yaml up -d

更新前先备份，跨版本可能涉及数据结构变更。

7.3 安全

• 用 Nginx 反代 + HTTPS，别直接暴露 8777
• 只放行 22 / 80 / 443
• 如果你已按 1Panel 腾讯云部署教程 装了面板，直接用它的反代功能配 HTTPS，省事

18 条故障排查

落地建议

1. 内存先买够 20GB —— 在这上面省钱只会换来无限重启。
2. git-lfs 提前装 —— 漏了会导致权重全是空指针，是最隐蔽的坑。
3. 访问路径别漏 /qanything/ —— 包括末尾斜杠，少了就 404。
4. 用「只有文档知道答案」的问题验收 —— 通用问题测不出检索是否真的生效。
5. 知识库的价值在入口 —— 挂进群聊或内部工具，别指望员工主动打开一个新网址。