SQL Server

SQL Server Embedding Store 与 SQL Server 2025 引入的向量搜索与向量索引集成。

Maven 依赖

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-community-sqlserver</artifactId>
    <version>${latest version here}</version>
</dependency>

API

SQLServerEmbeddingStore

用法

可通过配置 builder 创建该存储的实例。builder 要求提供 DataSource 和嵌入表。

建议配置可池化连接的 DataSource，例如 Universal Connection Pool 或 Hikari。连接池可避免反复创建新数据库连接带来的延迟。

嵌入存储配置示例

如果数据库中已存在嵌入表，请提供表配置：

EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()
   .dataSource(myDataSource)
   .embeddingTable(EmbeddingTable.builder()
           .name("my_embedding_table")
           .dimension(384) // Must specify dimension
           .build())
   .build();

如果表尚不存在，可通过设置 create 选项来创建：

EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()
   .dataSource(myDataSource)
   .embeddingTable(EmbeddingTable.builder()
           .name("my_embedding_table")
           .createOption(CreateOption.CREATE)
           .dimension(384) 
           .build())
   .build();

上一个选项在表已存在时会失败。此时可使用 CREATE_IF_NOT_EXISTS 选项：

EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()
   .dataSource(myDataSource)
   .embeddingTable(EmbeddingTable.builder()
           .name("my_embedding_table")
           .createOption(CreateOption.CREATE_IF_NOT_EXISTS)
           .dimension(384) 
           .build())
   .build();

最后，如果想重新创建表，可使用 CREATE_OR_REPLACE 选项：

EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()
   .dataSource(myDataSource)
   .embeddingTable(EmbeddingTable.builder()
           .name("my_embedding_table")
           .createOption(CreateOption.CREATE_OR_REPLACE)
           .dimension(384) 
           .build())
   .build();

如果现有表的列名与预定义列名不匹配，或者希望使用不同的列名，可以自定义表配置：

SQLServerEmbeddingStore embeddingStore =
SQLServerEmbeddingStore.dataSourceBuilder()
    .dataSource(myDataSource)
    .embeddingTable(EmbeddingTable.builder()
            .createOption(CreateOption.CREATE_OR_REPLACE)
            .name("my_embedding_table")
            .idColumn("id_column_name")
            .embeddingColumn("embedding_column_name")
            .textColumn("text_column_name")
            .metadataColumn("metadata_column_name")
            .dimension(1024)
            .build())
    .build();

也可以不提供 DataSource，直接配置 SQL Server 连接：

SQLServerEmbeddingStore embeddingStore =
SQLServerEmbeddingStore.connectionBuilder()
    .host("localhost")
    .port(1433)
    .database("MyDatabase")
    .userName("myuser")
    .password("mypassword")
    .embeddingTable(EmbeddingTable.builder()
            .name("embeddings")
            .createOption(CreateOption.CREATE_OR_REPLACE)
            .dimension(384)
            .build())
    .build();

嵌入表结构

默认情况下，嵌入表将包含以下列：

Name	Type	Description
id	NVARCHAR(36)	主键。用于存储嵌入存储生成时产生的 UUID 字符串
embedding	VECTOR(dimension)	使用 SQL Server 2025 原生向量类型存储嵌入
text	NVARCHAR(MAX)	存储文本片段
metadata	JSON	使用 SQL Server 2025 原生 JSON 数据类型存储元数据

半精度（float16）支持

动机

SQL Server 中标准的 float32 向量限制为 1998 维。这意味着生成超过 1998 维向量的嵌入模型（例如 OpenAI 的 text-embedding-3-large，最高可达 3072 维）无法使用默认向量类型存储。

为克服此限制，SQL Server 支持半精度（float16）向量，从而可存储更高维度的向量。更多详情请参阅 Microsoft 关于半精度向量的文档以及 JDBC 驱动文档。

要求

要使用半精度向量，必须在 SQL Server 数据库中启用预览功能。
JDBC 驱动属性 vectorTypeSupport 必须设置为 v2。

配置

EmbeddingTable 上的 halfPrecision 参数控制是否使用半精度向量：

HalfPrecisionConfiguration.OFF（默认）：强制使用 float32 向量。注意：若维度大于 1998，表创建将失败。
HalfPrecisionConfiguration.ON：强制使用 float16 向量。
HalfPrecisionConfiguration.AUTO：默认使用 float32，但当配置的维度大于 1998 时自动切换到 float16。

EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()
   .dataSource(myDataSource)
   .embeddingTable(EmbeddingTable.builder()
           .name("my_large_embedding_table")
           .dimension(3072)
           .halfPrecision(HalfPrecisionConfiguration.ON)
           .build())
   .build();

限制

半精度向量支持目前仅适用于 Azure SQL 数据库。
使用半精度向量相比 float32 向量可能导致精度损失。

重要说明

数值类型

元数据字段中的所有数值都以 JSON 字符串形式写入，以避免诸如 Long.MAX_VALUE 这类数字的溢出问题。

向量存储与相似度

SQL Server 2025+ 支持原生 VECTOR 数据类型，本模块使用 VECTOR_DISTANCE 相似度函数。本模块支持 VECTOR_DISTANCE 函数的以下度量：

COSINE：余弦相似度（默认）
EUCLIDEAN：欧氏距离。欧氏度量需要额外计算，才能从距离得到分数。

JSON 元数据支持

SQL Server 2025 提供原生 JSON 数据类型支持和 JSON 索引能力。本模块使用原生 JSON 数据类型存储元数据，并支持创建 JSON 索引，以便通过 JSON_VALUE 函数优化元数据过滤。

可以为特定元数据键配置 JSON 索引创建，并可选择指定键的顺序：

EmbeddingTable embeddingTable = EmbeddingTable.builder()
    .name("test_table")
    .createOption(CreateOption.CREATE_OR_REPLACE)
    .dimension(4)
    .build();

SQLServerEmbeddingStore embeddingStore =
    SQLServerEmbeddingStore.dataSourceBuilder()
        .dataSource(myDataSource)
        .embeddingTable(embeddingTable)
        .addIndex(Index.jsonIndexBuilder()
            .createOption(CreateOption.CREATE_OR_REPLACE)
            .key("author", String.class, JSONIndexBuilder.Order.ASC)
            .key("year", Integer.class)
            .build()
        )
        .build();

使用 Index.jsonIndexBuilder() 创建的索引不支持 CreateOption.CREATE_IF_NOT_EXISTS 选项。

限制

向量索引性能取决于数据规模与分布
不支持在向量列上使用 DiskANN 索引
数据库排序规则应设置为区分大小写的排序规则，以便进行元数据区分大小写的字符串比较
不支持 DOT 距离度量

Maven 依赖​

API​

用法​

嵌入存储配置示例​

嵌入表结构​

半精度（float16）支持​

动机​

要求​

配置​

限制​

重要说明​

数值类型​

向量存储与相似度​

JSON 元数据支持​

限制​