ModelInference

ModelInference 插件可在 DolphinDB 中直接将文本转换为向量，方便将数据库中的文档、问答、日志等文本数据接入 RAG 应用。可先使用 DolphinScript 完成数据查询、清洗和整理，再调用该插件生成 FLOAT 类型的向量矩阵，用于向量入库、相似度检索、召回排序等后续处理。本次发布仅包含 RAG 场景所需的模型环境检查、模型注册与查询、模型加载与停止、文本向量化等功能。

在使用 DolphinX RAG 功能前，请先加载本插件。

安装插件

版本要求

DolphinDB Server 版本要求：3.00.6 及以上版本。

部署环境要求： LINUX-ABI。

安装步骤

  1. 在 DolphinDB 客户端中使用 listRemotePlugins 函数查看可供安装的插件。
    login("admin", "123456")
listRemotePlugins()
  2. 使用 installPlugin 函数安装插件。
    installPlugin("ModelInference")
  3. 使用 loadPlugin 函数加载插件。
    loadPlugin("ModelInference")

插件加载后，可通过 ModelInference:: 命名空间调用模型管理、实例管理和文本向量化相关函数。

使用流程

准备模型

ModelInference 面向 DolphinX RAG 场景提供预置的 embedding 模型能力。使用前确认插件已安装并完成模型资源部署；示例代码可直接使用预置模型名称加载实例并调用 embed 生成文本向量，无需在示例中展示 ONNX 模型导出、配置或注册流程。

默认注册表根目录为 getHomeDir() 下的 modelInference 子目录，实际路径可通过 ModelInference::info() 返回的 registryRoot 查看。注册后的模型文件会被复制到插件管理目录，后续加载时使用注册包中的模型副本。

<DDBHomeDir>/modelInference/
├── models/
│   └── <modelKey>/
│       ├── model.manifest.json
│       └── 模型运行所需文件
├── plans/
│   └── <planId>.json
├── staging/
└── backup/

执行文本向量化

建议在推理前使用 getModelCapabilities 查询模型支持的任务、接口和输入限制，再选择对应推理函数。
texts = ["What is DolphinDB?", "How to build a RAG pipeline?"]
vectors = ModelInference::embed(instanceName, texts)

ModelInference::stopInstance(instanceName)

接口说明

info

语法

ModelInference::info()

详情

返回插件、LibTorch 和 ONNX Runtime 运行环境信息，用于启动检查、设备选择和兼容性诊断。该函数为只读操作。

参数

无。

返回值

返回 STRING-ANY 字典，包含以下字段：

字段 类型 说明
apiVersion STRING API 版本，当前为 2。
libtorchVersion STRING LibTorch 版本。
onnxRuntimeVersion STRING ONNX Runtime 版本。
runtimeFlavor STRING 构建 flavor。
supportedDevices STRING 支持的设备，例如 CPU、CUDA。
supportedBackends STRING 支持的后端，例如 native、ONNX。
cudaCompiled BOOL 是否编译 CUDA。
cudaAvailable BOOL 当前 CUDA 是否可用。
libtorchIntraOpThreads LONG LibTorch 用于执行单个算子内部并行计算的线程数（intra-op），为进程级配置。
libtorchInterOpThreads LONG LibTorch 用于并行调度多个算子或任务的线程数（inter-op），为进程级配置。
registryType STRING 模型注册表类型。local-manifest 表示使用本地 manifest 文件管理模型注册信息。
registryRoot STRING 本地注册表根目录。
supportedDtypes STRING 支持的计算类型。当前仅支持 float32。
executionMode STRING 执行模式，当前为 synchronous。

registerModel

语法

ModelInference::registerModel(modelKey, modelPath, [options])

详情

在插件系统中登记指定模型。该函数会校验模型文件的完整性，并将其纳入插件的本地管理目录。注册成功后，系统即可识别并加载该模型，实现模型从外部文件到系统可用资源的转化。

参数

modelKey 非空 STRING 类型标量，指定注册后的模型名称。

modelPath 非空 STRING 类型标量，指定模型源目录。

options 可选参数，STRING 到 ANY 类型的字典，指定注册后端、覆盖行为和加载检查选项，支持以下 key：

  • backend：STRING 类型标量， 指定模型后端，可取 “native” 或 “onnx”，默认为 “native”。

  • overwrite：BOOL 类型标量，指定是否覆盖已有同名模型，默认为 false。

  • check：BOOL 类型标量，指定是否在发布前构造临时 Backend 做加载检查，默认为 true。

