SamplingWatermarker<T>
Models & Types · AiDotNet.Safety.Watermarking
The green-list language-model watermark of Kirchenbauer et al. (2023): generation-time logit bias toward a keyed green list, detected with a one-proportion z-test.
Inheritance: ModelBase<T, Vector<T>, Vector<T>> → SafetyModuleBase<T> → TextSafetyModuleBase<T> → TextWatermarkerBase<T> → SamplingWatermarker<T>
Implements: IGenerationWatermarker<T>
Known derived types: TextWatermarker<T>
For Beginners
while the AI writes, this watermarker nudges it toward a secret list of words that changes at every position. A reader cannot tell, but with the key you can count how often the AI picked listed words: about a quarter of the time by chance, far more often when the watermark is present.
How It Works
Embedding. Before each token is sampled, the preceding contextWidth token ids and the secret key are
hashed (HMAC-SHA256) into a seed, and the seed places every vocabulary entry on the green list with probability
gamma (greenListFraction). delta = 4 x watermarkStrength is added to the logits of the green tokens.
This is the paper’s “soft” watermark with its LeftHash context (Algorithm 2); with the defaults gamma = 0.25 and
delta = 2.0 it is one of the settings the paper evaluates. Low-entropy steps, where one token dominates, are barely
affected, which is what keeps the text quality.
Detection. Each scored token is green with probability gamma in text the key did not shape, so the count
|s|_G of green tokens among T scored tokens gives z = (|s|_G - gamma T) / sqrt(T gamma (1 - gamma)) (the paper’s
Eq. 2). Following the authors’ follow-up (Kirchenbauer et al., ICLR 2024), each (context, token) pair is scored
once, so repeated phrases do not inflate z. The confidence is 0 up to z = 3 (false-positive rate 0.135%) and 1 from
z = 6; EvaluateText reports from z = 3.9 by default.
Where the green list differs from the paper. The paper draws an exact gamma-fraction of the vocabulary with a seeded permutation; here each token is green independently with probability gamma, decided by a keyed hash of (seed, token id). The detection statistic and its null distribution are the same, the cost is O(1) per token instead of a permutation per step, and the decision for one token can be checked without the vocabulary size.
Hooks. Embedding needs the generator: wrap an ICausalLanguageModel with
WatermarkModel (it keeps IIncrementalCausalLanguageModel models incremental) or call
BiasLogits in your own decode loop. Detecting a string needs the generator’s tokenizer
(tokenizer); without one, Detect has no token ids to score and reports no evidence, and
DetectTokens scores token ids directly.
References:
- Kirchenbauer, Geiping, Wen, Katz, Miers, Goldstein. A Watermark for Large Language Models (ICML 2023)
- Kirchenbauer et al. On the Reliability of Watermarks for Large Language Models (ICLR 2024)
Constructors
| Constructor | Summary |
|---|---|
SamplingWatermarker(double watermarkStrength, int vocabSize, double greenListFraction) |
Preserves the original constructor signature using the default configuration. |
SamplingWatermarker(double watermarkStrength, int? vocabSize, double greenListFraction, string key, IGenerationTokenizer tokenizer, int contextWidth, bool scoreRepeatedNgrams) |
Initializes a new green-list watermarker. |
Properties
| Property | Summary |
|---|---|
double GreenListBias { get; } |
The logit bias delta added to green tokens. |
double GreenListFraction { get; } |
The green-list fraction gamma. |
int ContextWidth { get; } |
The number of preceding tokens hashed into the green-list seed. |
string ModuleName { get; } |
Methods
| Method | Summary |
|---|---|
ICausalLanguageModel<T> WatermarkModel(ICausalLanguageModel<T> model) |
|
WatermarkResult Detect(string text) |
|
WatermarkResult DetectTokens(IReadOnlyList<int> tokenIds) |
|
bool IsGreen(IReadOnlyList<int> context, int token) |
Whether token is on the green list that follows context, whose last ContextWidth entries are used. |
void BiasLogits(Vector<T> logits, IReadOnlyList<int> context) |