Implementation:Neuml Txtai Explain
| Knowledge Sources | |
|---|---|
| Domains | Explainability, Embeddings |
| Last Updated | 2026-02-09 17:00 GMT |
Overview
The Explain class provides permutation-based token importance explanations for txtai similarity search results, revealing which tokens in a query contribute most to each match.
Description
The Explain class implements a leave-one-out approach to measure each token's contribution to similarity scores. For each query-text pair, it systematically removes one token at a time from the query, recomputes the similarity score, and measures the resulting change. Tokens whose removal causes the largest drop in similarity are identified as the most important contributors to the match. This provides interpretable explanations of why certain results were returned for a given query.
Usage
Use the Explain class when you need to understand why specific documents were returned for a similarity search query. This is particularly valuable for debugging search quality, building trust in search results, and creating user-facing explanations that highlight the most relevant terms. It is accessed through the embeddings.explain() method rather than being instantiated directly.
Code Reference
Source Location
- Repository: Neuml_Txtai
- File: src/python/txtai/embeddings/search/explain.py
- Lines: 1-120
Signature
class Explain:
def __init__(self, embeddings):
"""
Creates an Explain instance.
Args:
embeddings: embeddings instance used for similarity scoring
"""
def __call__(self, queries, texts, limit):
"""
Explains similarity between queries and texts using token importance.
Args:
queries: list of query strings
texts: list of candidate text strings
limit: maximum number of results per query
Returns:
list of dicts with token importance scores for each query-text pair
"""
Import
from txtai.embeddings.search import Explain
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| embeddings | Embeddings | Yes | txtai Embeddings instance used to compute similarity scores during permutation |
| queries | list[str] | Yes | List of query strings to explain |
| texts | list[str] | Yes | List of candidate texts to explain similarity against |
| limit | int | Yes | Maximum number of results to return per query |
Outputs
| Name | Type | Description |
|---|---|---|
| results | list[dict] | List of dictionaries, each containing token importance scores. Each dict maps tokens to their contribution scores, where higher values indicate greater importance to the similarity match. |
Usage Examples
Basic Usage
from txtai.embeddings import Embeddings
# Create and index embeddings
embeddings = Embeddings(path="sentence-transformers/all-MiniLM-L6-v2")
embeddings.index([
"Machine learning algorithms for classification",
"Deep neural network architectures",
"Natural language processing with transformers",
"Computer vision and image recognition"
])
# Explain search results - shows token importance
results = embeddings.explain("neural network models", limit=2)
for result in results:
print(result)
# Each result includes token importance scores showing which
# query tokens contributed most to the similarity match
Analyzing Token Contributions
from txtai.embeddings import Embeddings
# Build embeddings with content storage
embeddings = Embeddings(
path="sentence-transformers/all-MiniLM-L6-v2",
content=True
)
embeddings.index([
{"text": "Supervised learning for text classification"},
{"text": "Unsupervised clustering of documents"},
{"text": "Reinforcement learning in game environments"}
])
# Get explanations for a query
results = embeddings.explain("learning algorithms for text", limit=2)
# Inspect which tokens drove the match
for result in results:
# Sort tokens by importance to see most contributing terms
tokens = sorted(result.items(), key=lambda x: x[1], reverse=True)
for token, score in tokens:
print(f" {token}: {score:.4f}")