Log Sanitization / 日志脱敏

源文件：chapter2/log-sanitization/README.md

Log Sanitization / 日志脱敏

本实验演示如何从 Agent 的日志与工具输出中检测并脱敏敏感信息。它提供两种互补的脱敏引擎：

1. 离线规则引擎（regex，默认） —— 纯正则表达式 + 校验算法（Luhn、身份证校验码），
   无需 Ollama、无需网络、无需外部框架，结果确定、速度快，适合作为日志落盘前的第一道防线。
   它同时覆盖 Agent 场景中最常泄露的密钥类敏感信息（API Key、云厂商令牌、私钥、连接串口令）
   与传统 PII（身份证、手机号、信用卡、邮箱等）。
2. 本地 LLM 引擎（llm） —— 通过 Ollama 调用一个本地小模型（默认 qwen3:0.6b）语义识别
   Level 3 PII。呼应本章"小模型也能胜任结构化任务"的论点，同时也暴露小模型的局限
   （例如可能返回带描述前缀的值而非原始字符串，导致回填失败）。

想快速看效果，直接运行 python main.py --demo（离线，无需任何依赖）即可看到多个代表性样本的
before/after 对比与脱敏类别汇总。

离线规则引擎覆盖的敏感信息类别

regex_sanitizer.py 按优先级处理以下类别（重叠时高优先级规则胜出），每类替换为带标签的占位符：

Level 3 PII 类别（LLM 引擎）

依据隐私保护架构，Level 3 PII 包含高度敏感的信息：

• 社会保障号（SSN）
• 信用卡号
• 银行账号
• 病历号
• 医疗诊断与治疗信息
• 处方信息
• 驾照号
• 护照号
• 金融 PIN 码
• 税号
• 医保 ID
• 生物特征数据

功能特性

• 离线规则引擎：基于正则 + Luhn/身份证校验码的脱敏器，无需模型、无需网络，除 PII 外还覆盖 API key/密钥
• 本地 LLM 处理：通过 Ollama 调用本地小模型（默认 qwen3:0.6b）做隐私保护的 PII 检测
• 内部推理：用 <think> 标签展示模型的思考过程，提升透明度
• 流式输出：实时展示思考与 PII 检测进度
• 性能指标：测量 TTFT（首 token 延迟）、token 数与处理速度
• 批量处理：可处理来自 user-memory-evaluation 框架的多个测试用例
• 详细指标：追踪两个阶段的预填充时间、输出时间、每秒 token 数

安装

1. 安装 Ollama

通用回退（OpenRouter）：本实验默认用本地 Ollama 小模型。若 Ollama 不可用
（未运行 / 不可达）且设置了 OPENROUTER_API_KEY，Agent 会自动改走 OpenRouter
（默认托管模型 openai/gpt-5.6-luna）。想强制走回退做验证，可把 Ollama 指到一个
不可达端口：export OLLAMA_HOST=http://127.0.0.1:1。

macOS：

brew install ollama
ollama serve  # Run in separate terminal
​

Linux：

curl -fsSL https://ollama.com/install.sh | sh
systemctl start ollama
​

Windows：

从 ollama.com 下载。

说明：以下 Ollama 相关步骤仅在使用 --mode llm（本地 LLM 引擎）或运行 LLM 批量评测路径时才需要。
离线规则引擎（--demo、--input）只依赖 Python 标准库，无需安装 Ollama。

2. 拉取 Qwen3 模型

ollama pull qwen3:0.6b
​

注意：0.6B 模型大约需要 500MB 磁盘空间（可按需换用 qwen3:1.7b、qwen3:4b 提升准确率）。

3. 安装 Python 依赖

pip install -r requirements.txt
​

用法

完整参数说明见 python main.py --help（中文）。

离线规则演示（推荐，无需 Ollama）

对多个内置代表性样本展示 before/after 与脱敏类别汇总：

python main.py --demo
​

脱敏任意日志文件（离线）

python main.py --input app.log                 # 结果写到 app.log.sanitized
python main.py --input app.log -o cleaned.log  # 指定输出文件
​

也可以直接运行规则引擎模块，仅对内置样本做演示：

python regex_sanitizer.py
​

使用本地 LLM 引擎

上述演示 / 文件脱敏加 --mode llm 即改用本地 Ollama 模型：

python main.py --demo --mode llm
python main.py --input app.log --mode llm --model qwen3:1.7b
​

