Register AI Models via AI_CreateModel for PAI Inference - PolarDB

Registers an AI model and its metadata in the polar_ai._ai_models table, making it available for invocation via AI_CallModel.

AI_CreateModel registers metadata only — it does not call or execute the model.

Syntax

table AI_CreateModel(
    text model_id,
    text model_url,
    text model_provider,
    text model_type,
    text model_name,
    json model_config,
    regprocedure model_headers_fn,
    regprocedure model_in_transform_fn,
    regprocedure model_out_transform_fn
)

Parameters

Parameter	Required	Description
`model_id`	Yes	The unique identifier of the AI model. Must differ from `model_name` and cannot start with an underscore (`_`). Built-in AI models created by the `Polar_AI` extension use names that start with `_`. To view built-in models, run `SELECT * FROM polar_ai._ai_models;`.
`model_url`	Yes	The URL used to access the AI model. Supports HTTP, HTTPS, and FILE protocols. For models deployed on Platform for AI (PAI), use the endpoint from the model's call information.
`model_provider`	No	The provider of the AI model. Examples: `AWS`, `Alibaba`, `Baidu`, `Tencent`.
`model_type`	No	The type of the AI model. Examples: `LSTM`, `GRU`.
`model_name`	Yes	The name of the AI model. Example: `text-embedding-v2`.
`model_config`	Yes	The model configuration in JSON format. Must include `author_type` and `token` fields: `{"author_type": "token", "token": "<YOUR_API_KEY>"}`. Only token-based authentication is supported. API keys are encrypted at rest. For PAI-deployed models, use the token from the model's call information.
`model_headers_fn`	No	The function that constructs custom request headers. Returns JSONB. Set to `NULL` if the model has no special header requirements. Default: `NULL`.
`model_in_transform_fn`	Yes	The function that converts input data into a JSONB-formatted HTTP request body required by the AI model.
`model_out_transform_fn`	Yes	The function that parses and transforms the JSON output returned by the AI model into the required JSONB format.

Return values

Returns a table row with the following columns.

Column	Description
`model_seq`	The sequence number of the AI model.
`model_schema`	The workspace to which the AI model belongs.
`model_id`	The unique identifier of the AI model.
`model_qname`	The name of the AI model.
`created`	Whether the AI model was created successfully. `t`: Creation succeeded. `f`: Creation failed.

Input and output functions

All requests to an AI model go through two transformation functions. Define these functions before calling AI_CreateModel.

Input function (model_in_transform_fn)

The input function converts your input into a JSONB HTTP request body. The following example shows the expected request body format for the DeepSeek-R1-Distill-Qwen-7B model deployed on PAI:

{
  "model": "DeepSeek-R1-Distill-Qwen-7B",
  "prompt": "Hello!"
}

The request body must contain the model and prompt fields. Define the input function as follows:

CREATE OR REPLACE FUNCTION ai_text_in_fn(model_name text, content text)
    RETURNS jsonb
    LANGUAGE plpgsql
    AS $function$
    BEGIN
        RETURN ('{"model": "'|| model_name ||'","prompt":"'|| content ||'"}')::jsonb;
    END;
    $function$;

Output function (model_out_transform_fn)

The output function extracts the required data from the model's JSON response. The following example shows the raw JSON response from a text completion model:

{
    "id": "8e44xxxx",
    "object": "text_completion",
    "created": 1744355891,
    "model": "DeepSeek-R1-Distill-Qwen-7B",
    "choices": [
        {
            "index": 0,
            "text": " I have a\n\n\n</think>\n\nHello! How can I assist you today? ",
            "logprobs": null,
            "finish_reason": "stop",
            "matched_stop": 151643
        }
    ],
    "usage": {
        "prompt_tokens": 3,
        "total_tokens": 21,
        "completion_tokens": 18,
        "prompt_tokens_details": null
    }
}

To extract choices[0].text as JSONB, define the output function as follows:

CREATE OR REPLACE FUNCTION ai_text_out_fn(model_id text, response_json jsonb)
    RETURNS jsonb
    AS $$
    SELECT (response_json->'choices'->0->'text')::jsonb
    $$ LANGUAGE sql IMMUTABLE;

Examples

The following example registers the DeepSeek-R1-Distill-Qwen-7B model deployed on Elastic Algorithm Service (EAS) within PAI.

Step 1: Create the input function.

CREATE OR REPLACE FUNCTION ai_text_in_fn(model_name text, content text)
    RETURNS jsonb
    LANGUAGE plpgsql
    AS $function$
    BEGIN
        RETURN ('{"model": "'|| model_name ||'","prompt":"'|| content ||'"}')::jsonb;
    END;
    $function$;

Step 2: Create the output function.

CREATE OR REPLACE FUNCTION ai_text_out_fn(model_id text, response_json jsonb)
    RETURNS jsonb
    AS $$
    SELECT (response_json->'choices'->0->'text')::jsonb
    $$ LANGUAGE sql IMMUTABLE;

Step 3: Register the model.

Set model_url to the VPC endpoint of the PAI-deployed model with the invocation path /v1/completions appended. Set token in model_config to the EAS access token.

SELECT polar_ai.AI_CreateModel(
    'my_text_pai_model',
    '<EAS Endpoint>/v1/completions',
    'Alibaba',
    'EAS LLM',
    'DeepSeek-R1-Distill-Qwen-32B',
    '{"author_type": "token", "token": "<EAS Token>"}',
    NULL,
    'ai_text_in_fn'::regproc,
    'ai_text_out_fn'::regproc
);

Step 4: Verify the result.

ai_createmodel
-------------------------------------------------------------
(1,my_text_pai_model,polar_ai,DeepSeek-R1-Distill-Qwen-7B,t)

(Optional) Step 5: View all registered AI models.

SELECT * FROM polar_ai._ai_models;

Sample output:

 model_seq |          model_id           | model_url | model_provider | model_type |       model_name       |                      model_config                       | model_headers_fn |        model_in_transform_fn         |         model_out_transform_fn
-----------+-----------------------------+-----------+----------------+------------+------------------------+---------------------------------------------------------+------------------+--------------------------------------+-------------------------------
         1 | my_text_embedding_model     | https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding | Alibaba | General-purpose text embedding model | text-embedding-v2 | {"token": "20E0BE9E5438xxxxxxxxxxxxxxxxxxxx", "author_type": "token"} | - | ai_text_embedding_in_fn(text,text) | ai_text_embedding_out_fn(text,jsonb)

What's next

To call a registered AI model, see AI_CallModel.