This topic describes how to register AI models and providers by using the DBMS_AI_SERVICE package, so that you can use AI functions in OceanBase AI Database.
Notice
You do not need to register a model or provider configuration when using the AI_SPLIT_DOCUMENT function.
Prerequisites
- You have the required permissions for AI models. For details, see AI Function Service Permissions.
- You have obtained the API key of the third-party model service.
Register a provider configuration
You can use the REGISTER_PROVIDER statement to register provider configurations and call AI functions in the provider/model format. This eliminates the need to create models and endpoints separately or to specify complete URL paths.
Note
Provider configuration registration is supported starting from V4.6.2.1.
Note
If you only need to use a specific type of AI function, you can register only the corresponding provider. For example, if you only use AI_COMPLETE, complete the registration steps below and select the corresponding model.
Note
Semantic indexes do not currently support provider registration using the REGISTER_PROVIDER statement. You must register them separately using CREATE_AI_MODEL or CREATE_AI_MODEL_ENDPOINT. For more information, see Semantic search.
Supported providers
You can register both built-in and non-built-in providers (including vLLM and custom providers). The details are as follows:
- Built-in providers: You only need to specify the
access_key. Theprotocolandbase_urlparameters can be omitted as the system will automatically fill in the default values. For a complete list, see the table below. - vLLM: The
protocolandbase_urlparameters are required and cannot be omitted. - Custom provider: You must specify at least
base_urlandaccess_key. The default value ofprotocolisopenai. - If a provider with the same name already exists, use
ALTER_PROVIDERto update the configuration.
The following table lists the supported built-in providers and their default protocol and base_url values. These values take effect only for first-time registration of a built-in provider and when protocol or base_url is not specified:
provider |
protocol |
base_url |
|---|---|---|
aliyun |
openai |
https://dashscope.aliyuncs.com/compatible-mode/v1 |
aliyun-dashscope |
dashscope |
https://dashscope.aliyuncs.com/api/v1 |
deepseek |
openai |
https://api.deepseek.com |
siliconflow |
openai |
https://api.siliconflow.cn/v1 |
openai |
openai |
https://api.openai.com/v1 |
cohere |
cohere |
https://api.cohere.com/v2 |
tencent |
openai |
https://api.hunyuan.cloud.tencent.com/v1 |
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('aliyun', '{
"access_key": "sk-xxxx"
}');
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('aliyun-dashscope', '{
"access_key": "sk-xxxx"
}');
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('deepseek', '{
"access_key": "sk-xxxx"
}');
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('siliconflow', '{
"access_key": "sk-xxxx"
}');
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('tencent', '{
"access_key": "sk-xxxx"
}');
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('openai', '{
"access_key": "sk-xxxx"
}');
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('cohere', '{
"access_key": "sk-xxxx"
}');
vLLM is a locally deployed framework. When connecting, you must configure protocol and base_url, which cannot be omitted. If the service does not validate the key, access_key must also be filled with a non-empty placeholder value. Currently, only embedding (AI_EMBED) is supported:
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('vllm', '{
"protocol": "vllm",
"base_url": "https://vllm.example.com/v1",
"access_key": "sk-xxxx"
}');
For other non-built-in providers, you must at least fill in base_url and access_key. The default protocol is openai:
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('ob-mass', '{
"protocol": "openai",
"base_url": "https://example.com/v1",
"access_key": "sk-xxxx"
}');
Call an AI function
After registering a provider configuration using REGISTER_PROVIDER, you can call AI functions in the provider/model format. Taking Alibaba Cloud DashScope as an example:
-- Call the embedding model.
SELECT AI_EMBED('aliyun-dashscope/text-embedding-v3', 'hello');
-- Call the text generation model.
SELECT AI_COMPLETE('aliyun-dashscope/qwen-plus', 'hello');
-- Call the reranking model.
SELECT AI_RERANK('aliyun-dashscope/gte-rerank-v2', 'query', '["doc1", "doc2"]');
(Optional) Configure model parameters
Use ALTER_MODEL_PROFILE to set call parameters for provider/model:
CALL DBMS_AI_SERVICE.ALTER_MODEL_PROFILE('aliyun/qwen-plus', '{
"model_config": {
"max_tokens": 4096,
"temperature": 0,
"enable_thinking": false
},
"run_config": {
"batch_size": 16,
"max_image_size": 4194304,
"min_concurrency": 10,
"max_concurrency": 100
}
}');
(Optional) Configure a gateway
An AI gateway sits between AI functions and the actual model service, providing routing and disaster recovery capabilities: it manages multiple endpoints under the same logical model (which can correspond to different keys, providers, or models), distributes traffic to healthy nodes based on weights, and automatically fuses an endpoint and switches to another available endpoint if it fails consecutively.
When creating a gateway using CREATE_AI_GATEWAY, you can configure endpoint weights and circuit-breaking parameters simultaneously:
CALL DBMS_AI_SERVICE.CREATE_AI_GATEWAY('prod_gateway', '{
"endpoints": [
{"name":"ep1","model":"aliyun/qwen-plus","weight":70},
{"name":"ep2","model":"deepseek/deepseek-chat","weight":30}
],
"circuit_breaker": {
"failure_rate_threshold": 50,
"window_size_seconds": 60,
"minimum_requests": 10,
"break_duration_seconds": 60,
"probe_requests": 3
}
}');
For the complete syntax and parameter descriptions, see CREATE_AI_GATEWAY.
Register a multimodal model
Note
Image embedding and processing are supported starting from V4.6.2.1.
Note
The current multimodal capabilities are described as follows:
- Multimodal Embedding : Supported
providersincludealiyun-dashscopeandvllm. - Multimodal Text Generation : Currently only supports
aliyun-dashscope,vllmis not supported yet. - Supported AI Functions : Include
AI_EMBED,AI_COMPLETE, andAI_PROMPT.
Register a multimodal embedding provider
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('aliyun-dashscope', '{
"access_key": "sk-xxxx"
}');
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('vllm', '{
"protocol": "vllm",
"base_url": "https://vllm.example.com/v1",
"access_key": "sk-xxxx"
}');
Note
Replace access_key with your actual API Key.
Call a multimodal embedding model
Used for AI_EMBED image embedding. You can provide an image URL or Base64-encoded binary image data.
-- Replace the image URL with the actual image URL.
SET @img_url = 'https://example.com/image.jpg';
-- Embed an image URL.
SELECT AI_EMBED('aliyun-dashscope/qwen2.5-vl-embedding', @img_url, '{"type":"image"}');
-- Use Base64-encoded binary image data.
SET @img_base64 = 'xxxxxxxxxxxxxxxxxxxxxxxxxxx';
-- Embed Base64-encoded binary image data.
SELECT AI_EMBED('aliyun-dashscope/qwen2.5-vl-embedding', FROM_BASE64(@img_base64), '{"type":"image"}');
Register a multimodal text generation provider
Only the aliyun-dashscope provider is supported.
CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('aliyun-dashscope', '{
"access_key": "sk-xxxx"
}');
Call the multimodal text generation model
Use AI_COMPLETE with an image placeholder from AI_PROMPT to process an image. You can provide either an image URL or Base64-encoded binary image data.
-- Understand a single image from an image URL.
SELECT AI_COMPLETE(
'aliyun-dashscope/qwen3.5-plus',
AI_PROMPT('Please describe this image {img_0}', @img_url)
);
-- Understand a single image from Base64-encoded data.
SELECT AI_COMPLETE(
'aliyun-dashscope/qwen3.5-plus',
AI_PROMPT('Please describe this image {img_0}', FROM_BASE64(@img_base64))
);
References
- Get started with AI Function Service: Steps to run the first example after registration.
- Syntax and examples of AI functions: Syntax and more examples for each AI function.
- Overview of DBMS_AI_SERVICE: Complete parameter descriptions for provider configuration and related subprograms.
- Semantic search: Semantic indexing does not currently support model registration via
REGISTER_PROVIDER.