Register an AI model|V4.6.0|OceanBase Database|docs|OceanBase Documentations

Last Updated：2026-09-17 06:26:55 Updated

This topic describes how to configure AI model access using the DBMS.AI_SERVICE package, so that you can use AI function services in OceanBase Database.

Notice

No model or endpoint registration is required for using the AI_SPLIT_DOCUMENT function.

Prerequisites

You have the necessary permissions for AI models. For details, see AI Function Service Permissions.
You have obtained the API Key of the third-party model service.

Register provider configuration template (new interface)

You can use the REGISTER_PROVIDER interface to register a provider configuration and call AI functions in the provider/model format. There is no need to create models and endpoints separately, nor to specify a complete URL path.

Note

The provider configuration registration interface is supported starting from V4.6.0 BP1. Permissions related to the old interface are fully retained, and existing usage can continue to work. You can use both the old and new interfaces for registration as long as you avoid naming conflicts.

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, you can complete the Register Text Generation Model step below.

Note

Semantic indexes do not support registering provider configurations using the new interface.

Register provider configuration

You can register built-in or custom providers. The details are as follows:

Built-in providers: You only need to specify access_key. protocol and base_url can be omitted, as the system will automatically fill in default values. For a complete list, see the table below.
Custom providers: You must specify at least base_url and access_key. protocol defaults to openai.
If a provider with the same name already exists, use ALTER_PROVIDER to update the configuration.

