Models reference v7

Reference for all model-related functions and views in AIDB. For guide-style documentation, see Integrating models.

Configuration model

A model's behavior is controlled two ways, and it matters which one you use for a given setting:

• Creation-time config — set when you call aidb.create_model(), using a provider-specific config helper (aidb.bert_config(), aidb.completions_config(), and so on). This is the model's persistent, stored configuration.
• Call-time inference_config — an optional per-call override, built with aidb.inference_config(), passed directly to an inference function. It overrides the model's stored config for that one call only; anything you don't override falls back to the value set at creation time.

Only some inference functions accept a call-time override — the rest are fixed entirely by the model's creation-time config:

This asymmetry follows from what each capability needs: text generation has runtime knobs worth tuning per call (temperature, system prompt, and so on); embeddings, reranking, and OCR don't, so there's nothing to override.

Catalog views

aidb.model_providers

Lists the model providers you can pass to aidb.create_model().

aidb.models

Lists all models in the registry, including default and user-created models.

Example

SELECT * FROM aidb.models;

  name  |  provider  |    options    |                         functions                         | credential
--------+------------+---------------+-----------------------------------------------------------+------------
 bert   | bert_local | {"config={}"} | {aidb-openai-text-embeddings}                             | none
 clip   | clip_local | {"config={}"} | {aidb-openai-text-image-embeddings}                       | none
 t5     | t5_local   | {"config={}"} | {aidb-openai-text-embeddings,aidb-openai-text-completion} | none
(3 rows)

Model names

A schema-qualified name, such as alice.summarizer, always names that model. A bare name, such as summarizer, resolves to a built-in model of that name first, and otherwise to the only model of that name in any schema. If two models of that name exist in different schemas, a bare name raises an error. Use the schema-qualified name instead. aidb.delete_model() resolves a bare name through search_path.

aidb.credentials

Lists the model credentials. See Model credentials.

The view never shows the secret.

Example

SELECT name, owner, endpoint, shared, has_secret, can_use FROM aidb.credentials WHERE name = 'openai_prod';

    name     | owner | endpoint       | shared | has_secret | can_use
-------------+-------+----------------+--------+------------+---------
 openai_prod | alice | api.openai.com | t      | t          | t
(1 row)

Model management functions

aidb.create_model

Registers a new model in the AIDB model registry.

Parameters

Pass at most one of credential, credentials, credentials_env, and credentials_k8s_secret. A model can't use a different credential later. Delete and recreate it instead.

Secrets on aidb.create_model()

Passing credentials, credentials_env, or credentials_k8s_secret creates a credential named <schema>.<model>, for example public.summarizer. It's owned by the caller, private unless share => true, and its endpoint is the host the model calls. If the model's host can't be determined, the endpoint is *.

• The call fails if the model or the credential already exists. Pass replace_credentials => true to replace the credential's secret instead.
• The call fails if <schema>.<model> is longer than 63 bytes. Create a credential with aidb.create_credential() and pass credential instead.

Credentials from environment variables

Pass credentials_env to read the secret from an environment variable of the Postgres server each time the model is used. Only the variable's name is stored. Only superusers and members of aidb_admins can pass it.

SELECT aidb.create_model(
    name            => 'my_openai',
    provider        => 'openai_embeddings',
    config          => aidb.embeddings_config(model => 'text-embedding-3-small'),
    credentials_env => 'AIDB_OPENAI_API_KEY'
);

The variable holds either a bare secret, used as api_key, or a JSON object such as {"basic_auth": "..."}.

The variable's name must start with the prefix set by aidb.env_var_allowed_prefix (AIDB_ by default). To limit the hosts the secret is sent to, set a variable with the same name plus _HOST, for example AIDB_OPENAI_API_KEY_HOST, to an endpoint pattern. A change to the variable takes effect after a server restart.

Credentials from a Kubernetes Secret

Pass credentials_k8s_secret to read the secret from a file each time the model is used, for example from a Kubernetes Secret mounted into the Postgres pod. Only the path is stored. Only superusers and members of aidb_admins can pass it.

