Langchain-Chatchat如何设置黑白名单过滤？内容安全控制

Langchain-Chatchat 内容安全控制：黑白名单过滤实战

在企业逐步将大语言模型（LLM）引入内部知识管理系统的今天，一个看似简单却至关重要的问题浮出水面——如何防止用户问出“不该问的”，或者上传“不能要”的内容？尤其是在完全离线部署的私有化问答系统中，没有云端审核兜底，一旦放任敏感请求进入模型推理链路，轻则生成不当回复影响专业形象，重则触碰合规红线。

Langchain-Chatchat 作为当前主流的开源本地知识库问答框架，虽然默认不包含完善的内容审查机制，但其模块化设计为自定义安全策略提供了充足空间。其中，黑白名单过滤因其轻量、高效、可控性强，成为构建第一道防线的首选方案。

这套机制的核心思想并不复杂：在用户提问或文档上传时，先过一遍“词库关”。如果命中黑名单关键词，比如“破解”、“翻墙”、“赌博”，直接拦截；若启用了白名单，则仅允许预设术语通行，其余一概拒绝。整个过程可在毫秒内完成，几乎不影响系统响应速度，且全程本地执行，无需依赖外部服务。

那么，具体该如何实现并集成到 Langchain-Chatchat 中？

我们不妨从最基础的 Python 实现开始。以下是一个简洁但实用的内容过滤器类：

import re from typing import List, Tuple class ContentFilter: def __init__(self, blacklist_path: str = None, whitelist_path: str = None): self.blacklist = self._load_words(blacklist_path) if blacklist_path else set() self.whitelist = self._load_words(whitelist_path) if whitelist_path else None # 编译正则表达式以提高匹配效率 if self.blacklist: escaped = [re.escape(word.strip()) for word in self.blacklist if word.strip()] pattern = "|".join(escaped) self.black_pattern = re.compile(pattern, re.IGNORECASE) else: self.black_pattern = None @staticmethod def _load_words(file_path: str) -> set: """从文件加载词汇，每行一个词""" words = set() with open(file_path, 'r', encoding='utf-8') as f: for line in f: word = line.strip() if word and not word.startswith("#"): # 忽略注释行 words.add(word.lower()) return words def check_blacklist(self, text: str) -> Tuple[bool, List[str]]: """ 检查文本是否包含黑名单词汇 :param text: 待检测文本 :return: (是否安全, 命中的词列表) """ if not self.black_pattern: return True, [] cleaned_text = re.sub(r'[^\w\s]', '', text.lower()) # 去除标点 matches = self.black_pattern.findall(cleaned_text) unique_matches = list(set(matches)) is_clean = len(unique_matches) == 0 return is_clean, unique_matches def check_whitelist(self, text: str) -> bool: """ 检查文本是否仅包含白名单词汇（严格模式） :param text: 待检测文本 :return: 是否合法 """ if self.whitelist is None: return True # 无白名单即不限制 words_in_text = set(re.findall(r'\w+', text.lower())) return all(word in self.whitelist for word in words_in_text) def filter(self, text: str) -> dict: """ 综合过滤接口 """ # 先检查黑名单 safe, bad_words = self.check_blacklist(text) if not safe: return { "allowed": False, "reason": "blacklist_hit", "details": {"blocked_by": bad_words} } # 再检查白名单（如有） if self.whitelist and not self.check_whitelist(text): return { "allowed": False, "reason": "not_in_whitelist" } return {"allowed": True}

这个类的设计有几个值得注意的细节：

• 支持从.txt文件动态加载词表，运维人员只需编辑文本即可更新规则；
• 自动忽略以#开头的注释行，便于维护带说明的词库；
• 对输入文本进行清洗（去标点、转小写），提升匹配鲁棒性；
• 正则表达式预先编译，避免每次调用重复解析，适合高频场景；
• 返回结构化结果，方便后续做日志记录或策略决策。

接下来是如何将其嵌入 Langchain-Chatchat 的请求流程。该系统通常基于 FastAPI 构建后端服务，因此最自然的方式是通过 HTTP 中间件实现全局拦截：

from fastapi import Request, HTTPException # 初始化过滤器 filter = ContentFilter(blacklist_path="config/blacklist.txt") @app.middleware("http") async def content_security_middleware(request: Request, call_next): if request.method == "POST" and request.url.path == "/chat": body = await request.json() query = body.get("query", "") result = filter.filter(query) if not result["allowed"]: raise HTTPException(status_code=403, detail="Content rejected by security policy") response = await call_next(request) return response

