问题现象与错误分析
当开发者调用anthropic.Client.write()方法时，经常会遇到JSON serialization error。典型错误提示为：
TypeError: Object of type 'ndarray' is not JSON serializable
这个错误发生在库尝试将Python对象转换为JSON格式时，主要由于：
- 输入数据包含NumPy数组等非基本数据类型
- 自定义对象未实现
__dict__方法 - 循环引用的数据结构
- 包含datetime对象的复杂结构体
5种解决方案对比
1. 使用默认JSON序列化器
最简单的解决方案是预处理数据：
import json
import numpy as np
class NumpyEncoder(json.JSONEncoder):
def default(self, obj):
if isinstance(obj, np.ndarray):
return obj.tolist()
return json.JSONEncoder.default(self, obj)
data = {"array": np.random.rand(3,3)}
serialized = json.dumps(data, cls=NumpyEncoder)
client.write(serialized)
2. 第三方序列化库
使用orjson或simplejson等高性能替代方案：
import orjson
def serialize_complex(obj):
if hasattr(obj, 'dict'):
return obj.dict()
raise TypeError
result = orjson.dumps(data, default=serialize_complex)
3. 数据预处理管道
构建专门的数据转换层：
def prepare_for_anthropic(data):
if isinstance(data, (dict, list)):
return {k: prepare_for_anthropic(v) for k,v in data.items()}
elif hasattr(data, '__array__'):
return data.__array__().tolist()
return data
4. 修改anthropic配置
某些情况需要调整客户端配置：
client = anthropic.Client(
json_serializer=lambda x: json.dumps(x, cls=CustomEncoder)
)
5. 使用Protocol Buffers替代
对于大型项目建议改用二进制序列化：
from google.protobuf import json_format message = json_format.ParseDict(data, YourMessage()) serialized = message.SerializeToString()
最佳实践建议
- 类型检查：在数据进入管道前进行严格验证
- 性能测试：比较不同方案在万级数据量下的表现
- 错误处理：实现fallback机制处理异常情况
- 文档规范：明确团队的数据格式约定
深度技术解析
根本原因在于Python的json模块默认只支持：
| 支持类型 | 示例 |
|---|---|
| 基本类型 | str, int, float, bool |
| 简单容器 | dict, list, tuple |
| None值 | None |
需要特别注意Pandas DataFrame等常见结构的特殊处理：
def df_to_json(df):
return {
"columns": df.columns.tolist(),
"data": df.values.tolist(),
"index": df.index.to_list()
}