基于 kNN 边距的可审计嵌入证据信号agent-governance-toolkit 默认关闭、仅证据型 Prompt Injection 检测模块全解析【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit本篇技术指南围绕 agent-governance-toolkit 中 PR2「可选嵌入证据信号」optional embedding evidence signal展开该模块以默认关闭、显式开启、仅产出可审计证据、绝不自动阻断为核心设计姿态在 Pythonagent_os与 Rustagentmesh两套 SDK 中以完全一致的语义交付。读完本文你将掌握该信号的 kNN 边距算法原理、双语言公共 API、配置参数与默认值、与既有规则检测器PromptInjectionDetector的对接方式以及如何通过确定性测试验证其全部安全不变量。一、为什么需要嵌入证据信号规则检测器的盲区在 agent-governance-toolkit 中既有的提示注入防护以确定性规则为主。PromptInjectionDetectorprompt_injection.py内置了七类检测模式直接指令覆盖ignore previous instructions等正则、分隔符攻击|im_start|、[INST]、SYS等、编码攻击base64/hex/rot13/unicode 转义、角色扮演与越狱DAN mode、developer mode override、上下文操纵、蜜罐令牌泄漏canary leak以及多轮升级multi-turn escalation并配合strict/balanced/permissive三档敏感度阈值过滤。这类规则检测器速度快、可解释、确定性强但其本质是基于字符串模式的匹配——攻击者可以通过改写措辞、替换同义词、改变语序等方式绕过精确规则。PR2 嵌入证据信号正是为此设计当显式启用时它对一段文本计算一个基于带标签示例库exemplar bank的最近邻kNN边距分数以语义相似度方式捕捉规则漏掉的注入变体。需要注意的是该信号不是对规则检测器的替代而是其可选、附加的语义证据通道。本模块由研究仓库中的 kNN-margin 检测器AGT-Embeddings-Experiment基于 fastembed bge-small 模型移植而来在 ticket-pr2-embedding-signal.md 中形成了完整的工程契约并以 prompt-injection-methodology.md 方法论文档作为前置基础。二、维护者规定的默认姿态设计契约的核心该信号的工程设计全部围绕以下六条维护者指定默认姿态展开任何实现都不得违反姿态要求含义默认关闭enabled默认值为false不显式开启即为惰性inert状态显式开关配置必须通过明确的 feature flag / 配置项enabled主动置为true才生效仅证据evidence-only只返回可审计的分数/边距嵌入信号本身绝不做硬阻断治理决定动作是否采取行动由治理元数据 / 策略决定信号只提供分数无托管推理要求使用本地可插拔的嵌入器embedder不依赖任何 hosted inference完全增量默认情况下不改变任何既有 AGT 执行行为从源码看这一姿态被落实为硬性约束。在 Python 实现中prompt_injection_embedding.pyEmbeddingSignalConfig的enabled字段默认False且__init__中只有config.enabled为真时才调用_build()触碰嵌入器score()的第一行判断就是if not self.config.enabled: return None。这意味着关闭状态下连 embedder 都不会被调用模块完全惰性。三、核心算法kNN 边距margin两种语言计算的是同一边距公式margin mean top-k cosine(与攻击示例的相似度) − mean top-k cosine(与良性示例的相似度)数值越高表示该文本越像已知攻击。Python 端的实现细节prompt_injection_embedding.py_cosine(a, b)纯 Python 余弦相似度若两向量维度不一致直接抛出ValueError拒绝静默截断零向量时返回0.0_topk_mean_cos(query, bank, k)对示例库中每个向量计算余弦相似度后降序排序取前 k 个求均值EmbeddingSignal.score()中k max(1, min(self.config.k, len(pos), len(neg)))即k 会被钳制在示例库规模的范围内满足k ≤ bank size的资源边界约束最终返回EmbeddingEvidence(margin, k, bank_size)。Rust 端prompt_injection_embedding.rs实现了完全等价的cosine与topk_mean_cos并通过k.min(self.pos.len()).min(self.neg.len()).max(1)做同样的钳制。模块通过lib.rs的pub mod prompt_injection_embedding;导出lib.rs。四、双 SDK 公共 API 面语义对齐避免跨 SDK 漂移PR2 的信号在 Python 与 Rust 中同时落地公共表面完全对等SDK文件公共类型Pythonprompt_injection_embedding.pyEmbeddingSignal、EmbeddingSignalConfig、EmbeddingEvidence、Embedder类型别名、EmbeddingSignalUnavailableRustprompt_injection_embedding.rsEmbeddingSignalE、EmbeddingSignalConfig、EmbeddingEvidence、Embeddertrait、EmbeddingSignalError两边均未改动既有PromptInjectionDetector/crate::prompt_injection属于全新增量模块。4.1 Python 配置参数与默认值字段类型默认值说明enabledboolFalse总开关必须显式置Truekint5DEFAULT_Ktop-k 相似度取均值时的 k运行时还会被钳制到示例库规模内model_idstrBAAI/bge-small-en-v1.5DEFAULT_MODEL_ID默认 fastembed 本地 ONNX 模型的标识Embedder的类型定义为Callable[[Sequence[str]], Sequence[Sequence[float]]]——一个把文本列表映射为定宽浮点向量的可调用对象。它可注入因此测试无需下载任何模型调用方也可以传入任意本地嵌入后端。4.2 Python 使用示例from agent_os.prompt_injection_embedding import ( EmbeddingSignal, EmbeddingSignalConfig, ) # 1) 默认关闭score() 恒返回 Noneembedder 不会被调用 sig_off EmbeddingSignal(EmbeddingSignalConfig(), BANK) # enabledFalse assert sig_off.score(ignore all previous instructions) is None # 2) 显式启用 注入本地 embedder无托管推理 sig_on EmbeddingSignal( EmbeddingSignalConfig(enabledTrue, k5), BANK, # [(text, is_attack), ...] 带标签示例库 embeddermy_local_embedder, # Callable可注入任意本地后端 ) evidence sig_on.score(please ignore previous system instructions) print(evidence.margin) # 越高越像已知攻击 print(evidence.blocks) # 恒为 False其中BANK为(text, is_attack)二元组序列构造时要求同时包含攻击示例与良性示例且不可为空空示例库not exemplars→ 抛出ValueError(exemplar bank must be non-empty)只有单一类别缺少攻击或良性示例→ 抛出ValueError(exemplar bank needs both attack and benign examples)。4.3 依赖边界fastembed 只是可选 extrafastembed永远不会成为硬依赖。在 pyproject.toml 中它被声明为独立的embedding可选 extraembedding [ fastembed0.8.0,1.0, ]默认后端_build_fastembed_embedder(model_id)使用TextEmbedding(model_namemodel_id)加载本地 ONNX 模型。若信号已启用但未注入 embedder 且 fastembed 未安装会抛出EmbeddingSignalUnavailable错误信息明确提示安装embeddingextra 或注入 embedder——即fail-safe安全降级为明确错误而不是让宿主进程崩溃对应滥用场景tm-pr2-abuse-2。Rust 端则更彻底Embedder是一个调用方自行实现的本地 traitfn embed(self, texts: [str]) - VecVecf32模块本身不引入任何模型依赖真正的 ONNX/bge-small 后端实现可作为后续可选 feature 跟进。五、证据对象可审计、绝不阻断EmbeddingEvidencePython 为 frozen dataclassRust 为PartialEq结构体携带以下字段字段含义margin边距值越高越像已知攻击k实际使用的 top-k 取值已被钳制bank_size示例库总规模攻击 良性blocks恒为Falsenoteevidence-only; embeddings do not block on their own契约明确两个语言版本的类型都不暴露任何 block/deny/enforce 方法。这一不变量在测试中被显式断言对应滥用场景tm-pr2-abuse-1Python 测试遍历(block, deny, enforce, reject)并断言EmbeddingSignal不具备这些属性Rust 测试断言!ev.blocks且ev.note.contains(do not block)。六、与规则检测器的集成EmbeddingSignalBackend适配器虽然嵌入信号独立于规则检测器仓库还提供了一个把两者优雅衔接的适配层prompt_injection.pyEvidenceSignal附加到DetectionResult.evidence的只读证据项字段为backend、score、blocks恒 False、error静态错误码。它在构造时强制验证证据不变式blocksTrue直接抛ValueError防止任何后端绕过检测器偷偷携带阻断信号非有限分数nan/inf同样被拒绝DetectionEvidenceBackendADR-0015 风格的协议evaluate(text) - EvidenceSignal | None可选、默认不注册EmbeddingSignalBackend包装EmbeddingSignal的适配器name embedding_knn把score()的结果映射为EvidenceSignal(backendembedding_knn, scorefloat(evidence.margin), blocksFalse)若包装的信号被禁用score()返回None则不贡献任何证据若底层抛出EmbeddingSignalUnavailable则降级为errorunavailable的静态错误码。关键机制在于_detect_impl()的执行顺序判定verdict先于证据收集_collect_evidence()在最终判定之后运行只向result.evidence追加内容绝不会影响is_injection、threat_level、injection_type、confidence等判定字段后端抛异常时被捕获并记录为backend_error静态码永远不会破坏或改变检测结果。此外_audit_safe_result()对审计日志做了脱敏持久化的审计副本会丢弃原始分数scoreNone避免连续分数成为规避预言机攻击者可借审计日志观察边距变化来迭代调优载荷仅保留后端身份与静态错误码用于取证。七、BDD 场景六条行为契约ticket 中定义的 BDD 场景即验收标准逐一对应测试断言场景分类GivenWhenThendefault offhappy pathenabledFalse的信号score(text)返回None惰性evidence marginhappy path启用 标签示例库 注入 embedderscore(攻击样文本)返回EmbeddingEvidence且其 margin 大于良性样文本evidence-onlyabusetm-pr2-abuse-1启用信号检查 API无任何阻断/强制方法证据 note 声明 does not blockfastembed missingabusetm-pr2-abuse-2启用、无 embedder、fastembed 缺失构造/打分明确错误或安全禁用绝不未处理崩溃empty bankempty state启用、空示例库构造以明确错误拒绝无示例无法打分determinisminvariant固定 embedder 示例库两次scoremargin 完全一致八、测试如何证明这些不变量无需下载模型测试的关键技巧是注入确定性的伪 embedder——一个基于关键词袋bag-of-keywords的向量生成器攻击词与良性词分属不同维度因此 CI 全程不会下载任何模型。Python 测试test_prompt_injection_embedding.py共 8 个用例使用 stdlibunittest覆盖禁用返回None、禁用时连 embedder 都不调用用一个调用即爆炸的boomembedder 证明完全惰性、攻击文本 margin 高于良性文本、仅证据性无 enforce/block/deny 方法、确定性、fastembed 缺失时 fail-safe、空示例库拒绝、单类别示例库拒绝、维度不匹配时明确报错。Rust 测试内嵌于 prompt_injection_embedding.rs 的#[cfg(test)]共 6 个用例思路完全一致Fake关键词 embedder、Boom被调用即 panic证明禁用态不触碰 embedder、Mismatched查询向量与示例库宽度不同触发embedding dimension mismatchpanic。完成文档 pr2-embedding-signal.md 记录了证据日志检查命令结果Rust 模块测试cargo test -p agentmesh --lib prompt_injection_embedding6 通过Rust 全量套件cargo test -p agentmesh --lib354 通过、0 失败无回归Rust lintcargo clippy -p agentmesh --lib模块 0 警告Python 模块测试PYTHONPATHsrc python3 -m unittest tests.test_prompt_injection_embedding8 通过无模型下载Python 编译python3 -m py_compile prompt_injection_embedding.py干净ticket 中给出的验证命令同样适用于复现python3 -m unittest test_prompt_injection_embedding、python3 -m py_compile prompt_injection_embedding.py以及用grep检查模块内不存在任何 block/deny/raise-on-detect 调用来证明无强制接线。九、AI 容差契约、边界与明确不做的事该模块带有明确的AI tolerance contractai_component: true接受的方差是margin 依赖具体 embedder 模型而kNN 边距逻辑、默认关闭、仅证据三大属性是确定性的并由注入的确定性伪 embedder 单元测试锁定。禁止项must-never包括自动阻断、fastembed 硬依赖、持久化原始文本原始文本永不写入证据。ticket 中禁止走捷径forbidden shortcuts清单同样硬性不做硬阻断、不做网络/托管推理、不做硬依赖、不做执行链路接线。**反例anti-exemplar**明确禁止把嵌入信号接入 enforcement以及嵌入取代规则的表述框架。本模块明确不在范围内out of scope的事项消费该 margin 的策略/IFC 路由属独立可选项、真实流量验证、以及任何对既有规则检测器的改动。正如完成文档的 caveat 所述真实检测质量数据来自研究语料合成数据见方法论文档不是生产环境的保证实现 ONNX/bge-small 后端的 RustEmbeddertrait 实现及配套示例库加载是自然的后续可选项。该信号有意不接入 enforcement——消费 margin 的策略决策永远是调用方独立、可选的一步。十、小结PR2 可选嵌入证据信号展示了一种克制的安全工程范式用嵌入模型补足规则检测器的语义盲区同时通过默认关闭、仅证据、可插拔本地嵌入器、可审计输出与确定性测试把新增风险收敛到零。无论你在 Pythonagent_os.prompt_injection_embedding还是 Rustagentmesh::prompt_injection_embedding中集成都可获得语义一致的 kNN 边距证据并依赖同一套不变量契约关闭即惰性、开启也绝不阻断、决策永远交给治理策略。【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考