返回值

返回一个表，包含如下列：

列名 类型 说明
modelKey STRING 模型名称，即注册时指定的唯一标识符。
architecture STRING 模型架构类型。
adapter STRING 所使用的适配器名称。
adapterVersion STRING 适配器版本号。
parameterCount LONG 模型的参数总量。
sizeBytes LONG 模型注册包在本地占用的磁盘大小（字节）。
digest STRING 注册包的聚合 SHA-256 校验值，用于确保模型文件的完整性与一致性。
status STRING 模型状态。注册成功后固定为 REGISTERED。
registeredAt TIMESTAMP 模型首次完成注册的时间。
weightDtypes STRING 模型权重支持的数据类型（如 FP32, INT8 等）。
tasks STRING 该模型支持的任务类型列表。
updatedAt TIMESTAMP 模型元数据的最后更新时间。
backend STRING 模型运行的后端环境（native 或 onnx）。

unregisterModel

语法

ModelInference::unregisterModel(modelKey)

详情

从本地注册表移除一个已发布模型记录。调用前需要先停止该模型的 Instance，并清除关联自动加载计划。原始源目录不受影响。

参数

modelKey 非空 STRING 类型标量，指定待移除的模型名称。

返回值

返回 BOOL。模型记录成功移除时返回 true；删除失败时报错。

listRegisteredModels

语法

ModelInference::listRegisteredModels()

详情

返回本地注册表中当前已发布模型的快照。函数只读取 manifest 和注册表索引，不加载模型权重；无模型时返回 0 行空表。

参数

无。

返回值

返回一个表，包含如下列：

列 类型 说明
modelKey STRING 模型名称。
architecture STRING 模型架构。
adapter STRING 适配器名称。
adapterVersion STRING 适配器实现的版本号，用于判断注册模型与当前插件内置适配器的兼容性。
parameterCount LONG 参数量。
sizeBytes LONG 模型包大小。
digest STRING 聚合 SHA-256。
status STRING 当前为 REGISTERED。
registeredAt TIMESTAMP 注册时间，UTC+8。
weightDtypes STRING 模型权重文件使用的数据类型列表，多个类型以逗号分隔，例如 FP32、FP16 或 INT8。
tasks STRING 任务列表，逗号分隔。
updatedAt TIMESTAMP 模型注册记录最后一次更新的时间（UTC+8），例如重新注册或覆盖同名模型时会刷新。
backend STRING native 或 onnx。

getModelCapabilities

语法

ModelInference::getModelCapabilities(modelKey)

详情

返回指定注册模型的推理能力和输入约束，供调用方在加载和调用前选择接口。能力描述来自实际模型包和 Adapter。

参数

modelKey 非空 STRING 类型标量，指定已注册模型名称。

返回值

返回 STRING-ANY 字典，主要字段如下：

字段 类型 说明
modelKey STRING 已注册模型名称。
architecture STRING 模型架构类型。
adapter STRING 所使用的适配器名称。
tasks STRING 向量 任务类型，当前包括 forecast、embedding 和 imputation。
capabilities STRING 向量 模型支持的推理 API。
computeDtypes STRING 向量 支持的计算 dtype。
categoricalEncodings STRING 向量 分类协变量编码方式。
nativeQuantiles DOUBLE 向量 原生分位点；不适用时为空。
longHorizonStrategy STRING 长预测步策略。
maxInputLength LONG 最大输入长度；不适用时为 0。
maxVariableCount LONG 多变量输入允许的最大变量数；不适用时为 0。
outputDimension LONG 输出向量维度；不适用时为 0。
embeddingNormalize BOOL embedding 输出是否已进行 L2 归一化；非 embedding 模型为 false。
embeddingMetric STRING 向量索引和查询应使用的距离度量；embedding 模型为 euclidean，非 embedding 模型为空字符串。
contextLength LONG 上下文长度；不适用时为 0。
directPredictionLength LONG 直接预测长度；不适用时为 0。
maxPredictionLength LONG 最大预测长度；不适用时为 0。
multivariate BOOL 多变量能力。
categoricalCovariates BOOL 分类协变量能力。
crossLearning BOOL 跨序列学习能力。
timeFeatureCount LONG 每个时间点所需的时间特征数量；不适用时为 0。

loadModel

语法

ModelInference::loadModel(modelKey, [options])

详情

同步加载一个已注册模型，创建一个独立 Instance，并返回其名称。一次调用创建一个 Instance。

参数

