---
title: "AI 模型交互（Batch File） - OceanBase 数据库 V4.6.0 | OceanBase 文档中心"
description: AI 模型交互（Batch File） 本文介绍 OceanBase AI 中支持的模型交互方式 Batch File：在建向量索引时，将表中待嵌入的文本批量导出为 JSONL 文件，通过 AI 服务商的 Batch API 异步完成嵌入计算，再将向量写入索引。该方式适用于已有大量历史数据的后建索引场景，相比逐行同步…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.6.0

# AI 模型交互（Batch File）

更新时间：2026-08-12 15:21:43

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.6.0/zh-CN/640.ob-vector-search/370.ob-vector-search-ai-function/250.ob-ai-model-batch-file.md)  

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

#### 注意

本功能目前仅支持语义索引的后建索引方式。

## 前提条件

- 已具备 AI 模型相关权限，具体请参见 [AI 函数服务权限](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682095)。
 - 已注册嵌入模型及端点，且 AI 服务商支持 Batch API（当前支持 OpenAI 与阿里云 DashScope）。注册示例请参见 [AI 模型注册](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682098) 中的”注册嵌入模型及端点“小节。
 - 租户已开启语义索引功能:

  ```sql
  ALTER SYSTEM SET _enable_semantic_index = true;

  ```

## 使用 Batch File 建索引

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

### 第一步：准备数据

```sql
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`，其余参数与语义索引一致。

```sql
-- 请将 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 独有参数说明：

| 参数 | 默认值 | 可选值 | 说明 |
| --- | --- | --- | --- |
| `ai_service_tier` | `STANDARD` | `STANDARD` / `BATCH` | AI 模型交互模式。`STANDARD` 为逐行同步 HTTP 调用；`BATCH` 为批量文件异步处理，异步处理仅作用于建表阶段。 |
| `allow_null_on_failure` | `FALSE` | `TRUE` / `FALSE` | 批量嵌入失败时的容错行为，仅 `ai_service_tier=BATCH` 时生效。为 `TRUE` 时，失败行的向量置为 `NULL`，索引构建继续完成；为 `FALSE` 时，任一行失败即中止整个 DDL 任务。Batch File 整体容错机制原理说明见下文”重试与容错机制“小节。 |

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

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

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

### 第三步：验证语义搜索

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

```sql
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 服务交互时的超时与重试行为配置参数说明如下：

| 参数 | 类型 | 默认值 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| [model_request_timeout](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005685383) | 时间 | `60s` | `[1s, ∞)` | 单次 AI 模型 HTTP 调用的超时时间。 |
| [model_max_retries](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005685349) | 整数 | `2` | `[0, ∞)` | AI 交互失败后的最大重试次数；`0` 表示始终重试。 |

## 监控任务进度

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

| 视图 | 说明 |
| --- | --- |
| [DBA_OB_AI_BATCH_TASKS](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006768685) | 当前进行中的 Batch File 任务 |
| [DBA_OB_AI_BATCH_TASK_HISTORY](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006768684) | 已完成任务的历史记录，额外包含 token 用量与等待时间 |

查询示例：

```sql
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;

```

#### 说明

已完成或失败的任务会在约 10 分钟后从 `DBA_OB_AI_BATCH_TASKS` 归档至 `DBA_OB_AI_BATCH_TASK_HISTORY`。如需长期追溯，请及时查询历史视图。

## 注意事项

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

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

## 相关文档

- [语义索引](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682088)：语义索引的创建、搜索与 `sync_mode` 等参数说明。
 - [AI 模型注册](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682098)：注册嵌入模型与端点。
 - [AI 函数服务权限](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682095)：权限授予与回收。

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线