Langchian-chatchat私有化部署和踩坑问题以及解决方案[v0.3.1]

一 langchain-chatchat项目

• langchain-chatchat项目地址

• LangChain-ChatChat 基于 ChatGLM 等大语言模型与 Langchain 等应用框架实现，开源、可离线部署的 RAG 与 Agent 应用项目。

• LangChain-ChatChat 提供了丰富的对话及问答功能，包括：通用对话管理：支持多轮对话、会话历史保存、角色提示词自定义等功能。Web UI 可同时管理多个会话，每个会话可设置不同的系统指令和参数。具体核心功能如下：

  • 本地知识库 QA：通过“知识库对话”功能，将用户上传的文档、网页内容等构建向量化知识库，用户提问时从本地知识库检索相关信息并生成回答。支持多种文件格式（TXT、DOCX、PDF、Markdown 等）和知识库管理命令（如 chatchat kb -r 初始化、添加文件等）。

  • 文档检索问答（File RAG）：与知识库 QA 类似，但针对单个或选定文件进行分块检索，支持 BM25+KNN 等混合检索算法，实现对长文档或 PDF 的精确问答。

  • 搜索引擎对话：集成了可选的搜索引擎（如 Searx 等）作为知识补充，可在对话中检索实时网络信息，并作为上下文提供给模型。

  • 数据库问答：0.3.x 新增了直接对接数据库的能力，用户可以配置数据库连接，系统将根据用户提问生成 SQL 查询并返回结果（需使用支持 Function Call 的模型）。

  • 多模态功能：支持图片对话和文本生成图像。例如可上传图片让模型进行描述或分析（推荐使用 Qwen-VL-Chat 等视觉语言模型），或使用模型自带的文生图功能生成图片。

  • 工具/插件机制（Agent）：0.3.x 核心功能由 Agent 实现，用户可在配置中启用 Agent 模式，并选择多个工具（如 Wolfram、翻译、计算器、网络检索 等）。当启用 Agent 时，LLM 会根据请求自动调用合适的工具；也可手动选择单个工具进行 API 调用。这一机制使系统能够扩展各种“插件”功能，如事实查询、代码运行、表格操作等。

  • UI 前端：内置基于 Streamlit 的网页界面，提供聊天交互、模型选择、参数配置等功能。UI 支持多会话标签、上下文导出、记忆管理等，方便用户进行实验和演示。

  • 权限/多用户管理：当前版本主要面向个人或小团队部署，并未专门实现复杂的角色权限体系。系统默认允许本地访问，用户需在配置中调整监听地址（如改为 0.0.0.0）才能远程访问。

---

• LangChain-ChatChat 的核心架构是一个标准的 RAG 管道：加载文档→文本切分→向量化检索→合并上下文→LLM 生成回答。具体来说，系统首先通过多种文件解析器读取文档内容，然后用文本切分器（如基于句段或固定长度切分）将内容拆分为小块，对每块计算文本向量。用户提问后，同样将问题向量化，在向量数据库中检索与问题最相似的 TopK 文本块，将检索结果作为上下文与问题一并组织到提示词中，最后交给大模型生成答案。如下图所示：
  
• 详细流程示意：LangChain-ChatChat 内置整套检索问答流程，由 LangChain 负责串联各组件、管理上下文和对话记忆。 系统技术栈方面，ChatChat 基于 Python3.8+ 开发，核心依赖 LangChain 框架。它通过 FastAPI 暴露后端服务接口，也提供基于 Streamlit 的 Web UI 供用户交互。在模型支持上，从 0.3.0 版本起，所有模型（包括 LLM、Embedding、可视化模型 等）均通过模型推理框架接入，例如 Xinference、LocalAI、Ollama、FastChat 或 One API 等。这些框架可以加载如 GLM-4-Chat、Qwen-2、LLaMA3、Vicuna、Alpaca、Koala、RWKV 等多种开源大模型，并支持 GPU/CPU 异构部署和加速（如 GPTQ、vLLM、TensorRT 等）。系统内部还使用了数据库或文件系统来存储知识库元数据，默认使用 SQLite+FAISS 向量库，用户可通过配置接入其他矢量数据库（如 Chroma、Milvus 等）。整体运行时，通过 chatchat init 命令生成配置、初始化知识库，通过 chatchat start 启动服务，用户既可以以 API 形式调用，也可在浏览器中使用内置的多会话聊天界面。
  

二 本地私有部署

2.1 源码下载

• 访问langchain-chatchat项目地址，下载源码。并将其解压到你的代码目录下。

2.2 创建虚拟环境

• Langchain-Chatchat 自 0.3.0 版本起，为方便支持用户使用 pip 方式安装部署，以及为避免环境中依赖包版本冲突等问题， 在源代码/开发部署中不再继续使用 requirements.txt 管理项目依赖库，转为使用 Poetry 进行环境管理。
• 需要通过Conda创建一个独立的环境，并安装Poetry。

  conda create -n langchain_chat python=3.11
  

