02｜pi-ai：为什么需要单独一层来统一模型调用

这篇写什么

只讲 packages/ai（pi-ai）的设计动机与职责边界：它到底统一了什么、为什么对 agent 很关键、它和 pi-agent-core 的分工是什么。

先说结论

pi-ai 的本质不是“又一个模型 SDK”，而是：一个面向 agent 场景的多模型统一抽象层。

它的目标是把不同厂商、不同协议、不同风格的大模型调用方式，收敛成一套统一输入输出标准，让上层系统稳定工作。

为什么值得单独做一层

如果没有这一层，上层会直接面对：

• 不同厂商的 API 结构、消息格式、流式协议差异
• tool calling 表达差异
• reasoning/thinking 支持差异
• usage / cost 统计差异

最终会导致：

• agent 层被 provider 细节污染
• 每加一个 provider 都要横向改大量代码
• 跨模型继续对话变得不稳定

pi-ai 的价值不是“让调用更方便一点”，而是：让上层架构不被底层模型差异拖垮。

它到底统一了什么

可以粗分四类：

1. 统一输入
2. 统一输出
3. 统一模型描述
4. 统一兼容策略

1) 统一输入

上层只表达：

• 用哪个模型
• 当前上下文是什么
• 这轮允许哪些工具
• 运行参数是什么

2) 统一输出

对 agent 来说，统一输出比统一输入更关键，因为 agent 需要过程：

• 文本增量
• thinking/reasoning 增量
• tool call 增量
• stop reason
• usage/cost

pi-ai 把各家原始流式返回翻译成统一事件流，上层不需要理解各家 chunk 细节。

3) 统一模型描述

模型不是一个字符串，而是调用语义载体：

• provider / 协议类型
• 上下文窗口与最大输出
• 是否支持 reasoning、多模态
• 成本信息
• 兼容配置

这些信息让上层可以做能力判断、成本统计与路由。

4) 统一兼容策略

现实里“兼容”带脏细节。pi-ai 把兼容处理集中在底层适配与模型兼容配置里，而不是让上层四处写 if/else。

协议层视角：不以 provider 为唯一抽象单位

一个关键设计点是：抽象单位更像“协议类型”，而不是“厂商名”。

这样 OpenAI-compatible 或 Anthropic-compatible 的服务可以大量复用实现，只在少数不兼容点做局部修正。

它为什么特别适合 agent

因为 agent 需要：

• 工具调用
• 多轮循环
• 中间态事件
• 上下文可重放
• 成本与 stop reason

pi-ai 从一开始就不是“聊天式封装”，而是“agent 式封装”。

和 pi-agent-core 的边界

• pi-ai 负责：统一模型调用、上下文表示、流式事件、工具表达、usage/cost/stop reason、屏蔽 provider 差异。
• pi-agent-core 负责：什么时候调模型、什么时候执行工具、工具结果怎么回灌、是否继续下一轮、什么时候停止。

一句话：pi-ai 解决“怎么和模型说话”，pi-agent-core 解决“怎么让模型持续干活”。