Langchain-Chatchat本地知识库部署指南

Langchain-Chatchat 本地知识库部署指南

在企业智能化转型的浪潮中，如何高效利用内部文档、技术手册和规章制度成为一大挑战。传统搜索方式难以理解语义，而直接调用大模型又存在数据泄露风险。这时候，一个既能保障隐私又能精准响应的专业问答系统就显得尤为关键。Langchain-Chatchat正是为此类需求量身打造的开源利器。

它基于LangChain架构构建，专为中文环境优化，支持私有文档管理与完全离线运行，所有处理流程均在本地完成，真正实现“数据不出域”。无论是企业知识库、合规政策查询，还是研发资料辅助，Chatchat 都能提供安全、可控、高效的智能问答能力。

核心机制：RAG 如何让回答有据可依？

Chatchat 的核心技术采用检索增强生成（RAG）模式，巧妙结合了信息检索的准确性与大语言模型的语言生成能力。整个流程并非依赖模型“记忆”知识，而是通过实时检索相关文本片段来支撑回答，从根本上缓解了幻觉问题。

其工作流可以概括为以下几个步骤：

1. 文档解析：系统首先读取 PDF、Word、Excel 等格式文件，使用Unstructured或PyPDF2提取纯文本内容。
2. 文本分块：将长文档切分为固定长度的段落（如 512 token），同时保留句子完整性，避免语义断裂。
3. 向量化嵌入：每个文本块被送入 Embedding 模型（如 BGE 或阿里云text-embedding-v1）转换为高维向量。
4. 向量存储：这些向量存入 FAISS、Chroma 等向量数据库，并建立索引以支持快速近似最近邻搜索（ANN）。
5. 用户提问：当用户输入问题时，同样进行向量化处理。
6. 语义匹配：系统在向量空间中查找与问题最相似的 Top-K 个文本块作为上下文依据。
7. 提示工程：将原始问题与检索到的相关段落组合成结构化 Prompt。
8. 模型推理：交由大语言模型（LLM）综合上下文生成自然语言回答。

这种设计不仅提升了答案的准确性和可解释性，还使得系统能够灵活适配不同领域的专业知识，无需重新训练模型。

graph TD A[用户提问] --> B{问题向量化} B --> C[向量数据库检索] D[原始文档] --> E[文本提取与分块] E --> F[文本向量化] F --> G[存入向量库] C -->|Top-K 相关段落| H[构造 Prompt] H --> I[大模型生成回答] I --> J[返回结果 + 引用来源] style A fill:#f9f,stroke:#333 style J fill:#cfc,stroke:#333

环境准备：从零开始搭建基础平台

要顺利部署 Chatchat，需提前准备好以下组件：

💡 若你计划使用云端模型（如通义千问、GPT），则无需本地 GPU；若追求彻底离线，则推荐搭配 Ollama 或 Xinference 运行本地 LLM。

分步部署实战

第一步：获取远程模型访问权限（以阿里云百炼为例）

Langchain-Chatchat 支持多种 LLM 接入方式，包括 OpenAI、FastChat、Ollama 和 OneAPI。这里我们选择阿里云百炼平台，因其对中文场景高度优化且提供免费额度。

注册与开通服务

1. 访问 阿里云百炼官网
2. 使用阿里云账号登录并开通“通义百炼”
3. 新用户通常赠送大量 Token，适合初期测试

创建 API Key

1. 登录后进入「API 密钥管理」页面
2. 点击「创建密钥」，复制生成的sk-xxxxxx
3. 保存好该密钥，后续将在 OneAPI 中使用

推荐模型：
- 文本生成：qwen-turbo
- 文本嵌入：text-embedding-v1

第二步：部署 OneAPI —— 统一接口网关

OneAPI 是一个强大的中间件，能聚合多个模型厂商的 API 并提供标准化的 OpenAI-like 接口，极大简化 Chatchat 的集成复杂度。

使用 Docker 启动服务

mkdir -p /opt/one-api chmod 777 /opt/one-api docker run --name one-api -d --restart=always \ -p 3000:3000 \ -e TZ=Asia/Shanghai \ -v /opt/one-api:/data \ justsong/one-api:latest

✅ 启动成功后可通过浏览器访问：http://localhost:3000/login
默认用户名：root，密码：123456

添加阿里云百炼渠道

1. 登录 OneAPI 控制台
2. 进入「渠道管理」→「添加渠道」
3. 填写如下信息：
   - 名称：Aliyun Bailian
   - 类型：Aliyun
   - API Key：填入上一步获取的密钥
   - 勾选模型：qwen-turbo,text-embedding-v1
4. 提交保存

生成访问令牌（Token）

1. 进入「令牌管理」→「创建令牌」
2. 设置参数：
   - 名称：chatchat-token
   - 关联模型：选择qwen-turbo和text-embedding-v1
   - 过期时间：设为“永久”
   - 额度限制：建议设置为 1,000,000 tokens
3. 复制生成的 Token 字符串（形如sk-xxxxxxxx）

此 Token 将用于 Chatchat 的配置文件中，作为调用模型的身份凭证。

第三步：安装 Langchain-Chatchat

创建独立 Conda 环境

conda create -n chatchat python=3.10.16 conda activate chatchat

安装主程序包

