AutoDL部署Langchain-Chatchat 0.3.0完整指南

AutoDL部署Langchain-Chatchat 0.3.0完整指南

在企业知识管理日益智能化的今天，如何让AI真正理解你的内部文档、快速精准地回答员工或客户的问题，已经成为技术团队关注的核心议题。开源项目Langchain-Chatchat正是在这一背景下脱颖而出——它基于 LangChain 框架和大语言模型（LLM），结合检索增强生成（RAG）技术，实现了私有文档的本地化智能问答，数据不出内网，安全可控。

从 v0.3.0 版本开始，该项目进行了重大架构升级：不再直接加载本地.bin或.safetensors模型文件，而是通过统一的推理服务接口（如 Xinference、Ollama 等）调用模型。这一变化提升了系统的可扩展性与稳定性，但也增加了部署复杂度。

本文将带你以AutoDL 平台为载体，手把手完成Langchain-Chatchat v0.3.0的全流程部署，涵盖环境配置、Xinference 模型服务搭建、依赖安装、项目启动及常见问题处理，助你零基础也能快速构建属于自己的本地知识库系统。

部署准备：选择合适的GPU实例与系统镜像

首先访问 AutoDL 官网 注册并登录账号。创建一个适合运行中大型语言模型的 GPU 实例是成功部署的关键。

推荐配置如下：

• 地区：重庆 A 区（国内延迟较低）
• GPU 类型：RTX 4090（24GB 显存，足以支持 9B 级别模型非量化运行）
• 磁盘空间：建议 ≥50GB（后续需存储模型缓存和向量数据库）
• 镜像系统：PyTorch 2.3.0 + Python 3.12 + CUDA 12.1（Ubuntu 22.04）

创建完成后等待系统初始化完毕，通过 SSH 连接终端即可进入操作阶段。

⚠️ 提示：若计划部署更大模型（如 Qwen1.5-14B），建议选用 A100 或多卡实例，并确保磁盘容量充足。

网络优化与虚拟环境初始化

在国内访问 GitHub 和 HuggingFace/ModelScope 资源时常受限。虽然本文作者已配置科学上网工具，但如果你没有代理，强烈建议使用 AutoDL 提供的“学术加速”功能来提升下载速度。

启用方式非常简单，在终端执行：

source /etc/network_turbo

该命令会自动设置http_proxy和https_proxy，使 pip、git、wget 等工具走加速通道。

取消加速只需清除环境变量：

unset http_proxy && unset https_proxy

接下来进行 Conda 虚拟环境的基础配置。新建的实例默认未激活 Conda，需要先初始化 shell 支持：

source ~/.bashrc conda init

然后关闭当前终端，重新打开一个新的连接窗口，确保conda命令可用且能正常切换环境。

安装 Langchain-Chatchat 及其扩展依赖

我们采用分环境策略：一个用于运行 Chatchat 主程序，另一个专用于模型推理服务（Xinference），避免依赖冲突。

创建主应用环境

conda create -n glm4_text python==3.11 conda activate glm4_text

Python 3.11 是目前兼容性最好的版本，部分依赖（如 Pydantic V1）对高版本存在兼容问题。

克隆项目源码：

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

安装核心包并启用[xinference]插件支持（关键！否则无法对接 Xinference）：

pip install langchain-chatchat[xinference] -U -i https://pypi.tuna.tsinghua.edu.cn/simple

✅ 验证是否安装成功：

chatchat --help

如果输出帮助信息，说明安装成功。此时你可以看到可用的子命令，包括chatchat-config、chatchat-kb等。

部署 Xinference 推理框架并加载模型

自 v0.3.0 起，Langchain-Chatchat 不再内置模型加载逻辑，必须依赖外部推理服务提供 LLM 和 Embedding 功能。我们选择Xinference作为后端引擎，原因有三：

1. 对中文模型支持良好（尤其是 GLM、Qwen 系列）
2. 支持 ModelScope 源直连拉取
3. 提供 Web UI 控制台，便于调试与监控