• Poetry 是一款现代化的 Python 包管理和项目构建工具，旨在为开发者提供一种简单一致、可复现的依赖管理与发布流程。
• 与传统的 pip 和 setup.py 相比，Poetry通过引入声明式的 pyproject.toml 配置文件，实现了项目依赖、开发依赖、版本锁定以及构建配置的统一管理。Poetry不仅支持对项目依赖进行精确版本约束和哈希校验，确保在不同环境中安装的依赖完全一致，还内置了虚拟环境自动管理机制，能够在每个项目目录下创建隔离的运行环境，从而避免依赖冲突和环境污染。
  通过简单的命令，开发者可以快速完成项目的初始化、依赖安装、版本更新、打包构建和发布到PyPI等操作，大幅提升了Python项目的可维护性和可移植性。

2.3 安装Poetry

• 进入新创建的虚拟环境，并安装Poetry

conda activate langchain_chat
pip install poetry==1.8.3

2.4 安装项目依赖

cd Langchain-Chatchat-0.3.1
cd .\libs\chatchat-server\
pip install -e .

2.5 初始化项目

• chatchat项目相关命令

chatchat init # 项目初始化
chatchat kb   # 知识库相关功能
chatchat start # 启动服务

• 执行项目初始化命令：

  chatchat init
  

2.6 修改配置信息

• 准备本地ollama beg-m3向量模型环境(本地安装ollama，然后使用ollama部署bge-m3模型，进行使用)和在线阿里云百炼api key。
• 打开项目中生成的配置文件，并修改如下内容
  
  
  

2.7 初始化知识库

• 项目提供了一个默认的knowledge_base知识库，可以通过如下命令进行初始化。

• 注意：前提是已经正确的配置了model_settings.yaml文件中对话模型和Embedding模型的配置信息。

chatchat kb -r

2.8 启动服务

chatchat start -a

(langchain_chat) D:\Code\Langchain-Chatchat-0.3.1\libs\chatchat-server>chatchat start -a
cwd:D:\Code\Langchain-Chatchat-0.3.1\libs\chatchat-server==============================Langchain-Chatchat Configuration==============================
操作系统：Windows-10-10.0.19045-SP0.
python版本：3.11.13 | packaged by Anaconda, Inc. | (main, Jun  5 2025, 13:03:15) [MSC v.1929 64 bit (AMD64)]
项目版本：0.3.1
langchain版本：0.1.17
数据目录：D:\Code\Langchain-Chatchat-0.3.1\libs\chatchat-server当前使用的分词器：ChineseRecursiveTextSplitter
默认选用的 Embedding 名称： bge-m3
==============================Langchain-Chatchat Configuration==============================

• 启动成功后，会自动打开浏览器(http://127.0.0.1:8501)，并显示如下界面
  

三 问题和解决方法

3.1 poetry和packaging版本兼容性

• 问题：poetry=2.1.4要求packaging>=24.0，但是langchain-chatchat项目中的langchain相关依赖要求packaging<24.0，导致依赖安装失败
• 解决方法：将poetry降级为1.8.3版本

pip install poetry==1.8.3

3.2 Langchain-chatchatPDF加载错误分析[win平台]

• 参考文章langchain-chatchat知识库初始化失败的坑

• 问题：本地部署完毕，chatchat init初始化完成，在进行chatchat kb -r时候，系统提示错误如下：

langchain chatchat 部署UnpicklingError: 从文件 samples/test_files/langchain.pdf 加载文档时出错：pickle data was truncated

• 原因分析：错误发生在RapidOCRPDFLoader加载PDF文件时，具体路径为samples/test_files/langchain.pdf 。错误链显示在加载NLTK的averaged_perceptron_tagger模型时失败。模型下载不完整：averaged_perceptron_tagger模型文件损坏或下载中断

• NLTK是用于人类自然语言处理包。NLTk是langchain-chathcat知识库矢量化需要用的包，这里可能出现了未能完全下载和解压，导致报错。

• 解决方法：手动下载、安装模型。

1. 访问nltk_data下载网址（可能需要魔法环境加快下载），下载下图中的两个文件
   
2. 解压后放入C:\Users\xxx\AppData\Roaming\nltk_data\taggers\

C:\Users\用户名\AppData\Roaming\nltk_data\taggers

3.3 向量模型处理数量问题

• 问题：使用轨迹流动平台的向量化模型存在批处理限制，导致如下报错：

openai.APIStatusError: Error code: 413 - {'code': 20042, 'message': 'input batch size 172 > maximum allowed batch size 64', 'data': None}

• 解决方法：本地安装ollama，然后使用ollama部署bge-m3模型，进行使用