SELECT aidb.create_model(
    name                   => 'my_openai',
    provider               => 'openai_embeddings',
    config                 => aidb.embeddings_config(model => 'text-embedding-3-small'),
    credentials_k8s_secret => '/var/run/secrets/aidb/openai/api-key'
);

The path can point to:

• A file. Its content is either a bare secret, used as api_key, or a JSON object such as {"basic_auth": "..."}.
• A directory with exactly two files named username and password. They're combined into basic_auth.
• A directory with exactly one file, which is read like a single file.

The path must start with the prefix set by aidb.k8s_secret_allowed_path_prefix (/var/run/secrets/aidb by default).

To limit the hosts the secret is sent to, add an endpoint pattern in a file named <file>_HOST next to a secret file, or in a file named host in a secret directory. Files that end in _HOST are never read as secrets. A change to the files takes effect on the next call.

TLS configuration

To connect to HTTPS model endpoints, include a tls_config field inside config:

"tls_config": {
  "insecure_skip_verify": true,
  "ca_path": "/etc/aidb/myCA.pem"
}

A model whose credential holds a secret can't use insecure_skip_verify: true. Use ca_path for a private CA instead.

Validation

By default (validate => true), aidb.create_model() runs a minimal probe inference before the registration commits, to confirm the model is functional:

• Local models are downloaded and loaded, and a test inference is run — so a bad model identifier or unloadable weights fail at creation time rather than on first use.
• External models receive a small test request — so an invalid API key, wrong URL, or unreachable endpoint is caught right away.

If the probe fails, aidb.create_model() raises an error and registers nothing. Pass validate => false to skip the probe — for example, to defer a large download to first use, or to register a model before its endpoint or credentials are available. You can validate a model later with aidb.validate_model().

Examples

-- Minimal registration
SELECT aidb.create_model('my_t5', 't5_local');

-- With a credential
SELECT aidb.create_model(
    name       => 'my_openai',
    provider   => 'openai_embeddings',
    config     => aidb.embeddings_config(model => 'text-embedding-3-small'),
    credential => 'openai_prod'
);

-- With a secret, which creates the credential public.my_openai_2
SELECT aidb.create_model(
    name        => 'my_openai_2',
    provider    => 'openai_embeddings',
    config      => aidb.embeddings_config(model => 'text-embedding-3-small'),
    credentials => '{"api_key": "sk-..."}'::JSONB
);

aidb.get_model

Returns the configuration for a registered model.

Parameters

Returns

Example

SELECT * FROM aidb.get_model('t5');

 name | provider |    options    | credential
------+----------+---------------+------------
 t5   | t5_local | {"config={}"} | none
(1 row)

aidb.delete_model

Removes a model from the registry. Doesn't affect pipelines or knowledge bases that reference it until they are next executed. The model's credential isn't deleted. To delete it, use aidb.delete_credential().

Parameters

Returns

The name, provider, and options of the deleted model.

Example

SELECT aidb.delete_model('t5');

     delete_model
---------------------------------
 (t5,t5_local,"{""config={}""}")
(1 row)

aidb.validate_model

Probes a registered model to confirm it's functional, running a minimal test inference. Called automatically by aidb.create_model() unless validate => false; you can also call it directly to recheck an existing model.

Parameters

Returns

TEXT — the model capability that was probed (for example, text embedding, language, reranking, image embedding, or OCR). Raises an error if the probe fails.

Example

SELECT aidb.validate_model('my_bert');

 validate_model
----------------
 text embedding
(1 row)

Credential management functions

See Model credentials for how to use these functions.

aidb.create_credential

Creates a credential. The calling role owns it.

Parameters

Pass at most one of credentials, credentials_env, and credentials_k8s_secret. If you pass none, the credential has no secret until you set one with aidb.update_credential().

Example

SELECT aidb.create_credential(
    name        => 'openai_prod',
    credentials => '{"api_key": "sk-..."}'::JSONB,
    endpoint    => 'api.openai.com',
    share       => true
);

aidb.update_credential

Changes a credential's secret, endpoint, or sharing. Only the owner, or a role that has the owner role's privileges, can call it. Changes take effect on the next call in every session.

