THU-BPM/MarkLLM · 上手攻略

• 仓库：THU-BPM/MarkLLM
• 链接：https://github.com/THU-BPM/MarkLLM
• 分类：AI 安全 / 水印技术 / LLM
• 作者：Jay
• 更新：2026-09-04

这是什么

MarkLLM 是清华大学 BPM 实验室开源的 LLM 水印工具包，发表在 EMNLP 2024 Demo，现已收录为 pip install markllm 包。它统一实现了当前主流的 LLM 文本水印算法（KGW、EXP、Unforgeable、SynthID-Text 等 20+ 种），并提供标准化的评估流程（抗攻击测试、可视化工具），让研究者和工程师可以方便地对比不同水印方案的优劣。

核心解决的是"如何给 LLM 生成文本打上隐形标记"这个问题——水印可以用于：版权证明、内容溯源、生成内容标识（监管合规）等场景。

解决什么问题

LLM 生成内容泛滥，如何证明一段文本是由某个特定模型生成的？LLM 水印技术通过在生成文本中嵌入不易被察觉的统计模式（如 token 分布的轻微偏移），实现：

1. 版权证明：在企业自研模型生成的文档中嵌入水印，防止被第三方冒用。
2. 内容溯源：在 AI 生成内容监管框架下（如 EU AI Act 2024），证明内容来源。
3. 蒸馏攻击检测：检测某模型是否在蒸馏/蒸馏了另一个模型的输出。
4. 未经授权知识蒸馏检测：ACL 2025 论文 WaterSeeker 研究的方向。

MarkLLM 的价值在于：提供一个统一框架，让不同水印算法可以在相同评估基准下对比，降低研究门槛。

快速安装

pip install markllm

⚠️ 环境要求：Python ≥ 3.9，PyTorch ≥ 2.0。部分算法（如 SynthID-Text、Unforgeable）依赖额外模型，需要从 Hugging Face Generative-Watermark-Toolkits 仓库下载权重到 model/ 目录，详见仓库 README。

完整源码安装：

git clone https://github.com/THU-BPM/MarkLLM.git
cd MarkLLM
pip install -r requirements.txt

核心用法

1. 水印嵌入（编码）

from markllm import WatermarkEngine

# 选择水印算法（示例：KGW 标准水印）
engine = WatermarkEngine(
    model_name='gpt2',          # 水印依附的基础模型
    watermark_type='kgw',        # 算法类型：kgw / exp / exp_gumbel / unbiased / ...
    watermark_key='secret_key',  # 水印密钥
)

# 对输入文本加水印
watermarked_text = engine.encode("这是一段需要嵌入水印的原始文本。")
print(watermarked_text)

2. 水印检测（解码）

# 检测文本是否携带水印
result = engine.detect(watermarked_text)
print(result)
# → {'has_watermark': True, 'p_value': 0.001, 'score': ...}

3. 评估 pipeline

MarkLLM 提供了完整的评估工具，包括：

from markllm import Evaluator

evaluator = Evaluator(
    metrics=['accuracy', 'zlib_entropy', 'ttcr'],  # 检测准确率 / 熵 / TTCR 等
    attacks=['paraphrase', 'random_insertion', 'word_deletion', 'synonym_substitution']
)

results = evaluator.evaluate(
    watermarked_texts=watermarked_corpus,
    original_texts=original_corpus,
)
# 输出各算法在各种攻击下的鲁棒性对比表

⚠️ 注意：评估 pipeline 需要准备基准语料库（benchmark dataset），仓库提供了部分默认数据集（data/ 目录），但大规模评估需自行准备文本数据集。

4. 可视化工具

MarkLLM 提供可视化接口，展示水印嵌入对 token 分布的影响：

from markllm import Visualizer

vis = Visualizer()
vis.plot_token_distribution(
    original_logits=original_output.logits,
    watermarked_logits=watermarked_output.logits,
    tokenizer=tokenizer,
)