The list of supported built-in providers and their corresponding default protocol/base_url values are as follows (only effective for first-time registration of a built-in provider and when protocol/base_url are 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`

Alibaba Cloud

Alibaba Cloud DashScope

DeepSeek

Silicon Flow

Tencent Hunyuan

OpenAI

Cohere

Custom

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"
}');

For non-built-in vendors, you must at least provide base_url and access_key. The default value for 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 vendor configuration using REGISTER_PROVIDER, you can call AI functions in the provider/model format. Taking Alibaba Cloud DashScope as an example:

-- Call the embedded model
SELECT AI_EMBED('aliyun-dashscope/text-embedding-v3', 'hello');

-- Call the text generation model
SELECT AI_COMPLETE('aliyun-dashscope/qwen-plus', 'hello');

-- Call Reordering Model
SELECT AI_RERANK('aliyun-dashscope/gte-rerank-v2', 'query', '["doc1", "doc2"]');

(Optional) Configure model parameters

Use ALTER_MODEL_PROFILE to set invocation 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 (Gateway)

An AI gateway sits between the AI function and the actual model service, providing routing and disaster recovery capabilities: it unifies management of multiple endpoints (Endpoints) under the same logical model (which can correspond to different keys, vendors, or models), distributes traffic to healthy nodes based on weights; and if a particular endpoint fails consecutively, it automatically fuses and switches to another available endpoint.

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 the related documentation at the end of this topic.

Register a model and endpoint template (Legacy API)

Use CREATE.AI_MODEL to register a model, then use CREATE_AI_MODEL_ENDPOINT to register the access endpoint for that model. The following example registers three model keys: ob_complete, ob.embed, and ob_rerank, for text generation (AI_COMPLETE), vector embedding (AI_EMBED), and re-ranking (AI_RERANK), respectively. Please replace access_key with your actual API Key.

Note

If you only need to use a specific type of AI function, you can register only the corresponding model and endpoint. For example, if you only use AI_COMPLETE, complete the Register text generation model and endpoint step below.

Register an embedding model and endpoint

For AI_EMBED.

Alibaba Cloud

Alibaba Cloud DashScope

SiliconFlow

Tencent Hunyuan

This example shows how to register an embedding model and endpoint for Alibaba Cloud (compatible with OpenAI format).

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_embed');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_embed_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_embed', '{
    "type": "dense_embedding",
    "model_name": "BAAI/bge-m3"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_embed_endpoint', '{
    "ai_model_name": "ob_embed",
    "url": "https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings",
    -- To be replaced with the actual access_key
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "aliyun-openAI"
}');

This example shows how to register an embedding model and endpoint for Alibaba Cloud DashScope (not compatible with OpenAI format).

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_embed');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_embed_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_embed', '{
    "type": "dense_embedding",
    "model_name": "BAAI/bge-m3"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_embed_endpoint', '{
    "ai_model_name": "ob_embed",
    "url": "https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding",
    -- To be replaced with the actual access_key
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "aliyun-dashscope"
}');

This example shows how to register an embedding model and endpoint for SiliconFlow.

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_embed');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_embed_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_embed', '{
    "type": "dense_embedding",
    "model_name": "BAAI/bge-m3"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_embed_endpoint', '{
    "ai_model_name": "ob_embed",
    "url": "https://api.siliconflow.cn/v1/embeddings",
    -- To be replaced with the actual access_key
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "siliconflow"
}');

This example shows how to register an embedding model and endpoint for Tencent Hunyuan (Hunyuan) (compatible with OpenAI format).

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_embed');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_embed_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_embed', '{
    "type": "dense_embedding",
    "model_name": "BAAI/bge-m3"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_embed_endpoint', '{
    "ai_model_name": "ob_embed",
    "url": "https://api.hunyuan.cloud.tencent.com/v1/embeddings",
    -- To be replaced with the actual access_key
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "hunyuan-openAI"
}');

Register a text generation model and endpoint

For AI_COMPLETE and AI_PROMPT.

Alibaba Cloud

Alibaba Cloud DashScope

deepseek

SiliconFlow

Hunyuan

This example shows how to register a text generation model and endpoint for Alibaba Cloud (compatible with OpenAI format).

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_complete');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_complete_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_complete', '{
    "type": "completion",
    "model_name": "THUDM/GLM-4-9B-0414"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_complete_endpoint', '{
    "ai_model_name": "ob_complete",
    "url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
    -- To be replaced with the actual access_key
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "aliyun-openAI"
}');

This example shows how to register a text generation model and endpoint for Alibaba Cloud DashScope (not compatible with OpenAI format).

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_complete');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_complete_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_complete', '{
    "type": "completion",
    "model_name": "THUDM/GLM-4-9B-0414"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_complete_endpoint', '{
    "ai_model_name": "ob_complete",
    "url": "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation",
    -- To be replaced with the actual access_key
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "aliyun-dashscope"
}');

This example shows how to register a text generation model and endpoints for deepseek.

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_complete');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_complete_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_complete', '{
    "type": "completion",
    "model_name": "THUDM/GLM-4-9B-0414"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_complete_endpoint', '{
    "ai_model_name": "ob_complete",
    "url": "https://api.deepseek.com/chat/completions",
    -- To be replaced with the actual access_key
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "deepseek"
}');

This example shows how to register a text generation model and endpoints for SiliconFlow.

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_complete');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_complete_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_complete', '{
    "type": "completion",
    "model_name": "THUDM/GLM-4-9B-0414"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_complete_endpoint', '{
    "ai_model_name": "ob_complete",
    "url": "https://api.siliconflow.cn/v1/chat/completions",
    -- To be replaced with the actual access_key
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "siliconflow"
}');

This example shows how to register a text generation model and endpoints for Tencent's Hunyuan (compatible with OpenAI format).

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_complete');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_complete_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_complete', '{
    "type": "completion",
    "model_name": "THUDM/GLM-4-9B-0414"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_complete_endpoint', '{
    "ai_model_name": "ob_complete",
    "url": "https://api.hunyuan.cloud.tencent.com/v1/chat/completions",
    -- To be replaced with the actual access_key
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "hunyuan-openAI"
}');

Register a re-ranking model and its endpoints

For AI_RERANK.

DashScope

SiliconFlow

This example shows how to register a re-ranking model and its endpoints for Alibaba Cloud's DashScope (not compatible with OpenAI format).

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_rerank');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_rerank_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_rerank', '{
    "type": "rerank",
    "model_name": "BAAI/bge-reranker-v2-m3"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_rerank_endpoint', '{
    "ai_model_name": "ob_rerank",
    "url": "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank",
    -- To be replaced with the actual access_key
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "aliyun-dashscope"
}');

This example shows how to register a re-ranking model and its endpoints for SiliconFlow.

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_rerank');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_rerank_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_rerank', '{
    "type": "rerank",
    "model_name": "BAAI/bge-reranker-v2-m3"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_rerank_endpoint', '{
    "ai_model_name": "ob_rerank",
    "url": "https://api.siliconflow.cn/v1/rerank",
    -- To be replaced with the actual access_key
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "siliconflow"
}');

Register a multimodal model (image)

Notice

Image embedding and processing are supported starting with V4.6.0 Hotfix1.

Note

The multimodal embedding model currently only supports provider set to aliyun-dashscope.

You can choose the interface based on your scenario for multimodal capabilities:

AI functions (AI_EMBED / AI.Complete): You can use the new interfaces.
Semantic index: The new interfaces are not yet supported. You must use the old interfaces in this section to register the model and endpoint, and specify the model_key in the WITH clause of the index.

Register a multimodal embedding model and endpoint

New interface

Old interface

CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('aliyun-dashscope', '{
  "access_key": "sk-xxxx"
}');

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_vl_embed');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_vl_embed_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_vl_embed', '{
    "type": "dense_embedding",
    "model_name": "qwen2.5-vl-embedding"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_vl_embed_endpoint', '{
    "ai_model_name": "ob_vl_embed",
    "url": "https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding",
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "aliyun-dashscope"
}');

Note

Replace access_key with your actual API Key. When creating a semantic index, dim must match the actual output dimension of the selected model.

Call a multimodal embedding model

For AI_EMBED image embedding, you can provide an image URL or binary image data (BASE64).

New interface

Old interface

-- Replace the image URL with the actual image URL.
SET @img_url = 'https://example.com/image.jpg';
-- Image URL Embedding
SELECT AI_EMBED('aliyun-dashscope/qwen2.5-vl-embedding', @img_url, '{"type":"image"}');

-- Using binary image data (encoded with BASE64)
SET @img_base64 = 'xxxxxxxxxxxxxxxxxxxxxxxxxxx';
-- Image Binary Data Embedding (BASE64)
SELECT AI_EMBED('aliyun-dashscope/qwen2.5-vl-embedding', FROM_BASE64(@img_base64), '{"type":"image"}');

-- Replace the image URL with the actual image URL.
SET @img_url = 'https://example.com/image.jpg';
-- Image URL Embedding
SELECT AI_EMBED('ob_vl_embed', @img_url, '{"type":"image"}');

-- Using binary image data (encoded with BASE64)
SET @img_base64 = 'xxxxxxxxxxxxxxxxxxxxxxxxxxx';
-- Image Binary Data Embedding (BASE64)
SELECT AI_EMBED('ob_vl_embed', FROM_BASE64(@img_base64), '{"type":"image"}');

Register a multimodal text generation model and endpoint

New API

Old API

CALL DBMS_AI_SERVICE.REGISTER_PROVIDER('aliyun-dashscope', '{
  "access_key": "sk-xxxx"
}');

CALL DBMS_AI_SERVICE.DROP_AI_MODEL ('ob_complete');
CALL DBMS_AI_SERVICE.DROP_AI_MODEL_ENDPOINT ('ob_complete_endpoint');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL(
'ob_complete', '{
    "type": "completion",
    "model_name": "qwen3.5-plus"
}');

CALL DBMS_AI_SERVICE.CREATE_AI_MODEL_ENDPOINT (
'ob_complete_endpoint', '{
    "ai_model_name": "ob_complete",
    "url": "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation",
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "aliyun-dashscope"
}');

Call the multimodal text generation model

Use AI_COMPLETE with the image placeholder from AI_PROMPT to process an image. You can provide either an image URL or binary image data (BASE64).

New API

Old API

-- Single Image Processing (Image URL)
SELECT AI_COMPLETE(
  'aliyun-dashscope/qwen3.5-plus',
  AI_PROMPT('Please describe this image {img_0}', @img_url)
);

-- Single Image Processing (BASE64)
SELECT AI_COMPLETE(
  'aliyun-dashscope/qwen3.5-plus',
  AI_PROMPT('Please describe this image {img_0}', FROM_BASE64(@img_base64))
);

-- Single Image Processing (Image URL)
SELECT AI_COMPLETE(
  'ob_complete',
  AI_PROMPT('Please describe this image {img_0}', @img_url)
);

-- Single Image Processing (BASE64)
SELECT AI_COMPLETE(
  'ob_complete',
  AI_PROMPT('Describe this image {img_0}', FROM_BASE64(@img_base64))
);

References

Quick start with AI Function Service: Steps to run the first example after registration.
Use AI Function Service and examples: Syntax and more examples for each AI function.
DBMS_AI_SERVICE package: Complete parameter description for AI models and endpoints.

OceanBase

Customer Stories

Documentation

Register an AI model

Notice

Prerequisites

Register provider configuration template (new interface)

Note

Note

Note

Register provider configuration

Call an AI function

(Optional) Configure model parameters

(Optional) Configure a gateway (Gateway)

Register a model and endpoint template (Legacy API)

Note

Register an embedding model and endpoint

Register a text generation model and endpoint

Register a re-ranking model and its endpoints

Register a multimodal model (image)

Notice

Note

Register a multimodal embedding model and endpoint

Note

Call a multimodal embedding model

Register a multimodal text generation model and endpoint

Call the multimodal text generation model

References