Langchain-Chatchat API接口调用示例代码大全

Langchain-Chatchat API 接口调用实践与系统集成指南

在企业智能化转型的浪潮中，一个日益突出的问题浮出水面：通用大语言模型虽然“见多识广”，但在面对公司内部制度、产品手册或客户合同这类私有知识时，往往答非所问，甚至凭空编造答案。更令人担忧的是，将敏感文档上传至云端API存在不可控的数据泄露风险。

这正是本地化知识库问答系统的价值所在——它让AI既能“懂业务”，又能“守秘密”。而Langchain-Chatchat作为当前开源社区中最成熟的解决方案之一，正被越来越多团队用于构建私有AI助手。它不是简单的工具组合，而是一套完整的技术闭环：从文档解析、向量检索到本地推理，全程无需联网，数据始终留在企业内网。

要真正用好这套系统，关键在于理解其背后各模块如何协同工作，并掌握API层面的调用细节。接下来，我们将跳过理论堆砌，直接进入实战视角，看看如何一步步打通这个本地智能问答链路。

构建知识库：从一份PDF说起

假设你刚接手一项任务：把公司《员工手册》变成可对话的AI助手。这份PDF包含了考勤、休假、报销等政策条款。第一步，当然是让它“读懂”这份文件。

from langchain.document_loaders import UnstructuredFileLoader from langchain.text_splitter import RecursiveCharacterTextSplitter # 加载任意格式文档（自动识别类型） loader = UnstructuredFileLoader("员工手册.pdf", mode="elements") raw_documents = loader.load()

这里用到了UnstructuredFileLoader，它是Langchain提供的“万能读取器”，能处理PDF、Word、PPT等多种格式。但要注意，如果是扫描版PDF，必须提前通过OCR转换为文本，否则提取结果为空。

接下来是分块。不能整篇喂给模型，那样会超出上下文窗口；也不能切得太碎，否则丢失语义连贯性。经验法则是控制在300~800字符之间：

text_splitter = RecursiveCharacterTextSplitter( chunk_size=600, chunk_overlap=60, separators=["\n\n", "\n", "。", "！", "？", "；", " ", ""] ) texts = text_splitter.split_documents(raw_documents) for i, doc in enumerate(texts[:3]): print(f"【文本块 {i+1}】{doc.page_content}\n---\n")

separators参数很关键——它定义了优先断句的位置。比如先尝试按段落（\n\n）切，再按句子结束符（。！？），最后才考虑空格和单字符。这样可以避免把一句话生生拆开。

向量化存储：让机器“记住”知识

文本准备好后，下一步是将其转化为向量。这是实现语义搜索的核心步骤。我们通常使用轻量级Embedding模型，例如专为中文优化的bge-small-zh-v1.5：

from langchain.embeddings import HuggingFaceEmbeddings import torch # 检查是否可用GPU device = "cuda" if torch.cuda.is_available() else "cpu" embeddings = HuggingFaceEmbeddings( model_name="BAAI/bge-small-zh-v1.5", model_kwargs={"device": device} )

然后将这些文本块存入向量数据库。FAISS 是最常用的选项，因为它轻便且支持本地持久化：

from langchain.vectorstores import FAISS import os # 构建并保存向量索引 vectorstore = FAISS.from_documents(texts, embeddings) vectorstore.save_local("vectorstore/employee_handbook") print("✅ 知识库已构建完成，共写入 %d 个文本片段" % len(texts))

以后每次启动服务时，可以直接加载这个索引，无需重复解析文档：

# 启动时快速加载已有知识库 if os.path.exists("vectorstore/employee_handbook"): vectorstore = FAISS.load_local( "vectorstore/employee_handbook", embeddings, allow_dangerous_deserialization=True # 允许加载pickle序列化内容 )

注意allow_dangerous_deserialization=True这个参数，是因为FAISS默认禁用反序列化以防安全风险。如果你确信数据来源可信，可以开启。

本地大模型接入：离线也能“思考”

现在知识有了，还得有个“大脑”来生成回答。Langchain-Chatchat 的一大优势就是支持多种本地LLM后端。对于大多数中文场景，推荐使用经过微调的国产模型，如通义千问 Qwen 或智谱 ChatGLM。

以 GGUF 格式的量化模型为例（适用于 llama.cpp 后端），可以在消费级设备上运行7B级别的模型：