这段中间件代码的作用是在每次/chat接口被调用前自动触发内容检查。一旦发现黑名单命中，立即返回403 Forbidden，从而彻底阻断恶意请求进入 LangChain 的检索与推理流程。这不仅保障了输出安全，也节省了宝贵的计算资源——毕竟没人希望把 GPU 算力浪费在处理“如何制作炸弹？”这类问题上。

实际部署中，这套机制往往位于整个系统的最前端，形成一道“前置网关”式的防护层：

graph TD A[用户客户端] --> B[API Gateway / Middleware] B --> C{内容过滤模块} C -->|否| D[拒绝请求] C -->|是| E[LangChain问答流程] E --> F[文档检索 → Prompt拼接 → LLM调用]

这种架构遵循“尽早拦截”原则，确保危险请求不会深入系统核心。尤其对于高并发环境，提前终止非法请求能显著降低后端负载。

不过，简单的关键词匹配也有局限。攻击者可能通过拆字、同音替换、拼音缩写等方式绕过检测，例如用“破jie”代替“破解”，或“fanqiang”代替“翻墙”。为此，我们需要增强防绕过能力：

1. 模糊匹配扩展：除了精确匹配，可加入常见变体。例如，在黑名单中同时添加“破解”、“破 解”、“po jie”、“p0jie”等；
2. 使用高性能多模匹配算法：当词库规模上升至数千甚至上万条时，朴素的正则遍历会成为性能瓶颈。此时推荐采用 Aho-Corasick 算法，它能在一次扫描中完成所有关键词的匹配。Python 中可通过pyahocorasick库实现：

import ahocorasick def build_automaton(word_list): A = ahocorasick.Automaton() for idx, word in enumerate(word_list): A.add_word(word, (idx, word)) A.make_automaton() return A # 使用示例 blacklist = ["破解", "翻墙", "赌博"] matcher = build_automaton(blacklist) text = "我想知道怎么破 解软件" matches = [item[1][1] for item in matcher.iter(text)] # 输出: ['破解']

Aho-Corasick 在大规模词库下的性能优势明显，即便是百万级关键词也能保持亚毫秒级响应。

此外，黑白名单不应孤立存在。更健全的安全体系应是“规则 + 模型”的双引擎模式：

• 黑白名单负责拦截明确已知的威胁，速度快、准确率高；
• 同时接入轻量级 NLP 分类模型（如基于 BERT 的敏感意图识别），用于捕捉语义层面的风险，弥补规则覆盖不足的问题；
• 输出阶段也可增加二次过滤，对模型生成的回答再次扫描，形成闭环控制。

配置管理方面，建议将词库存放在独立目录，并支持热重载或重启生效。有条件的企业还可开发简易 Web 管理界面，让非技术人员也能便捷地增删敏感词，降低运维门槛。

值得一提的是，黑白名单的价值远不止于“防坏人”。在某些受监管行业，它可以发挥更精细的治理作用。例如：

• 在金融客服系统中，设置白名单仅允许“理财”、“基金”、“利率”等业务相关术语，防止员工查询竞品信息；
• 在医疗知识库中，屏蔽未上市药品名称，避免误导性回答；
• 在教育机构内部系统中，限制只能访问教学大纲范围内的知识点，维持问答的专业边界。

这些策略本质上是一种“权限分级”的体现——不是所有知识都应对所有人开放，AI 助手的回答也需符合组织的合规框架。

回顾整个方案，黑白名单之所以能在 Langchain-Chatchat 这类系统中脱颖而出，正是因为它完美契合了私有化部署的核心诉求：低成本、低延迟、高可控。相比动辄需要标注数据、持续训练的机器学习模型，或依赖网络连接的第三方审核 API，一套精心设计的规则系统反而更具落地优势。

当然，它并非万能。面对复杂的语义欺骗或新型攻击手法，仍需结合其他技术手段。但作为第一道防线，黑白名单的性价比无可替代。

未来的发展方向，很可能是将这类轻量规则引擎与小型化安全模型深度融合，形成可插拔、可组合的内容风控中间件。而 Langchain-Chatchat 的开放架构，恰恰为这样的创新预留了足够的演进空间。

某种意义上，这不仅是技术选型的问题，更是对 AI 可信性的实践回应：真正的智能，始于克制。