Local models v7

AIDB supports two kinds of local models — both run directly on your Postgres host without requiring an external API:

• Built-in models — AIDB bundles a default variant of each supported model type and registers them automatically. No configuration is needed to start using them.
• Custom local models — If you need a different model variant, a fine-tuned model, or a specific local path, you can register a custom version using aidb.create_model().

Built-in models

The following models are available in every AIDB installation without any configuration:

Use them directly by name in any AIDB SQL function or pipeline step configuration:

-- Text embedding with the built-in BERT model
SELECT aidb.encode_text('bert', 'The quick brown fox');

-- Image embedding with the built-in CLIP model
SELECT aidb.encode_image('clip', pg_read_binary_file('/tmp/photo.jpg')::BYTEA);

-- Text generation with the built-in T5 model
SELECT aidb.decode_text('t5', 'Translate to French: Hello, world.');

Custom local models

Use aidb.create_model() to register a custom variant when you need a different model version, a fine-tuned model, or a specific local path:

SELECT aidb.create_model(
    name     => 'my_model',
    provider => '<provider>',
    config   => <config_helper>(...)
);

BERT

Use aidb.bert_config() to specify the HuggingFace model identifier, an optional revision, and an optional local cache directory:

SELECT aidb.create_model(
    'my_bert',
    'bert_local',
    config => aidb.bert_config('sentence-transformers/all-MiniLM-L6-v2')
);

CLIP

Use aidb.clip_config() to configure a CLIP-based multimodal model for joint text and image embeddings:

SELECT aidb.create_model(
    'my_clip',
    'clip_local',
    config => aidb.clip_config('openai/clip-vit-base-patch32')
);

T5

Use aidb.t5_config() to configure a T5 text-to-text model. T5 models support tasks like translation, summarization, and question answering depending on the variant:

SELECT aidb.create_model(
    'my_t5',
    't5_local',
    config => aidb.t5_config('google/flan-t5-base')
);

Llama

Use aidb.llama_config() to configure a Llama-family language model for text generation. Llama models support temperature, top-p sampling, context length, and other generation parameters:

SELECT aidb.create_model(
    'my_llama',
    'llama_instruct_local.',
    config => aidb.llama_config(
        'meta-llama/Llama-3.2-3B-Instruct',
        temperature => 0.5
    )
);

Local model downloads

When a local model is used for the first time (or any time its cache is missing or corrupt), AIDB downloads the model files from HuggingFace into the configured cache_dir. The downloader emits progress messages and automatically retries transient network failures.

Progress messages

For each file, AIDB emits a downloading line when the request starts and a complete line when it finishes. For multi-gigabyte files, a heartbeat line reports cumulative bytes and percent complete approximately every 30 seconds, so the session doesn't appear frozen during large downloads.

SELECT aidb.decode_text('t5', 'test');

NOTICE:  [t5_local] loading t5-small (rev refs/pr/15) -> /var/.../snapshots/refs/pr/15
NOTICE:  [hf] downloading https://huggingface.co/t5-small/resolve/refs%2Fpr%2F15/config.json (expected: 1.2 KB)
NOTICE:  [hf] complete: https://huggingface.co/t5-small/resolve/refs%2Fpr%2F15/config.json (1.2 KB) in 0.9s
NOTICE:  [hf] downloading https://huggingface.co/t5-small/resolve/refs%2Fpr%2F15/model.safetensors (size unknown)
NOTICE:  [hf] downloading t5-small/model.safetensors: 115.4 MB / 230.8 MB (50.0%)
NOTICE:  [hf] downloading t5-small/model.safetensors: 216.4 MB / 230.8 MB (93.7%)
NOTICE:  [hf] complete: https://huggingface.co/t5-small/resolve/refs%2Fpr%2F15/model.safetensors (230.8 MB) in 83.5s

By default, these lines are sent to the client at NOTICE level. Use the aidb.download_log_level parameter to route them to the server log instead, or to suppress them entirely.

Retries and resume

A CDN that drops the connection partway through a multi-gigabyte download will not fail the request outright:

• Each retry sends a Range header from wherever the previous attempt stopped, so progress accumulates across attempts instead of restarting from zero.
• AIDB distinguishes "still receiving new bytes" from "zero progress" and only counts stalled attempts against aidb.download_max_attempts, with exponential backoff between attempts.
• A Ctrl-C from psql lands between retries instead of waiting for the current request to time out.

The total number of attempts per file is capped by aidb.download_max_attempts (default 30).

Verification and self-heal

AIDB verifies downloaded files using the size and (when available) the SHA-256 hash advertised by HuggingFace, and writes a small sidecar file next to each completed download recording those values. On every cache hit AIDB rechecks the file size against the sidecar, so a file truncated after the original download is caught before it's used.

If a cached file is detected as corrupt at model-load time, AIDB purges the affected snapshot and re-downloads it once automatically.

Using a registered model

Once registered, a model is referenced by its name in any AIDB function. Custom and built-in models are interchangeable:

-- Use a custom BERT model for embedding
SELECT aidb.encode_text('my_bert', 'Hello world');

-- Use a custom BERT model in a pipeline step
SELECT aidb.create_pipeline(
    name => 'my_pipeline',
    source => 'my_source_table',
    source_key_column => 'id',
    source_data_column => 'content',
    step_1 => 'KnowledgeBase',
    step_1_options => aidb.knowledge_base_config(model => 'my_bert', data_format => 'Text')
);

See the Models reference for full parameter details on all model config helper functions.

For a list of HuggingFace model variants that have been tested and verified to work with AIDB's local providers, see Support matrix.