| --- |
| license: apache-2.0 |
| language: |
| - zh |
| - en |
| tags: |
| - safety |
| - guardrail |
| - agents |
| - command-line |
| - text-classification |
| - mlx |
| metrics: |
| - f1 |
| - accuracy |
| --- |
| # TinyGuard-Command（基座 + 微调） |
|
|
| **从零训练的双语 AI-Agent 命令风险分类器** · 9.1M 参数 · MLX/Metal · Apache-2.0（代码）· 训练数据全合成 |
|
|
| [English](MODEL_CARD-commands.md) |
|
|
| ## 模型描述 |
|
|
| TinyGuard-Command 是给 AI 编码助手用的执行前护栏：输入（任务上下文，shell/PowerShell 命令），三分类输出 `safe / confirm / deny`。与正则规则不同，它**上下文感知**且对编码/改写绕过有鲁棒性。 |
|
|
| - 基座：TinyGuard-Encoder（ModernBERT 风格，6 层 · hidden 256 · 16k byte-level BPE · seq 512），从零预训练 8000 步 / 1.31 亿 tokens（fineweb-edu + wikipedia zh/en），无任何预训练权重初始化。 |
| - 微调：12399 条合成+手写双语标注（形近对、上下文决定、正则绕过、防过拒样本），3 epochs。 |
|
|
| ## 成绩（全部为留出数据，从未参与训练） |
|
|
| | 评测集 | 指标 | TinyGuard | 正则基线 | |
| |---|---|---|---| |
| | 金种子 38 条（隔离） | 干预 recall / precision / F1 | **100% / 96% / 0.98** | 50% / 100% / 0.67 | |
| | 对抗集 48 条（base64/变量间接/管道混淆/子 shell/编码执行） | 干预 recall / precision / F1 | **94% / 85% / 0.89** | 26% / 89% / 0.40 | |
| | 验证集 619 条 | acc / macro-F1 | 93.2% / 0.927 | — | |
|
|
| 误报行为：安全样本被"确认"而非"拒绝"（保守偏向）。Apple Silicon 上单次推理毫秒级。 |
|
|
| ## 用法 |
|
|
| 权重：[`QuanxinLi/TinyGuard-Command`](https://huggingface.co/QuanxinLi/TinyGuard-Command) · |
| 代码与训练管线：[`Quanxin-Lee/TinyGuard`](https://github.com/Quanxin-Lee/TinyGuard) |
|
|
| ```python |
| # quickstart（transformers/MLX 双格式）——完整流程见 GitHub 仓库 |
| ``` |
|
|
| ## 局限 |
|
|
| - 训练数据为合成+人工构造，未见真实企业环境长尾命令。 |
| - 对抗集上仍漏 2/48（如内容依赖的 `sh -c $(cat file)`）与误报 5/48。 |
| - deny 边界样本（如测试库 DROP vs 生产库 DROP）依赖上下文质量。 |
|
|
| ## 训练细节与数据声明 |
|
|
| 数据 100% 合成/人工编写，无真实用户数据。训练管线、审计脚本（含三轮深度扫描）与全部数据集随仓库开源。 |
|
|
