aisuite:一个统一接口调用全球顶级大模型的利器,附详细教程

前言

大模型生态最大的矛盾之一就是碎片化。

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 支持的模型提供商

二、安装与配置

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. 1. 模型判断需要调用 will_it_rain 工具
2. 2. aisuite 执行该函数，获取返回结果 "YES"
3. 3. 结果自动注入消息历史，模型继续处理
4. 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 命令执行

生产级特性

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，只需两步：

1. 1. 在 aisuite/providers/ 下创建 myprovider_provider.py
2. 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. 1. 消除供应商锁定（Vendor Lock-in）：一次编写，随处运行。你写的 LLM 调用代码不会因为换了一个模型供应商而失效。
2. 2. 降低 AI 开发门槛：统一的 API 风格降低了学习曲线，开发者无需为每家模型重新学习 SDK。
3. 3. 加速原型验证：几分钟内就能在多个模型间做 A/B 对比，快速找到最适合特定任务的模型。
4. 4. 本地优先支持：Ollama 集成让完全本地化的 LLM 应用成为可能，数据不出本地，隐私有保障。

7.2 适用场景

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