This topic describes how to use the AI_EMBED function in the AI function service to directly convert text or images into vector data within OceanBase AI Database.
Note
Image embedding is supported starting from V4.6.2.1.
Overview
Notice
Hybrid Search depends on AI model management and the AI_EMBED function. When deleting an AI model, you must check whether it is referenced by Hybrid Search to avoid potential issues.
OceanBase AI Database supports using the AI_EMBED function of the AI function service to generate vector embeddings. Users do not need to install any dependencies; they only need to register vendor information by calling the DBMS_AI_SERVICE PL package, after which they can call this function in SQL statements.
AI_EMBED uses model_key to specify a registered Embedding Model, and converts text, image URLs, or image binaries into vectors. If the model supports multiple dimensions, you can specify the output vector dimensionality via dim. For image inputs, specify the type using the JSON parameter parameters with {"type":"image"}.
Prerequisites
Grant privilege
Before using AI function services such as the AI_EMBED function, ensure you have the required privileges. For detailed privileges, see AI Function Service Permissions.
Register model
Before using the AI_EMBED function, you must register a vendor. The following is an example of the syntax:
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('aliyun-dashscope', '{
"access_key": "sk-xxxx"
}');
After registration, you can call it in the provider/model format, for example, aliyun-dashscope/text-embedding-v3. For more vendor information, see Register an AI model.
Syntax
AI_EMBED(model_key, input[, dim[, parameters]])
Parameter description:
Parameters |
Description |
Type |
Optional |
|---|---|---|---|
| model_key | Model identifier,provider/modelformat, for example,aliyun-dashscope/text-embedding-v3. |
VARCHAR(128) | No |
| input | Data to be embedded: text, image URL (HTTP/HTTPS), or image binary (for example,BLOBcolumns,FROM_BASE64(...)). |
VARCHAR / BLOB | No |
| dim | Specifies the output vector dimensionality. Some models support configuring multiple dimensions; this parameter is optional. If omitted, the model's default dimensionality is used. | INT64 | Yes |
| parameters | Optional configuration. It can be a JSON object or a JSON string. When you input an image, you must specify {"type":"image"}. If dim is omitted, this parameter can be passed directly as the third argument. |
JSON | Yes |
If either model_key or input is specified as NULL, the function returns an error.
The return value is described as follows:
- A string in vector format, representing the vector converted by the embedding model based on the input.
Examples
Generate a text vector
SELECT AI_EMBED(
'aliyun-dashscope/text-embedding-v3',
'OceanBase is a distributed database',
128
) AS embedding;
The third parameter 128 indicates that a 128-dimensional vector is expected. If this parameter is omitted, the model’s default dimension is used.
Generate a vector from an image URL
SELECT AI_EMBED(
'aliyun-dashscope/qwen2.5-vl-embedding',
'https://example.com/sample.png',
'{"type":"image"}'
) AS embedding;
The image URL must use HTTP or HTTPS.
Generate a vector from image binary data
Image binary data can be passed in using FROM_BASE64(...) or directly using a BLOB column. OceanBase AI Database automatically identifies the image format and converts it into a format acceptable to the model.
-- Convert the BASE64 image to binary and embed it.
SET @img_base64 = '...'; -- Replace with the actual image BASE64 string
SELECT AI_EMBED(
'aliyun-dashscope/qwen2.5-vl-embedding',
FROM_BASE64(@img_base64),
'{"type":"image"}'
) AS embedding;
-- When an image is already stored in a BLOB column, you can directly pass the column as follows:
SELECT id,
AI_EMBED(
'aliyun-dashscope/qwen2.5-vl-embedding',
image_blob,
'{"type":"image"}'
) AS embedding
FROM image_table;