DocArray 数据序列化完全指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00057/article/details/148755291

DocArray 数据序列化完全指南

docarray Represent, send, store and search multimodal data 项目地址: https://gitcode.com/gh_mirrors/do/docarray

前言

在数据处理和传输过程中，序列化是一个至关重要的环节。DocArray 作为一个高效的多模态数据处理框架，提供了丰富而灵活的序列化方案。本文将全面介绍 DocArray 中三大核心数据结构（BaseDoc、DocList 和 DocVec）的序列化方法，帮助开发者根据实际场景选择最合适的序列化策略。

BaseDoc 序列化

BaseDoc 是 DocArray 中最基础的文档类型，支持两种主流序列化格式：

JSON 序列化

JSON 是最常用的轻量级数据交换格式，DocArray 提供了简单易用的 API：

from typing import List
from docarray import BaseDoc

class MyDoc(BaseDoc):
    text: str
    tags: List[str]

# 序列化到JSON字符串
doc = MyDoc(text='hello world', tags=['hello', 'world'])
json_str = doc.json()

# 从JSON字符串反序列化
new_doc = MyDoc.parse_raw(json_str)

特点：

人类可读的文本格式
跨语言支持
适合网络传输和配置文件

Protobuf 序列化

Protobuf 是 Google 开发的高效二进制序列化格式：

# 序列化到Protobuf对象
proto_message = doc.to_protobuf()

# 从Protobuf对象反序列化
new_doc = MyDoc.from_protobuf(proto_message)

特点：

二进制格式，体积小
序列化/反序列化速度快
需要预定义 schema
适合高性能场景

DocList 序列化

DocList 是 DocArray 中处理文档集合的核心类型，支持多种序列化方式：

1. JSON 序列化

from docarray import BaseDoc, DocList

class SimpleDoc(BaseDoc):
    text: str

dl = DocList[SimpleDoc]([SimpleDoc(text=f'doc {i}') for i in range(2)])

# 序列化到JSON
json_data = dl.to_json()

# 从JSON反序列化
new_dl = DocList[SimpleDoc].from_json(json_data)

2. Protobuf 序列化

# 序列化到Protobuf
proto_message = dl.to_protobuf()

# 从Protobuf反序列化
new_dl = DocList[SimpleDoc].from_protobuf(proto_message)

3. Base64 编码

适用于网络传输场景：

# 序列化为Base64
base64_str = dl.to_base64()

# 从Base64反序列化
new_dl = DocList[SimpleDoc].from_base64(base64_str)

支持多种压缩算法：lz4, bz2, lzma, zlib, gzip

4. 二进制文件操作

# 保存到二进制文件
dl.save_binary('data.pickle')

# 从二进制文件加载
new_dl = DocList[SimpleDoc].load_binary('data.pickle')

5. CSV 格式

适合表格数据处理：

# 导出到CSV
dl.to_csv('data.csv')

# 从CSV导入
new_dl = DocList[SimpleDoc].from_csv('data.csv')

6. Pandas DataFrame 互转

# 转换为DataFrame
df = dl.to_dataframe()

# 从DataFrame转换
new_dl = DocList[SimpleDoc].from_dataframe(df)

DocVec 序列化

DocVec 是 DocArray 中处理张量数据的优化类型，序列化方法与 DocList 类似但有以下特点：

张量类型处理

import torch
from docarray import BaseDoc, DocVec
from docarray.typing import TorchTensor

class SimpleDoc(BaseDoc):
    text: str
    tensor: TorchTensor

dv = DocVec[SimpleDoc]([SimpleDoc(text=f'doc {i}', tensor=torch.rand(64)) for i in range(2)])

# 序列化时保留张量类型信息
proto_message = dv.to_protobuf()

# 反序列化时可指定不同张量类型
new_dv = DocVec[SimpleDoc].from_protobuf(proto_message, tensor_type=TorchTensor)

重要特性：

支持在反序列化时转换张量类型（Numpy/PyTorch/TensorFlow）
默认使用 Numpy 数组（NdArray）
列式存储优化，适合大规模张量数据

与 DocList 的差异

CSV 支持：DocVec 不支持直接 CSV 序列化，需先转换为 DocList
存储格式：JSON 输出采用列式结构而非行式
性能优化：针对张量操作进行了特殊优化

序列化方案选择指南

| 场景 | 推荐格式 | 优点 | 缺点 | |------|----------|------|------| | 调试/配置 | JSON | 可读性强 | 体积较大 | | 高性能传输 | Protobuf | 速度快，体积小 | 二进制不可读 | | 网络传输 | Base64 | 兼容性好 | 有编码开销 | | 本地存储 | 二进制 | 速度快 | 不跨平台 | | 表格处理 | CSV | 通用性强 | 不支持复杂结构 | | 数据分析 | DataFrame | 便于分析 | Pandas 依赖 |