Langchain-Chatchat轻量级部署与配置指南

Langchain-Chatchat 轻量级部署与配置指南

在企业知识管理日益智能化的今天，如何快速构建一个安全、高效、支持中文的本地问答系统，成为许多团队关注的重点。Langchain-Chatchat 正是在这一背景下脱颖而出的开源项目——它不仅专为中文场景优化，还实现了文档解析、向量化检索和大模型推理的全流程本地化处理，真正做到了“数据不出内网”。

更关键的是，即便你只有一台 2核4G 的轻量云服务器，也能通过其--lite模式快速启动服务，无需复杂依赖即可体验完整的私有知识库问答能力。本文将带你从零开始，完成一次低门槛、高可用的部署实践，并深入剖析常见问题背后的原理与应对策略。

从克隆到运行：三步启动你的本地 AI 助手

部署的第一步永远是最直接的：获取代码并安装最小依赖。Langchain-Chatchat 提供了requirements_lite.txt，仅包含 WebUI、API 核心模块和基础工具链，避开了 Faiss、Milvus、PostgreSQL 等重型组件，非常适合资源有限的环境。

git clone https://github.com/chatchat-space/Langchain-Chatchat.git cd Langchain-Chatchat/ pip install -r requirements_lite.txt

如果你使用的是国内服务器或网络较慢，强烈建议加上清华源加速安装：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements_lite.txt

接下来是配置文件初始化。项目中所有.py.example文件都是模板，需要重命名为实际配置文件：

mv basic_config.py.example basic_config.py mv kb_config.py.example kb_config.py mv model_config.py.example model_config.py mv prompt_config.py.example prompt_config.py mv server_config.py.example server_config.py

这些文件分工明确：
-kb_config.py控制文本如何切分（比如按中文句子分割），直接影响检索精度；
-model_config.py是核心，决定了用哪个 LLM 和 Embedding 模型；
-server_config.py则关乎并发性能，多用户访问时可调整 worker 数量。

如何选择模型？在线 API 还是本地加载？

这是部署前必须权衡的问题。如果你追求极致轻量且能接受外部调用，推荐使用 OpenAI 兼容接口；若强调完全私有化，则应考虑本地部署量化模型如 ChatGLM3-6B-int4。

以调用 GPT-3.5 Turbo 为例，在model_config.py中配置如下：

