External model connections v7

External models are API-based models hosted outside your Postgres instance. AIDB connects to them by registering a model with aidb.create_model(), supplying the provider name, a configuration object, and credentials such as an API key, if required.

Once registered, an external model is used exactly like a built-in local model — by name in any AIDB SQL function or pipeline step.

OpenAI-compatible endpoints

AIDB supports any embedding or chat/completions service that implements the OpenAI API. This includes OpenAI itself, self-hosted servers like Ollama, and any other compliant endpoint.

Embeddings

Use the openai_embeddings provider with aidb.embeddings_config(). Override the url parameter to redirect requests to any OpenAI-compatible server:

-- OpenAI
SELECT aidb.create_model(
    'my_openai_embedder',
    'openai_embeddings',
    config => aidb.embeddings_config(
        model   => 'text-embedding-3-small',
        api_key => 'sk-...',
        url     => 'https://api.openai.com/v1'
    )
);

-- Local Ollama server
SELECT aidb.create_model(
    'my_ollama_embedder',
    'openai_embeddings',
    config => aidb.embeddings_config(
        model => 'llama3.2',
        url   => 'http://llama.local:11434/v1/embeddings'
    )
);

Chat completions

Use the openai_completions provider with aidb.completions_config(). The url parameter works the same way — omit it for OpenAI, or override it for any other compliant server:

SELECT aidb.create_model(
    'my_openai_llm',
    'openai_completions',
    config => aidb.completions_config(
        model       => 'gpt-4o',
        api_key     => 'sk-...',
        temperature => 0.2
    )
);

NVIDIA NIM

AIDB supports NVIDIA NIM microservices hosted on build.nvidia.com as well as NIM instances running in your own environment.

Text generation (NIM completions)

Use the nim_completions provider with the model identifier and your NIM API key:

SELECT aidb.create_model(
    'my_nim_llm',
    'nim_completions',
    '{"model": "meta/llama-3.3-70b-instruct"}'::JSONB,
    '{"api_key": "<NIM API KEY>"}'::JSONB
);

To use a NIM instance running in your own environment, add a url key to the config pointing at your NIM endpoint.

After registering, run the model with aidb.decode_text():

SELECT aidb.decode_text('my_nim_llm', 'Tell me a short, one sentence story');

                                      decode_text
----------------------------------------------------------------------------------
 As the clock struck midnight, a single tear fell from the porcelain doll's eye.
(1 row)

Multimodal embeddings (NIM CLIP)

Use the nim_clip provider with aidb.nim_clip_config() for joint text and image embeddings:

SELECT aidb.create_model(
    'my_nim_clip',
    'nim_clip',
    config => aidb.nim_clip_config(
        api_key => 'nvapi-...',
        model   => 'nvidia/nvclip'
    )
);

aidb.nim_clip_config() parameters:

OCR (NIM OCR)

Use the nim_ocr provider with aidb.nim_ocr_config() to extract text from images:

SELECT aidb.create_model(
    'my_nim_ocr',
    'nim_paddle_ocr.',
    config => aidb.nim_ocr_config(api_key => 'nvapi-...')
);

aidb.nim_ocr_config() parameters:

Reranking (NIM reranking)

Use the nim_reranking provider with aidb.nim_reranking_config() to re-score search results by relevance. See Reranking text for usage with aidb.rerank_text():

SELECT aidb.create_model(
    'my_reranker',
    'nim_reranking',
    config => aidb.nim_reranking_config(
        api_key => 'nvapi-...',
        model   => 'nvidia/nv-rerankqa-mistral-4b-v3'
    )
);

aidb.nim_reranking_config() parameters:

To get a NIM API key, create an account at build.nvidia.com, select a model, and generate a key from the model's page.

Google Gemini

Use the gemini provider with aidb.gemini_config(). Pass your Google API key as the first argument:

SELECT aidb.create_model(
    'my_gemini',
    'gemini',
    config => aidb.gemini_config(
        'AIza...',
        model => 'gemini-2.0-flash'
    )
);

aidb.gemini_config() parameters:

OpenRouter

OpenRouter provides a unified API gateway to 200+ models from multiple providers. AIDB supports both chat completions and embeddings via OpenRouter.

Chat completions

SELECT aidb.create_model(
    'my_or_chat',
    'openrouter_chat',
    config => aidb.openrouter_chat_config(
        'anthropic/claude-3-5-haiku',
        api_key => 'sk-or-...'
    )
);

aidb.openrouter_chat_config() parameters:

Embeddings

SELECT aidb.create_model(
    'my_or_embedder',
    'openrouter_embeddings',
    config => aidb.openrouter_embeddings_config(
        'mistral/mistral-embed',
        api_key => 'sk-or-...'
    )
);

aidb.openrouter_embeddings_config() parameters:

See the Pipelines API reference for full parameter details on all config helper functions.