Implementation:Neuml Txtai Pooling Factory
| Knowledge Sources | |
|---|---|
| Domains | Factory Pattern, Embeddings, Model Configuration |
| Last Updated | 2026-02-10 01:00 GMT |
Overview
Concrete tool for auto-detecting and creating the appropriate pooling model provided by txtai.
Description
The PoolingFactory class implements the factory pattern for creating pooling model instances. It provides a static create method that automatically determines the correct pooling strategy based on model configuration files from the Hugging Face Hub. The detection logic follows a priority chain: (1) if the path is a raw file (bytes or file path) or the method is explicitly "pooling", it returns a base Pooling instance; (2) if not explicitly specified, it inspects the model's 1_Pooling/config.json to distinguish between CLS and mean pooling; (3) it checks for 1_Dense/config.json or a "HF_ColBERT" architecture in config.json to detect late interaction models. The factory also handles reading max_seq_length from the sentence-transformers config and loading JSON configuration files from the Hugging Face Hub with error handling for invalid repos.
Usage
Use PoolingFactory as the primary entry point for creating pooling models in txtai. It is the recommended way to instantiate pooling models because it auto-detects the correct pooling strategy from model metadata, eliminating the need for manual configuration. Pass a configuration dictionary with at minimum a path and device key.
Code Reference
Source Location
- Repository: Neuml_Txtai
- File:
src/python/txtai/models/pooling/factory.py
Signature
class PoolingFactory:
@staticmethod
def create(config)
@staticmethod
def method(path)
@staticmethod
def maxlength(path)
@staticmethod
def load(path, name)
Import
from txtai.models.pooling.factory import PoolingFactory
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| config | dict | Yes | Configuration dictionary with keys: path (model path or Hugging Face model id, required), device (tensor device id, required), method (explicit pooling method: "pooling", "clspooling", "meanpooling", or "latepooling"), tokenizer (optional tokenizer path), maxlength (max sequence length; if True, reads from sentence-transformers config), loadprompts (whether to load instruction prompts), modelargs (additional model arguments dict).
|
| path | str | Yes (for method/maxlength/load) | Model path or Hugging Face Hub model id for auto-detection. |
| name | str | Yes (for load) | Config file name to load (e.g., "1_Pooling/config.json"). |
Outputs
| Name | Type | Description |
|---|---|---|
| create() | Pooling | An instance of the appropriate pooling subclass: Pooling (base/raw), ClsPooling (CLS token), MeanPooling (mean of token embeddings, default), or LatePooling (late interaction/ColBERT). |
| method() | str | Detected pooling method string: "clspooling", "meanpooling", or "latepooling". |
| maxlength() | int or None | Maximum sequence length from sentence_bert_config.json, or None if not available.
|
| load() | dict or None | Parsed JSON configuration from a Hugging Face Hub file, or None if not found or invalid. |
Usage Examples
from txtai.models.pooling.factory import PoolingFactory
# Auto-detect and create a pooling model
config = {
"path": "sentence-transformers/all-MiniLM-L6-v2",
"device": "cpu",
"maxlength": True, # Read from sentence-transformers config
"loadprompts": True
}
model = PoolingFactory.create(config)
# Returns MeanPooling instance based on model's 1_Pooling/config.json
# Explicitly specify pooling method
config_cls = {
"path": "sentence-transformers/bert-base-nli-cls-token",
"device": "cpu",
"method": "clspooling"
}
cls_model = PoolingFactory.create(config_cls)
# Returns ClsPooling instance
# Check which method a model uses
method = PoolingFactory.method("sentence-transformers/all-MiniLM-L6-v2")
# method: "meanpooling"
# Get max sequence length
maxlen = PoolingFactory.maxlength("sentence-transformers/all-MiniLM-L6-v2")
# maxlen: 256