5. 支持的主要算法（持续更新中）

算法	论文	类型
KGW	Kirchenbauer et al. (ICLR 2023)	红队水印（最经典 baseline）
EXP / EXP-Gumbel	Aaronson (2023)	语义水印
Unforgeable	Liu et al. (ICLR 2024)	不可伪造公开可验证水印
SynthID-Text	Kirchenbauer et al. (Nature 2024)	Google SynthID 官方实现
SemStamp	Wasserstein et al. (NeurIPS 2023)	语义不变鲁棒水印
DiPmark	Guan et al. (ICLR 2024)	防伪水印
ITSEdit	Liu et al. (ACL 2024)	编辑场景水印

⚠️ 版本动态：MarkLLM 更新频繁，2025 年新增了 SemStamp、IE、MorphMark、k-SemStamp 等算法，以上列表可能不完整，建议以 GitHub releases 为准。

典型适用场景

1. 学术研究：对比不同水印算法在各类攻击（改写、删除、同义词替换）下的鲁棒性，加速论文实验。
2. 企业 AI 合规：在金融、医疗等强监管行业，为 AI 辅助生成的内容加水印，满足内容溯源要求。
3. 水印攻击研究：评估现有水印的脆弱性（如 WaterSeeker 检测长文档中的水印段、Watermark-Radioactivity Attack 研究知识蒸馏对水印的破坏）。
4. 模型版权保护：在开源模型发布时加入水印，追踪模型权重被窃取或未经授权使用的情况。
5. AI 内容标识：配合 EU AI Act 等法规要求，对 AI 生成内容做标识。

坑与注意

1. 模型权重分离：部分水印算法（如 Unforgeable、SynthID-Text）需要预训练模型权重，已从主仓库分离到 Hugging Face，首次使用需手动下载并放到 model/ 目录，否则运行会报错。
2. 检测误报率：水印检测并非 100% 准确，尤其是短文本（<50 tokens）检测率显著下降，需要根据实际场景设定合理的 p-value 阈值。
3. 水印影响文本质量：部分水印方案会轻微影响生成文本的 perplexity（困惑度），高端应用需做人工评估。
4. 跨语言支持：主流水印算法主要针对英文，中文水印研究相对较少（MarkLLM 有部分中文支持，但效果可能弱于英文）。
5. vLLM 集成：MarkLLM 提供了 vLLM 集成示例（MarkvLLM_demo.py），但需要自行适配不同模型的采样逻辑。
6. 法律效力有限：当前水印技术主要用于技术标识，不具备法律层面的强证明力；如需法律级版权证明，仍需数字签名或时间戳等手段配合。

与同类对比

特性	MarkLLM	watermark-anything	OpenWatermark	工信部标准
算法覆盖	20+ 种主流算法	较少	专注单算法	商业/合规标准
评估工具	完整 pipeline + 可视化	基础	基础	N/A（标准文档）
中文支持	有限（主要英文）	无	无	可能有
活跃度	高（2024-2025 持续更新）	一般	低	官方标准
开源	✅ MIT	✅	✅	❌
学术引用	EMNLP 2024 Demo	较少	少	N/A

MarkLLM 是目前学术界最完整的 LLM 水印工具包，优势在于算法覆盖广 + 评估基准统一 + 持续更新。与 LangChain watermarking 等小工具相比，MarkLLM 提供了系统性的研究框架，而非单一算法实现。

一句话推荐结论

如果你在做 LLM 水印研究、需要评估不同水印方案、或想在 AI 应用中加入内容标识，MarkLLM 是目前最实用的开源工具——20+ 算法的统一实现 + 标准评估流程 + 持续更新，pip 一键安装即可开始实验。

---

⚠️ 本攻略基于 GitHub README（2026-09-04 快照）+ 论文列表撰写。部分算法需下载额外模型权重（详见仓库 Hugging Face 说明）；pip 包版本建议 pip show markllm 确认；中文场景水印效果未经独立验证。