文章目錄
- 一 langchain-chatchat項目
- 二 本地私有部署
- 2.1 源碼下載
- 2.2 創建虛擬環境
- 2.3 安裝Poetry
- 2.4 安裝項目依賴
- 2.5 初始化項目
- 2.6 修改配置信息
- 2.7 初始化知識庫
- 2.8 啟動服務
- 三 問題和解決方法
- 3.1 poetry和packaging版本兼容性
- 3.2 Langchain-chatchatPDF加載錯誤分析[win平臺]
- 3.3 向量模型處理數量問題
一 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知識庫矢量化需要用的包，這里可能出現了未能完全下載和解壓，導致報錯。
- 解決方法：手動下載、安裝模型。
- 訪問nltk_data下載網址（可能需要魔法環境加快下載），下載下圖中的兩個文件
- 解壓后放入
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模型，進行使用
)
