一文看懂openapi-python-client生成的SDK和openai-python库的风格差异

原创于 2025-12-18 23:47:07 发布 · 553 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#python #机器学习 #人工智能 #openai-python #openapi #自动代码生成 #大千AI助手

OTHER 同时被 3 个专栏收录

349 篇文章

订阅专栏

Python

344 篇文章

订阅专栏

计算机

16 篇文章

订阅专栏

本文由「大千AI助手」原创发布，专注用真话讲AI，回归技术本质。拒绝神话或妖魔化。搜索「大千AI助手」关注我，一起撕掉过度包装，学习真实的AI技术！

两者在底层原理（都支持同步/异步、都基于强类型模型、都对 IDE 友好）上是非常相似的。

但在调用风格（语法糖）和代码组织结构上，OpenAI 的官方 SDK（v1.0+ 版本，由 Stainless 引擎生成）属于“豪华精装修版”，而 openapi-python-client 生成的代码属于“实用毛坯版”或“标准工业版”。

以下是详细的对比分析：

1. 代码风格对比（最直观的区别）

这是写代码时感受最深的地方。

OpenAI SDK (v1+) 的风格

OpenAI 采用的是 “资源导向” 的链式调用，非常优雅，符合直觉。

# OpenAI 风格
from openai import OpenAI

client = OpenAI(api_key="...")

# 结构：client.资源.动作(参数...)
# 特点：参数扁平化，不需要手动构建 RequestBody 对象
completion = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)

本文由「大千AI助手」原创发布，专注用真话讲AI，回归技术本质。拒绝神话或妖魔化。搜索「大千AI助手」关注我，一起撕掉过度包装，学习真实的AI技术！

往期文章推荐:

openapi-python-client 生成的 SDK 风格

这个工具生成的代码通常是 “函数导向” 的。你需要导入具体的 API 函数，把 client 当作参数传进去。

# openapi-python-client 风格
from daqianai import Client
from daqianai.api.llms import create_llm # 需要导入具体函数
from daqianai.models import CreateRequest # 需要导入具体模型

client = Client(base_url="...")

# 结构：函数.sync(client=client, body=模型对象)
# 特点：需要显式构建 Body 对象 (CreateRequest)，层级较深
response = create_approval_instance.sync(
    client=client,
    body=CreateRequest(  # 必须先实例化请求体模型
        title="OpenAI模型GPT-5.2",
        type="openai",
        name="gpt-5.2",
        creator="daqianai",
    )
)

差异点总结：

OpenAI：帮你在内部把参数（如 model, messages）自动组装成了 JSON Body，调用时感觉像在使用普通的 Python 函数。
生成版：比较“老实”，OpenAPI 文档里定义了 Body 是个 Object，你就必须在 Python 里创建一个 Object 传给它。

2. 相似之处（优点）

尽管调用方式不同，但它们的核心优势是一样的：

强类型提示 (Type Hints)：
- 两者在 VS Code / PyCharm 中都有极好的代码补全。
- 你把鼠标悬停在 response 对象上，都能看到具体的字段（如 id, status），而不是一个黑盒的 dict。
同时支持同步和异步 (Sync & Async)：
- OpenAI: OpenAI() vs AsyncOpenAI()。
- 生成版: 提供 client 和 async_client，API 函数提供 .sync() 和 .asyncio() 两种方法。
数据模型 (Pydantic / Attrs)：
- 两者都将 API 返回的 JSON 自动解析为 Python 对象（Class），你可以用 item.id 而不是 item['id'] 来访问数据。

3. 为什么会有差异？

OpenAI Python SDK：使用的是一个名为 Stainless 的商业闭源生成器。这个生成器专门为了优化开发者体验（DX）做了大量“魔法”处理，比如自动平铺参数、自动重试机制、自动分页处理等。它是目前 API SDK 界的“天花板”。
openapi-python-client：是一个开源的通用生成器。它的目标是“准确无误地还原 OpenAPI 规范”。它不会自作主张地改变参数结构，因此虽然稍显繁琐，但非常严谨。

4. 如何让生成的 SDK 更像 OpenAI？

如果你非常喜欢 OpenAI 的那种 client.resource.action() 的写法，而觉得 openapi-python-client 这种 api_function.sync(client) 的写法太啰嗦，你有两个选择：

方案 A：自己再封装一层（推荐）

企业内部使用时，通常会写一个 Wrapper 类。

# 自己封装一个类似 OpenAI 的入口类
class DaqianAI:
    def __init__(self, token):
        self._client = Client(base_url="...", headers={...})
        # 挂载子模块
        self.llm = LLMResource(self._client)
        self.agent = AgentResource(self._client)


class LLMResource:
    def __init__(self, client):
        self._client = client

    def create(self, title, type, ...):
        # 在这里把扁平参数转为 Body 对象
        body = CreateRequest(title=title, type=type, ...)
        from daqianai.api.llms import create_llm
        return create_llm.sync(client=self._client, body=body)


# 使用时就和 OpenAI 一样了
app = DaqianAI(token="...")
app.llm.create(title="OpenAI模型GPT-5.2", type="openai", name="gpt-5.2", creator="daqianai")

方案 B：使用其他生成器

有一些其他的 Python 生成器试图模仿 OpenAI 的风格（Stainless 风格）：

Fern: (fern-api) 这是一个比较新的商业化工具（有免费版），它生成的 SDK 风格非常接近 OpenAI，支持 client.instance.create() 这种写法，体验比 openapi-python-client 更好，但配置稍微复杂一点。

结论

openapi-python-client 生成的 SDK 是“工业级”的，OpenAI 的 SDK 是“消费级”的。

如果你追求快速落地、稳定、完全符合文档定义，openapi-python-client 是目前 Python 社区最好的开源选择。
虽然它写起来比 OpenAI 稍微繁琐一点（需要多 import 几个类），但对于企业内部对接来说，类型安全和可维护性才是第一位的，这方面它完全达标。