夜雨聆风前言
大模型生态最大的矛盾之一就是碎片化。
OpenAI 的 API 格式和 Anthropic 不一样，Anthropic 的格式和 Google 又不一样。当你想在项目里切换模型做对比测试，或者想让同一个 Agent 调用不同厂商的能力，你面临的不是"换一个模型"这么简单，而是一整套 SDK 的重写、认证体系的重新对接、参数体系的重新翻译。
这就是 aisuite 要解决的问题。
aisuite 是一个轻量级 Python 库，它在主流大模型提供商之上包装了一层统一接口，让你用 OpenAI 风格的 API 调用方式，桥接到任何一家大模型服务商——OpenAI、Anthropic、Google、Mistral、HuggingFace、AWS、Cohere、Ollama、OpenRouter，不一而足。
更进一步的，aisuite 还提供了工具调用（Tool Calling）、Agent 框架、MCP 协议支持，以及一个基于它构建的桌面端 AI 助手 OpenCoworker。
本文将带你从零掌握 aisuite，深度解析它的设计哲学、项目架构和工程实践。
一、项目概览
1.1 是什么
aisuite 由 AI 创业者 Andrew Ng（吴恩达）团队开发并维护（仓库地址：github.com/andrewyng/aisuite[1]），核心定位是：
Build with LLMs, without being locked into any one.
它用统一的 Chat Completions API 消除了各厂商 SDK 的差异，同时提供上层 Agent 抽象，让开发者可以快速构建多模型 Agent 应用。
1.2 技术架构
aisuite 的整体架构分为三层：
┌─────────────────────────────────────────────┐
│ OpenCoworker │ 桌面端 AI 助手，基于 aisuite 构建
├─────────────────────────────────────────────┤
│ Agents API · Toolkits · MCP │ 上层 Agent 抽象，支持工具集、MCP
├─────────────────────────────────────────────┤
│ Chat Completions API │ 底层统一接口，OpenAI 风格
├────────┬───────────┬────────┬────────┬──────┤
│ OpenAI │ Anthropic │ Google │ Ollama │ 更多 │ 支持 10+ 模型提供商
└────────┴───────────┴────────┴────────┴──────┘1.3 支持的模型提供商
| 提供商 | 示例模型 | 备注 |
|---|---|---|
| OpenAI | gpt-4o, gpt-4o-mini | 最常用 |
| Anthropic | claude-3-5-sonnet, claude-opus | 强大推理能力 |
| gemini-1.5-pro, gemini-1.5-flash | Google 全家桶 | |
| Ollama | llama3.3, mistral | 本地运行，无需 API Key |
| Mistral | mistral-large, mistral-small | |
| HuggingFace | meta-llama/Llama-3 | |
| AWS Bedrock | Claude, Llama via AWS | 企业级 |
| Cohere | command-r-plus | |
| OpenRouter | 各种模型聚合 |
二、安装与配置
2.1 安装方式
aisuite 采用了模块化安装策略：
# 仅安装核心包（不含任何 provider SDK）
pip install aisuite
# 安装核心包 + 指定 provider SDK
pip install 'aisuite[anthropic]'
# 安装核心包 + 所有 provider SDK
pip install 'aisuite[all]'
# MCP 支持（Model Context Protocol）
pip install 'aisuite[mcp]'建议：按需安装，用哪个装哪个，全量安装会拉取大量依赖。
2.2 配置 API Keys
各 provider 的 API Key 通过环境变量管理：
# OpenAI
export OPENAI_API_KEY="sk-..."
# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
# Google
export GOOGLE_API_KEY="..."
# Ollama（本地，无需 Key）
# 完全免费，只需本地安装 Ollama也可以在代码中直接传入：
client = ai.Client({
"openai": {"api_key": "sk-..."},
"anthropic": {"api_key": "sk-ant-..."}
})三、核心功能详解
3.1 Chat Completions API——一个接口，多家模型
这是 aisuite 最基础也最核心的能力。你只需要学会一种 API 格式，就能调用任意提供商的模型。
基本用法
import aisuite as ai
client = ai.Client()
models = [
"openai:gpt-4o",
"anthropic:claude-3-5-sonnet-20240620",
"google:gemini-1.5-pro"
]
messages = [
{"role": "system", "content": "你是一个用海盗英语回答问题的助手。"},
{"role": "user", "content": "给我讲个笑话。"}
]
for model in models:
response = client.chat.completions.create(
model=model,
messages=messages,
temperature=0.75,
max_tokens=500
)
print(f"[{model}] {response.choices[0].message.content}")关键点：
- • 模型名称格式为
<provider>:<model-name>，切换模型只需改这一个字符串 - • 所有核心参数（temperature、max_tokens、tools 等）以 provider-agnostic 的方式工作
- • aisuite 内部自动完成参数到各 SDK 格式的映射
本地模型（Ollama）
无需任何 API Key，直接本地运行：
response = client.chat.completions.create(
model="ollama:llama3.3",
messages=[{"role": "user", "content": "你好！"}]
)
print(response.choices[0].message.content)前提是本地已安装 Ollama[2]，并通过 ollama pull llama3.3 下载模型。
3.2 工具调用（Tool Calling）——让 AI 连接真实世界
aisuite 将工具调用做到极致简洁。你只需传一个普通 Python 函数，aisuite 自动生成 schema、执行调用、喂回结果——一条龙服务。
自动工具循环（max_turns）
import aisuite as ai
def will_it_rain(location: str, time_of_day: str):
"""检查某地某时是否下雨。
Args:
location (str): 城市名称
time_of_day (str): 时间，格式为 HH:MM
"""
return "YES"
client = ai.Client()
response = client.chat.completions.create(
model="openai:gpt-4o",
messages=[{
"role": "user",
"content": "我住在旧金山，能帮我查一下天气并计划一个下午 2 点的户外野餐吗？"
}],
tools=[will_it_rain], # 直接传函数
max_turns=2 # 最多两轮对话
)
print(response.choices[0].message.content)运行流程：
- 1. 模型判断需要调用
will_it_rain工具 - 2. aisuite 执行该函数，获取返回结果 "YES"
- 3. 结果自动注入消息历史，模型继续处理
- 4. 重复直到模型输出最终回复或达到 max_turns 上限
完整交互历史保存在 response.choices[0].intermediate_messages 中，方便调试或继续对话。
手动控制模式
如果需要更精细的控制（自定义错误处理、选择性执行等），可以跳过 max_turns，自己写循环：
# 传入 OpenAI 格式的 JSON Schema，而非 Python 函数
tools = [{
"type": "function",
"function": {
"name": "will_it_rain",
"description": "检查某地某时是否下雨",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"},
"time_of_day": {"type": "string"}
},
"required": ["location", "time_of_day"]
}
}
}]
response = client.chat.completions.create(
model="openai:gpt-4o",
messages=messages,
tools=tools
)
# 自己判断调用了哪个工具、执行它、注入结果……3.3 Agents API——构建生产级 Agent 应用
当你的任务更复杂、需要持久化和结构化管理时，Agents API 提供了完整的上层抽象：
import aisuite as ai
from aisuite import Agent, Runner
# 声明一个 Agent，配备文件工具和 Git 工具
agent = Agent(
name="repo-helper",
model="anthropic:claude-sonnet-4-6",
instructions="你是一个细心的代码库助手，使用工具回答关于代码的问题。",
tools=[*ai.toolkits.files(root="."), *ai.toolkits.git(root=".")]
)
# Runner.run() 是阻塞调用，返回最终结果
result = Runner.run(agent, "最近一次提交改了什么？用3点概括。")
print(result.final_output)Toolkits（预构建工具集）：
- •
ai.toolkits.files(root=".")—— 文件系统读写，带沙箱隔离 - •
ai.toolkits.git(root=".")—— Git 操作（commit、diff、log 等） - •
ai.toolkits.shell(root=".")—— 沙箱化 Shell 命令执行
生产级特性
| 特性 | 说明 |
|---|---|
| Tool Policies | 工具执行策略，可配 RequireApprovalPolicy（审批后执行）、AllowList/DenyList、自定义 callable |
| State Stores | 运行状态持久化：InMemory（内存）、FileStateStore（文件）、PostgresStateStore（数据库），支持跨进程恢复对话 |
| Artifacts | 捕获 Agent 生成的产物（文件、代码等），FileArtifactStore 或 InMemoryArtifactStore |
| Tracing | 每个 RunResult 携带完整执行链路和 trace_id，插桩可观测性 |
3.4 MCP 支持——Model Context Protocol 原生集成
MCP（Model Context Protocol）[3] 是 Anthropic 主导的开放协议，旨在标准化 AI 模型与外部工具/数据源的连接。 aisuite 对 MCP 提供了开箱即用的支持：
client = ai.Client()
response = client.chat.completions.create(
model="openai:gpt-4o",
messages=[{"role": "user", "content": "列出当前目录下的文件"}],
tools=[{
"type": "mcp",
"name": "filesystem",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
}],
max_turns=3
)对于复用场景，可以使用显式的 MCPClient，支持安全过滤和工具前缀：
from aisuite.mcp import MCPClient
mcp = MCPClient(
command="npx",
args=["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
)
response = client.chat.completions.create(
model="openai:gpt-4o",
messages=[{"role": "user", "content": "列出文件"}],
tools=mcp.get_callable_tools(),
max_turns=3
)
mcp.close() # 记得关闭四、OpenCoworker——基于 aisuite 的桌面 AI 助手
aisuite 仓库还包含一个基于它构建的完整桌面应用 OpenCoworker，这是一个可以在你的桌面上运行的 AI Agent，能完成真实的工作任务：
- • 读取文件、获取上下文
- • 读写 Slack、Email 等消息
- • 生成 PDF 报告、文档、电子表格
- • 按计划执行自动化任务（如每日新闻摘要推送）
下载链接：
- • macOS（Apple Silicon）：OpenCoworker-macos-arm64.dmg[4]
- • Windows：OpenCoworker-windows-setup.exe[5]
OpenCoworker 的源代码在仓库 platform/ 目录下，是学习如何基于 aisuite 构建完整 Agent Harness 的优秀参考。
五、扩展 aisuite——添加新 Provider
aisuite 的扩展机制极度轻量，遵循命名约定自动发现原则：
| 元素 | 约定 |
|---|---|
| 模块文件名 | <provider>_provider.py |
| 类名 | <Provider>Provider（首字母大写） |
添加一个新 Provider，只需两步：
- 1. 在
aisuite/providers/下创建myprovider_provider.py - 2. 定义
class MyproviderProvider(BaseProvider)
系统会自动发现并加载，无需修改任何注册表或配置文件。
这种设计保证了 零配置扩展——任何人都能为 aisuite 贡献新 Provider。
六、设计哲学深度解析
6.1 抽象的力量——统一接口的工程价值
aisuite 背后最核心的设计哲学是通过统一抽象降低复杂度。
在软件工程中，抽象层的作用不只是"少写代码"，更是变更成本的隔离层。当你需要从 GPT-4o 切换到 Claude-3.5，没有 aisuite 的情况下：
- • 重写 API 认证逻辑
- • 重写请求构建代码
- • 重写响应解析代码
- • 重写错误处理分支
有了 aisuite，只需要把 "openai:gpt-4o" 改成 "anthropic:claude-3-5-sonnet-20240620"，其余代码一字不动。
6.2 最小化侵入——渐进式采用
aisuite 的设计允许你渐进式采用：
- • 阶段一：只用 Chat Completions API，替代 SDK 调用
- • 阶段二：引入工具调用，增强模型能力
- • 阶段三：迁移到 Agents API，获得生产级特性
每一步都是可选的，不需要一次性重构整个应用。
6.3 工具优先——Function Calling 是 Agent 的灵魂
aisuite 把 Tool Calling 做成"传入 Python 函数即用"的极致体验，反映了项目团队的核心认知：LLM 的价值不在于"说话"，而在于"做事"。通过工具调用，大模型从被动应答者变成主动行动者，这才是 Agent 的本质。
6.4 开放生态——Provider 可插拔
不同于一些厂商锁定的多模型封装库，aisuite 的 Provider 发现机制完全开放，任何人都可以通过简单的命名约定贡献新的 Provider。这种 "种植菌棒而非建造花园" 的生态思维，保证了项目不会因为维护者精力有限而停滞。
6.5 零运行时绑定——轻量不添乱
aisuite 自身不引入重型依赖（核心包无 provider SDK），不强制绑定任何运行时框架。任何已有的 Python 项目都可以在不改变任何现有逻辑的情况下引入 aisuite，获得多模型切换能力。
七、观点归纳与总结
7.1 aisuite 的核心价值
- 1. 消除供应商锁定（Vendor Lock-in）：一次编写，随处运行。你写的 LLM 调用代码不会因为换了一个模型供应商而失效。
- 2. 降低 AI 开发门槛：统一的 API 风格降低了学习曲线，开发者无需为每家模型重新学习 SDK。
- 3. 加速原型验证：几分钟内就能在多个模型间做 A/B 对比，快速找到最适合特定任务的模型。
- 4. 本地优先支持：Ollama 集成让完全本地化的 LLM 应用成为可能，数据不出本地，隐私有保障。
7.2 适用场景
| 场景 | 受益 |
|---|---|
| 多模型对比评测 | 一套代码跑遍所有模型，公平对比 |
| 模型无关的产品架构 | 根据成本/性能/可用性动态切换模型 |
| 企业级 AI 应用 | 利用 AWS Bedrock 集成，调用企业内部署模型 |
| 本地隐私应用 | Ollama 本地运行，数据完全私有 |
| 快速原型开发 | 不绑定任何供应商，快速验证想法 |
| Agent 开发 | 完整的工具调用和 Agent 框架支持 |
7.3 不适合的场景
- • 需要深度使用某家厂商独有特性的场景（如 OpenAI 的 Fine-tuning、Anthropic 的 Computer Use 等高级能力）
- • 对延迟极致敏感的生产系统（中间多了一层转发）
- • 高度定制化的 provider 封装需求（此时直接用原生 SDK 更合适）
7.4 行业意义
aisuite 的出现反映了一个更大的趋势：LLM 应用层的标准化战争。随着 LLM Provider 越来越多，应用层需要一个"SQL 数据库驱动"式的中间层来抽象差异。这和早些年的云计算时代，应用程序通过 ODBC/JDBC 抽象数据库访问异曲同工。
未来我们会看到更多类似的抽象层涌现，而 aisuite 是这个方向目前做得最干净、最轻量的实现之一。
八、快速上手 Checklist
✅ 安装：pip install 'aisuite[all]'
✅ 配置环境变量 OPENAI_API_KEY / ANTHROPIC_API_KEY 等
✅ 写第一行代码：client = ai.Client()
✅ 发送第一次请求：client.chat.completions.create(model="openai:gpt-4o", messages=[...])
✅ 切换模型：一字不改，改 model 参数即可
✅ 添加工具：tools=[your_python_function]
✅ 启用 Agent：from aisuite import Agent, Runner
✅ 添加 MCP：pip install 'aisuite[mcp]' + tools=[{"type": "mcp", ...}]九、资源链接
- • GitHub 仓库：https://github.com/andrewyng/aisuite
- • PyPI 主页：https://pypi.org/project/aisuite/
- • OpenCoworker 下载：https://github.com/andrewyng/aisuite/releases
- • Model Context Protocol：https://modelcontextprotocol.io
- • Discord 社区：https://discord.gg/T6Nvn8ExSb
- • Ollama 本地模型：https://ollama.com
结语：在 AI 模型能力日新月异、供应商格局远未稳定的当下，选择正确的抽象层，就是在为自己的应用构建护城河。 aisuite 用最小的侵入、最轻的依赖、最开放的设计，为 Python 开发者提供了一个穿越模型供应商变迁周期的稳定基础设施。
MIT 许可证开源，商业和非商业均可免费使用。
本文由蓝鲸会 AI 助手基于开源项目文档整理撰写，所有技术细节以官方仓库为准。
引用链接
[1] github.com/andrewyng/aisuite: https://github.com/andrewyng/aisuite
[2] Ollama: https://ollama.com
[3] MCP（Model Context Protocol）: https://modelcontextprotocol.io
[4] OpenCoworker-macos-arm64.dmg: https://github.com/andrewyng/aisuite/releases/latest/download/OpenCoworker-macos-arm64.dmg
[5] OpenCoworker-windows-setup.exe: https://github.com/andrewyng/aisuite/releases/latest/download/OpenCoworker-windows-setup.exe