Parameters

Arguments that are NULL stay unchanged. Pass at most one of credentials, credentials_env, and credentials_k8s_secret.

Example

SELECT aidb.update_credential(
    'openai_prod',
    credentials => '{"api_key": "sk-new"}'::JSONB,
    endpoint    => 'api.openai.com'
);

aidb.delete_credential

Deletes a credential and its secret. Only the owner, or a role that has the owner role's privileges, can call it.

Parameters

The built-in none credential can't be deleted.

Example

SELECT aidb.delete_credential('openai_prod', cascade => true);

aidb.validate_endpoint_pattern

Checks an endpoint pattern and returns it in normalized form. Raises an error if the pattern is invalid.

Parameters

Example

SELECT aidb.validate_endpoint_pattern('api.openai.com, .openai.azure.com');

aidb.endpoint_host

Returns the host a model of the given provider calls for the given URL. If url is NULL, returns the provider's default host.

Parameters

Example

SELECT aidb.endpoint_host('openai_completions', 'https://myorg.openai.azure.com/v1/chat/completions');

      endpoint_host
--------------------------
 myorg.openai.azure.com
(1 row)

HCP model functions

These functions manage models running on EDB Hybrid Manager (HM).

aidb.list_hcp_models

Lists models currently running on HM.

Returns

Example

SELECT * FROM aidb.list_hcp_models();

             name              |                         url                          |            model
-------------------------------+------------------------------------------------------+------------------------------
 llama-3-1-8b-instruct-1xgpu   | http://llama-3-1-8b-predictor.default.svc.local      | meta/llama-3.1-8b-instruct
(1 row)

aidb.create_hcp_model

Registers an HCP-hosted model by referencing its running instance name.

Parameters

aidb.sync_hcp_models

Synchronizes the AIDB model registry with models currently running on HCP. Creates entries for new HCP models and deletes entries for models no longer running there.

Returns

Inference functions

aidb.encode_text

Encodes a single text string into a vector using the specified model.

Parameters

Returns

real[] — the embedding for the input text. Cast to vector to use with pgvector operators.

Example

SELECT aidb.encode_text('bert', 'The quick brown fox');

aidb.encode_text_batch

Encodes an array of text strings into vectors in a single call.

Parameters

Returns

SETOF real[] — one row per input, in input order. The result column is named encode_text_batch.

Example

SELECT * FROM aidb.encode_text_batch('bert', ARRAY['The quick brown fox', 'Lorem ipsum dolor sit amet']);

aidb.encode_image

Encodes a binary image into a vector using a multimodal model (for example, CLIP).

Parameters

Returns

real[] — the embedding for the input image. Cast to vector to use with pgvector operators.

Example

SELECT aidb.encode_image('clip', pg_read_binary_file('/tmp/photo.jpg')::BYTEA);

aidb.generate_text

Generates a text response from a prompt using the specified model.

Parameters

Returns

TEXT — the generated response.

Examples

-- Basic usage
SELECT aidb.generate_text('t5', 'translate to French: Hello, world.');

-- With inference configuration
SELECT aidb.generate_text(
    'my_llama',
    'Explain quantum computing in one sentence.',
    aidb.inference_config(
        system_prompt => 'Be concise and factual.',
        temperature   => 0.7,
        max_tokens    => 100
    )::json
);

aidb.generate_text_batch

Generates text responses for an array of prompts in a single call.

Parameters

Returns

SETOF TEXT — one row per input prompt, in input order. The result column is named generate_text_batch.

Example

SELECT aidb.generate_text_batch('t5', ARRAY[
    'translate to German: hello',
    'translate to German: goodbye'
]);

aidb.rerank_text

Scores and ranks a set of text inputs against a query using a reranking model.

Parameters

Returns

Example

SELECT * FROM aidb.rerank_text(
    'my_reranker',
    'How do I configure AIDB?',
    ARRAY[
        'AIDB requires shared_preload_libraries.',
        'Postgres supports JSON natively.',
        'Run CREATE EXTENSION aidb CASCADE to install.'
    ]
) ORDER BY logit_score DESC;

