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

在企业数字化转型的浪潮中，如何高效利用海量非结构化文档——从技术手册到合同协议——成为知识管理的核心挑战。传统搜索依赖关键词匹配，难以理解语义；而通用大模型虽能生成流畅文本，却容易“一本正经地胡说八道”。有没有一种方式，既能保留私有数据的安全性，又能实现真正精准的智能问答？

Langchain-Chatchat 正是为此而生。它不是一个简单的聊天机器人，而是一套完整的检索增强生成（RAG）系统，专为中文场景优化，支持完全离线部署。你可以把公司内部的所有资料喂给它，然后像问同事一样自然提问：“去年Q3的产品故障率是多少？”、“这份合同里关于违约金的条款是怎么写的？”，它会精准定位原文并给出清晰回答。

整个流程其实很巧妙：先将你的 PDF、Word 等文档拆解成小段落，用嵌入模型（Embedding Model）转换成向量存入数据库；当你提问时，问题也被转为向量，在数据库中找出最相关的几段文字；最后把这些“上下文”和你的问题一起交给大语言模型，让它基于真实材料作答——这就从根本上抑制了幻觉，让 AI 的回答有据可依。

这套系统的架构非常清晰：

[原始文档] 
    ↓ 加载与解析
[纯文本提取]
    ↓ 文本分块（Chunking）
[文本片段集合]
    ↓ 嵌入模型编码
[向量数据库存储]
    ↓ 用户提问 → 问句向量化
[相似度匹配 Top-K]
    ↓ 匹配结果 + 原始问题 → Prompt 组装
[提交给 LLM 生成回答]
    ↓
[最终答案输出]

整个链路融合了文档解析、向量化、语义检索与生成推理四大环节，每一步都决定了最终的回答质量。比如文本分块不能太短（否则丢失上下文），也不能太长（超出模型上下文限制），通常 512~1024 token 是个不错的起点。而 Embedding 模型的选择更是关键，中文环境下推荐使用 BAAI/bge 系列，其对中文语义的理解远超通用英文模型。

要跑通这套系统，硬件要求其实相当亲民。如果你通过 API 接入远程模型（如阿里云百炼、OpenAI），一台普通笔记本就能胜任，所有计算都在云端完成，本地只负责文档解析和向量检索。但如果你想实现真正的“数据不出内网”，就需要本地运行大模型，这时建议配备 NVIDIA 显卡，并安装 CUDA 和 cuDNN。不过对于大多数中小企业而言，API 方案已经足够安全且高效。

下面是具体的部署步骤。

首先创建一个干净的 Python 环境，强烈建议使用 Conda 来避免依赖冲突：

conda create -n chatchat_env python=3.10.16
conda activate chatchat_env

Python 3.10 是目前兼容性最好的版本，许多底层库（如 LangChain）对其支持最为稳定。接着安装主程序：

pip install langchain-chatchat -U

如果遇到依赖问题，先升级 pip 再试：

pip install --upgrade pip

安装完成后，需要设置工作根目录。这个路径将存放配置文件、知识库和向量数据库，建议指定一个专用位置：

export CHATCHAT_ROOT=/Users/yourname/chatchat_data  # macOS/Linux
# set CHATCHAT_ROOT=C:\chatchat_data              # Windows

然后初始化项目结构：

chatchat init

执行后会在 $CHATCHAT_ROOT 下生成标准目录树：

chatchat_data/
├── config/
│   └── model_settings.yaml        # 主要模型配置文件
├── knowledge_base/
│   └── samples/                   # 示例知识库（可清空）
└── database/
    └── faiss/                     # FAISS 向量数据库存储

接下来进入最关键的一步：配置 model_settings.yaml。这是整个系统的“大脑设定”，决定了使用哪个模型、如何连接、参数如何调优。

对于初学者，推荐采用 OneAPI + 阿里云百炼 的组合。OneAPI 是一个开源的 API 聚合网关，可以统一管理多个 LLM 平台的密钥和流量，避免在不同服务间切换的麻烦。而阿里云百炼提供了高性能的 Qwen 系列模型（如 qwen-turbo、qwen-plus），新用户还有大量免费额度可用。

先去 阿里云百炼平台 注册账号，开通服务后在「密钥管理」中创建 AccessKey ID 和 Secret。记住，这些是你的账户凭证，不要泄露。

然后用 Docker 启动 OneAPI 服务：

mkdir -p /Users/yourname/one-api
chmod 777 /Users/yourname/one-api

docker run --name one-api -d \
  --restart=always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v /Users/yourname/one-api:/data \
  justsong/one-api:latest

访问 http://localhost:3000/login，初始账号密码为 root / 123456。登录后进入「渠道」页面，添加一个新的 Alibaba (Tongyi) 渠道，填入刚才获取的 AK/SK，并启用 qwen-turbo 和 text-embedding-v1 模型。

