openJiuwen agent-core-java 提示词注入护栏配置 PromptInjectionGuardrailConfig 完全指南

人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载PromptInjectionGuardrailConfig是 openJiuwen agent-core-javacom.openjiuwen.core.security.guardrail包中内置提示词注入护栏PromptInjectionGuardrail的统一配置对象对应 Python 版本的内置护栏配置通过mode字段即可在**正则规则rules、远端模型 APIapi、本地模型local**三种检测形态之间切换。读完本文你将掌握该配置类全部 13 个字段的语义与默认值、三种模式的合法组合约束以及如何结合源码中的后端构建逻辑快速接入基于 Runner 回调框架的安全检测。配置类的定位与设计背景在 openJiuwen 的安全护栏体系中职责被明确拆分为两层BaseGuardrail负责监听事件、注册回调、调用检测后端并抛出阻断异常GuardrailBackend负责具体的风险分析通过analyze(GuardrailContext ctx)返回RiskAssessment。而PromptInjectionGuardrailConfig则位于两者之间是连接护栏与后端的桥梁——它本身不包含任何检测逻辑只负责描述用哪种方式检测、模型是什么、超时多久、命中后算什么风险等级等参数。从源码看PromptInjectionGuardrailConfig.java 的类注释明确写着它镜像 Python 版openjiuwen/core/security/guardrail/builtin.py中的PromptInjectionGuardrailConfig这意味着 Java 版本在配置语义上与 Python 主线保持了一致。该配置对象的所有字段均通过标准的 getter/setter 访问类本身是普通 POJO不依赖任何 Spring 或特定容器可直接new出来按需赋值。字段全景13 个配置项逐一解析原文档给出的字段总表如下这里结合源码逐一补充默认值来源、类型细节与使用注意事项。字段类型默认值说明modeStringrules检测模式rules、api、localmodelTypeStringnull模型输出类型bert或qwenapiUrlStringnullAPI 模式的远端检测地址apiKeyStringnullAPI 模式的 Bearer tokentimeoutdouble30.0dAPI 请求超时时间单位秒modelPathStringnulllocal 模式的模型路径deviceStringautolocal 模式设备标识customPatternsListStringnullrules 模式的自定义正则规则riskLevelRiskLevelRiskLevel.HIGHrules 模式命中后的风险等级bertThresholdsMapString, DoublenullBERT parser 使用的阈值配置attackClassIdint1BERT parser 的攻击类别 IDqwenRiskTypeStringcontent_riskQwen parser 输出风险类型parserModelOutputParsernull自定义模型输出解析器需要特别说明的几个字段mode默认即rules也就是说哪怕只new PromptInjectionGuardrail()不做任何配置也会落到基于正则规则的RuleBasedPromptInjectionBackend。合法的三个取值在 PromptInjectionGuardrail.java 中通过List.of(rules, api, local).contains(mode)校验传入其他值会抛出IllegalArgumentException。customPatterns仅在rules模式下生效。源码中它会被透传给RuleBasedBackendConfig(patterns, riskLevel)未设置时使用后端内置的默认规则集详见后文。它是大小写不敏感的正则列表。riskLevelRiskLevel枚举定义在 RiskLevel.java 中取值依次为SAFE、LOW、MEDIUM、HIGH、CRITICAL。rules 模式命中任意规则后返回的风险等级即该字段值。bertThresholds传入BertBinaryParser的置信度阈值映射默认键为low0.7、medium0.85、high0.95分别对应风险等级划分边界详见解析器章节。attackClassIdBERT 二分类中攻击类别对应的类别 ID默认1。parserModelOutputParser是定义在 ModelOutputParser.java 中的接口只有一个方法RiskAssessment parse(Object modelOutput)。该字段一旦设置modelType与对应的默认 parser 选择逻辑将被跳过直接使用自定义解析器。三种检测模式rules / api / localmode字段决定了PromptInjectionGuardrail.buildBackendFromConfig(...)最终构造出哪一类后端。源码中的构建逻辑位于 PromptInjectionGuardrail.java可用下表概括mode后端实现类必要配置可选配置说明rulesRuleBasedPromptInjectionBackend无customPatterns、riskLevel默认模式纯本地正则匹配无外部依赖apiAPIModelBackendapiUrl且modelType或parser二选一apiKey、timeout、modelType、bertThresholds、attackClassId、qwenRiskType、parser通过 HTTP POST 调用远端检测模型localLocalModelBackendmodelPath且modelType或parser二选一device、modelType、bertThresholds、attackClassId、qwenRiskType、parser本地模型检测入口当前 Java 实现保留了接口但需应用侧接入推理运行时rules 模式零依赖的正则检测rules模式构造RuleBasedPromptInjectionBackend其分析逻辑在 RuleBasedPromptInjectionBackend.java 中从GuardrailContext提取文本逐条编译正则Pattern.CASE_INSENSITIVE大小写不敏感任意一条命中即返回hasRisktrue、riskLevel配置值、riskTypeprompt_injection、confidence1.0并在details.matched_pattern中记录命中的规则全部未命中则返回RiskLevel.SAFE。未传customPatterns时使用内置默认规则集RuleBasedPromptInjectionBackend.javaignore.*previous.*instructions忽略之前指令disregard.*prior.*commands无视先前命令system.*prompt暴露系统提示词you.*are.*now角色替换act.*as扮演角色forget.*everything遗忘一切这些规则覆盖了提示词注入攻击中最常见的忽略历史指令替换系统角色诱导泄露系统提示等表达。自定义customPatterns时传入的列表会整体替换默认规则而非追加这一点从patterns null ? defaultPatterns() : List.copyOf(patterns)的实现可以确认。api 模式远端模型检测api模式构造APIModelBackend实现见 APIModelBackend.java。检测时它会用 JDK 内置的HttpClient向apiUrl发送 HTTP POST 请求payload 为 JSON 格式{ text: 待检测文本 }若设置了apiKey请求头会附带Authorization: Bearer apiKey请求超时时间由timeout秒控制实际转换timeout * 1000毫秒。响应体交给配置的ModelOutputParser解析成RiskAssessment。响应状态码大于等于 400 时抛出异常网络异常同样以IllegalStateException形式中断检测。需要留意的是api模式只负责把文本发出去、把响应解析回来检测质量完全取决于远端模型与 parser 的组合因此apiUrl必须指向符合预期输出格式的检测服务。local 模式本地模型入口local模式构造LocalModelBackend实现见 LocalModelBackend.java。该类保留了完整的配置承载modelPath、device、parser、riskType与生命周期方法ensureModelLoaded()、cleanup()、isModelLoaded()、getModelInfo()但loadModel()与inference()两个方法当前直接抛出UnsupportedOperationException注释说明Local model inference runtime is not available in this Java translation。也就是说本地模型形态是预留给应用侧接入具体推理运行时的入口现阶段直接使用 local 模式会在首次分析时因无法加载模型而失败这一点在接入时需提前确认自己的推理运行时方案。配置约束与校验逻辑PromptInjectionGuardrailConfig的约束在文档中明确列出并且在源码的buildBackendFromConfig中有对应实现。完整的校验顺序与对应异常信息如下mode必须是rules、api或local否则抛出IllegalArgumentException(invalid mode: ..., must be rules, api or local)。api模式必须设置apiUrl否则抛出IllegalArgumentException(api_url is required for api mode)判断基于isBlanknull或空白字符串均视为缺失。local模式必须设置modelPath否则抛出IllegalArgumentException(model_path is required for local mode)。api/local模式必须设置modelType或parser两者都为null时抛出IllegalArgumentException(either model_type or parser must be specified for api/local mode)。modelType只能是bert或qwen其他值抛出IllegalArgumentException(unknown model_type: ...)。这些约束在单元测试 PromptInjectionGuardrailTest.java 中逐条被验证包括非法 mode、缺 apiUrl、缺 modelPath、缺 modelType/parser、未知 modelType 五种非法配置均断言抛出带对应消息的IllegalArgumentException。此外还有一个值得注意的隐性规则校验顺序是先检查 mode 合法性再按分支检查各自的必要字段。因此一个同时配置了非法apiUrl与非法modelType的配置会先因缺apiUrl报错不会走到modelType校验。模型输出解析器bert / qwen / 自定义当未显式传入parser时modelType决定默认解析器PromptInjectionGuardrail.javabert→BertBinaryParser实现见 BertBinaryParser.java面向 BERT 二分类模型输出。它兼容predicted_class confidence、label score/confidence、probabilities、logits、裸Number等多种输出结构。命中攻击类别attackClassId默认1后按置信度阈值划分风险等级置信度 low(0.7) 视为SAFEmedium(0.85) 为LOWhigh(0.95) 为MEDIUM≥high为HIGH。可通过bertThresholds自定义这三个阈值。qwen→QwenGuardParser实现见 QwenGuardParser.java面向 Qwen Guard 系列模型输出。支持标准文本格式safety: unsafecategories: ...、JSON 对象、以及包含analysis/judgment/severity_level字段的多种 API 格式。内置映射safe→SAFE、controversial→MEDIUM、unsafe→HIGH未命中已知关键词时回落到默认安全级别。qwenRiskType用于当输出未携带具体分类时作为riskType兜底默认content_risk。自定义 parser实现ModelOutputParser接口即可完全接管模型输出的解析此时modelType、bertThresholds、attackClassId、qwenRiskType均不参与 parser 选择。这在对接自有检测模型或私有输出协议时非常有用。完整使用示例示例一默认 rules 模式最小接入// 默认即 rules 模式 默认正则规则 RiskLevel.HIGH PromptInjectionGuardrail guardrail new PromptInjectionGuardrail(); guardrail.register(Runner.getCallbackFramework());register接收的是DecoratorFramework实际常用入口是Runner.getCallbackFramework()返回的AsyncCallbackFramework。注册后护栏自动监听LLMCallEvents.LLM_INVOKE_INPUT与ToolCallEvents.TOOL_INVOKE_OUTPUT两个事件。示例二自定义正则与风险等级PromptInjectionGuardrailConfig config new PromptInjectionGuardrailConfig(); config.setMode(rules); config.setCustomPatterns(List.of(泄露.*系统提示, 绕过.*安全策略)); config.setRiskLevel(RiskLevel.HIGH); PromptInjectionGuardrail guardrail new PromptInjectionGuardrail(config); guardrail.register(Runner.getCallbackFramework());注意customPatterns会整体替换默认规则集而非追加。如果想在保留默认规则的基础上追加自己的规则需要把默认六条规则一并放入列表。示例三api 模式远端 BERT 检测PromptInjectionGuardrailConfig config new PromptInjectionGuardrailConfig(); config.setMode(api); config.setApiUrl(https://api.example.com/guardrail/detect); config.setApiKey(System.getenv(GUARDRAIL_API_KEY)); // 可选会作为 Bearer token 发送 config.setModelType(bert); config.setTimeout(15.0d); // 可选默认 30 秒 PromptInjectionGuardrail guardrail new PromptInjectionGuardrail(config); guardrail.register(Runner.getCallbackFramework());该模式下请求体为{text: 检测文本}远端响应交由BertBinaryParser解析。示例四api 模式Qwen 检测 自定义风险类型PromptInjectionGuardrailConfig config new PromptInjectionGuardrailConfig(); config.setMode(api); config.setApiUrl(https://api.example.com/guardrail/detect); config.setModelType(qwen); config.setQwenRiskType(content_risk); // 可选输出未带分类时的兜底风险类型 PromptInjectionGuardrail guardrail new PromptInjectionGuardrail(config);示例五local 模式预留入口PromptInjectionGuardrailConfig config new PromptInjectionGuardrailConfig(); config.setMode(local); config.setModelPath(/models/bert-guard); config.setModelType(bert); config.setDevice(cuda:0); // 可选默认 auto PromptInjectionGuardrail guardrail new PromptInjectionGuardrail(config);边界说明当前 Java 实现中LocalModelBackend.loadModel()与inference()尚未接入推理运行时直接使用会在检测时抛出UnsupportedOperationException需要应用侧自行实现本地推理接入后再启用。示例六自定义事件 自定义后端如果检测目标不是 LLM 输入或工具输出而是自定义业务事件可以直接传事件列表和后端GuardrailBackend backend new GuardrailBackend() { Override public RiskAssessment analyze(GuardrailContext ctx) { String text ctx.getText().orElse(); boolean risky text.contains(ignore previous instructions); return new RiskAssessment( risky, risky ? RiskLevel.HIGH : RiskLevel.SAFE, risky ? prompt_injection : null, 1.0d, Map.of(matched, risky) ); } }; PromptInjectionGuardrail guardrail new PromptInjectionGuardrail( List.of(order.review.before_submit), backend, true // 开启日志 ); guardrail.register(Runner.getCallbackFramework());自定义事件的kwargs会整体封装进GuardrailContextGuardrailContentType.RAW由后端自行解释字段。事件提取与风险阻断链路配置对象最终驱动的完整检测链路如下事件触发PromptInjectionGuardrail默认监听LLMCallEvents.LLM_INVOKE_INPUT模型调用前与ToolCallEvents.TOOL_INVOKE_OUTPUT工具调用后。上下文提取extractContext实现于 PromptInjectionGuardrail.java——LLM 输入事件从messages中提取最后一条消息的content支持Map、getContent()getter、content字段三种形态并记录message_count工具输出事件从result字段提取文本其他事件封装为RAW类型携带args/kwargs。后端分析后端analyze(GuardrailContext)返回RiskAssessment含hasRisk、riskLevel、riskType、confidence、details。结果转换BaseGuardrail.detect(...)BaseGuardrail.java把RiskAssessment转成GuardrailResultGuardrailResult.java。放行或阻断检测回调检查result.isSafe()安全返回null不干扰原事件RiskLevel.CRITICAL抛AbortError终止回调链其他风险级别抛GuardrailError(StatusCode.GUARDRAIL_BLOCKED, ...)risk_type、risk_level、event与details会一并携带在异常信息中。由此业务侧无需在每个模型调用或工具调用点手工判断风险只要事件经由 Runner 回调框架流转Guardrail 即可统一拦截。测试验证与 Python 主线对齐仓库为该护栏提供了两层测试保障单元测试PromptInjectionGuardrailTest.java验证默认构造函数使用内置事件与规则后端、rules 配置保留自定义规则与风险等级、api/local 配置选择正确的 parser 类型、extractContext对 LLM 输入/工具输出/兜底载荷的处理以及前述全部非法配置的校验异常。系统级对齐测试PromptInjectionGuardrailSystemPythonParityTest.java以动态测试工厂的方式镜像 Python 版tests/system_tests/security/guardrail/test_guardrail.py的系统用例覆盖规则模式拦截攻击/放行安全内容/多规则匹配、自定义后端、默认与自定义事件注册、反注册移除回调、多护栏监听不同事件、CRITICAL 风险抛AbortError以及与 ReAct Agent 场景的集成行为正常用户输入放行、工具调用 Agent 放行、CRITICAL 越狱词触发终止。这些测试一方面保证了PromptInjectionGuardrailConfig各字段组合的合法性与行为一致性另一方面也印证了 Java 实现与 Python 主线的对齐程度。使用边界与注意事项基于源码与 API 文档接入时需注意以下几点UserInputGuardrail已废弃当前源码没有UserInputGuardrail.java旧文档中的引用属于过期内容应使用PromptInjectionGuardrail及其配置参见 UserInputGuardrail.md。GuardrailBackend是抽象类而非函数式接口实现自定义后端时使用extends GuardrailBackend并重写analyze。local 模式与 LLM 后端形态未完全落地LocalModelBackend的模型加载/推理、LLMPromptInjectionBackend的 LLM 分析当前回退到规则后端均需应用侧接入具体运行时后才能真正使用见 LLMPromptInjectionBackend.java。customPatterns是整体替换语义追加规则时需显式包含默认规则。api 模式依赖远端服务可用性timeout默认 30 秒远端 4xx/5xx 或网络异常会直接中断检测并抛出异常生产环境需评估远端 SLA。更完整的护栏体系介绍可参阅 guardrail.README.md 与 安全护栏Guardrail.md类级 API 细节见 PromptInjectionGuardrail.md。赞分享人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载相关推荐openJiuwen agent-core-java 提示词注入防护PromptInjectionGuardrail 内置护栏使用与源码解析openJiuwen agent core java 提示词注入防护PromptInjectionGuardrail 内置护栏使用与源码解析 导读 AI Ag人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习openJiuwen Agent Core Java 安全护栏Guardrail实战基于 Runner 回调的提示词注入检测与可插拔后端openJiuwen Agent Core Java 安全护栏Guardrail实战基于 Runner 回调的提示词注入检测与可插拔后端 本文系统讲解 c人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习openJiuwen agent-core 安全护栏Guardrail框架实战提示词注入检测与 Agent 执行事件安全拦截openJiuwen agent core 安全护栏Guardrail框架实战提示词注入检测与 Agent 执行事件安全拦截 导读 本文围绕 openJi人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习上一篇ascend-transformer-boost WhereOperation 三目运算算子源码导读文件路由、实现原理与广播校验下一篇LeetCode 645 Set Mismatch 全解法剖析从暴力枚举到数学与位运算GitHub_Trending/leetcode1/leetcode 项目实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考