ChatWiki 开源 AI 文档助手搭建教程：多格式文档接入，打造专属知识库机器人

一、搭建核心亮点

• 开源免费无限制：完全开源，无付费功能、无调用次数限制，可自由修改源码，适配个人/团队专属需求

• 多格式文档兼容：无缝接入 PDF、Word、Markdown、TXT、Excel 等主流格式，文档解析精准，无需手动转换格式

• 本地化部署：模型、文档、问答数据全量存储在本地，无云端上传，彻底保障数据隐私安全，适配隐私敏感场景

• 零门槛搭建：支持 Docker（新手首选）、Python 源码两种部署方式，命令可直接复制，10 分钟内完成搭建

• 知识库自定义：可创建多个专属知识库，支持文档批量上传、分类管理、检索优化，打造个性化 AI 文档助手

二、前置准备（必看，缺一不可，全系统适配）

2.1 硬件要求（最低配置，普通电脑均可达标）

• CPU：任意双核及以上（四核更流畅，不影响搭建，仅影响文档解析速度）

• 内存：≥4G（知识库越大，内存需求越高，4G 可满足日常个人使用）

• 存储空间：≥10G（预留源码、依赖、文档、知识库缓存空间，文档多时可扩容）

• 系统：Windows 10/11、MacOS、Linux（均适配，Docker 方式跨系统无差异）

2.2 软件/工具准备（直接下载/安装，无需额外配置）

• 核心部署工具（二选一，新手优先 Docker，进阶选 Python）：

  • Docker（新手首选，极简无门槛）：官网下载对应系统版本 →https://www.docker.com/（安装后启动 Docker 后台服务）

  • Python（进阶，自定义配置）：Python 3.8+ 版本 → https://www.python.org/（安装时勾选"Add Python to PATH"）

• 基础工具：

  • Git：用于克隆 ChatWiki 开源仓库 → https://git-scm.com/（安装时勾选"Add Git to PATH"）

  • 浏览器：任意浏览器（用于访问 ChatWiki 可视化界面）

• ChatWiki 源码/镜像：

  • GitHub 开源地址（优先）：https://github.com/zhimaAi/chatwiki.git（Docker/Python 部署均需用到）

  • 国内镜像地址（避免网络卡顿）：https://gitee.com/zhimaAi/chatwiki.git（GitHub 克隆失败时替换使用）

• 多格式文档解析依赖（Python 部署需提前知晓，后续一键安装）：自动适配 PDF/Word 解析，无需手动下载额外工具

三、两种搭建方式（纯实操，命令可直接复制，新手优先 Docker）

方式一：Docker 部署（新手首选，1 分钟启动，无需配置依赖）

1. 安装 Docker：双击下载的 Docker 安装包，下一步到底完成安装，安装后启动 Docker（桌面版启动后在后台运行，出现鲸鱼图标即正常）。

2. 验证 Docker 安装：打开终端（Windows：Win+R 输入 cmd；Mac/Linux：直接打开终端），输入以下命令，显示版本即安装成功： docker --version ``docker compose --version

3. 克隆 ChatWiki 仓库（复制命令，直接执行）： # 优先使用 GitHub 仓库 ``git clone https://github.com/zhimaAi/chatwiki.git `` ``# GitHub 克隆失败，替换为国内 Gitee 仓库 ``# git clone https://gitee.com/zhimaAi/chatwiki.git

4. 进入仓库目录，启动服务（核心步骤，直接复制命令）： # 进入 chatwiki/docker 目录 ``cd chatwiki/docker `` ``# 启动服务（自动拉取镜像、安装依赖，无需手动操作） ``docker compose up -d说明：启动过程约 3-5 分钟（取决于网络），终端无报错即正常，耐心等待即可。

5. 验证搭建成功：打开浏览器，输入 http://localhost:18080，出现登录界面即搭建成功，默认账号：admin，默认密码：chatwiki.com@123。

