LangChain-Chatchat私有化部署实践指南

LangChain-Chatchat 私有化部署实战：从零搭建企业级本地知识库系统

在企业智能化转型的浪潮中，越来越多团队开始尝试引入大模型技术来提升内部协作效率。然而，一个现实的问题摆在面前：如何在享受AI强大能力的同时，确保敏感数据不离开内网？公有云API虽然便捷，但面对员工手册、项目文档、客户资料这类机密信息时，安全边界成了不可逾越的红线。

正是在这种背景下，LangChain-Chatchat走进了我的视野。它不像某些“黑盒”平台那样封闭，而是一个真正意义上的开源解决方案——代码透明、流程可控、支持完全本地化运行。更重要的是，它的架构设计非常贴近实际业务场景：文档解析、向量化存储、语义检索、答案生成，整套 RAG（检索增强生成）链条一气呵成，且对中文支持极为友好。

经过几轮选型对比，我最终决定基于 LangChain-Chatchat 搭建一套私有化的智能问答系统。本文将完整还原整个部署过程中的关键步骤与踩坑经验，希望能为正在寻找类似方案的技术同行提供一份可复用的实践参考。

环境准备：打好地基才能跑得更稳

任何成功的部署都离不开扎实的基础环境。以下是我在物理服务器上配置的核心参数：

• 操作系统：Ubuntu 22.04 LTS
• Python 版本：3.10（推荐使用 conda 或 venv 创建独立环境）
• 硬件要求：至少 16核CPU、32GB内存、500GB硬盘空间

  若计划启用 GPU 加速（强烈建议），需配备 NVIDIA A10/A100 显卡，并安装对应版本的 CUDA 驱动和 PyTorch GPU 版本。

为了便于管理，我提前规划了以下目录结构：

这个布局看似简单，但在后续多模型切换和权限控制中起到了重要作用。比如当多个团队共用一台服务器时，可以通过软链接方式隔离各自使用的模型资源，避免误删或冲突。

安装流程：为什么我选择手动部署而非 Docker？

你可能会问：“不是有 Docker 镜像吗？直接docker-compose up不就行了吗？”
确实可以，但我选择了手动部署，原因有三：

1. 调试更直观：日志分散在不同服务中时，Docker 日志追踪成本较高；
2. 定制空间更大：未来要加权限模块、审计功能、自定义分词器等，源码级掌控更有利；
3. 理解底层机制：只有亲手走一遍组件协作流程，才知道哪里可能成为瓶颈。

工具预装：别让依赖问题打断节奏

在克隆项目之前，先解决几个常见的安装陷阱：

# 防止 setuptools 报错 pip install setuptools-scm seqeval # 安装 git-lfs，用于拉取 HuggingFace 上的大文件 git lfs install # 验证是否成功 git lfs version # 正常输出应类似：git-lfs/3.5.1 (GitHub; linux amd64; go 1.21.6)

这一步很容易被忽略，尤其是seqeval这个包，在没有安装的情况下，后续执行requirements.txt时会因编译失败导致中断。

获取源码与模型

进入工作目录并克隆项目（推荐使用国内镜像加速）：

cd /data0/Projects git clone https://github.com/chatchat-space/Langchain-Chatchat.git Langchain-Chatchat

接下来是重头戏——下载模型。这里我选用了一组经过验证的中文友好组合：

使用huggingface-cli下载示例：

huggingface-cli download THUDM/chatglm3-6b \ --local-dir /data0/Projects/LLMs/chatglm3-6b \ --local-dir-use-symlinks False

⚠️ 注意事项：
- 确保模型解压后路径清晰，不要嵌套过深；
- 推荐使用aria2c多线程下载，提升大文件稳定性；
- 所有模型统一放在/data0/Projects/LLMs/下，方便后续配置统一管理。

配置与初始化：让系统“认得清”你的模型

安装依赖包

进入项目根目录，依次安装三类依赖：

cd /data0/Projects/Langchain-Chatchat # 基础依赖 pip install -r requirements.txt # API 服务依赖（FastAPI） pip install -r requirements_api.txt # WebUI 依赖（Gradio） pip install -r requirements_webui.txt

如果网络较慢，可替换为清华源：

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

生成配置文件

运行脚本生成默认配置结构：

python copy_config_example.py

该命令会将config_example复制为configs目录，后续所有修改都在此进行。

核心配置一：configs/model_config.py

这是最关键的文件之一，决定了系统“用哪个模型、在哪找”。

MODEL_ROOT_PATH = "/data0/Projects/LLMs" EMBEDDING_MODEL = "bge-large-zh-v1.5" EMBEDDING_DEVICE = "cuda" # 如果有GPU，务必设为 cuda，速度提升显著 LLM_MODELS = ["chatglm3-6b"] LLM_DEVICE = "cuda" # 同样建议启用GPU MODEL_PATH = { "embed_model": { "bge-large-zh-v1.5": f"{MODEL_ROOT_PATH}/bge-large-zh-v1.5", }, "llm_model": { "chatglm3-6b": f"{MODEL_ROOT_PATH}/chatglm3-6b", } }