"openai-api": { "model_name": "gpt-3.5-turbo", "api_base_url": "https://api.chatanywhere.tech/v1", "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "openai_proxy": "", }

这里使用的 ChatAnywhere 是一个广受好评的免费代理服务，延迟低、稳定性好，适合测试阶段使用。当然，也可以同时启用多个模型提供 fallback 能力：

"zhipu-api": { "api_key": "your_zhipu_api_key", "model_name": "glm-4", "temperature": 0.7, }

获取智谱 AI 的 API Key 很简单：注册账号 → 开发者中心 → 创建应用 → 获取密钥。注意不要把 key 提交到 Git，可以用环境变量注入：

export ZHIPU_API_KEY="your_real_key"

然后在代码中读取：

import os os.getenv("ZHIPU_API_KEY")

这种做法既安全又便于运维。

启动服务：一条命令跑通全链路

准备好之后，执行以下命令启动整个系统：

python startup.py -a --lite

参数说明：
--a表示自动启动所有子服务（API Server + WebUI）
---lite启用轻量模式，跳过非必要组件加载

首次运行可能会提示缺少某些 Streamlit 插件，根据报错补充安装即可：

pip install streamlit-aggrid streamlit_modal streamlit_chatbox sentence-transformers markdownify strsimpy

特别提醒：sentence-transformers是 BGE 嵌入模型的运行依赖，必须安装；而streamlit-aggrid支持表格渲染，否则知识库页面显示异常。

如果一切顺利，终端会输出类似以下信息：

==============================Langchain-Chatchat Configuration============================== 操作系统：Linux-5.15.0-92-generic-x86_64-with-glibc2.35 python版本：3.11.7 (main, Feb 27 2024, 00:07:27) [GCC 11.4.0] 项目版本：v0.2.10 langchain版本：0.0.354 | fastchat版本：0.2.36 当前使用的分词器：ChineseRecursiveTextSpliter 当前启动的LLM模型：['openai-api', 'zhipu-api'] @ cpu 当前Embeddings模型：bge-large-zh-v1.5 @ cpu 服务端运行信息： OpenAI API Server: http://127.0.0.1:20000/v1 Chatchat API Server: http://127.0.0.1:7861 Chatchat WEBUI Server: http://0.0.0.0:8501 ==============================Langchain-Chatchat Configuration==============================

此时打开浏览器访问http://<你的IP>:8501即可进入 WebUI 界面。例如公网 IP 为47.98.123.45，则访问：

http://47.98.123.45:8501

确保防火墙或安全组已放行8501端口，否则无法外网访问。

实际使用流程：上传文档 → 检索问答

进入 WebUI 后，第一步是创建知识库：

1. 左侧导航栏点击「知识库管理」
2. 点击「新建知识库」，命名如company_policy
3. 分块策略建议选“按中文句子分割”，避免断句不完整
4. 上传支持格式：.txt,.pdf,.docx,.xlsx,.pptx

系统后台会自动完成：
- 文档解析 → 文本提取
- 分句处理 → 构建文本块
- 向量化编码 → 存入 Chroma 向量数据库（默认）

⚠️ 注意：首次上传大 PDF 可能耗时较长，尤其是超过 50MB 的文件容易引发内存溢出。建议提前拆分或压缩。

完成后切换到「对话页面」：
1. 选择目标知识库
2. 选择使用的 LLM（如openai-api）
3. 输入问题：“年假是怎么规定的？”

系统将：
- 在向量库中检索最相关的文本片段
- 把原始问题 + 上下文拼成 Prompt 发送给大模型
- 返回回答并标注来源文档与段落位置

✅ 示例输出：

根据《员工手册_v2.pdf》第5页内容，正式员工每年享有带薪年假10天，工作满五年后增加至15天……

这种方式既能保证答案准确性，又能追溯依据，非常适合制度查询、产品文档辅助等场景。

遇到问题怎么办？常见错误排查清单

端口被占用：Address already in use

很常见的情况是上次服务未彻底关闭，导致 8501、7861 等端口仍被占用。

解决方法：运行自带的清理脚本：

chmod +x shutdown_all.sh ./shutdown_all.sh

该脚本会终止监听关键端口的所有 Python 进程。若仍无效，手动查找并 kill：

lsof -i :8501 kill -9 <PID>

缺少模块：ModuleNotFoundError

尤其在新环境中，常出现以下缺失包：

pip install streamlit-aggrid sentence-transformers markdownify strsimpy cachetools websockets

其中strsimpy用于文本相似度计算，cachetools提升响应速度，都属于关键依赖。

建议一次性安装完整前端组件，避免反复调试：

pip install streamlit-aggrid streamlit_modal streamlit_chatbox streamlit-option-menu

WebUI 显示空白或卡顿

可能原因包括：
- 浏览器禁用了 JavaScript（极少见但存在）
- 手机热点访问公网 IP 被运营商封锁动态端口
- 安全组未开放8501端口

临时验证方式是在服务器本地运行 Streamlit 调试：

streamlit run --server.port=8501 --server.address=0.0.0.0 webui.py

这样可以直接看到是否有前端报错日志输出。

文档上传失败或乱码

典型原因有三类：
1.PDF 是扫描件无文本层→ 不支持 OCR，需先用 PaddleOCR 预处理
2.Word 编码异常→ 建议另存为 UTF-8 再上传
3.文件过大导致 OOM→ 修改kb_config.py中的CHUNK_SIZE = 256减小单块长度

此外，某些加密 PDF 或权限限制文档也无法正常读取，建议统一转换为标准格式后再导入。

性能调优建议：从小规模测试到生产级部署

💡 小技巧：对于长期运行的知识库系统，建议定期备份两个目录：
-data/knowledge_base/：原始文档存储
-data/vectordb/：向量索引数据

一旦丢失，重建成本极高。

进阶用户还可以使用 Docker Compose 编排服务，实现版本隔离与一键启停。官方虽暂未提供标准 compose 文件，但社区已有成熟实践可供参考。

安全性设计：为什么说它是真正的“私有化”方案？

Langchain-Chatchat 的最大优势在于对数据主权的尊重：

• 所有文档上传后直接在本地进行解析和向量化，不会上传任何第三方
• 向量数据库默认保存在data/vectordb/，完全可控
• 若使用本地 LLM（如 ChatGLM3-6B），全程无网络请求
• 即便调用在线 API，也可配置仅发送检索后的上下文片段，而非原始文档全文

企业部署时建议进一步加固：
- 使用 Nginx 反向代理 + HTTPS 加密通信
- 添加 Basic Auth 或未来支持的登录认证机制
- 关闭匿名上传权限，防止恶意注入

这使得它非常适合金融、医疗、政府等对数据敏感的行业。

写在最后：轻量不是妥协，而是起点

Langchain-Chatchat 并非只是一个玩具项目。它的模块化架构允许你从最简单的--lite模式起步，逐步演进到支持 GPU 加速、分布式检索、多租户管理的企业级系统。

更重要的是，它专注于中文语境下的真实需求：无论是复杂的 Word 表格解析，还是长文档的精准定位，都在持续优化中展现出强大的实用性。

哪怕你现在只有一台轻量 VPS，也可以用本文的方法快速搭建一个具备语义理解能力的内部助手。当你的第一份 PDF 成功被检索并返回准确答案时，你会发现——构建私有 AI 并没有想象中那么遥远。

技术的温度，往往就藏在这样一个个“原来真的能跑起来”的瞬间里。