6. 停止/重启服务（按需操作）： # 停止服务 ``cd chatwiki/docker ``docker compose down `` ``# 重启服务 ``cd chatwiki/docker ``docker compose restart

方式二：Python 源码部署（进阶，可自定义配置，适配个性化需求）

1. 安装基础依赖（Git、Python 已安装可跳过，复制命令逐行执行）： # Windows 无需执行 sudo，直接去掉即可 ``# 1. 安装 Git（已安装可跳过） ``sudo apt update && sudo apt install git -y # Linux ``# brew install git # Mac（无 brew 先安装 brew） `` ``# 2. 验证 Python 安装（已安装可跳过） ``python --version # 或 python3 --version，显示 3.8+ 即可

2. 克隆 ChatWiki 仓库（同 Docker 方式，二选一）： git clone https://github.com/zhimaAi/chatwiki.git ``# 克隆失败替换为：git clone https://gitee.com/zhimaAi/chatwiki.git

3. 进入仓库目录，安装核心依赖（一键安装，包含多格式文档解析依赖）： # 进入仓库根目录 ``cd chatwiki `` ``# 安装 Python 依赖（Windows/Mac/Linux 通用） ``pip install -r requirements.txt # 或 pip3 install -r requirements.txt说明：若依赖安装失败，执行 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple（换清华源加速）。

4. 配置环境变量（简化配置，复制命令即可）： # 复制配置文件模板，生成配置文件（Windows/Mac/Linux 通用） ``cp .env.example .env无需修改配置文件，默认配置即可启动，进阶用户可打开 .env 文件，修改端口、数据库路径等（非必需）。

5. 启动 ChatWiki 服务（核心命令，直接复制）： # Windows ``python app.py `` ``# Mac/Linux ``python3 app.py说明：启动成功后，终端会显示"Running on http://0.0.0.0:18080"，无需关闭终端，关闭终端即停止服务。

6. 验证搭建成功：打开浏览器，输入 http://localhost:18080，使用默认账号密码（admin/chatwiki.com@123）登录即可。

四、核心实操：多格式文档接入 + 专属知识库打造（重点，纯干货）

4.1 多格式文档接入（支持 PDF/Word/Markdown/TXT/Excel，步骤通用）

1. 登录 ChatWiki 可视化界面（http://localhost:18080），输入默认账号密码登录。

2. 新建知识库（打造专属知识库）：

   1. 点击左侧「知识库管理」→「新建知识库」，输入知识库名称（如"个人技术文档库"），选择存储路径（默认即可），点击「创建」。

3. 上传文档（多格式兼容，批量/单个均可）：

   1. 进入新建的知识库，点击「上传文档」，选择本地文档（可多选，支持 PDF、Word、Markdown、TXT、Excel），点击「开始上传」。

   2. 文档解析：上传后自动解析，解析时间取决于文档大小，解析完成后显示"解析成功"，文档内容自动存入知识库（无需手动处理）。

4. 文档管理（分类/删除/重新解析）： # 无需命令，可视化操作即可： ``1. 分类：选中文档，点击「分类」，添加标签（如"Python""PDF文档"），便于检索； ``2. 删除：选中文档，点击「删除」，即可从知识库中移除； ``3. 重新解析：若文档解析失败，点击「重新解析」，确保文档未加密、未损坏即可。

4.2 专属知识库机器人使用（问答/检索，贴合文档内容）

1. 进入 ChatWiki 首页，选择左侧「知识库问答」，选中需要查询的知识库（如"个人技术文档库"）。

2. 输入问题（如"PDF 中的 Python 基础语法有哪些？""Word 文档中的接口参数说明"），点击「提问」，AI 会基于知识库中的文档内容精准回复，同时标注回复来源（哪个文档、哪个页码）。

