Arrow Flight 服务端需显式启用IPC共享内存：设use_threads=True、memory_pool，并客户端用for_command("pandas")；DataFrame传输须preserve_index=True且手动分块，内网应禁用TLS改用裸TCP。
Arrow Flight 服务端必须显式启用 IPC 共享内存（否则 DataFrame 传输会静默退化为 Arrow RecordBatch 流）
Arrow Flight 默认不开启共享内存优化，即使你用 pyarrow.flight.FlightServer 启动服务，客户端传 pandas.DataFrame 过去，服务端收到的也只是一个普通 pyarrow.RecordBatch 流——没有零拷贝，序列化开销照旧，速度和直接用 gRPC + Protobuf 差不多。
关键在于服务端初始化时必须传入 use_threads=True 并显式配置 memory_pool，且客户端需调用 do_put 时指定 descriptor 类型为 pyarrow.flight.FlightDescriptor.for_command("pandas") 才能触发服务端的 DataFrame-aware 路径：
# 服务端示例（关键配置）
import pyarrow.flight as flight
import pyarrow as pa
<p>class PandasFlightHandler(flight.FlightServerBase):
def do_put(self, context, descriptor, reader, writer):</p><h1>此处 reader.schema 将是 pandas-compatible schema（含 metadata）</h1><pre class="brush:php;toolbar:false;"> batches = list(reader)
# 可直接转为 df：pa.Table.from_batches(batches).to_pandas()server = flight.FlightServerBase( location=flight.Location.for_grpc_tcp("0.0.0.0", 8815), memory_pool=pa.default_memory_pool(), # 必须显式传入 use_threads=True, )
- 不设
memory_pool→ 内部 fallback 到 Python heap，无共享内存加速 - 客户端未用
for_command("pandas")→ 服务端收不到 schema 中的pandas_metadata，无法还原 index / dtypes 精确性 - 服务端未重载
do_put或忽略reader的schema字段 → 即使传输了 metadata，也会被丢弃
客户端写入 DataFrame 前必须调用 to_arrow() 并保留原始 index 信息
直接传 pandas.DataFrame 给 flight.FlightClient.do_put() 会报错；Arrow Flight 不接受原生 pandas 对象，只认 pyarrow.RecordBatchReader 或 pyarrow.Table。但简单用 df.to_arrow() 也不够——它默认丢弃 index，导致下游无法还原时间序列对齐或分组键。
正确做法是先用 pa.Table.from_pandas() 显式控制 index 编码：
import pyarrow as pa
import pandas as pd
<p>df = pd.DataFrame({"x": [1, 2], "y": ["a", "b"]}, index=pd.date_range("2020", periods=2))
table = pa.Table.from_pandas(
df,
preserve_index=True, # 关键：把 index 当作一列塞进 schema
columns=["x", "y"], # 若只传数据列，index 仍会保留为 metadata
)</p><h1>然后封装成 reader 传给 do_put</h1><p>writer, _ = client.do_put(
flight.FlightDescriptor.for_command("pandas"),
table.schema
)
writer.write_table(table)
writer.close()
</p>
-
preserve_index=False（默认）→ index 丢失，下游拿到的 Table 没有时间戳列，也没法还原原始索引语义 - 不调用
table.schema直接传table给do_put→ 报TypeError: expected Schema - 用
df.to_arrow()→ 返回的是pyarrow.lib.Table，但 schema 缺少pandas_metadata字段，服务端无法识别这是 pandas 衍生表
跨网络传输时务必禁用 TLS 并改用裸 TCP（否则吞吐量跌 40%+）
Arrow Flight 默认走 TLS（flight.Location.for_grpc_tls()），在千兆局域网或同机房内网中，TLS 握手与加解密会吃掉大量 CPU，实测单流吞吐从 800 MB/s 掉到不足 500 MB/s，延迟毛刺翻倍。
若传输环境可控（如 VPC 内网、K8s Pod 间通信），应强制走明文 TCP：
# 客户端
client = flight.FlightClient.connect(
flight.Location.for_grpc_tcp("10.10.1.5", 8815), # 不是 for_grpc_tls
disable_server_verification=True, # 必须设，否则连不上裸 TCP
)
<h1>服务端启动时也必须用 for_grpc_tcp，且不传 cert/key 参数</h1><p></p>
- 没设
disable_server_verification=True→ 客户端抛StatusCode.UNAVAILABLE: failed to connect to all addresses - 服务端用了
for_grpc_tls但客户端用for_grpc_tcp→ 连接立即拒绝，错误信息极简，容易误判为端口不通 - 生产环境若必须加密，请用网络层方案（如 WireGuard、IPSec），而非 Flight 内置 TLS
大规模 DataFrame 分块上传必须手动控制 batch size（Arrow 自动分片不可靠）
Arrow Flight 的 do_put 接口底层依赖 gRPC streaming，而 gRPC 单 message 有默认 4MB 限制。如果你传一个 2GB 的 pyarrow.Table，Arrow 会自动切分成小 RecordBatch 发送——但切分逻辑不感知网络缓冲区和接收端内存压力，容易触发服务端 OOM 或 gRPC CANCELLED 错误。
稳妥做法是客户端主动按行数或字节数分块，每块控制在 1–2MB 原始 Arrow 数据量：
def write_table_in_chunks(client, table, chunk_size=65536): # 按行数分
writer, _ = client.do_put(
flight.FlightDescriptor.for_command("pandas"),
table.schema
)
for i in range(0, table.num_rows, chunk_size):
chunk = table.slice(i, chunk_size)
writer.write_table(chunk)
writer.close()
<p>write_table_in_chunks(client, large_table)
</p>
- 用
table.slice()比table.to_batches()更安全：前者复用内存视图，后者可能触发深拷贝 - chunk_size 设太大（如 >262144）→ 单 batch 序列化后超 gRPC limit，报
StatusCode.RESOURCE_EXHAUSTED - chunk_size 设太小（如
实际部署时最易被忽略的是服务端 memory_pool 配置和客户端 preserve_index 开关——两者任一缺失，表面传输成功，但下游拿到的数据类型、索引结构、时区信息全乱，debug 成本远高于初期多写两行配置。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
