Run AI Embedding & NLP Inference in PolarDB via Polar_AI - PolarDB

Polar_AI is a PolarDB extension that lets you call AI models directly from your database using standard SQL. This guide walks you through enabling the extension, registering a custom model, and calling it — all without leaving your database.

Prerequisites

Before you begin, ensure that you have:

A PolarDB for PostgreSQL (Compatible with Oracle) cluster running version 2.0, revision 2.0.14.13.28.0 or later
A privileged account for the cluster

To check your revision version, run SHOW polardb_version; in your cluster or view it in the PolarDB console. If your revision is older, update it before continuing.

How it works

Polar_AI bridges your database and external AI model services:

You register an AI model by providing its endpoint URL and authentication token.
Polar_AI stores the model configuration in the database.
You call the model using a SQL wrapper function, which passes your input to the model service and returns the response.

All data stays in your database environment throughout the process. The model service must run in the same virtual private cloud (VPC) as your PolarDB cluster.

Key concepts

Embedding: the process of converting high-dimensional data (such as text or images) into a compact, dense vector representation, enabling similarity search and other ML tasks.
Natural language processing (NLP): a field of AI for processing and generating human language, covering text classification, sentiment analysis, machine translation, and dialogue systems.

Get started with Polar_AI

This guide uses a DeepSeek-R1-Distill-Qwen-7B model deployed on Platform for AI (PAI) as the example. All steps build on each other — the model name my_test_pai_model and the input function ai_text_in_fn you create in earlier steps are referenced in later ones.

Step 1: Enable the extension

Connect to your cluster with a privileged account and run:

CREATE EXTENSION IF NOT EXISTS polar_ai;

Step 2: Deploy a model service

Deploy the AI model that Polar_AI will call.

Deploy DeepSeek-R1-Distill-Qwen-7B on PAI. Make sure the service is deployed in the same VPC as your PolarDB cluster.
After deployment, go to Service details > Call Information and click View Call Information. Note the Access address and Token — you need both in the next steps.

Step 3: Define an input function

The input function translates your SQL inputs into the JSON request body that the model service expects.

The DeepSeek-R1-Distill-Qwen-7B model expects this request body format:

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

Create an input function that builds this JSON from a model name and a text prompt:

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 4: Register the model

Call AI_CreateModel to register the model in your database:

SELECT polar_ai.ai_createmodel(
    'my_test_pai_model',                              -- model_id: unique name for this model
    '<access address>/v1/completions',                -- model_url: endpoint + call method
    'Alibaba',                                        -- model_provider
    'EAS large language model',                       -- model_type
    'DeepSeek-R1-Distill-Qwen-7B',                   -- model_name
    '{"author_type": "token", "token": "<model service token>"}', -- model_config: auth token
    NULL,                                             -- model_headers_fn: optional
    'ai_text_in_fn'::regproc,                         -- model_in_transform_fn: input function
    NULL                                              -- model_out_transform_fn: optional
);

Replace <access address> and <model service token> with the values from Step 2.

Key parameters:

Parameter	Description
`model_url`	The model's access address with the call method appended. `Chat` and `Completions` are supported. This example uses `Completions`, so `/v1/completions` is appended.
`model_config`	Authentication configuration. Set `token` to the model service token from Step 2.
`model_in_transform_fn`	The input function that formats your SQL inputs as a JSON request body. Set this to `ai_text_in_fn`, the function created in Step 3.
`model_headers_fn`	Optional. A function that adds custom HTTP headers to requests. Set to `NULL` if not needed.
`model_out_transform_fn`	Optional. A function that transforms the raw model response before returning it. Set to `NULL` to return the raw response.

To verify that the model was registered, run:

SELECT * FROM polar_ai._ai_models;

Step 5: Create a wrapper function

Create a SQL function that calls AI_CallModel and extracts the response text:

CREATE OR REPLACE FUNCTION my_text_pai_model_func(model_id text, content text)
    RETURNS text
    AS $$ SELECT (polar_ai.AI_CALLMODEL($1, $2)::jsonb -> 'choices' -> 0 ->> 'text')::text AS result $$
    LANGUAGE 'sql' IMMUTABLE;

This function passes model_id and content to AI_CALLMODEL, then extracts the response text from the choices[0].text field of the JSON response.

Step 6: Call the model

SELECT my_text_pai_model_func('my_test_pai_model', 'Hello');

Expected output:

my_text_pai_model_func
--------------------------------------
 Hello! How can I assist you today?
(1 row)

What's next

AI_CreateModel — full parameter reference for registering models
AI_CallModel — full reference for calling models from SQL