VecGrep

GPU-accelerated semantic similarity grep. Find lines/chunks in logs, code, and documents that are semantically similar to your query - not just exact text matches.

Use Cases

• Log forensics: Find lines semantically similar to "database connection timeout" across gigabytes of logs
• Code archaeology: Find implementations similar to a concept or example snippet
• Document search: Find paragraphs relevant to a query across a corpus
• Deduplication/clustering: Find near-duplicate content

Installation

pip install numpy onnxruntime transformers huggingface_hub torch

For GPU acceleration:

pip install onnxruntime-gpu

Usage

# Stream mode - pipe input
cat server.log | vecgrep "connection refused"

# Search files directly
vecgrep "memory leak" app.log

# Recursive directory search
vecgrep -r "auth failure" ./logs/

# Adjust similarity threshold (default: 0.6)
vecgrep -t 0.75 "payment error" tx.log

# Show similarity scores
vecgrep -s "null pointer" debug.log
# Output: 0.823  debug.log:1442: NullPointerException in UserService.java

# Context lines (like grep -C)
vecgrep -C 3 "stack overflow" crash.log

Options

Flag	Description
-t, --threshold	Similarity threshold 0-1 (default: 0.6)
-s, --scores	Show similarity scores in output
-r, --recursive	Recursively search directories
-C, --context	Lines of context to show
--line	Line-by-line mode (default)
--paragraph	Paragraph chunking mode
--chunk-size N	Fixed chunk size in tokens
--overlap N	Overlap for fixed chunks (default: 64)
--model	Model to use (default: BAAI/bge-small-en-v1.5)
--cpu	Force CPU mode
--batch-size	Batch size for encoding (default: 64)
--debug	Show live processing stats

Chunking Modes

Mode	Use Case	Flag
Line	Logs, code	--line (default)
Paragraph	Docs, markdown	--paragraph
Fixed tokens	Dense text	--chunk-size N
Sliding window	Overlapping context	--chunk-size N --overlap M

Model

Uses BAAI/bge-small-en-v1.5 by default. Models are:

• Cached in ~/.cache/vecgrep/
• Auto-downloaded from HuggingFace on first run
• Exported to ONNX format for fast inference
• Falls back to hf-mirror.com if HuggingFace is unavailable

Performance

• GPU acceleration via ONNX Runtime with CUDA
• Batched encoding for efficiency
• Use --debug to monitor processing speed and profiling breakdown