AI 模型交互（Batch File）

本文介绍 OceanBase AI 数据库中支持的模型交互方式 Batch File：在建向量索引时，将表中待嵌入的文本批量导出为 JSONL 文件，通过 AI 服务商的 Batch API 异步完成嵌入计算，再将向量写入索引。该方式适用于已有大量历史数据的后建索引场景，相比逐行同步 HTTP 调用，可显著降低网络往返开销，并支持断点续传与更高吞吐量。

前提条件

• 已具备 AI 模型相关权限，具体请参见 AI 函数服务权限。
• 已注册嵌入模型及端点，且 AI 服务商支持 Batch API（当前支持 OpenAI 与阿里云 DashScope）。注册示例请参见 语义搜索 中的「注册文本嵌入模型」小节。语义索引须使用旧接口 CREATE_AI_MODEL / CREATE_AI_MODEL_ENDPOINT。
• 租户已开启语义索引功能:

  ALTER SYSTEM SET _enable_semantic_index = true;
  

使用 Batch File 建索引

本节为 Batch File 方式建索引的示例，附带参数和原理说明。

第一步：准备数据

CREATE TABLE articles (
  id INT PRIMARY KEY,
  content VARCHAR(512)
);

INSERT INTO articles VALUES
  (1, 'machine learning neural network'),
  (2, 'deep learning transformer attention'),
  (3, 'natural language processing embeddings');

第二步：创建语义索引

在 WITH 子句中指定 ai_service_tier=BATCH，其余参数与语义索引一致。

-- 请将 model 替换为已注册的嵌入模型名称
CREATE VECTOR INDEX idx_articles ON articles(content)
  WITH (distance=l2, type=hnsw, lib=vsag, model=ob_embed, dim=1024,
        sync_mode=immediate, ai_service_tier=BATCH);

BatchFile 独有参数说明：

执行期间还可以进行如下操作：

• 通过视图监控任务进度，具体请参见下文”监控任务进度“小节。
• 进行容错降级，具体请参见下文”重试与容错机制“小节。

索引创建完成后，DML 操作（如 INSERT、UPDATE、DELETE）和后台刷新会通过 HTTP 同步调用，延迟较低。

第三步：验证语义搜索

索引就绪后，可直接用 semantic_distance 进行语义搜索：

SELECT id FROM articles
  ORDER BY semantic_distance(content, 'language model')
  APPROX LIMIT 3;

重试与容错机制

Batch File 方式下，批量嵌入结果并非全成功或全失败的二选一，结果文件中可以按行成功或失败。具体而言，当 Batch 文件中包含大量数据行时，系统会首先通过自动重试机制（对 HTTP 网络错误、限流、服务端错误等可重试情况）应对临时性故障。若重试仍有部分行失败，则可通过配置 allow_null_on_failure 索引参数控制后续行为：若设置为 TRUE，系统会将失败行的向量结果置为 NULL，其余行正常完成，索引整体构建继续；若设置为 FALSE，则任意行失败都会导致整个 DDL 任务失败。

Batch File 模式下，与 AI 服务交互时的超时与重试行为配置参数说明如下：

监控任务进度

Batch File 索引构建会生成可追踪的批处理任务。可通过以下系统视图查询任务状态：

查询示例：

SELECT TASK_ID, STATUS, PROGRESS_PERCENT, ERROR_DETAIL
  FROM oceanbase.DBA_OB_AI_BATCH_TASKS
  WHERE MODEL_NAME = 'ob_embed'
  ORDER BY TASK_CREATE_TIME DESC;

注意事项

在正式使用前，请注意以下事项：

• 仅支持后建索引：ai_service_tier=BATCH 不支持随表建索引（在 CREATE TABLE 中内联定义向量索引）。
• 依赖 Batch API：须正确配置模型 endpoint，且 AI 服务商 Batch API 可用；Batch 任务为异步处理，完成时间取决于服务商负载，大批量数据可能需要较长时间。
• 不支持稀疏索引：ai_service_tier 不适用于稀疏向量索引类型。
• 远程文件管理：上传至 AI 服务商的 JSONL 文件及结果文件由服务商管理，OceanBase AI 数据库仅保留文件 ID 引用；任务完成后会在固定时间内清理远程文件。

相关文档

• 语义搜索：语义索引的创建、搜索与 sync_mode 等参数说明。
• AI 模型注册：注册嵌入模型与端点。
• AI 函数服务权限：权限授予与回收。