LLM Hallucination Detector

Highlights the words an AI chatbot was unsure about, so you know which parts of its answer to double-check.

For anyone who ships or checks LLM answers: developers, evaluators, and CI pipelines. Works with OpenAI, OpenRouter, Together, vLLM, Ollama and any OpenAI-compatible API that returns token logprobs. Rust CLI and library (llm-token-visualizer).

Works on answers in any language: words are found with Unicode word segmentation, so a single unsure character in a Chinese or Japanese answer is flagged on its own. Reads OpenAI-style, completions-style and Google Gemini (logprobsResult) responses.

Install

Linux (x86_64, Ubuntu 20.04+ / Debian 11+). One line, no dependencies, installs to ~/.local/bin:

mkdir -p ~/.local/bin && curl -fsSL https://gitlab.com/mattbusel/LLM-Hallucination-Detection-Script/-/releases/permalink/latest/downloads/llm-token-visualizer-linux-x86_64.tar.gz | tar xz --strip-components=1 -C ~/.local/bin --wildcards '*/llm-token-visualizer'

The release archives also include the sample answers under samples/. Every release, with SHA-256 checksums: Releases.

In GitLab CI: fail a pipeline when a saved LLM answer has low-confidence words with the hallucination-gate CI/CD component.

How it works

When a model writes an answer, it picks each token (a word or piece of a word) from a list of candidates, each with a probability. APIs expose these as logprobs. Hallucinations often sit where that probability drops: a name, a date, a city the model half-remembers. This tool turns the numbers into a heatmap and flags the shaky words, with the alternatives the model almost said. No model of its own, no API calls unless you ask for --live.

Examples

Real answers from Llama 3.1 8B Instruct, bundled in examples/logprobs/. The first two of the four answers in the output of cargo run --example detect (threshold 0.6):

examples/logprobs/cuyp.json
  answer: Aelbert Cuyp died in 1691 in Dordrecht, Netherlands.
  flagged "Aelbert": p=0.49 at "A"; model also considered "The" (0.43), "D" (0.08)
  flagged "Dordrecht": p=0.57 at "ord"; model also considered "üsseldorf" (0.39), "elf" (0.03)

examples/logprobs/tour-de-france.json
  answer: Stephen Roche won the 1987 Tour de France, riding for the Carrera Jeans-Vagabond team.
  flagged "Stephen": p=0.49 at "Stephen"; model also considered "The" (0.43), "Steven" (0.03)
  flagged "-Vagabond": p=0.57 at "-V"; model also considered "–" (0.21), " -" (0.14)

The Dordrecht answer is right, but the model gave Düsseldorf a 39% chance: exactly the kind of claim to double-check. The "Aelbert" flag is the model choosing between starting with the name or with "The": low probability can be about phrasing, not facts.

The terminal report for the first one (--logprobs-file examples/logprobs/cuyp.json --threshold 0.6):

What it cannot tell you

Models can be confidently wrong. In moonwalk.json the model says "Pete Conrad was the second person to walk on the Moon" (it was Buzz Aldrin) with at least 72% probability on every token of the name, so the wrong name is not flagged. Use this to decide where to look first, not to certify an answer.

Why this tool

There is no other Rust crate for logprob-based confidence checks. In Python, LM-Polygraph and UQLM offer many more uncertainty methods (sampling consistency, claim-level scoring, trained estimators), and need the model loaded or several generations per answer. This tool does one cheap thing from a single saved response: show which words had low probability and what else the model considered, as a terminal heatmap, an HTML page, Markdown for a merge request, JSON, or a CI exit code. Each report also gives the answer's perplexity, and each flagged span the entropy of the alternatives at its weakest token.

Use it in 3 steps

1. Get a response with logprobs. Ask your API for "logprobs": true, "top_logprobs": 3 and save the JSON, or let the tool do it: set OPENAI_API_KEY and run llm-token-visualizer --live "your question" --save answer.json.
2. Run it: llm-token-visualizer --logprobs-file answer.json --threshold 0.6
3. Share or gate it: --format html -o report.html for a page you can send, --format markdown for a PR comment, --fail-on-flag to fail a CI job when anything is flagged.

Providers

--live asks a model and analyzes its answer. Pick where with --provider (default openai), and override the address with --base-url:

llm-token-visualizer --live "Who painted The Night Watch?" --provider ollama --model qwen2.5-coder:14b

llm-token-visualizer --live "Who painted The Night Watch?" --provider openrouter --save answer.json

llm-token-visualizer --live "..." --provider vllm --model my-model --base-url http://gpu-box:8000/v1

No hosted provider was called with a real key for this release. If a provider or model answers without logprobs, the CLI stops with an error that says so (and shows the answer) instead of printing an empty report. Anthropic's API does not return logprobs, so it has no preset.

Google Gemini's native API returns logprobs too (generationConfig: {responseLogprobs: true, logprobs: 3}); save the response and pass it with --logprobs-file.

No API key handy? Grab a sample first: curl -LO https://gitlab.com/mattbusel/LLM-Hallucination-Detection-Script/-/raw/main/examples/logprobs/cuyp.json

Library

use llm_token_visualizer::detect::{detect, parse_logprobs};

let json = std::fs::read_to_string("examples/logprobs/cuyp.json")?;
let report = detect(&parse_logprobs(&json)?, 0.6);
for span in &report.spans {
    println!("{:?}: {}", span.text.trim(), span.describe());
}
println!("perplexity {:.2}", report.perplexity);
# Ok::<(), anyhow::Error>(())

Examples (cargo run --example <name>): detect (every bundled sample), ci_gate (a directory of answers, exit 2 when any is flagged), html_report (write the HTML page for one answer).

Already using async-openai? Enable the feature and pass your CreateChatCompletionResponse to interop::async_openai::tokens_from_response, then detect. Using another client? Serialize its response to JSON and call parse_logprobs.

Performance

cargo bench --bench vs_0_4 parses a 4,000-token response and flags spans: 9.0 ms with 0.5.0 against 14.6 ms with 0.4.0 (criterion medians, i7-13700KF, Windows 11, Rust 1.91). 0.5.0 deserializes the logprobs without copying the JSON first, which more than pays for the Unicode word segmentation.

Documentation

License

MIT, see LICENSE.