jsdnaasd/rag-trace-auditor

# RAG Trace 审计员 RAG Trace Auditor 是一个小型 Python CLI，用于在运行后审查检索增强生成（RAG）和 Agent 的 trace。它会读取 JSONL trace，将每个回答句子与检索到的 chunk 进行比较，标记指向缺失 chunk 的引用，并报告在检索文本中发现的 prompt injection 标记。 RAG Trace Auditor 是一个小型 Python 命令行工具，用于在 RAG 或 Agent 运行结束后检查 trace。它会读取 JSONL，比较回答句子和检索片段，发现不存在的引用，并提示检索内容里的 prompt injection 风险。 ## 已实现的功能 - 带有明确校验错误的 JSONL trace 加载器。 - 使用 token overlap 和引用提示的确定性句子到 chunk 支持度评分。 - 针对 `[policy-2026]` 等括号引用的引用漂移检查。 - 检索 chunk 中的 prompt injection 标记检测。 - 输出 JSON、Markdown 和独立 HTML 报告。 - 用于 CI 或预发布检查的 `--fail-under` 门槛。 - 针对无支持声明、缺失引用和 injection 标记的单元测试。 中文说明： - 支持读取 JSONL trace，并在格式错误时给出明确错误。 - 使用可复现的 token overlap 方法评估回答句子是否被检索片段支持。 - 检查类似 `[policy-2026]` 的引用是否真的存在于 retrieved chunks。 - 检查检索片段中常见的 prompt injection 字样。 - 可输出 JSON、Markdown 和独立 HTML 报告。 - 提供 `--fail-under`，方便在 CI 中设置质量门槛。 - 包含覆盖核心逻辑的单元测试。 ## 架构 本项目刻意保持简单： - `rag_trace_auditor.analyzer` 加载 trace 记录，对回答句子和检索 chunk 进行分词，评估支持度，并汇总 trace 级别的指标。 - `rag_trace_auditor.render` 将结构化的审计结果转换为 Markdown 或独立 HTML 报告。 - `rag_trace_auditor.cli` 提供命令行入口和 CI 阈值行为。 - `examples/traces.jsonl` 包含两个示例 trace：一个包含无支持的声明，另一个包含检索到的 injection 标记。 - `docs/` 包含 GitHub Pages 演示文稿和生成的示例报告。 中文说明： - `analyzer` 负责读取 trace、分词、句子支持度评分和汇总指标。 - `render` 负责把结构化结果渲染成 Markdown 或 HTML。 - `cli` 负责命令行参数和质量门槛退出码。 - `examples/traces.jsonl` 提供带有问题的示例数据。 - `docs/` 用作 GitHub Pages 展示和示例报告。 ## 如何运行 使用 Python 3.10 或更高版本。 ``` cd /Users/Zhuanz1/Documents/rag-trace-auditor python3 -m venv .venv source .venv/bin/activate python -m pip install -e . rag-trace-auditor examples/traces.jsonl \ --json-out reports/audit.json \ --markdown-out reports/audit.md \ --html-out reports/audit.html ``` 你也可以在不安装的情况下运行： ``` PYTHONPATH=src python -m rag_trace_auditor.cli examples/traces.jsonl ``` 预期的 trace 格式： ``` {"id":"trace-1","question":"...","answer":"Answer sentence [chunk-a].","retrieved":[{"id":"chunk-a","text":"...","source":"https://example.com/doc"}]} ``` 中文说明： 项目只依赖 Python 标准库。安装为 editable package 后可以直接使用 `rag-trace-auditor` 命令；也可以用 `PYTHONPATH=src` 直接运行模块。 ## 验证 / 测试 运行单元测试： ``` PYTHONPATH=src python -m unittest discover -s tests ``` 生成示例报告： ``` rag-trace-auditor examples/traces.jsonl \ --json-out docs/sample-audit.json \ --markdown-out docs/sample-audit.md \ --html-out docs/sample-report.html ``` 使用 CI 式阈值： ``` rag-trace-auditor examples/traces.jsonl --fail-under 0.50 ``` 中文说明： `pytest` 会验证核心判断逻辑。示例报告会写入 `docs/`，可以直接用于 GitHub Pages。`--fail-under` 会在平均分低于阈值时返回非零退出码，适合接入 CI。 ## 已知限制 - 支持度评分基于词法而非语义。它会漏掉没有共享足够词汇的改写句子。 - 它不会调用 LLM judge，也不验证检索到的 chunk 本身是否真实。 - 引用解析目前侧重于诸如 `[chunk-id]` 之类的括号引用。 - injection 检测使用已知的字符串模式，无法捕获所有对抗性措辞。 - HTML 报告是本地静态文件，而不是托管的观测后端。 中文说明： - 当前支持度评分是词面匹配，不是语义匹配。 - 工具不会调用 LLM judge，也不会判断检索片段本身是否真实。 - 引用解析主要支持 `[chunk-id]` 这种格式。 - prompt injection 检测是规则型的，无法覆盖所有变体。 - HTML 报告是静态文件，不是完整的线上观测系统。 ## 路线图 - 添加可选的、基于 embedding 的语义支持度评分。 - 为常见的 LangChain 和 LlamaIndex trace 导出添加适配器。 - 添加 GitHub Action 示例，将审计摘要评论到 pull request 上。 - 添加可配置的项目专属 injection 模式和引用格式。 中文说明： - 增加可选的 embedding 语义支持度评分。 - 增加对 LangChain 和 LlamaIndex trace 导出的适配。 - 增加 GitHub Action 示例，把审计摘要评论到 PR。 - 支持项目自定义的 injection 规则和引用格式。

标签：DLL 劫持, RAG, 人工智能, 代码审查, 大语言模型, 文档结构分析, 用户模式Hook绕过, 聊天机器人, 逆向工具