语义索引

本文档介绍了如何在 OceanBase 数据库中使用语义索引（Semantic Index）。

概述

语义索引利用 OceanBase 数据库内置的嵌入（Embedding）能力，极大地简化了向量索引的使用流程。它实现了向量概念对用户的透明化：你可以直接写入需要存储的原始数据（如文本或图片 URL），OceanBase 数据库会在内部自动将其转换为向量并建立索引。在搜索时，你同样只需提供原始搜索内容，OceanBase 数据库也会自动进行嵌入并搜索向量索引，从而显著提升了使用的便捷性。

在文本语义索引基础上，OceanBase 还支持在 VARCHAR 列上存储图片 URL 并创建图片语义索引。系统自动调用多模态嵌入模型完成向量化，支持以图搜图与以文搜图（跨模态检索）等场景。

考虑到嵌入模型的性能开销，语义索引提供了同步和异步两种嵌入方式供用户选择：

• 同步模式：数据写入后立即进行嵌入和索引，确保数据实时可见。
• 异步模式：由后台任务分批进行数据的嵌入和索引，这能显著提升写入性能，数据延时可见。你可以根据对数据可见性时效的要求，灵活设置后台任务的触发周期。

此外，创建了语义索引的表，同样可以进行暴力搜索。暴力搜索指的是采用全表扫描的方式进行搜索，得到距离最近的前 n 行的精确结果。

功能支持

当前版本语义索引更新、删除与搜索的使用语法、内存管理方式与 HNSW 系列索引完全一致。支持索引监控与维护流程，异步模式下增量刷新会额外触发数据的嵌入。

支持的功能点如下：

一些使用注意事项如下：

• 同步模式下，写入性能可能受到嵌入性能的影响；异步模式下，数据可见性会有延迟。
• 对于重复搜索的场景，建议使用 AI 函数服务（AI Function Service）预先获取查询向量，避免每次搜索都进行嵌入。
• 同一列上不能创建多个语义索引。

前提条件

注册文本嵌入模型

在使用语义索引之前，必须先注册嵌入（Embedding）模型和端点。以下是注册示例：

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",
    "access_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "provider": "siliconflow"
}');

注册多模态嵌入模型（图片）

图片语义索引（content_type=image）须使用多模态（VL）嵌入模型，并通过旧接口注册模型与端点。创建索引时在 WITH 子句的 model 参数中指定注册的 model_key。

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

注意事项（图片语义索引）

• 模型要求：
  • 当前仅支持阿里云 DashScope 提供的多模态嵌入模型。
  • 非多模态（纯文本）嵌入模型用于 content_type=image 时会报错。
• 不支持的功能：
  • 不支持 Doc 模式（切片）。
  • 不支持视频、音频等其他多模态类型。
  • 不支持同一语义索引同时处理文本 URL 与图片 URL，需分别为 content_type=text 和 content_type=image 创建索引。
• 列类型限制：
  • 仅支持在 VARCHAR 列上创建图片语义索引，不支持以下类型：
    • TEXT / LONGTEXT / TINYTEXT / MEDIUMTEXT
    • CHAR / BINARY / VARBINARY / BLOB
• URL 约束：
  • 只支持 http:// 或 https:// 协议。
  • content_type=image 时不允许空字符串。
  • 支持的图片格式依赖所用 AI 模型（通常支持 JPEG、PNG、WebP、GIF 等）；暂不支持存储为二进制（如 BLOB/VARBINARY）。
• 查询限制：
  • 以文搜图（跨模态检索）要求多模态嵌入模型同时支持文本与图片输入，且输出在同一向量空间。
• 其他注意事项：
  • content_type 创建后不可变更，如需变更需删除索引后重建。
  • 若同一列需同时创建文本与图片语义索引，需开启 _enable_multiple_semantic_indexes_on_column 配置，并通过 VECTOR_INDEX Hint 指定具体索引。
• OSS 私有图片：
  • 对象存储 Bucket 默认为私有权限，直接写入对象 URL 可能因鉴权失败导致向量化报错。对于 OSS 上的图片，需先生成预签名 URL，再写入数据库或作为查询参数传入。
  • 可通过 OSS 控制台或阿里云 SDK 生成预签名 URL。
  • 预签名 URL 有有效期，在 sync_mode=manual 或 async 时后台异步向量化，建议有效期设置为 1 小时以上。
  • 向量化完成后 OceanBase 数据库只存储向量值，不会持久化 URL。URL 过期不影响已建好的向量索引。

手动启用语义索引

通过租户级配置项 _enable_semantic_index 启用语义索引功能，默认关闭：

