随着大模型与向量检索技术的深度融合，Milvus作为云原生的高性能向量数据库，其支持的向量类型不断丰富。其中FLOAT16_VECTOR字段类型因其在存储成本和计算效率上的优势，正被越来越多AI应用采用。然而，许多开发者在使用Apache Spark进行数据处理时，发现Spark原生只支持FloatType（32位浮点），如何将ArrayType(FloatType)的数据正确写入Milvus的16位半精度浮点向量字段，成为技术实践中的一道常见门槛。本文将从问题根源出发，提供一套实用、可落地的解决方案。

问题本质：精度与类型的鸿沟

在Spark生态中，ArrayType(FloatType)表示一个由32位单精度浮点数组成的数组，每个元素占用4字节。而Milvus的FLOAT16_VECTOR字段要求每个向量元素为16位半精度浮点数，仅占2字节。直接写入会导致字段类型不匹配，Milvus客户端通常会抛出类型转换异常。

更深层的矛盾在于：Spark目前没有内建的半精度浮点数据类型。即便通过Decimal或Double转换，也无法直接生成Milvus期望的二进制格式。因此，必须借助第三方库或Spark-UDF进行显式转换。

主流解决方案：两种高效路径

方案一：使用Milvus Spark Connector官方插件

Milvus官方提供了专门的Spark连接器（milvus-spark-connector），该插件原生支持向量类型自动转换。用户在写入数据时，只需将Spark DataFrame中的ArrayType(FloatType)列配置为Milvus的FLOAT16_VECTOR字段，连接器会在内部自动完成32位到16位的转换。

示例代码（PySpark）：

from pyspark.sql import SparkSession
from milvus_spark_connector import MilvusVectorWriter

spark = SparkSession.builder \
    .appName("WriteFloat16") \
    .config("spark.milvus.host", "localhost") \
    .config("spark.milvus.port", "19530") \
    .getOrCreate()

# 假设df包含列 "float32_vec" (ArrayType(FloatType))
df = spark.createDataFrame([(1, [0.1, 0.2, 0.3])], ["id", "float32_vec"])

df.write.format("milvus") \
    .option("collection.name", "test_collection") \
    .option("collection.vector.field", "float16_vec") \
    .option("collection.vector.type", "FLOAT16_VECTOR") \
    .save()

该方案代码量最少，且性能经过优化，推荐优先采用。

方案二：借助Spark UDF + 半精度转换库

若项目无法引入Spark Connector，或者需要对转换过程进行精细控制，可以自行编写UDF。核心思路是将每个Float32值通过精度截断转化为16位二进制表示（IEEE 754半精度格式）。推荐使用pyhalf或numpy.float16辅助。

核心步骤： 1. 将ArrayType(FloatType)的列通过UDF映射为BinaryType或ArrayType(ShortType)（按字节拆分）。 2. 将转换后的字节数组按照Milvus的协议序列化到InsertRequest中。

PySpark示例：

from pyspark.sql import functions as F
from pyspark.sql.types import BinaryType
import struct
import numpy as np

def float32_to_float16_bytes(float_list):
    # 将浮点数列表转换为半精度字节
    half_bytes = b''
    for val in float_list:
        half = np.float16(val)  # numpy自动截断为16位
        half_bytes += struct.pack('e', half)  # 'e'表示半精度
    return half_bytes

# 注册UDF
to_half_bytes_udf = F.udf(float32_to_float16_bytes, BinaryType())

# 应用转换
df_transformed = df.withColumn("half_vec_bytes", to_half_bytes_udf("float32_vec"))

# 通过Milvus Python SDK写入时，直接将字节插入
from pymilvus import Collection, FieldType, DataType

collection = Collection("test_collection")
for row in df_transformed.collect():
    entity = [row["id"], row["half_vec_bytes"]]
    collection.insert([entity])

注意：pymilvus的FLOAT16_VECTOR字段接受bytes对象，每个向量对应连续的半精度字节序列，长度必须为dim * 2字节。

实战中的关键注意事项

  1. 精度损失评估：32位浮点转换为16位后，有效数字从约7位降至约3位。对于余弦相似度等对精度不敏感的向量（如图像、文本Embedding），通常可以接受；但对于数值敏感的金融、科学计算场景，建议先测试召回率影响。

  2. 维度对齐：Milvus中FLOAT16_VECTOR字段的维度必须在创建集合时固定。Spark端传入的向量数组长度必须严格匹配该维度，否则写入会失败。

  3. 性能与吞吐：利用Spark Connector时，建议批量写入（batch_size参数），避免逐行插入。若使用UDF，由于Python UDF存在序列化开销，对百万级以上数据可考虑使用Pandas UDF或Scala UDF提升效率。

  4. 版本兼容性：Milvus从2.2版本开始支持FLOAT16_VECTOR，Milvus Spark Connector需2.4.0以上。建议查阅官方发布日志确认对应版本。

社区最佳实践与未来展望

目前Milvus社区已推荐优先使用Spark Connector，其内部基于批量RPC和自动类型映射，性能可比原始Python SDK提升3-5倍。对于已上线的Spark Pipeline，建议升级至Spark 3.3+及Milvus 2.4+，以获得对FLOAT16_VECTOR的原生支持。

此外，Milvus 2.5正在开发对BFLOAT16（Google Brain格式）的支持，未来Spark与Milvus的数据类型适配将更加灵活。开发者应持续关注官方文档（milvus.io/docs）中的Spark集成章节，获取最新示例配置。

总结

将Spark的ArrayType(FloatType)数据写入Milvus的FLOAT16_VECTOR字段，技术本质是精度降级与字节序列化。通过Milvus Spark Connector可一键解决问题，而自定义UDF则提供更高灵活性。无论选择哪种路径，都需关注精度损失、维度一致性以及写入性能。随着向量数据库在推荐系统、RAG、多模态搜索中的普及，掌握这一技巧，将帮助工程师更顺畅地打通“数据处理侧”与“向量检索引擎侧”的最后一公里。