aisuite
[!info] 知识库定位 这是一篇 工具评估 / 使用笔记，回答 aisuite “值不值得用、怎么用、什么时候不用”。 底层概念（统一抽象层、适配器模式、事实标准）见 aisuite-统一LLM调用抽象层；真实项目落地待补
used_in_projects。
一句话：Andrew Ng 团队的轻量 Python 库，用一套模仿 OpenAI 的统一接口调用 OpenAI / Anthropic / Google / Mistral / Cohere / Ollama 等多家 LLM——换模型只改一个字符串。
为什么需要它
每家 LLM provider 的 SDK 从导入名到调用方式都不同（认证、消息结构、system 消息位置、响应字段、流式分块），代码和供应商死死绑定，换一家就要重写整个调用层，A/B 测试和多模型选型成本随 provider 数量线性膨胀。aisuite 把这层”翻译”收口，让你只面对一个 OpenAI 风格的接口，业务逻辑和具体 provider 解耦。
核心优势
- 极简上手：一个
Client、一个chat.completions.create()，Hello World 不到 5 行；熟悉 OpenAI SDK 就等于会 aisuite。 - 真·换模型零成本：
"openai:gpt-4o"→"anthropic:claude-3-5-sonnet"，业务代码一个字不改。 - 源码极薄、可读性强：一个 provider 一个文件，半小时读完全部源码，适合学 适配器模式 和”事实标准”如何落地。
- 轻量 agent 免费送：
max_turns参数自动跑工具执行循环；工具直接传 Python 函数，框架读类型注解自动生成 schema 并执行；原生支持 MCP 与 CLI 工具。 - 插件式扩展：命名约定
<provider>_provider.py自动发现，加新 provider 只需丢一个文件。
性能表现
官方无公开 benchmark。aisuite 本身是薄客户端，自身开销只是请求/响应的格式翻译（可忽略不计），瓶颈永远在网络往返 + 模型推理，不在 aisuite。
| 维度 | 表现 | 说明 |
|---|---|---|
| 单次调用延迟 | ≈ provider 原生 SDK | 适配层翻译开销 < 1ms 量级 |
| 吞吐 / 并发 | 受限 | chat 无原生 async（源码核实 client.py：0.1.14 / main 的 chat 路径仍无 async def），高并发场景被同步阻塞拖累 |
| 内存占用 | 极低 | 薄库，依赖各 provider 官方 SDK |
[!warning] 高并发是它的硬伤 评估期内（v0.1.x）无原生 async。要做批量调用、高 QPS、流式并发，要么自己包线程池，要么直接上 LiteLLM（原生 async + 并发控制）。
快速上手
安装
# 只装本体（不含任何 provider SDK）
pip install aisuite
# 装本体 + 指定 provider 的 SDK
pip install 'aisuite[anthropic]'
# 一次装齐所有 provider SDK
pip install 'aisuite[all]'
# 需要 MCP 工具支持时
pip install 'aisuite[mcp]'最小示例
import aisuite as ai
client = ai.Client()
models = ["openai:gpt-4o", "anthropic:claude-3-5-sonnet-20240620"]
messages = [
{"role": "system", "content": "Respond in Pirate English."},
{"role": "user", "content": "Tell me a joke."},
]
for model in models:
resp = client.chat.completions.create(model=model, messages=messages)
print(resp.choices[0].message.content)配置要点
- API Key 用环境变量：
OPENAI_API_KEY/ANTHROPIC_API_KEY/GOOGLE_API_KEY…，适配器各自认领；也可在ai.Client(config={...})构造时传入。 - 模型字符串是路由钥匙：格式严格
<provider>:<model-name>，冒号前半决定走哪个适配器；支持的 provider 列表看aisuite/providers/目录。 - Python ≥ 3.10：版本硬约束，低版本环境会装不上。
- 工具调用两种模式：不传
max_turns= 手动处理（你拿 tool_call 自己执行）；传max_turns=N= 自动循环（直接传 Python 函数）。
适用场景
适合：
- 多模型 A/B 测试——同一 prompt 跑遍主流模型对比效果/成本，零集成成本。
- 原型与教学——学一套 API 调所有模型；源码薄到能读懂适配器模式。
- 避免供应商锁定——业务代码面向抽象编程，未来换 provider 不动核心逻辑。
- 轻量 agent / 工具调用——
max_turns+ Python 函数工具，低门槛搭起一个会调工具的 agent。 - OpenAI 兼容生态互通——和 LLM vLLM、Ollama 的 OpenAI 兼容端点天然契合，本地与云模型同一套代码。
不适合：
- 高并发生产服务——chat 无原生 async（源码核实 0.1.14 / main），同步阻塞扛不住高 QPS。
- 需要成本管控 / 路由 / 降级 / 用量追踪——这些是 LLM 网关职责，aisuite 没有，选 LiteLLM。
- 复杂多步 agent 编排——
max_turns是教学级简化循环，要状态机/多智能体协作选 LangGraph。
已知坑 & 注意事项
[!warning] 仍是 0.x 版本，API 可能 breaking change 当前 v0.1.14（2025-11-25，PyPI）。
pin住版本（aisuite==0.1.14），别用latest/不锁版本，升级前看 Release Notes。1.0 之前接口不保证稳定。
[!warning] 无 async 支持 高并发、批量、流式并发场景受限。这是生产引入最大的拦路虎——源码核实 client.py chat 路径至今无
async def（0.1.14 / main 均如此，命中的async/stream仅 audio 转写流式）。
[!warning] 统一了接口，没统一能力 provider 间能力差异真实存在（不是所有都支持 tools / 流式 / 视觉 / 长上下文）。换模型前查支持矩阵，否则运行时才暴露错误。
[!warning] max_turns 循环不够健壮 教学级简化，缺错误处理、超时、重试、并发控制。生产用要自己补。
- Python 3.10+ 硬约束：低版本 CI/生产环境注意。
- 同一 prompt 跨模型行为差异大：aisuite 统一的是接口不是模型行为，切换后常需调 prompt / temperature。
竞品对比
| 维度 | aisuite | LiteLLM | LangChain | OpenAI SDK |
|---|---|---|---|---|
| 定位 | 极简统一客户端 | 生产级 LLM 网关/客户端 | 大而全 LLM 应用框架 | 单 provider 官方 SDK |
| 上手难度 | ⭐ 极低 | ⭐⭐ 低 | ⭐⭐⭐⭐ 高（概念多） | ⭐ 极低 |
| 跨 provider | ✅（多家） | ✅（100+ 家，最全） | ✅ | ❌（仅 OpenAI 兼容端点） |
| async 支持 | ❌ | ✅ 原生 | ✅ | ✅ |
| 成本/用量追踪 | ❌ | ✅ | 部分 | ❌ |
| Proxy / 路由 / 降级 | ❌ | ✅（proxy server） | ❌ | ❌ |
| Agent / 工具 / 记忆 / 检索 | 极简（max_turns） | 工具调用 | ✅ 全套（chain/memory/RAG） | ❌ |
| 源码可读性 | ⭐⭐⭐⭐⭐ 极薄 | ⭐⭐⭐ 中 | ⭐⭐ 厚 | ⭐⭐⭐⭐ |
| 生产成熟度 | 🟡 观望（0.x） | 🟢 成熟 | 🟢 成熟 | 🟢 成熟 |
选择建议：
- 教学 / 原型 / A-B 测试 / 轻量解耦 → 选 aisuite（最薄、最好读、零负担）。
- 生产服务、高并发、要成本管控/路由/降级/统一计费 → 选 LiteLLM（Issue #87 官方也这么说：aisuite 主打简单，LiteLLM 主打生产）。
- 要 RAG / 记忆 / 复杂链 / 多步编排 → 选 LangChain 或 LangGraph。
- 只用 OpenAI（或其兼容端点如 vLLM/Ollama） → 直接 OpenAI SDK 即可，没必要加一层。
[!tip] aisuite 和 LiteLLM 不是二选一 官方在 Issue #87 表态：两者可互补——LiteLLM 当生产网关，aisuite 当开发期的薄抽象。小项目/学习用 aisuite，规模化时再迁到 LiteLLM。
生态 & 社区
- 维护状态：活跃但有起伏。PyPI 版本时间线显示 0.1.11(2025-03) → 0.1.12(2025-10) 有 7 个月空档——正是 Issue #227 “Anyone maintaining this project?”（已 closed）质疑维护停滞的源头；之后 0.1.12 / 13 / 14 连发（截至 2026-06-14 仍在 push）才恢复节奏。
- 项目在演进：
main分支已超出”极简客户端”范畴，新增framework/（provider 接口重构 + ASR 语音转写）、agents/（runner / state_store / postgres_state_store / policies / viewer）、toolkits/（files / git / shell）、tracing/（可观测性）等目录——正向”带状态 / 可观测 / 内置工具的轻量 agent 框架”方向走。是否已全部反映到 PyPI 0.1.14 待确认，但定位正在漂移，“不是框架”的旧判断需随版本持续重估。 - 文档质量：一般偏实用——README +
examples/notebook 就是全部文档，上手够用，深度场景要读源码。 - 周边生态：依赖各家 provider 官方 SDK；原生集成 MCP 与 CLI 工具协议；和 OpenAI 兼容端点（LLM vLLM、Ollama）天然互通。
- 社区活跃度：Andrew Ng 背书带来高关注度（2024-11 发布即破万，现 14.2k star）；有官方 Discord。但相比 LiteLLM/LangChain，issue 响应和迭代速度更慢。
引入评估
| 维度 | 评分（/5） | 备注 |
|---|---|---|
| 上手难度 | 5 | 极简，会 OpenAI SDK 就会 |
| 文档完善度 | 3.5 | README+examples 够用，深度文档不足 |
| 社区活跃 | 4 | Andrew Ng 背书，关注度高 |
| 性能 | 3 | 薄客户端本身没问题，但无 async 拖累并发 |
| 稳定性 | 3 | 0.x，API 未冻结，需 pin 版本 |
| 综合 | 4 ⭐⭐⭐⭐ | 特定场景强推，生产高并发慎用 |
结论：推荐（限定场景）⭐⭐⭐⭐ —— 教学、原型、多模型 A/B 测试、想给业务薄薄解耦一层 provider，aisuite 是同类里最省心的选择，源码还能当适配器模式教材。但生产高并发、需要成本管控/路由/降级等网关特性时，选 LiteLLM；aisuite 仍是 0.x、无 async，别把它当生产底座硬扛。一句话：当”开发期的统一遥控器”，别当”生产期的 LLM 网关”。
推荐引入版本：aisuite==0.1.14（pin 住，0.x 期间禁止用 latest；升级前查 Release Notes。注意 0.1.8+ 多数版本直推 PyPI、未建 GitHub Release，看 PyPI changelog 而非 Releases 页）
相关链接
前置知识：aisuite-统一LLM调用抽象层 · OpenAI Chat Completions API 竞品：LiteLLM · LangChain · LangGraph 使用场景：Agent 的概念、原理与构建模式 · 多模型 A/B 测试 · 供应商解耦 底层概念：aisuite-统一LLM调用抽象层 · 适配器模式 · 事实标准 项目落地：待补充
- GitHub - andrewyng/aisuite
- Releases
- Issue #87 - aisuite vs LiteLLM（官方定位）
- Issue #227 - “Anyone maintaining this project?”（维护停滞质疑，已 closed）
个人备注
留白——供后续实际使用后补充心得（如踩到的 provider 能力差异、max_turns 循环的边界 case、迁移到 LiteLLM 的触发点）。