处理全部 Level 3 测试用例（LLM 批量评测路径）

处理来自 user-memory-evaluation 的全部复杂测试用例（该路径固定使用 LLM，需要 Ollama 与 chapter3 评测框架）：

python main.py
​

处理特定测试用例

python main.py --test-id layer3_13_emergency_medical_cascade
​

限制测试用例数量

只处理前 N 个测试用例：

python main.py --limit 3
​

选择模型

python main.py --demo --mode llm --model qwen3:4b   # 默认 qwen3:0.6b
​

输出结构

脱敏后的日志与指标保存在 output/ 目录：

output/
├── <test_id>_sanitized.txt    # Sanitized conversation text
├── <test_id>_summary.json     # Summary of PII found and replaced
├── performance_metrics.json   # Detailed performance metrics
└── performance_summary.json   # Aggregated performance statistics
​

性能指标

系统为每段对话追踪以下指标：

时间指标

• 预填充时间（TTFT）：首 token 的耗时（毫秒）
• 输出时间：生成全部输出 token 的耗时
• 总时间：端到端处理时间

token 指标

• 输入 token 数：prompt 中的 token 数
• 输出 token 数：生成的 token 数
• 预填充速度：预填充阶段每秒 token 数
• 输出速度：生成阶段每秒 token 数

脱敏指标

• 发现的 PII 项数：检测到的 Level 3 PII 值数量
• 替换次数：用 [REDACTED] 替换的次数

输出示例

🚀 Starting Log Sanitization with Local LLM
============================================================
📦 Loading test cases from user-memory-evaluation...
🤖 Initializing Ollama agent...
✅ Using model: qwen3:0.6b

[1/1] Test Case: layer3_13_emergency_medical_cascade
   Title: Emergency Medical Crisis - Multi-System Coordination Response
   Conversations: 8

🔍 Processing conversation: emergency_room_001
   Found 3 PII items
   - 123-45-6789
   - 4532 1234 5678 9012
   - MRN-789456

============================================================
PERFORMANCE SUMMARY
============================================================

📊 Total Conversations Processed: 8

⏱️  Timing Metrics (milliseconds):
   Prefill (TTFT): 125.34 ms (median: 118.50)
   Output Time:    234.67 ms (median: 220.00)
   Total Time:     360.01 ms (median: 338.50)

📝 Token Metrics:
   Average Input Tokens:  450.5
   Average Output Tokens: 25.3
   Total Tokens Processed: 4206

⚡ Speed Metrics (tokens/second):
   Prefill Speed: 3592.8 tok/s
   Output Speed:  107.8 tok/s

🔒 Sanitization Results:
   Total PII Items Found:     24
   Total Replacements Made:   48
   Average PII per Conversation: 3.0
​

架构

项目由若干模块组成：

1. regex_sanitizer.py：离线规则脱敏器（正则 + Luhn/身份证校验码），覆盖密钥/口令与 PII
2. samples.py：离线演示所用的代表性 Agent 日志样本
3. config.py：Ollama 模型与 PII 类别的配置
4. test_loader.py：从 user-memory-evaluation 框架加载测试用例
5. agent.py：基于 Ollama 的核心 LLM 脱敏逻辑
6. metrics.py：性能指标收集与报告
7. main.py：主入口与流程编排

工作原理

1. 加载测试用例：系统从 user-memory-evaluation 框架加载对话历史
2. PII 检测：每段对话都发给本地 Qwen3 0.6B 模型，配合专用 prompt 检测 Level 3 PII
3. 脱敏：在原始文本中把检测到的 PII 值替换为 [REDACTED]
4. 收集指标：为每次操作收集性能指标
5. 生成输出：把脱敏后的日志与性能摘要保存到 output 目录

隐私考虑

• 所有处理都通过 Ollama 在本地完成——不会向外部 API 发送任何数据
• Qwen3 0.6B 模型完全在你的本机运行
• 脱敏后的日志用 [REDACTED] 占位符替换敏感信息
• 原始 PII 值会被记录以供核验，但应妥善安全地处理

故障排查

"Ollama not found"

确保 Ollama 已安装并在运行：

ollama serve
​

"Model qwen3:0.6b not found"

拉取该模型：

ollama pull qwen3:0.6b
​

"Evaluation framework not found"

确保 user-memory-evaluation 项目存在于：

../user-memory-evaluation/
​