创建独立模型服务环境

conda create -n llm_tl python==3.11 conda activate llm_tl

安装 Xinference 全功能版：

pip install "xinference[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple

⚠️ 常见报错：

ERROR: Could not build wheels for llama-cpp-python...

这通常是因为 GCC 版本过高（>10）。解决方案是降级 g++ 编译器：

conda config --add channels conda-forge conda install gxx_linux-64=10

重新安装即可成功。

启动 Xinference 主服务

为了避免占用系统盘空间，我们将模型存储路径设为/root/autodl-tmp/：

XINFERENCE_HOME=/root/autodl-tmp/xinference \ XINFERENCE_MODEL_SRC=modelscope \ xinference-local --host 0.0.0.0 --port 9997

参数说明：

• XINFERENCE_HOME：指定模型根目录
• XINFERENCE_MODEL_SRC=modelscope：优先从魔搭社区拉取模型
• --host 0.0.0.0：允许外部访问
• --port 9997：Web 控制台端口

启动后可在浏览器访问http://<your_ip>:9997查看可视化界面。

加载 Embedding 模型

Embedding 模型负责将文本转换为向量，是知识库检索的基础。我们选用广泛使用的中文嵌入模型bge-large-zh-v1.5。

新开终端，激活llm_tl环境：

conda activate llm_tl xinference launch --model-name bge-large-zh-v1.5 --model-type embedding

该模型约 1.3GB，首次加载会自动从 ModelScope 下载，耗时几分钟。

加载大语言模型（以 GLM4-9B-Chat 为例）

接下来加载对话模型。这里我们使用智谱 AI 的GLM4-9B-Chat，性能优秀且对中文任务适配良好。

xinference launch \ --model-engine vllm \ --model-name glm4-chat \ --size-in-billions 9 \ --model-format pytorch \ --quantization none

关键参数解释：

• --model-engine vllm：使用 vLLM 引擎，显著提升推理吞吐量和显存利用率
• --size-in-billions 9：声明模型规模为 90 亿参数
• --quantization none：不进行量化，保证最高精度（但要求显存 ≥24GB）

💡 若显存不足，可尝试使用 4bit 量化：

--quantization q4_k_m

这样可在 16GB 显存下运行 9B 模型。

验证模型状态

执行以下命令查看当前运行中的模型：

xinference list

预期输出应包含两个 RUNNING 状态的模型：

只要这两项都就绪，说明模型服务已准备完毕，可以被 Langchain-Chatchat 调用。

启动 Langchain-Chatchat 主服务

回到最初的glm4_text环境：

conda activate glm4_text

配置模型映射关系

Chatchat 需要知道去哪里找对应的模型。检查当前模型配置：

chatchat-config model --show

你会看到类似 JSON 输出：

{ "DEFAULT_LLM_MODEL": "glm4-chat", "DEFAULT_EMBEDDING_MODEL": "bge-large-zh-v1.5" }

✅ 如果名称与你在 Xinference 中启动的一致，则无需修改；否则手动设置：

chatchat-config model --default_llm_model glm4-chat chatchat-config model --default_embedding_model bge-large-zh-v1.5

注意：这里的模型名必须与xinference list中显示的完全一致！

初始化知识库（可选）

如果你想测试官方示例文档的效果，可以初始化默认知识库：

chatchat-kb -r

这个过程会解析data/samples目录下的文档，构建 FAISS 向量库。但首次运行可能报错：

RuntimeError: 向量库 samples 加载失败。

原因是缺少faiss库。解决办法：

pip install faiss-cpu==1.7.4 pip install rank_bm25 -i https://mirrors.aliyun.com/pypi/simple

再次执行chatchat-kb -r即可成功。

启动主服务

一切就绪后，启动整个系统：

chatchat -a

该命令会同时启动：

• API 服务（Flask，监听 7861 端口）
• WebUI 服务（Streamlit，监听 8501 端口）

日志末尾出现以下提示即表示成功：

