How andriymulyar/semantic-text-similarity works
Project type and purpose
• This is an open-source Python library (“semantic-text-similarity”) that provides a clean interface over fine-tuned BERT models (and fallback string-based metrics) to compute semantic similarity scores.
• It abstracts away research benchmarking into easy “predict(…)” calls for real-world applications.
File structure
Top-level:
• examples/ – sample scripts showing how to call the library
• semantic_text_similarity/ – the core package
• data/ – data loaders for STS-B datasets (STS-B, MED-STS)
• models/ – model implementations
– bert/ – BERT-based similarity models and preprocessing
– string_similarity/ – lexical similarity baselines
• util and test utilities
• setup.py, README.md, cache location (~/.cache/torch/…)
README for additional insights
• Two main pre-trained BERT models: Web STS and Clinical STS
• Uses Huggingface pytorch-transformers under the hood
• Exposes a simple Python API: instantiate model class, call predict()
a. Main components:
1. User Layer (scripts, CLI, application code)
2. Semantic-Text-Similarity Package
• API Facade (WebBertSimilarity, ClinicalBertSimilarity, StringSimilarity)
• Data Loader (semantic_text_similarity.data)
• Preprocessing (bert_preprocessing.py)
• Model Inference (similarity.py in bert/ and lexical metrics)
• Utilities (tokenization helpers, test utilities)
3. External Dependencies
• Huggingface pytorch-transformers (model zoo, tokenizers)
• GPU/CPU device
• Local cache directory for downloaded checkpoints
b. Relationships & data flow:
1. User calls Model API →
2. API Facade invokes Data Loader (optional if batching raw text) →
3. Preprocessing transforms sentences into token IDs →
4. BERT model loaded from cache or downloaded via Huggingface →
5. Forward pass → similarity score output →
6. Return real-valued score to user
c. Architectural patterns & principles:
• Layered architecture: API layer, data layer, model layer.
• Separation of concerns: data handling vs. preprocessing vs. model inference.
• Modular design: interchangeable similarity backends (BERT vs. string metrics).
d. Key technologies/frameworks:
• Python packaging (setup.py)
• pytorch-transformers (Huggingface)
• PyTorch for model execution
• CSV data files for STS datasets