pip install langchain-chatchat -U

⚠️ 注意：部分版本可能存在httpx兼容性问题。若启动时报错连接异常，请执行以下命令降级：

pip uninstall httpx -y pip install httpx==0.27.2

初始化项目目录

# Linux/macOS 用户 export CHATCHAT_ROOT="/Users/yourname/chatchat_data" # Windows 用户 set CHATCHAT_ROOT="C:\Users\yourname\chatchat_data" # 执行初始化 chatchat init

该命令会自动生成标准目录结构：

$CHATCHAT_ROOT/ ├── config/ │ └── model_settings.yaml # 模型配置文件 ├── knowledge_base/ │ └── samples/ # 示例知识库 ├── models/ # （可选）本地模型缓存 └── logs/

第四步：配置 model_settings.yaml

编辑$CHATCHAT_ROOT/config/model_settings.yaml文件，关键修改项如下：

DEFAULT_LLM_MODEL: qwen-turbo DEFAULT_EMBEDDING_MODEL: text-embedding-v1 platform_name: oneapi platform_type: oneapi api_base_url: http://127.0.0.1:3000/v1 api_key: sk-xxxxxxxxxxxxxxxx # 替换为 OneAPI 中生成的 Token

确保MODEL_PLATFORMS列表中的oneapi条目配置完整：

- platform_name: oneapi platform_type: oneapi api_base_url: http://127.0.0.1:3000/v1 api_key: sk-xxxxxxxxxxxxxxx llm_models: - qwen-turbo - qwen-plus - qwen-max embed_models: - text-embedding-v1

🔍注意事项：
- 若 OneAPI 部署在远程服务器，需将api_base_url中的 IP 地址替换为实际主机地址
- 生产环境中不建议关闭 SSL 校验，应确保证书有效

第五步：构建知识库并启动服务

清理并重建向量库（首次运行）

# 可选：清空默认示例文件 rm -rf $CHATCHAT_ROOT/knowledge_base/samples/content/* # 重建向量索引 chatchat kb -r

📌 建议首次使用前清除默认测试文件，避免无效计算开销。

启动 Web UI 服务

chatchat start -a

参数说明：
--a：同时启动 API 和前端界面
-start api：仅启动后端接口
-start webui：仅启动前端

验证服务状态

看到如下日志表示服务已就绪：

INFO: Uvicorn running on http://0.0.0.0:7861 INFO: Started reloader process [xxxxx] INFO: Application startup complete. Streamlit app started at http://0.0.0.0:8501

访问以下地址即可使用系统：

• 🖥️ Web 界面：http://localhost:8501
• 🧩 API 文档：http://localhost:7861/docs

日常使用与高级管理

上传文档

1. 打开 Web 页面 →「知识库管理」
2. 选择目标知识库（默认samples）
3. 点击「上传文件」，支持.txt,.pdf,.docx,.xlsx等格式
4. 上传完成后点击「更新向量库」

⏱️ 首次构建可能耗时较长，取决于文档数量和大小。

发起问答

切换至「聊天对话」页面：

• 输入问题，例如：“员工年假有多少天？”
• 系统自动检索相关段落并生成回答
• 回答下方显示引用来源，支持溯源验证

创建自定义知识库

# 创建名为 company_policy 的新知识库 chatchat kb create -n company_policy # 指定使用的 embedding 模型 chatchat kb create -n company_policy -e text-embedding-v1

之后可在 Web 界面中选择该知识库进行独立管理和查询。

故障排查与性能调优

❌ 启动失败：httpx.ConnectError或Too Many Requests

• 原因：网络不通或请求频率超限
• 解决方法：
• 检查 OneAPI 是否运行：docker ps | grep one-api
• 查看日志：docker logs one-api
• 调整并发设置或更换 API Key

⚠️ 回答质量不佳？试试这些优化策略

💡 完全离线部署方案（适用于敏感数据场景）

对于金融、政务等高安全要求领域，推荐采用全链路本地化架构：

[本地文档] → [Ollama 运行 qwen2:7b] → [Embedding 使用 BGE-ZH] → [FAISS 向量库本地存储] → [Langchain-Chatchat 全流程本地运行]

优势：
- 数据全程不联网
- 审计友好，符合国产化替代趋势
- 响应更稳定，不受公网波动影响

部署参考：

# 安装 Ollama curl -fsSL https://ollama.com/install.sh | sh # 拉取中文优化模型 ollama pull qwen2:7b ollama pull BAAI/bge-large-zh-v1.5 # 修改 model_settings.yaml platform_type: ollama api_base_url: http://127.0.0.1:11434 DEFAULT_LLM_MODEL: qwen2:7b DEFAULT_EMBEDDING_MODEL: BAAI/bge-large-zh-v1.5

Langchain-Chatchat 凭借其模块化设计、出色的中文支持以及灵活的模型接入能力，已成为构建私有知识问答系统的首选框架之一。无论你是想为企业搭建一个内部技术支持助手，还是为个人打造专属的知识查询工具，这套方案都能提供强大而安全的技术底座。

随着本地大模型生态的不断完善，未来还可进一步集成多轮对话记忆、角色权限控制、语音交互等功能，逐步演化为完整的智能知识服务平台。现在正是动手实践的最佳时机。