Inference configuration helper

aidb.inference_config

Builds a JSONB configuration object for runtime inference settings. Pass the result (cast to json) to aidb.generate_text(), aidb.generate_text_batch(), or use it with aidb.summarize_text_config().

All parameters are optional — omit any you don't need.

Parameters

Returns

JSONB — cast to ::json before passing to inference functions.

Examples

-- With temperature and token limit
SELECT aidb.generate_text(
    'my_llama',
    'What is machine learning?',
    aidb.inference_config(temperature => 0.5, max_tokens => 150)::json
);

-- Full configuration
SELECT aidb.generate_text(
    'my_llama',
    'Explain relativity.',
    aidb.inference_config(
        system_prompt  => 'You are a physics professor. Be precise.',
        temperature    => 0.3,
        max_tokens     => 200,
        top_p          => 0.9,
        seed           => 42,
        repeat_penalty => 1.1
    )::json
);

-- Hide reasoning tags from a thinking model
SELECT aidb.generate_text(
    'my_reasoning_model',
    'Solve: 2x + 5 = 15',
    aidb.inference_config(thinking => false)::json
);

Tool calling and structured output

Three more inference settings exist but aren't exposed as named parameters of aidb.inference_config() — build them as raw JSON instead, merged with the helper's output using || if you also need other settings. Only llamacpp_generate, openai_responses (+ openai_responses_azure), and anthropic_messages (+ anthropic_messages_azure/anthropic_messages_bedrock) honor these; every other provider rejects them.

-- Tool calling
SELECT aidb.generate_text(
    'my_llamacpp_chat',
    'What is the weather in Paris?',
    (aidb.inference_config(temperature => 0.2) || jsonb_build_object(
        'tools', jsonb_build_array(
            jsonb_build_object(
                'type', 'function',
                'function', jsonb_build_object(
                    'name', 'get_weather',
                    'description', 'Get current weather for a city',
                    'parameters', jsonb_build_object(
                        'type', 'object',
                        'properties', jsonb_build_object('city', jsonb_build_object('type', 'string')),
                        'required', jsonb_build_array('city')
                    )
                )
            )
        ),
        'tool_choice', 'auto'
    ))::json
);

-- Structured output
SELECT aidb.generate_text(
    'my_llamacpp_chat',
    'Extract the city from: I live in Paris.',
    jsonb_build_object(
        'response_format', jsonb_build_object(
            'type', 'json_schema',
            'json_schema', jsonb_build_object(
                'schema', jsonb_build_object(
                    'type', 'object',
                    'properties', jsonb_build_object('city', jsonb_build_object('type', 'string')),
                    'required', jsonb_build_array('city')
                )
            )
        )
    )::json
);

Model config helpers

These functions return a JSONB configuration object for the config parameter of aidb.create_model(). Each helper corresponds to a specific model provider.

Several helpers accept api_key and basic_auth parameters. Don't use them: aidb.create_model() rejects a config that contains either key. Pass the secret through create_model()'s credentials argument instead.

For the local providers bert_local, clip_local, t5_local, and llama_instruct_local, the config key that names the Hugging Face repository is hf_model. The helpers below write it under the old name model, which these providers still accept with a deprecation warning. To avoid the warning, build the config with jsonb_build_object('hf_model', ...) instead of the helper.

aidb.embeddings_config

For openai_embeddings and any OpenAI-compatible embeddings endpoint.

Example

SELECT aidb.create_model(
    'my_embedder',
    'openai_embeddings',
    config      => aidb.embeddings_config(
        model => 'text-embedding-3-small',
        url   => 'https://api.openai.com/v1'
    ),
    credentials => '{"api_key": "sk-..."}'::JSONB
);

aidb.completions_config

For openai_completions and any OpenAI-compatible completions endpoint.

Example

SELECT aidb.create_model(
    'my_llm',
    'openai_completions',
    config      => aidb.completions_config(
        model       => 'gpt-4o',
        temperature => 0.2
    ),
    credentials => '{"api_key": "sk-..."}'::JSONB
);

aidb.max_tokens_config

Builds the max_tokens object for use with aidb.completions_config().