from langchain.llms import LlamaCpp import os model_path = "./models/qwen-7b-chat-q4_k_m.gguf" if not os.path.exists(model_path): raise FileNotFoundError(f"模型文件未找到，请下载后放置于 {model_path}") llm = LlamaCpp( model_path=model_path, n_ctx=4096, # 上下文长度 n_batch=512, # 批处理大小 n_gpu_layers=35, # 尽可能多地卸载到GPU（NVIDIA/CUDA 或 Apple Metal） temperature=0.3, # 低温度保证输出稳定 max_tokens=1024, # 控制生成长度 repeat_penalty=1.1, # 抑制重复用词 verbose=False # 生产环境建议关闭详细日志 )

这里的n_gpu_layers非常重要。如果你使用的是Mac M系列芯片或NVIDIA显卡，设置足够大的层数可以让大部分计算在GPU执行，速度提升数倍。反之，若设为0，则完全依赖CPU，响应时间可能长达数十秒。

还有一个实用技巧：对高频问题做缓存。比如“年假有多少天？”这种问题每天会被问上百次，没必要每次都走完整检索流程：

from functools import lru_cache @lru_cache(maxsize=128) def cached_query(question: str): return qa_chain.run(question)

简单几行代码就能显著降低延迟和资源消耗。

组装问答链：把组件串起来

有了文档、向量库和模型，就可以构建完整的问答链了。LangChain 提供了高层封装，让我们用一行代码完成整个流程：

from langchain.chains import RetrievalQA qa_chain = RetrievalQA.from_chain_type( llm=llm, chain_type="stuff", # 将所有相关片段拼接后输入模型 retriever=vectorstore.as_retriever(search_kwargs={"k": 3}), return_source_documents=True # 返回引用来源，增强可信度 )

其中chain_type支持四种模式：
-stuff：全部拼接（适合短文档）
-map_reduce：逐段处理后再汇总（适合长文）
-refine：迭代优化答案（精度高但慢）
-map_rerank：每段打分排序，选最优回答

一般情况下选择stuff即可。search_kwargs={"k": 3}表示每次检索返回最相关的3个文本块作为上下文。

调用起来非常直观：

query = "哺乳期女员工每天有几次哺乳假？" result = qa_chain({"query": query}) print("💡 回答：", result["result"]) print("\n📚 引用来源：") for i, doc in enumerate(result["source_documents"]): print(f" [{i+1}] {doc.metadata.get('source', '未知')} | 内容片段：{doc.page_content.strip()[:100]}...")

输出类似：

💡 回答：根据公司规定，哺乳期女员工每日享有两次各30分钟的哺乳假，可合并使用。 📚 引用来源： [1] 员工手册.pdf | 内容片段：哺乳期女职工每天可享受两次共计60分钟的哺乳时间...

这种带溯源的回答方式，在企业应用中尤为重要——用户不仅知道答案是什么，还能验证其真实性。

API 对接：让系统对外服务

Langchain-Chatchat 自带 FastAPI 后端，提供了标准 RESTful 接口。你可以通过 HTTP 请求直接与之交互。

查询接口示例（POST）

curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-7b-chat", "messages": [ {"role": "user", "content": "新员工试用期多久？"} ], "stream": false }'

响应结构如下：

{ "id": "chat-abc123", "object": "chat.completion", "created": 1712345678, "model": "qwen-7b-chat", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "新员工试用期为三个月，表现优异者可申请提前转正。" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 15, "completion_tokens": 20, "total_tokens": 35 } }

如果你想在前端项目中集成，可以用 JavaScript 调用：

async function askBot(question) { const response = await fetch('http://localhost:8000/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'local-llm', messages: [{ role: 'user', content: question }] }) }); const data = await response.json(); return data.choices[0].message.content; } // 使用示例 askBot("年假怎么申请？").then(console.log);

为了保障安全性，建议在生产环境中启用认证机制。可以通过添加中间件实现 Token 验证：

from fastapi import Depends, FastAPI, HTTPException app = FastAPI() def verify_token(token: str = None): if token != "your-secret-token": raise HTTPException(status_code=401, detail="Invalid token") @app.post("/v1/chat/completions") def chat_completion(request: dict, token: str = Depends(verify_token)): # 正常处理逻辑... pass

实战中的设计权衡

在真实部署中，你会面临一系列工程决策。以下是几个常见考量点：

硬件适配建议

💡 提示：7B模型的4-bit量化版本约需5~6GB显存，13B模型则需10GB以上。如果显存不足，可启用部分层CPU卸载（split mode），但性能会下降。

性能优化技巧

• 预加载策略：启动时一次性加载所有知识库和模型，避免首次请求长时间等待。
• 异步处理：对耗时操作（如文档解析）使用后台任务队列（Celery/RQ）。
• 混合检索：结合关键词匹配（BM25）与向量检索，提升召回率。
• 动态chunk_size：对技术文档用较小分块（300字符），对小说类用较大分块（800字符）。

安全最佳实践

• 关闭公网暴露，仅限内网访问；
• 使用HTTPS加密通信；
• 定期备份向量库和模型文件；
• 敏感字段脱敏后再入库（如身份证号、银行卡号）。

结语

Langchain-Chatchat 并不是一个“开箱即用”的黑盒系统，而是一个高度可定制的技术底座。它的真正威力，体现在你能根据业务需求灵活调整每一个环节：换更好的Embedding模型、接入不同的向量数据库、切换更适合中文的本地LLM。

更重要的是，它重新定义了企业级AI的边界——不再是把数据送到云端去“求答案”，而是让AI走进你的服务器，成为真正可控、可信、可审计的知识代理人。

当你看到员工不再翻找PDF，而是直接问“报销流程是什么”，然后瞬间得到准确回复时，那种效率跃迁的感觉，才是技术落地最美的回响。