modelKey 非空 STRING 类型标量，指定已注册模型名称。

options 可选参数，STRING 到 ANY 类型的字典，指定加载参数，支持以下 key：

  • instanceName：STRING 类型标量，显式指定 Instance 名称，需在当前 Runtime 内全局唯一，默认自动生成。

  • device：STRING 类型标量，指定运行设备，可取 “cpu”、“cpu:0” 或可用的 “cuda:N”，默认为 “cpu”。ONNX 后端只支持 “cpu” 和 “cpu:0”。

  • computeDtype：STRING 类型标量，指定计算类型，当前版本支持 “float32”。

  • onnxCpuThreads：INT 或 LONG 类型标量，指定 ONNX Runtime 的 CPU 算子线程数，默认为 0，表示使用默认值。Native 后端暂不支持非零值。

返回值

返回 STRING 类型的 instanceName。后续推理和停止操作均使用该名称。

listLoadedModels

语法

ModelInference::listLoadedModels()

详情

返回当前 Runtime 中已发布 Instance 的快照。函数不加载新模型、不改变 Instance 状态；无 Instance 时返回 0 行空表。

参数

无。

返回值

返回一个表，包含当前 Runtime 中已加载实例的快照信息。表中包含以下列：

列名 类型 说明
modelKey STRING 该实例所属的模型名称。
instanceName STRING 实例的唯一标识名称，用于后续推理（如 embed）和停止操作。
status STRING 实例当前状态。加载成功后固定为 READY。
architecture STRING 模型架构类型。
adapter STRING 所使用的适配器名称。
device STRING 运行该实例的设备（如 cpu 或 cuda:0）。
computeDtype STRING 实例运行时的计算数据类型（当前仅支持 float32）。
onnxCpuThreads LONG ONNX Runtime 的 CPU 算子线程数。0 表示使用系统默认值。
parameterCount LONG 模型的参数总量。
loadedAt TIMESTAMP 实例加载完成的时间（UTC+8）。
planId STRING 创建该实例的自动加载计划 ID；若为手动加载则为空字符串。

stopInstance

语法

ModelInference::stopInstance(instanceName)

详情

停止并移除一个已加载 Instance。停止会阻止新的推理调用进入该 Instance，并等待已接纳的同步调用完成后释放 Backend。停止 Instance 不删除注册模型，不清除自动加载计划，也不影响同模型的其他 Instance。

参数

instanceName 非空 STRING 类型标量，指定待停止的 Instance 名称。

返回值

返回 BOOL。Instance 成功从 Runtime 移除并完成释放时返回 true。

embed

语法

ModelInference::embed(instanceName, texts)

详情

使用已加载的 embedding Instance 将文本编码为向量。接口同步执行，仅适用于 capabilities 包含 embed 的模型。

参数

instanceName 非空 STRING 类型标量，指定已加载 Instance 名称。

texts 非空 STRING 类型标量或向量，指定待编码文本；向量长度为 1 到 1024，不允许空字符串。

返回值

返回一个 FLOAT 矩阵，行数为输入文本的数量，列数为向量维度。。STRING 标量输入时 batch 为 1。

完整示例

以下示例演示在 RAG 流程中使用预置的 embedding 模型，将文档文本转换为向量。生成的向量可用于后续向量检索、召回和问答生成。本示例重点展示 RAG 推理逻辑。由于使用的是预置模型，代码中省略了模型导出、配置和注册等前置步骤；同时为了保持示例简洁，未包含复杂的向量入库持久化逻辑。

loadPlugin("ModelInference")
go

// 使用预置的 embedding 模型
modelKey = "embdding"

// 查询模型能力，确认支持 embed 接口
cap = ModelInference::getModelCapabilities(modelKey)
print(cap)

// 加载模型实例
loadOptions = dict(STRING, ANY)
loadOptions["device"] = "cpu"
loadOptions["computeDtype"] = "float32"
instanceName = ModelInference::loadModel(modelKey, loadOptions)

// RAG 示例：准备待向量化的文档片段
docs = table(
    1 2 3 as docId,
    ["DolphinDB is a high-performance analytical database.",
     "DolphinDB supports distributed time-series data processing.",
     "RAG retrieves relevant context before generating an answer."] as content)

// 将文档文本转换为向量
vectors = ModelInference::embed(instanceName, docs.content)

// 查看向量化结果。vectors 可用于后续向量检索、召回或写入向量库。
print(vectors)

// 停止实例，释放资源
ModelInference::stopInstance(instanceName)