SQL Server

SQL Server 嵌入存储与 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();

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

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();

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

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();

嵌入表结构

默认情况下，嵌入表会有以下列：

名称	类型	描述
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 距离度量