Example

SELECT aidb.completions_config(
    model      => 'gpt-4o',
    max_tokens => aidb.max_tokens_config(size => 1024, format => 'default')
);

aidb.bert_config

For the bert_local provider.

Example

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

aidb.clip_config

For the clip_local provider.

Example

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

aidb.llama_config

For the llama_instruct_local provider.

Example

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

aidb.t5_config

For the t5_local provider.

Example

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

aidb.gemini_config

For the gemini provider.

Example

SELECT aidb.create_model('my_gemini', 'gemini',
    config      => aidb.gemini_config(api_key => NULL, model => 'gemini-2.0-flash'),
    credentials => '{"api_key": "AIza..."}'::JSONB);

aidb.nim_clip_config

For the nim_clip provider (NVIDIA NIM multimodal embeddings).

Example

SELECT aidb.create_model('my_nim_clip', 'nim_clip',
    config      => aidb.nim_clip_config(model => 'nvidia/nvclip'),
    credentials => '{"api_key": "nvapi-..."}'::JSONB);

aidb.nim_ocr_config

For the nim_paddle_ocr provider (NVIDIA NIM OCR).

Example

SELECT aidb.create_model('my_nim_ocr', 'nim_paddle_ocr',
    config      => aidb.nim_ocr_config(),
    credentials => '{"api_key": "nvapi-..."}'::JSONB);

aidb.nim_reranking_config

For the nim_reranking provider.

Example

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

aidb.openrouter_chat_config

For the openrouter_chat provider.

Example

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

aidb.openrouter_embeddings_config

For the openrouter_embeddings provider.

Example

SELECT aidb.create_model('my_or_embedder', 'openrouter_embeddings',
    config      => aidb.openrouter_embeddings_config('mistral/mistral-embed'),
    credentials => '{"api_key": "sk-or-..."}'::JSONB
);

aidb.openai_responses_config

For the openai_responses and openai_responses_azure providers.

Examples

-- OpenAI
SELECT aidb.create_model(
    'my_gpt',
    'openai_responses',
    config      => aidb.openai_responses_config(model => 'gpt-5.1'),
    credentials => '{"api_key": "sk-..."}'::JSONB
);

-- Azure AI Foundry
SELECT aidb.create_model(
    'my_gpt_azure',
    'openai_responses_azure',
    config      => aidb.openai_responses_config(
        model => 'gpt-5.1',
        url   => 'https://<resource>.openai.azure.com/openai/v1/responses'
    ),
    credentials => '{"api_key": "..."}'::JSONB
);

This provider natively supports the tools, tool_choice, and response_format fields described in Tool calling and structured output.

aidb.anthropic_messages_config

For the anthropic_messages, anthropic_messages_azure, and anthropic_messages_bedrock providers.

Examples

-- Anthropic direct
SELECT aidb.create_model(
    'my_claude',
    'anthropic_messages',
    config      => aidb.anthropic_messages_config(model => 'claude-opus-4-6'),
    credentials => '{"api_key": "sk-ant-..."}'::JSONB
);

-- Azure AI Foundry
SELECT aidb.create_model(
    'my_claude_azure',
    'anthropic_messages_azure',
    config      => aidb.anthropic_messages_config(
        model => 'claude-opus-4-6',
        url   => 'https://<resource>.services.ai.azure.com/anthropic/v1/messages'
    ),
    credentials => '{"api_key": "..."}'::JSONB
);

-- AWS Bedrock
SELECT aidb.create_model(
    'my_claude_bedrock',
    'anthropic_messages_bedrock',
    config      => aidb.anthropic_messages_config(
        model => 'anthropic.claude-opus-4-6-v1:0',
        url   => 'https://bedrock-runtime.us-east-1.amazonaws.com'
    ),
    credentials => '{"api_key": "..."}'::JSONB
);

This provider natively supports the tools, tool_choice, and response_format fields described in Tool calling and structured output. Anthropic's Messages API has no native structured-output field, so response_format is implemented as a forced call to a synthetic tool — functionally equivalent, but it means response_format and tools/tool_choice can't be used in the same call.