3. 进阶操作（优化问答精度）：

   1. 点击「检索优化」，调整检索阈值（0.5-0.8 最佳），阈值越高，回复越精准；

   2. 批量导入文档：点击「批量上传」，一次性导入多个文档，适合快速搭建大型知识库；

   3. 多知识库切换：可创建多个知识库（如"工作文档库""学习文档库"），问答时自由切换，互不干扰。

五、常见问题排查（必看，避坑核心，纯实操解决方案）

1. 问题 1：Docker 启动失败，提示"docker compose: command not found" 解决方案：① 确认 Docker 安装完整（桌面版包含 docker compose）；② 重新安装 Docker，勾选"Install Docker Compose"；③ Linux/Mac 执行 sudo apt install docker-compose -y（Linux）、brew install docker-compose（Mac）。

2. 问题 2：浏览器无法访问 http://localhost:18080，提示"无法连接" 解决方案：① 确认 Docker/Python 服务已启动（Docker 执行 docker compose ps 查看，Python 终端未关闭且无报错）；② 检查端口 18080 是否被占用，替换端口（修改 .env 文件中的 PORT 字段，如改为 7860，重启服务）；③ 关闭电脑防火墙，重新启动服务。

3. 问题 3：文档上传失败/解析失败（提示"加密文档/格式不支持"） 解决方案：① 确保文档未加密、未损坏（加密 PDF/Word 需先解密）；② 确保文档格式为支持的类型（PDF/Word/Markdown/TXT/Excel）；③ Python 部署需重新安装依赖（pip install -r requirements.txt -i 清华源）；④ 大文件（＞100M）拆分后上传。

4. 问题 4：问答时无响应/回复无关内容 解决方案：① 确认文档已解析成功（进入知识库查看文档状态）；② 调整检索阈值（0.5-0.8）；③ 重新上传文档，确保文档内容清晰；④ 检查知识库是否选中（问答时需选中对应知识库）。

5. 问题 5：Python 部署提示"ModuleNotFoundError: No module named 'xxx'" 解决方案：① 执行 pip install xxx（xxx 为缺失的模块名）；② 重新执行 pip install -r requirements.txt -i 清华源，确保依赖全部安装成功。

6. 问题 6：登录失败，提示"账号密码错误" 解决方案：确认默认账号密码正确（账号：admin，密码：chatwiki.com@123）；若修改过密码，可删除 Docker 容器/重新部署，恢复默认账号密码。

六、核心优化建议（提升使用体验，专属知识库优化）

• 文档优化：上传前压缩大文档（拆分＞100M 文件），加密文档提前解密，避免解析失败；Markdown 文档优先使用，解析速度最快。

• 性能优化：① Docker 部署：定期清理容器缓存（docker system prune -a）；② Python 部署：关闭无关后台软件，增加内存占用（4G 内存建议单次解析不超过 5 个大文档）；③ 知识库优化：定期删除无用文档，减少缓存占用。

• 安全优化：登录后修改默认账号密码（左侧「个人中心」→「修改密码」），避免他人访问；本地化部署无需担心数据泄露，可定期备份知识库（复制 chatwiki/data 目录，Docker 部署备份 docker 挂载目录）。

• 个性化优化：修改 .env 文件，自定义端口、知识库存储路径、问答超时时间；进阶用户可修改源码，自定义 AI 回复风格、添加权限管理（如多用户访问）。

七、总结

本文全程聚焦「ChatWiki 开源部署、多格式文档接入、专属知识库打造」核心，两种部署方式（新手 Docker、进阶 Python）均可直接复制命令实操。ChatWiki 作为轻量化开源 AI 文档助手，完美适配 PDF/Word 等多格式文档，本地化部署保障数据安全，无需高端硬件，10 分钟内即可搭建专属知识库机器人，适配个人学习、团队协作、隐私敏感场景，跟着步骤操作，无需技术基础也能轻松上手，真正实现"文档一键导入、AI 精准问答"的高效体验。