initial commit

.gitignore

@@ -0,0 +1,164 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+samples/
+
+**.*ipynb

LICENSE.md

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Abhimanyu Hans, Avi Schwarzschild, Tom Goldstein
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README-doc.md

@@ -0,0 +1,85 @@
+# <img src="./assets/bino-logo.svg" width=40 style="padding-top: 0px"/>  Binoculars: Zero-Shot Detection of LLM-Generated Text [[paper]](https://arxiv.org/abs/2401.12070)
+
+<p align="center">
+  <img src="assets/binoculars.jpg" width="300" height="300" alt="ool Binoculars with Falcon on Top">
+</p>
+
+We introduce Binoculars, a state-of-the-art method for detecting AI-generated text. Binoculars is a
+zero-shot and domain-agnostic (requires no training data) method. It is based on a simple idea: most
+decoder-only, causal language models have a huge overlap in pretraining datasets, for e.g. Common Crawl, Pile, etc.
+More details about the method and results can be found in our paper **Spotting LLMs with Binoculars: Zero-Shot
+Detection of Machine-Generated Text**.
+
+## Getting Started
+
+### Installation
+
+To run the implementation of Binoculars, you can clone this repository and install the package using pip. This code was
+developed and tested on Python This code was developed and tested with Python 3.9. To install the package, run the
+following commands:
+
+```bash
+$ git clone https://github.com/ahans30/Binoculars.git
+$ cd Binoculars
+$ pip install -e .
+```
+
+### Usage
+
+Please note, this implementation comes with a fixed global threshold that is used to classify the input as AI-generated
+or not. This threshold is selected using _Falcon-7B_ and _Falcon-7B-Instruct_ models for scoring. If you want to
+use different scoring models, you can pass it as an argument to the `Binoculars` class. Please read the paper for more
+details about the Binoculars work.
+
+To detect AI-generated text, please use the following code snippet:
+
+```python
+from binoculars import Binoculars
+
+bino = Binoculars()
+
+# ChatGPT (GPT-4) output when prompted with “Can you write a few sentences about a capybara that is an astrophysicist?"
+sample_string = '''Dr. Capy Cosmos, a capybara unlike any other, astounded the scientific community with his 
+groundbreaking research in astrophysics. With his keen sense of observation and unparalleled ability to interpret 
+cosmic data, he uncovered new insights into the mysteries of black holes and the origins of the universe. As he 
+peered through telescopes with his large, round eyes, fellow researchers often remarked that it seemed as if the 
+stars themselves whispered their secrets directly to him. Dr. Cosmos not only became a beacon of inspiration to 
+aspiring scientists but also proved that intellect and innovation can be found in the most unexpected of creatures.'''
+
+print(bino.compute_score(sample_string))  # 0.75661373
+print(bino.predict(sample_string))  # 'AI-Generated'
+```
+
+In the above code, user can also pass a `list` of `str` to `compute_score` and `predict` methods to get results for
+the entire batch of samples.
+
+### Demo
+
+We have also made a demo available to predict AI-generated text interactively with a simple UI
+using [gradio](https://github.com/gradio-app/gradio). You can run the demo using the following command:
+
+```bash
+$ python app.py
+```
+
+## Limitations
+
+All AI-generated text detectors aim for accuracy, but none are perfect and can have multiple failure modes (e.g.,
+Binoculars is more proficient in detecting English language text compared to other languages). This implementation is
+for academic purposes only and should not be considered as a consumer product. We also strongly caution against using
+Binoculars (or any detector) without human supervision.
+
+## Cite our work
+
+If you find this work useful, please cite our paper:
+
+```bibtex
+@misc{hans2024spotting,
+      title={Spotting LLMs With Binoculars: Zero-Shot Detection of Machine-Generated Text}, 
+      author={Abhimanyu Hans and Avi Schwarzschild and Valeriia Cherepanova and Hamid Kazemi and Aniruddha Saha and Micah Goldblum and Jonas Geiping and Tom Goldstein},
+      year={2024},
+      eprint={2401.12070},
+      archivePrefix={arXiv},
+      primaryClass={cs.CL}
+}
+```

app.py

@@ -0,0 +1,5 @@
+from demo.demo import app
+
+if __name__ == "__main__":
+    # Launch the Gradio interface
+    app.launch(show_api=False, debug=True, share=True)

binoculars/__init__.py

@@ -0,0 +1,4 @@
+from config import huggingface_config
+from .detector import Binoculars
+
+__all__ = ["Binoculars"]

binoculars/detector.py

@@ -0,0 +1,84 @@
+from typing import Union
+
+import numpy as np
+import torch
+import transformers
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+from config import huggingface_config
+from .utils import assert_tokenizer_consistency
+from .metrics import perplexity, entropy
+
+torch.set_grad_enabled(False)
+
+GLOBAL_BINOCULARS_THRESHOLD = 0.9015310749276843  # selected using Falcon-7B and Falcon-7B-Instruct at bfloat16
+DEVICE_1 = "cuda:0" if torch.cuda.is_available() else "cpu"
+DEVICE_2 = "cuda:1" if torch.cuda.device_count() > 1 else DEVICE_1
+
+
+class Binoculars(object):
+    def __init__(self,
+                 observer_name_or_path: str = "tiiuae/falcon-7b",
+                 performer_name_or_path: str = "tiiuae/falcon-7b-instruct",
+                 use_bfloat16: bool = True,
+                 max_token_observed: int = 512,
+                 ) -> None:
+        assert_tokenizer_consistency(observer_name_or_path, performer_name_or_path)
+
+        self.observer_model = AutoModelForCausalLM.from_pretrained(observer_name_or_path,
+                                                                   device_map={"": DEVICE_1},
+                                                                   trust_remote_code=True,
+                                                                   torch_dtype=torch.bfloat16 if use_bfloat16
+                                                                   else torch.float32,
+                                                                   token=huggingface_config["TOKEN"]
+                                                                   )
+        self.performer_model = AutoModelForCausalLM.from_pretrained(performer_name_or_path,
+                                                                    device_map={"": DEVICE_2},
+                                                                    trust_remote_code=True,
+                                                                    torch_dtype=torch.bfloat16 if use_bfloat16
+                                                                    else torch.float32,
+                                                                    token=huggingface_config["TOKEN"]
+                                                                    )
+
+        self.observer_model.eval()
+        self.performer_model.eval()
+
+        self.tokenizer = AutoTokenizer.from_pretrained(observer_name_or_path)
+        if not self.tokenizer.pad_token:
+            self.tokenizer.pad_token = self.tokenizer.eos_token
+
+        self.max_token_observed = max_token_observed
+
+    def _tokenize(self, batch: list[str]) -> transformers.BatchEncoding:
+        batch_size = len(batch)
+        encodings = self.tokenizer(
+            batch,
+            return_tensors="pt",
+            padding="longest" if batch_size > 1 else False,
+            truncation=True,
+            max_length=self.max_token_observed,
+            return_token_type_ids=False).to(self.observer_model.device)
+        return encodings
+
+    @torch.inference_mode()
+    def _get_logits(self, encodings: transformers.BatchEncoding) -> torch.Tensor:
+        observer_logits = self.observer_model(**encodings.to(DEVICE_1)).logits
+        performer_logits = self.performer_model(**encodings.to(DEVICE_2)).logits
+        torch.cuda.synchronize()
+        return observer_logits, performer_logits
+
+    def compute_score(self, input_text: Union[list[str], str]) -> Union[float, list[float]]:
+        batch = [input_text] if isinstance(input_text, str) else input_text
+        encodings = self._tokenize(batch)
+        observer_logits, performer_logits = self._get_logits(encodings)
+        ppl = perplexity(encodings, performer_logits)
+        x_ppl = entropy(observer_logits.to(DEVICE_1), performer_logits.to(DEVICE_1),
+                        encodings.to(DEVICE_1), self.tokenizer.pad_token_id)
+        binoculars_scores = ppl / x_ppl
+        binoculars_scores = binoculars_scores.tolist()
+        return binoculars_scores[0] if isinstance(input_text, str) else binoculars_scores
+
+    def predict(self, input_text: Union[list[str], str]) -> Union[list[str], str]:
+        binoculars_scores = np.array(self.compute_score(input_text))
+        pred = np.where(binoculars_scores < GLOBAL_BINOCULARS_THRESHOLD, "AI-Generated", "Human-Generated").tolist()
+        return pred

binoculars/metrics.py

@@ -0,0 +1,57 @@
+import numpy as np
+import torch
+import transformers
+
+ce_loss_fn = torch.nn.CrossEntropyLoss(reduction="none")
+softmax_fn = torch.nn.Softmax(dim=-1)
+
+
+def perplexity(encoding: transformers.BatchEncoding,
+               logits: torch.Tensor,
+               median: bool = False,
+               temperature: float = 1.0):
+    shifted_logits = logits[..., :-1, :].contiguous() / temperature
+    shifted_labels = encoding.input_ids[..., 1:].contiguous()
+    shifted_attention_mask = encoding.attention_mask[..., 1:].contiguous()
+
+    if median:
+        ce_nan = (ce_loss_fn(shifted_logits.transpose(1, 2), shifted_labels).
+                  masked_fill(~shifted_attention_mask.bool(), float("nan")))
+        ppl = np.nanmedian(ce_nan.cpu().float().numpy(), 1)
+
+    else:
+        ppl = (ce_loss_fn(shifted_logits.transpose(1, 2), shifted_labels) *
+               shifted_attention_mask).sum(1) / shifted_attention_mask.sum(1)
+        ppl = ppl.to("cpu").float().numpy()
+
+    return ppl
+
+
+def entropy(p_logits: torch.Tensor,
+            q_logits: torch.Tensor,
+            encoding: transformers.BatchEncoding,
+            pad_token_id: int,
+            median: bool = False,
+            sample_p: bool = False,
+            temperature: float = 1.0):
+    vocab_size = p_logits.shape[-1]
+    total_tokens_available = q_logits.shape[-2]
+    p_scores, q_scores = p_logits / temperature, q_logits / temperature
+
+    p_proba = softmax_fn(p_scores).view(-1, vocab_size)
+
+    if sample_p:
+        p_proba = torch.multinomial(p_proba.view(-1, vocab_size), replacement=True, num_samples=1).view(-1)
+
+    q_scores = q_scores.view(-1, vocab_size)
+
+    ce = ce_loss_fn(input=q_scores, target=p_proba).view(-1, total_tokens_available)
+    padding_mask = (encoding.input_ids != pad_token_id).type(torch.uint8)
+
+    if median:
+        ce_nan = ce.masked_fill(~padding_mask.bool(), float("nan"))
+        agg_ce = np.nanmedian(ce_nan.cpu().float().numpy(), 1)
+    else:
+        agg_ce = (((ce * padding_mask).sum(1) / padding_mask.sum(1)).to("cpu").float().numpy())
+
+    return agg_ce

binoculars/utils.py

@@ -0,0 +1,10 @@
+from transformers import AutoTokenizer
+
+
+def assert_tokenizer_consistency(model_id_1, model_id_2):
+    identical_tokenizers = (
+            AutoTokenizer.from_pretrained(model_id_1).vocab
+            == AutoTokenizer.from_pretrained(model_id_2).vocab
+    )
+    if not identical_tokenizers:
+        raise ValueError(f"Tokenizers are not identical for {model_id_1.name_of_path} and {model_id_2.name_of_path}.")

config.py

@@ -0,0 +1,6 @@
+import os
+
+huggingface_config = {
+    # Only required for private models from Huggingface (e.g. LLaMA models)
+    "TOKEN": os.environ.get("HF_TOKEN", None)
+}

demo/demo.py

@@ -0,0 +1,111 @@
+__all__ = ["app"]
+
+import gradio as gr
+from binoculars import Binoculars
+
+BINO = Binoculars()
+TOKENIZER = BINO.tokenizer
+MINIMUM_TOKENS = 64
+
+
+def count_tokens(text):
+    return len(TOKENIZER(text).input_ids)
+
+
+def run_detector(input_str):
+    if count_tokens(input_str) < MINIMUM_TOKENS:
+        gr.Warning(f"Too short length. Need minimum {MINIMUM_TOKENS} tokens to run Binoculars.")
+        return ""
+    return f"{BINO.predict(input_str)}"
+
+
+# def load_set(progress=gr.Progress()):
+#     tokens = [None] * 24
+#     for count in progress.tqdm(tokens, desc="Counting Tokens..."):
+#         time.sleep(0.01)
+#     return ["Loaded"] * 2
+
+
+css = """
+.green { color: black!important;line-height:1.9em; padding: 0.2em 0.2em; background: #ccffcc; border-radius:0.5rem;}
+.red { color: black!important;line-height:1.9em; padding: 0.2em 0.2em; background: #ffad99; border-radius:0.5rem;}
+.hyperlinks {
+  display: flex;
+  align-items: center;
+  align-content: center;
+  padding-top: 12px;
+  justify-content: flex-end;
+  margin: 0 10px; /* Adjust the margin as needed */
+  text-decoration: none;
+  color: #000; /* Set the desired text color */
+}
+"""
+
+capybara_problem = '''Dr. Capy Cosmos, a capybara unlike any other, astounded the scientific community with his groundbreaking research in astrophysics. With his keen sense of observation and unparalleled ability to interpret cosmic data, he uncovered new insights into the mysteries of black holes and the origins of the universe. As he peered through telescopes with his large, round eyes, fellow researchers often remarked that it seemed as if the stars themselves whispered their secrets directly to him. Dr. Cosmos not only became a beacon of inspiration to aspiring scientists but also proved that intellect and innovation can be found in the most unexpected of creatures.'''
+
+with gr.Blocks(css=css,
+               theme=gr.themes.Default(font=[gr.themes.GoogleFont("Inconsolata"), "Arial", "sans-serif"])) as app:
+    with gr.Row():
+        with gr.Column(scale=3):
+            gr.HTML("<p><h1> binoculars: zero-shot llm-text detector</h1>")
+        with gr.Column(scale=1):
+            gr.HTML("""
+            <p>
+            <a href="https://arxiv.org/abs/2401.12070" target="_blank">paper</a>
+                
+            <a href="https://github.com/AHans30/Binoculars" target="_blank">code</a>
+                
+            <a href="mailto:ahans1@umd.edu" target="_blank">contact</a>
+            """, elem_classes="hyperlinks")
+    with gr.Row():
+        input_box = gr.Textbox(value=capybara_problem, placeholder="Enter text here", lines=8, label="Input Text", )
+    with gr.Row():
+        clear_button = gr.ClearButton()
+        submit_button = gr.Button("Run Binoculars", variant="primary")
+    with gr.Row():
+        output_text = gr.Textbox(label="Prediction", value="AI-Generated")
+
+    with gr.Row():
+        gr.HTML("<p><p><p>")
+    with gr.Row():
+        gr.HTML("<p><p><p>")
+    with gr.Row():
+        gr.HTML("<p><p><p>")
+
+    with gr.Accordion("Disclaimer", open=False):
+        gr.Markdown(
+            """
+            - `Accuracy` :
+                - AI-generated text detectors aim for accuracy, but achieving 100% is challenging.
+                - The provided prediction is for demo purposes only and should not be considered a consumer product.
+                - Users are advised to exercise discretion, and we assume no liability for any use.
+            - `Detection Use Cases` : 
+                - In this work, our focus is to achieve an ultra-low false positive rate, crucial for sensitive downstream use case (e.g., avoiding false accusations in academic honesty cases). 
+                - We find optimal application in content moderation, for example in detecting AI-generated reviews on platforms like Amazon, Google, Yelp, etc. This represents one of the most compelling and noteworthy use cases for Binoculars.
+            - `Human Supervision Advisory` :
+                - Strongly caution against using Binoculars (or any detector) without human supervision.
+            - `Performance by Language` :
+                - As noted in our paper, Binoculars exhibit superior detection performance in the English language compared to other languages.
+            """
+        )
+
+    with gr.Accordion("Cite our work", open=False):
+        gr.Markdown(
+            """
+            ```bibtex
+                @misc{hans2024spotting,
+                      title={Spotting LLMs With Binoculars: Zero-Shot Detection of Machine-Generated Text}, 
+                      author={Abhimanyu Hans and Avi Schwarzschild and Valeriia Cherepanova and Hamid Kazemi and Aniruddha Saha and Micah Goldblum and Jonas Geiping and Tom Goldstein},
+                      year={2024},
+                      eprint={2401.12070},
+                      archivePrefix={arXiv},
+                      primaryClass={cs.CL}
+                }
+            """
+        )
+
+    # confidence_bar = gr.Label(value={"Confidence": 0})
+
+    # clear_button.click(lambda x: input_box., )
+    submit_button.click(run_detector, inputs=input_box, outputs=output_text)
+    clear_button.click(lambda: ("", ""), outputs=[input_box, output_text])

main.py

@@ -0,0 +1,14 @@
+from binoculars import Binoculars
+
+bino = Binoculars()
+
+# ChatGPT (GPT-4) output when prompted with “Can you write a few sentences about a capybara that is an astrophysicist?"
+sample_string = '''Dr. Capy Cosmos, a capybara unlike any other, astounded the scientific community with his 
+groundbreaking research in astrophysics. With his keen sense of observation and unparalleled ability to interpret 
+cosmic data, he uncovered new insights into the mysteries of black holes and the origins of the universe. As he 
+peered through telescopes with his large, round eyes, fellow researchers often remarked that it seemed as if the 
+stars themselves whispered their secrets directly to him. Dr. Cosmos not only became a beacon of inspiration to 
+aspiring scientists but also proved that intellect and innovation can be found in the most unexpected of creatures.'''
+
+print(bino.compute_score(sample_string))  # 0.75661373
+print(bino.predict(sample_string))  # 'AI-Generated'

requirements.txt

@@ -0,0 +1,5 @@
+sentencepiece
+transformers[torch] @ https://github.com/huggingface/transformers/archive/refs/tags/v4.31.0.zip
+numpy
+gradio
+gradio_client

setup.py

@@ -0,0 +1,15 @@
+from setuptools import setup, find_packages
+
+setup(
+    name='Binoculars',
+    version='0.0.10',
+    packages=find_packages(),
+    url='https://github.com/ahans30/Binoculars',
+    license=open("LICENSE.md", "r", encoding="utf-8").read(),
+    author='Authors of "Binoculars: Zero-Shot Detection of LLM-Generated Text"',
+    author_email='ahans1@umd.edu',
+    description='A language model generated text detector.',
+    long_description=open("README.md", "r", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    install_requires=open("requirements.txt", "r", encoding="utf-8").read().splitlines(),
+)