ALTER SYSTEM SET _enable_semantic_index = true;

索引语法及说明

创建

语义索引支持建表时创建和后建两种方式。创建时需要注意：

• 创建索引必须指定在 VARCHAR 类型的列上。
• 支持在同一列上创建多个语义索引。
• model、sync_mode、ai_service_tier 参数不支持在常规向量索引上配置。
• ai_service_tier=BATCH 仅后建索引支持，不支持建表创建时使用。

CREATE TABLE table_name (
    column_name1 data_type1,
    column_name2 VARCHAR, -- 文本或图片 URL 列
    ...,
    VECTOR INDEX index_name (column_name2) WITH (param1=value1, param2=value2, ...)
);

CREATE VECTOR INDEX index_name 
ON table_name(varchar_column_name) 
WITH (param1=value1, param2=value2, ...);

param 参数说明如下：

其他向量索引参数（如 m、ef_construction、ef_search 等）的使用与常规 HNSW/HNSW_BQ 索引相同，具体请参见文末相关文档中的 HNSW 系列索引文档。

搜索

语义索引支持两种搜索方式：

• 使用原始内容搜索（文本或图片 URL）
• 使用向量搜索
  • 可指定 APPROXIMATE/APPROX 子句，使用向量索引进行最近邻搜索。
  • 也可不指定 APPROXIMATE/APPROX 子句，使用全表扫描的方式进行暴力搜索。

使用 Hint 说明与注意事项如下：

• 当在同一列上存在多个语义索引时，查询必须通过 VECTOR_INDEX Hint 明确指定所需使用的向量索引，否则系统会报错。通过 Hint，你不仅可以在查询语句中选择具体的向量索引，还可灵活配置前置或后置过滤条件，提高搜索的准确性和灵活性。
• VECTOR_INDEX Hint 可与 INDEX Hint 配合使用。
• 以上两点的使用说明请参见VECTOR_INDEX Hint。

SELECT ... FROM table_name
ORDER BY semantic_distance(column_name, 'query_content' [, 'query_type'])
APPROXIMATE|APPROX
LIMIT n;

APPROXIMATE/APPROX 子句的详细语法说明请参见文末相关文档中的 HNSW 系列索引文档。

创建、更新、搜索与删除示例

语义索引的 DML 操作（INSERT、UPDATE、DELETE）与常规向量索引完全一致。插入或更新 VARCHAR 类型的数据时，系统会根据 sync_mode 参数设置同步或异步进行向量嵌入。

建表时创建

1. 创建文本语义索引示例

   创建测试表 items 时创建 vector_idx 索引：

   -- 假设 ob_embed 模型的创建在此前已完成（请参考"前提条件"部分注册模型）
   CREATE TABLE items (
       id BIGINT PRIMARY KEY, 
       doc VARCHAR(100),
       VECTOR INDEX vector_idx(doc)
       WITH (distance=l2, lib=vsag, type=hnsw_sq, model=ob_embed, dim=1024, sync_mode=async, sync_interval=10s)
   );
   

   向测试表 items 插入一条数据，系统会自动进行嵌入：

   INSERT INTO items(id, doc) VALUES(1, 'Rose');
   

2. 创建图片语义索引示例

   -- 假设 ob_vl_embed 模型的创建在此前已完成（请参考"前提条件"部分注册模型）
   CREATE TABLE product_images (
   id INT PRIMARY KEY,
   image_url VARCHAR(4096),
   product_name VARCHAR(256),
   VECTOR INDEX img_idx(image_url)
       WITH (distance=l2, type=hnsw, lib=vsag,
           model=ob_vl_embed,
           dim=768, sync_mode=manual, content_type=image)
   ) ORGANIZATION HEAP;
   

后建

1. 后建文本语义索引示例

   创建测试表 items 后，使用 CREATE VECTOR INDEX 语句创建 vector_idx 索引：

   CREATE TABLE items (
       id BIGINT PRIMARY KEY, 
       doc VARCHAR(100)
   );
   
   -- 假设 ob_embed 模型的创建在此前已完成（请参考"前提条件"部分注册模型）
   CREATE VECTOR INDEX vector_idx 
   ON items (doc) 
   WITH (distance=l2, lib=vsag, type=hnsw_sq, model=ob_embed, dim=1024, sync_mode=async, sync_interval=10s);
   

   向测试表 items 插入一条数据，系统会自动进行嵌入：

   INSERT INTO items(id, doc) VALUES(1, 'Rose');
   