别忘了创建一个 API Key（令牌），这是后续 Langchain-Chatchat 调用模型的身份凭证。

现在回到 model_settings.yaml 文件，修改如下关键字段：

DEFAULT_LLM_MODEL: qwen-turbo
DEFAULT_EMBEDDING_MODEL: text-embedding-v1
STREAMING: true
HISTORY_LEN: 3
TEMPERATURE: 0.7

MODEL_PLATFORMS:
  - platform_name: oneapi
    platform_type: oneapi
    api_base_url: http://127.0.0.1:3000/v1
    api_key: sk-or-v1-xxxxxxxxxxxxxxxxxxxxx  # 替换为你在 OneAPI 中创建的令牌
    api_proxy: ''
    api_concurrencies: 5
    auto_detect_model: false
    llm_models:
      - qwen-turbo
      - qwen-plus
      - qwen-max
    embed_models:
      - text-embedding-v1
    text2image_models: []
    image2text_models: []
    rerank_models: []

注意：这里的 api_key 不是阿里云的原始密钥，而是你在 OneAPI 中生成的令牌。这种设计实现了权限隔离，即使令牌泄露也只影响单个应用。

配置完成后，就可以构建知识库索引了。如果是首次使用，建议先清空示例数据以加快处理速度：

rm -rf $CHATCHAT_ROOT/knowledge_base/samples/content/*

然后将你自己的文档（PDF、Word、TXT等）放入 samples/content 目录，执行重建命令：

chatchat kb -r

这个过程会遍历所有文件，进行文本提取、分块和向量化，最后存入 FAISS 数据库。耗时取决于文档总量，可能几分钟到几十分钟不等，请耐心等待。一旦完成，这些内容就具备了“被语义检索”的能力。

一切就绪后，启动服务：

chatchat start -a

-a 参数表示同时启动后端 API（FastAPI）和前端界面（Streamlit）。稍等片刻，打开浏览器访问：

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

在 Web 界面中，你可以上传新文档、选择知识库、发起多轮对话，并查看系统检索出的参考片段。这不仅提升了透明度，也方便你评估回答的可靠性——毕竟，知道答案来自哪一页，比盲目相信更重要。

当然，系统也支持更高级的定制。例如，若你追求彻底的隐私保护，希望所有模型都在本地运行，可以通过 Ollama 实现。Ollama 是一个轻量级本地模型运行框架，安装简单，支持主流模型一键拉取：

ollama pull qwen:7b
ollama pull BAAI/bge-large-zh-v1.5

随后修改 model_settings.yaml 中的平台配置为 Ollama：

platform_name: ollama
platform_type: ollama
api_base_url: http://127.0.0.1:11434/v1
api_key: EMPTY

llm_models:
  - qwen:7b
embed_models:
  - bge-large-zh-v1.5

重启服务后，整个推理过程将在本地完成，无需联网，适合对数据安全要求极高的场景。

此外，你也可以更换默认的 FAISS 向量数据库为 Chroma 或 Milvus。例如启用 Chroma：

VECTOR_SEARCH_CONFIG:
  vector_store_type: chroma
  chroma_host: 127.0.0.1
  chroma_port: 8000

并提前启动 Chroma 服务：

docker run -d --name chromadb -p 8000:8000 chromadb/chroma

Chroma 的优势在于原生支持元数据过滤和持久化，适合大规模知识库管理。

这套系统已经在多个领域展现出强大价值：

场景	说明
企业内部知识库	新员工入职无需翻阅上百页手册，直接提问即可获取操作指引
技术支持助手	客服人员输入客户问题，系统自动返回产品说明书中的解决方案
法律文书查询	律师快速定位合同中的责任条款或历史判例摘要
科研文献辅助	研究者上传论文集，通过自然语言检索关键实验数据
教学资料答疑	教师构建课程知识库，学生随时提问互动，减轻重复答疑负担

可以看到，Langchain-Chatchat 的核心价值不仅是“智能”，更是“可控”与“可信”。它不像通用聊天机器人那样漫无边际，而是扎根于你提供的每一份文档，确保每一次回答都有迹可循。

整个部署过程看似复杂，实则模块清晰：环境隔离、配置驱动、插件化扩展。你不需要一次性掌握所有细节，可以从最简单的 API 方案起步，逐步过渡到本地模型或分布式数据库。社区活跃，文档齐全，即便是初学者也能在半天内搭建出可用原型。

当你的第一份 PDF 被成功检索并生成准确回答时，那种感觉就像看着种子破土而出——沉默的文档终于开口说话了。而这，或许正是企业智能化最朴实的起点。

🚀 开始你的本地知识库之旅吧！让每一份文档都“活”起来。