💡 小技巧：后期若想接入 Qwen 或 Baichuan，只需在此字典中新增条目即可，无需改动其他逻辑。

可选优化：configs/server_config.py

调整端口与跨域设置，便于前端集成：

WEBUI_PORT = 7860 API_PORT = 7861 API_ENABLE_CORS = True # 允许跨域请求，方便调用API

初始化向量数据库

首次部署必须执行初始化：

python init_database.py --recreate-vs

这条命令会：
- 删除旧的data/vectordb目录（如有）
- 重建 Chroma 向量数据库
- 使用配置中的 Embedding 模型处理内置示例文档

❗ 常见报错：“Model not found”
排查方向：
- 检查MODEL_PATH中路径拼写是否正确；
- 确认目标目录下是否存在config.json、pytorch_model.bin等关键文件；
- 权限问题：确保运行用户有读取模型目录的权限。

启动与测试：见证系统的第一次呼吸

一切就绪后，启动全部服务：

python startup.py -a

正常启动后会有如下输出：

INFO: Uvicorn running on http://0.0.0.0:7861 INFO: Application startup complete. Gradio app launched at: http://0.0.0.0:7860

此时可通过浏览器访问：

• 🖥️ WebUI：http://your-server-ip:7860
• 📡 API 文档：http://your-server-ip:7861/docs

测试1：基础对话能力

打开 WebUI，切换到“LLM 对话”标签页，输入：

“请介绍一下你自己。”

预期响应应由chatglm3-6b生成，内容大致为：“我是一个基于 ChatGLM3 的语言模型……”。响应时间在 CPU 模式下约 3~8 秒，GPU 下可压缩至 1 秒以内。

📌 性能建议：
- CPU 用户可尝试绑定核心：taskset -c 0-7 python startup.py -a
- GPU 用户务必在model_config.py中设置LLM_DEVICE="cuda"

测试2：知识库问答全流程打通

这才是真正的价值所在——让系统读懂你的专属文档。

创建知识库

点击左侧菜单 → “知识库管理” → “创建知识库”，填写名称如company_policy，选择模型和分块策略（默认每块500字符）。

上传文档

支持格式包括.txt,.md,.pdf,.docx,.xlsx等。上传一份公司《员工手册》PDF 文件。

系统自动完成以下流程：
1. 使用Unstructured解析文档结构；
2. 通过RecursiveCharacterTextSplitter分段；
3. 调用bge-large-zh-v1.5生成向量；
4. 存入本地 Chroma 数据库。

上传完成后，可在“内容查看”中检查文本提取是否准确，特别是表格和标题层级是否保留良好。

发起查询

切换至“知识库问答”页面，提问：

“员工请假需要提前几天申请？”

若文档中有相关内容，系统应返回类似答案：

“根据《员工手册》第3章第5条，普通事假需至少提前3个工作日提交申请。”

这意味着 RAG 流程已完整跑通——从原始文档到精准回答，全程无需人工干预。

API 接口调用：让智能融入现有系统

LangChain-Chatchat 不只是一个演示工具，它提供了完整的 RESTful API，可用于深度集成。

Swagger 文档地址：http://your-server-ip:7861/docs

常用接口包括：

示例：调用知识库问答 API

curl -X POST "http://your-server-ip:7861/knowledge_base/chat" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "query": "年终奖发放时间是几月？", "knowledge_base_name": "company_policy", "top_k": 3, "score_threshold": 1.0, "history": [] }'

返回 JSON 包含answer和docs字段，其中docs是引用的原文片段，可用于前端高亮展示来源，增强可信度。

✅ 实际应用场景：
- 接入企业微信机器人，实现 HR 政策自动答疑；
- 集成到 OA 系统，在审批页面旁提供上下文帮助；
- 构建客服知识中枢，降低一线人员培训成本。

总结与思考：不只是部署，更是起点

LangChain-Chatchat 绝非简单的“玩具项目”。在我司的实际应用中，这套系统已稳定运行数月，支撑了人力、财务、IT 多个部门的知识检索需求。其模块化设计、活跃的社区更新以及出色的中文支持，使其成为当前国产开源项目中最成熟的本地知识库框架之一。

但这仅仅是个开始。下一步，我们计划在现有基础上做三件事：

1. 权限体系升级：实现按部门/角色划分知识库访问权限；
2. 操作日志审计：记录每一次查询行为，满足合规要求；
3. 微调+蒸馏实验：基于内部语料对bge和chatglm3进行轻量微调，进一步提升专业领域表现。

最终目标是打造一个安全、可控、可持续演进的企业级智能知识中枢。而这一切，始于一次干净利落的私有化部署。

如果你也在寻找一条通往“可信AI”的落地路径，不妨试试 LangChain-Chatchat——它或许不会让你一步登天，但一定能带你走得更远。