2. 后建图片语义索引示例

   CREATE TABLE product_images (
   id INT PRIMARY KEY,
   image_url VARCHAR(4096),
   product_name VARCHAR(256)
   ) ORGANIZATION HEAP;
   
   INSERT INTO product_images VALUES
   (1, 'https://example.com/shoes.jpg', 'Red Shoes'),
   (2, 'https://example.com/bag.jpg',   'Leather Bag');
   
   CREATE VECTOR INDEX img_idx ON product_images(image_url)
   WITH (distance=l2, type=hnsw, lib=vsag,
           model=ob_vl_embed,
           dim=768, sync_mode=manual, content_type=image);
   

更新

更新 VARCHAR 类型的数据时，系统会重新进行嵌入：

• 同步模式：更新后立即重新进行嵌入。
• 异步模式：更新后由后台任务在下次触发周期时重新进行嵌入。

使用示例：

UPDATE items SET doc = 'Lily' WHERE id = 1;

删除

删除操作与常规向量索引一致，直接删除数据即可。

使用示例：

DELETE FROM items WHERE id = 1;

搜索

-- 假设 ob_embed 模型的创建在此前已完成
CREATE TABLE items (
    id INT PRIMARY KEY, 
    doc varchar(100),
    VECTOR INDEX vector_idx(doc)
    WITH (distance=l2, lib=vsag, type=hnsw_sq, model=ob_embed, dim=1024, sync_mode=immediate)
);

INSERT INTO items(id, doc) VALUES(1, 'Rose');
INSERT INTO items(id, doc) VALUES(2, 'Sunflower');
INSERT INTO items(id, doc) VALUES(3, 'Rose');
INSERT INTO items(id, doc) VALUES(4, 'Sunflower');
INSERT INTO items(id, doc) VALUES(5, 'Rose');

-- 使用原始文本进行搜索
SELECT id, doc FROM items
ORDER BY semantic_distance(doc, 'Sunflower') 
APPROXIMATE LIMIT 3;

+----+-----------+
| id | doc       |
+----+-----------+
|  4 | Sunflower |
|  2 | Sunflower |
|  3 | Rose      |
+----+-----------+
3 rows in set

-- 假设 ob_embed 模型的创建在此前已完成（请参考"前提条件"部分注册模型）
CREATE TABLE items (
    id INT PRIMARY KEY, 
    doc varchar(100),
    VECTOR INDEX vector_idx(doc)
    WITH (distance=l2, lib=vsag, type=hnsw_sq, model=ob_embed, dim=1024, sync_mode=immediate)
);

INSERT INTO items(id, doc) VALUES(1, 'Rose');
INSERT INTO items(id, doc) VALUES(2, 'Lily');
INSERT INTO items(id, doc) VALUES(3, 'Sunflower');
INSERT INTO items(id, doc) VALUES(4, 'Rose');

-- 先获取查询向量
SET @query_vector = AI_EMBED('ob_embed', 'Sunflower');

-- 使用向量进行索引搜索
SELECT id, doc FROM items
ORDER BY semantic_vector_distance(doc, @query_vector) 
APPROXIMATE LIMIT 3;

+----+-----------+
| id | doc       |
+----+-----------+
|  3 | Sunflower |
|  1 | Rose      |
|  4 | Rose      |
+----+-----------+
3 rows in set

-- 使用向量进行暴力搜索（精确结果）
SELECT id, doc FROM items
ORDER BY semantic_vector_distance(doc, @query_vector) 
LIMIT 3;

+----+-----------+
| id | doc       |
+----+-----------+
|  3 | Sunflower |
|  4 | Rose      |
|  1 | Rose      |
+----+-----------+
3 rows in set

图片语义索引搜索示例：

-- 以图搜图（IMAGE → IMAGE）
SELECT id, product_name, image_url
FROM product_images
ORDER BY semantic_distance(image_url, 'https://example.com/query.jpg', 'IMAGE')
APPROXIMATE LIMIT 10;

-- 以文搜图（TEXT → IMAGE，跨模态）
SELECT id, product_name, image_url
FROM product_images
ORDER BY semantic_distance(image_url, 'a photo of red shoes', 'TEXT')
APPROXIMATE LIMIT 10;

-- 结合 WHERE 过滤
SELECT id, product_name
FROM product_images
WHERE product_name LIKE 'Red%'
ORDER BY semantic_distance(image_url, 'https://example.com/query.jpg', 'IMAGE')
APPROXIMATE LIMIT 10;

相关文档

• AI 常见问题
• AI 模型交互（Batch File）
• AI 函数语法及示例
• HNSW 系列索引
• 索引内存管理
• 索引监控与维护