✔️ Chatchat API Server running at: http://127.0.0.1:7861 ✔️ Chatchat WEBUI running at: http://127.0.0.1:8501

访问 WebUI 界面的两种方式

由于服务默认绑定127.0.0.1，公网 IP 无法直接访问。以下是两种解决方案。

方法一：使用 AutoDL 代理工具（强烈推荐）

这是最安全、最便捷的方式，无需开放防火墙端口。

操作步骤：

1. 登录 AutoDL 控制台
2. 进入实例详情页 → “SSH隧道映射”
3. 添加新映射：
   - 协议：HTTP
   - 本地端口：8501
   - 远程主机：127.0.0.1
   - 远程端口：8501
4. 点击“开始代理”，系统生成临时域名（如xxx.adpai.co）
5. 浏览器打开该链接即可访问 WebUI

优点：
- 自动 HTTPS 加密
- 无需修改任何配置
- 支持多人协作调试

方法二：修改监听地址（适用于内网部署）

如果你希望直接通过<your_ip>:8501访问，可以修改绑定地址：

chatchat-config server --default_bind_host=0.0.0.0

确认修改生效：

chatchat-config server --show

输出中应包含：

"WEBUI_SERVER": { "host": "0.0.0.0", "port": 8501 }

重启服务后即可远程访问。

⚠️ 注意：此方式暴露了服务端口，请仅在可信网络环境中使用，防止敏感信息泄露。

功能验证与测试

启动完成后进行两项基本测试：

1. 通用对话测试

输入：“你好，请介绍一下你自己。”

预期输出：一段流畅自然的回答，表明 LLM 已正确接入。

2. 本地知识库问答测试

• 在 WebUI 中上传一份 PDF 或 TXT 文档
• 点击“构建知识库”
• 提出相关问题（如“这份文档讲了什么？”）

系统应能准确引用原文内容作答，证明 RAG 流程完整可用。

服务器重启后的恢复流程

当实例重启或中断后，需按顺序重新启动各项服务。

终端 1：重启 Xinference 主服务

conda activate llm_tl XINFERENCE_HOME=/root/autodl-tmp/xinference XINFERENCE_MODEL_SRC=modelscope xinference-local --host 0.0.0.0 --port 9997

终端 2：重新加载模型

conda activate llm_tl xinference launch --model-name bge-large-zh-v1.5 --model-type embedding xinference launch --model-engine vllm --model-name glm4-chat --size-in-billions 9 --model-format pytorch --quantization none

🔁 注意：Xinference 默认不会持久化保存模型实例，每次重启都需要重新launch。未来可通过容器化+持久卷解决。

终端 3：启动 Chatchat 服务

conda activate glm4_text chatchat -a

全部启动完成后，即可继续使用系统。

实用技巧与注意事项

使用清华源加速依赖安装

国内用户建议始终使用镜像源：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package>

或配置全局镜像：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

模型命名一致性至关重要

Xinference 中的模型名必须与chatchat-config model设置的值完全匹配，否则会出现“模型未找到”错误。建议统一命名规范，例如：

• LLM：glm4-chat
• Embedding：bge-large-zh-v1.5

如何更换其他模型？

Xinference 支持多种主流模型，例如：

• Qwen1.5-7B-Chat
• Yi-6B-Chat
• Baichuan2-13B-Chat

只需替换--model-name和对应参数即可。例如加载 Qwen：

xinference launch \ --model-engine vllm \ --model-name qwen1.5-chat \ --model-family qwen \ --size-in-billions 7 \ --model-format pytorch \ --quantization q4_k_m

更多模型支持请参考 Xinference 官方文档。

这种模块化的设计思路，使得 Langchain-Chatchat 不仅是一个问答工具，更是一个可扩展的企业级 AI 应用底座。无论是替换更强的模型、集成新的数据源，还是对接业务系统，都可以在此基础上灵活演进。只要你按照上述步骤一步步操作，即使零基础也能成功运行这套强大的本地知识库系统。