构建本地化私有知识库：Langchain-Chatchat + Ollama 完整部署实践
在企业智能化转型的浪潮中，如何让内部沉淀的技术文档、产品手册和运营资料真正“活起来”，成为一线员工随手可查的智能助手？一个常见痛点是：通用大模型虽强，但无法掌握公司特有的业务语境；而将敏感数据上传至云端API又面临合规风险。
这时候，一套完全运行于本地、支持离线使用的私有知识库系统就显得尤为关键。本文基于Langchain-Chatchat v0.3.1与Ollama的深度集成，手把手带你搭建一个从文档解析到语义问答全流程闭环的本地AI问答平台。整个过程不依赖任何外部云服务，所有模型均在本地加载，确保数据零外泄。
我们选用qwen:7b作为对话生成模型，bge-large-zh-v1.5作为中文向量化引擎，二者均可通过 Ollama 一键拉取并高效运行。项目使用 Poetry 管理依赖，结构清晰，便于二次开发与维护。
准备工作：构建稳定的大模型运行基座
在动手之前，请确认你的机器已具备以下基础环境：
- Python 3.9（推荐使用 Conda/Miniconda 管理）
- Git 工具
- Ollama 服务
- 常用系统工具：wget、unzip、包管理器（yum/apt）
如果你尚未安装 Ollama，可通过官方脚本快速部署（适用于 Linux/macOS）：
curl -fsSL https://ollama.com/install.sh | sh安装完成后，启动服务并拉取所需模型：
ollama pull qwen:7b ollama pull bge-large-zh-v1.5验证是否正常运行：
ollama list你应该能看到类似输出：
NAME SIZE MODIFIED qwen:7b 4.7GB 2 hours ago bge-large-zh-v1.5 1.5GB 1 hour ago📌 提示：若你希望尝试其他中文友好的模型，如
llama3:8b或deepseek-coder:6.7b，也可提前下载。只要 Ollama 支持，Langchain-Chatchat 就能调用。
获取源码并切换版本
接下来克隆 Langchain-Chatchat 的官方仓库：
git clone https://github.com/chatchat-space/Langchain-Chatchat.git cd Langchain-Chatchat为保证稳定性，建议使用发布标签而非主干分支：
git checkout tags/v0.3.1 -b v0.3.1-release虽然也可以直接下载 release 包，但源码方式更利于后续定制开发，比如修改提示词模板、调整检索逻辑或接入自研模块。
创建独立虚拟环境
Python 项目的依赖冲突问题屡见不鲜，因此强烈建议创建专用虚拟环境隔离运行时：
conda create -n langchain-chat python=3.9 conda activate langchain-chat进入核心服务目录：
cd libs/chatchat-server安装依赖管理工具 Poetry：
pip install poetry为了让 Poetry 复用当前 conda 环境，避免额外生成.venv目录，执行以下配置：
poetry config virtualenvs.prefer-active-python true这样 Poetry 将直接绑定到当前解释器，既节省空间也方便统一管理。
安装项目依赖
在chatchat-server目录下运行：
poetry install --with lint,test -E xinference参数说明：
---with lint,test：同时安装代码检查与测试依赖，便于后期调试
--E xinference：启用 Xinference 扩展支持，保持兼容性（即使本次不用）
此外，还需手动安装文档解析组件：
pip install "unstructured[pdf]"该库支持 PDF、DOCX、PPTX 等多种格式的文本提取，是知识库构建的关键环节。
⚠️ 注意事项：部分 Linux 发行版缺少图形库依赖，可能导致导入失败。例如出现
ImportError: libGL.so.1: cannot open shared object file错误时，请根据系统类型补装：
# CentOS/RHEL sudo yum install mesa-libGL -y # Ubuntu/Debian sudo apt-get install libgl1-mesa-glx -y设置项目根路径环境变量
Langchain-Chatchat 在运行时需要$CHATCHAT_ROOT来定位配置文件和资源目录。务必设置正确，否则会报路径错误。
建议在当前会话中导出：
export CHATCHAT_ROOT=$(pwd)为防止终端重启后失效，可写入 shell 配置文件：
echo 'export CHATCHAT_ROOT='$CHATCHAT_ROOT >> ~/.bashrc source ~/.bashrc验证是否生效：
echo $CHATCHAT_ROOT输出应为当前所在路径，形如/home/xxx/Langchain-Chatchat/libs/chatchat-server。
初始化项目配置
使用内置 CLI 工具完成初始化，明确指定使用 Ollama 作为模型后端：
python chatchat/cli.py init -x ollama -l qwen:7b -e bge-large-zh-v1.5关键参数解读：
--x ollama：选择 Ollama 作为推理框架
--l qwen:7b：设定 LLM 模型
--e bge-large-zh-v1.5：设定 Embedding 模型
该命令会自动完成以下动作：
- 生成默认配置文件configs/model_config.json
- 创建知识库存储目录data/knowledge_base/
- 初始化向量数据库（默认 Chroma）
- 写入 Ollama API 地址http://localhost:11434
成功执行后，你会看到如下日志：
[INFO] Using model provider: ollama [INFO] LLM model set to: qwen:7b [INFO] Embedding model set to: bge-large-zh-v1.5 [INFO] Configuration initialized successfully.此时打开configs/model_config.json，可以进一步查看或微调连接参数，比如超时时间、重试次数等。
向量化知识库：让文档“可被理解”
配置完成后，下一步是对知识库进行向量化重建。这是实现语义检索的核心步骤。
执行命令：
python chatchat/cli.py kb --recreate-vs它将：
- 扫描data/knowledge_base下的所有文档
- 使用bge-large-zh-v1.5对文本分块编码为向量
- 存入本地 Chroma 数据库
首次运行耗时较长，具体取决于文档数量和大小。完成后即可支持基于语义的相似度查询。
🔍 实用技巧：
若仅需更新某个特定知识库（如
sample），可使用：
bash python chatchat/cli.py kb --update-in-db-name sample这样无需重建全部索引，提升迭代效率。
启动服务并访问前端
一切就绪后，启动后端服务：
nohup python chatchat/cli.py start -a > langchain.log 2>&1 &参数说明：
-start：启动 Web API 和任务队列
--a：启用所有模块（含前端界面）
-nohup+&：后台持久运行
- 日志重定向至langchain.log
服务启动后，默认开放两个端口：
- API 服务：http://0.0.0.0:7861
- Web 前端：http://0.0.0.0:8501
通过浏览器访问：
http://<your-ip>:8501你可以上传 TXT、PDF、Word 等格式文档，系统会自动完成：
1. 文档解析
2. 文本切片
3. 向量化存储
4. 支持自然语言提问
🌐 应用场景举例：
上传一份《公司产品说明书.pdf》，然后提问：“我们的主力产品有哪些核心功能？”
→ 系统将基于文档内容生成精准回答，而不是泛泛而谈的网络信息。
验证 Ollama 集成状态
服务启动后，可通过日志观察模型调用情况：
tail -f langchain.log正常情况下会出现以下记录：
[INFO] Connecting to Ollama at http://localhost:11434 [INFO] Loading embedding model: bge-large-zh-v1.5 ... [INFO] Sending text to embedding model... [INFO] Generating response with LLM: qwen:7b ...也可以手动测试 Ollama 接口连通性：
curl http://localhost:11434/api/generate -d '{ "model": "qwen:7b", "prompt":"你好，请介绍一下你自己" }'预期返回流式 JSON 响应，表明模型服务正常运行。
常见问题与优化建议
如何更换其他 LLM 模型？
只需修改初始化命令中的-l参数即可。例如改用llama3:8b：
python chatchat/cli.py init -x ollama -l llama3:8b -e bge-large-zh-v1.5前提是该模型已在本地存在：
ollama pull llama3:8b目前表现较好的中文友好模型包括：
-qwen:7b
-llama3:8b
-deepseek-coder:6.7b
-gemma:7b
可根据实际硬件条件和响应速度做权衡选择。
如何提升文档解析质量？
文档质量直接影响问答准确性。建议采取以下措施：
- 优先使用可复制文本的 PDF，避免扫描件；
- 若必须处理图像型 PDF，先用 OCR 工具预处理；
- 调整文本分割策略，在
configs/settings.py中修改：
text_splitter = { "separator": "\n\n", "chunk_size": 400, # 减小以提高精度 "chunk_overlap": 50 # 控制上下文连续性 }较小的chunk_size有助于提高检索准确率，但可能增加拼接开销，需根据场景平衡。
如何扩展支持更多文件类型？
当前unstructured支持的主要格式包括：
-.txt,.md
-.pdf
-.docx,.pptx,.xlsx
-.eml,.msg
若需支持.epub或.rtf，可安装完整包：
pip install "unstructured[all]"注意：全功能安装体积较大，建议按需启用。
如何安全升级项目代码？
当项目更新时，可通过 Git 拉取新版本：
cd Langchain-Chatchat git fetch origin git checkout origin/main # 或指定 tag重新安装依赖：
cd libs/chatchat-server poetry install原有配置文件和知识库数据位于data/与configs/，不会被覆盖。但仍建议在升级前备份重要数据，以防意外。
如何打包自定义代码用于部署？
若你在源码基础上做了二次开发（如新增接口、修改 UI 或集成内部系统），可通过 Poetry 构建发布包：
poetry build生成的.whl和.tar.gz文件位于dist/目录，可用于 CI/CD 流程或私有 PyPI 仓库，实现标准化交付。
这套基于 Langchain-Chatchat 与 Ollama 的本地化知识库方案，真正实现了“数据不出内网、模型自主可控”。无论是用于企业内部知识管理、技术支持自助化，还是打造专属 AI 助手，都能提供高安全性、低成本且易于落地的解决方案。
更重要的是，它的模块化设计为后续扩展留足了空间——你可以轻松替换模型、接入 RAG 流程、集成单点登录，甚至对接工单系统形成闭环。这种灵活性，正是开源生态赋予开发者的核心优势。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
