验证安装

python -c "from llm_guard import Scanner; from llm_guard.vault import Vault; print('LLM Guard OK')“ `` ### 快速上手：5 分钟跑通输入输出双向过滤 最小可用流程的思路：LLM Guard 的用法可以概括为「一个 Vault、两组扫描器、一次 scan 调用」——Vault 负责敏感数据的匿名化映射存储，输入扫描器与输出扫描器分别挂在模型调用前后，Scanner.scan() 同时接收原始 prompt 与模型输出，返回净化结果和放行判断。下面的示例装配了三个输入扫描器（PII 匿名化、提示注入检测、毒性检测）与两个输出扫描器（禁用主题、相关性校验），覆盖最基本的双向过滤场景。操作步骤如下： 1. 创建 Vault 实例，用于存放匿名化过程中的敏感数据映射。 2. 实例化输入扫描器与输出扫描器，按需传入配置参数。 3. 将两组扫描器组装进 Scanner 对象。 4. 在每次 LLM 调用时执行 scanner.scan(prompt, model_output)，把返回的净化后 prompt 传给模型，并根据 is_valid 决定是否放行输出。 `python from llm_guard import Scanner from llm_guard.vault import Vault from llm_guard.input_scanners import Anonymity, PromptInjection, Toxicity from llm_guard.output_scanners import BanTopics, Relevance vault = Vault() scanner = Scanner( input_scanners=[ Anonymity(vault), # PII 匿名化：替换手机号、身份证号等 PromptInjection(), # 提示注入检测 Toxicity(), # 有害内容检测 ], output_scanners=[ BanTopics(), # 禁用主题过滤 Relevance(), # 输出与输入相关性校验 ], ) prompt = “我的手机号是 138-0000-0000，请告诉我今天天气” model_output = “多云转晴，气温 20 度。欢迎致电 138-0000-0000 咨询更多信息。” sanitized_prompt, is_valid, scores = scanner.scan(prompt, model_output) print(“净化后输入：”, sanitized_prompt) print(“是否放行：”, is_valid) # 各扫描器全部通过才为 True print(“各扫描器风险分数：”, scores) # 以扫描器名称为键的字典 ` 运行后可以看到：sanitized_prompt 中手机号已被替换为占位符，模型实际看到的是脱敏文本；scores 字典给出了每个扫描器的风险分数，is_valid 是所有扫描器判断的综合结果。进阶用法是把这个 scanner.scan() 调用包在你的真实模型调用函数外层——先扫描 prompt 再发给模型，拿到输出后再次扫描，两关都过再返回给用户。 ### 核心能力详解：5 大支柱 支柱一：输入扫描器体系。 LLM Guard 在模型之前提供一组即插即用的检测器：Anonymity 对 PII（姓名、手机号、邮箱、身份证等）做匿名化替换；PromptInjection 识别试图覆盖系统指令的注入文本；Toxicity 检测仇恨言论与有害内容；Secrets 发现并拦截 API 密钥、令牌等凭证泄露；TokenLimit 限制单次输入长度，防止超长上下文攻击；另有 MaliciousURLs、Regex、SQLInjection、XSS 等覆盖特定攻击面。每个扫描器都返回风险分数，团队可以根据业务容忍度设定阈值，而非一刀切。 支柱二：输出扫描器体系。 模型输出并不总是可信，Sensitive 检测输出中是否泄漏了不应出现的敏感实体；BanTopics 按预设主题列表过滤违规内容；Relevance 判断输出与用户问题的相关度，拦截答非所问的幻觉文本；FactualConsistency 借助外部 LLM 校验输出是否存在事实性编造；LanguageSame 校验模型是否使用了与用户一致的语言，避免答非所问以另一种语言呈现。输出侧的价值在于，即使模型已经被注入或产生幻觉，恶意内容也不会到达用户端。 支柱三：Vault 匿名化与还原机制。 Vault 是 LLM Guard 的核心设计：输入阶段的 Anonymity 扫描器识别出 PII 后，将其替换为语义保留的占位符，并把「占位符 → 真实值」的映射存入 Vault；模型只看到占位符，从未接触真实 PII；输出阶段再由业务代码从 Vault 中取回映射做还原。这套机制让「隐私保护」与「业务可用性」同时成立——模型上下文里没有真实敏感数据，但你仍然能从最终输出中拿到完整的业务答案。 支柱四：内置 API 服务器。 项目自带基于 FastAPI 的服务器实现，安装 llm-guard[api] 后可通过 uvicorn llm_guard.server:app 启动。它提供分析 prompt、分析输出等 HTTP 端点，允许非 Python 技术栈（如 Java、Go 网关）通过 REST 调用接入同一套安全策略。这为微服务架构里的统一过滤层提供了落地形态，安全策略的更新也无需重新发布业务服务。 支柱五：可扩展扫描器机制。 当内置扫描器不满足业务需求时，自定义扫描器只需实现统一的 scan() 接口并返回（是否有效、风险分数）即可接入 Scanner 编排。框架不限制扫描器的实现方式——可以是用正则的规则检测、用 transformers 的本地小模型、也可以是调用外部 LLM 的评判器。扫描器名称会作为结果字典的键，因此同名扫描器需要显式指定 name 参数以避免结果覆盖。 ### 生产部署与监控：从上线到运维 部署方式一：嵌入式（库模式）。 直接把 Scanner 集成进现有 Python 推理服务，在模型调用函数前后各加一次 scan()。这是延迟最低的形态，适合单体应用或对 p99 延迟敏感的场景。注意扫描器是同步调用，建议在独立的 worker 线程中执行或做好超时控制，避免某个本地模型的推理耗时拖垮整个请求链路。 部署方式二：独立 API 服务（网关前置）。 用 Uvicorn 将 llm_guard.server 部署为独立服务，业务网关把 prompt 先转发给它“过安检”再放行到模型后端。在 Kubernetes 中可作为 sidecar 容器伴随业务 Pod 部署，也可作为独立 Service 供多个业务方共用。独立部署的好处是安全策略集中管理、扫描器升级不用发版业务代码，代价是多一跳网络开销，需在网关层做好超时与降级。 可观测性。 scan() 返回的 is_valid 与 scores 是天然的监控数据源：按扫描器维度统计拦截率、平均风险分、扫描耗时，导出为 Prometheus 指标；把 is_valid=False` 的拦截事件（含扫描器名、风险分、脱敏后的 prompt）写入安全日志，供事后归因与攻击模式分析。上线前务必对每个扫描器做阈值校准——不同扫描器的分数语义不同，不能套用同一个阈值。 <p class=”para-label“>避坑清单：</p> <ul class=”dash-list"><li>坑 1：本地模型扫描器（如基于 transformers 的检测器）首次加载会从 Hugging Face 下载模型文件，直接压到线上首请求会导致超时，务必在部署流水线中做模型预热。</li><li>坑 2：Vault 的映射默认存在内存中，服务重启后匿名化映射丢失，输出侧的还原会失败，生产环境需规划映射的持久化或接受重启后输出不回填真实值。</li><li>坑 3：盲目堆扫描器会让延迟和误拦率同步上升，每个扫描器都要有明确的威胁模型依据，上线前用真实业务样本回归误拦率。</li></ul> ## 同类工具对比 | 维度 | LLM Guard | Guardrails AI | NeMo Guardrails | Llama Guard | | --- | --- | --- | --- | --- | | 定位 | 输入输出安全过滤库 | 输出验证与修复框架 | 对话级护栏编排框架 | 输入输出审核分类模型 | | 编排范式 | 扫描器列表 + scan() 织入 | Rail 规范（XML）驱动 | Colang 对话语言 | 模型推理调用 | | 类型约束 | Python 库 + 内置 REST API | Python 库 | Python 库 | PyTorch / Transformers 模型 | | 学习曲线 | 低-中，配置扫描器即可 | 中，需学 Rail 语法 | 中-高，需学 Colang DSL | 高，需自建推理与服务化 | | 生态集成 | Hugging Face、OpenAI/Anthropic、Vault | 与 LangChain 集成紧密 | 与 NeMo 生态绑定 | MLCommons 安全分类基准 | | 生产部署 | 嵌入式或独立 FastAPI 服务 | 嵌入应用代码 | 嵌入 NeMo 应用 | 模型服务（vLLM、TGI） | | License | Apache 2.0 | Apache 2.0 | Apache 2.0 | Llama 3 Community（受限） | | 适合谁 | 需要开箱即用输入输出过滤的团队 | 强输出格式与质量校验团队 | 对话产品需可编程护栏的团队 | 需模型级审核并自行微调的团队 |