告别 Java 风格代码：使用 openapi-python-client 生成原生 Pythonic 的企业级 SDK

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

生成一个企业级（类型安全、支持异步/同步、文档完善、易于维护）的 Python SDK，目前开源社区最推荐的方案是使用openapi-python-client。

相比于老牌的Swagger Codegen或OpenAPI Generator（生成的代码风格比较像 Java，且依赖旧版库），openapi-python-client生成的代码具有以下优势：

1. 原生 Python 风格：完全符合 PEP 8 规范。
2. 强类型支持：利用 Python 3 Type Hints，IDE（VS Code/PyCharm）能完美自动补全。
3. 现代化依赖：底层使用httpx，同时支持同步（Sync）和异步（Async）调用。
4. 数据模型：自动生成 Pydantic 风格的数据类（Data Classes）。

以下是完整的生成与使用步骤：

第一步：准备工作

必须使用合并后的单文件。
生成器通常无法很好地处理本地文件系统中的复杂$ref嵌套引用。请务必使用生成的openapi_bundled.yaml文件，也就是单个文档，如果是多个OpenAPI文档则需要先合并。

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

往期文章推荐:

• 20.MBPP：评估大语言模型代码生成能力的基准数据集
• 19.RepoCoder：基于迭代检索与生成的仓库级代码补全框架
• 18.Py150数据集：Python代码建模与分析的基准资源
• 17.GPT-Neo：开源大型自回归语言模型的实现与影响
• 16.编辑相似度（Edit Similarity）：原理、演进与多模态扩展
• 15.CodeSearchNet：一个大规模代码-文档检索数据集的构建、应用与挑战
• 14.Text-Embedding-Ada-002：技术原理、性能评估与应用实践综述
• 13.RepoEval：定义仓库级代码补全评估的新基准
• 12.NaturalQuestions：重塑开放域问答研究的真实世界基准
• 11.SkCoder：基于草图的代码生成方法
• 10.长尾分布：现实世界数据的本质挑战与机器学习应对之道
• 9.概率校准：让机器学习模型的预测概率值得信赖
• 8.牛顿法：从最优化到机器学习的二阶收敛之路
• 7.交叉验证：评估模型泛化能力的核心方法
• 6.Softmax回归：原理、实现与多分类问题的基石
• 5.多重共线性：机器学习中的诊断与应对策略
• 4.惰性学习：延迟决策的机器学习范式
• 3.模糊集合理论：从Zadeh奠基到现代智能系统融合
• 2.基于实例的学习：最近邻算法及其现代演进
• 1.汉明距离：度量差异的基石与AI应用

第二步：安装生成工具

在终端中执行：

pipinstallopenapi-python-client

第三步：生成 SDK 代码

在终端中运行以下命令。假设合并文件名为openapi_bundled.yaml。

# --path: 指定 OpenAPI 文件路径# --config: (可选) 可以配置生成选项# --meta: 设置为 poetry 或 setup (生成完整的包结构) 或 none (只生成代码)openapi-python-client generate --path openapi_bundled.yaml --meta poetry

运行成功后，当前目录下会生成一个根据 info.title 名称加工后的文件夹，比如(大千AI助手API对应的名字默认为大千-ai-助手-api-client)。你可以手动重命名它，比如daqianai。

第四步：SDK 结构解析

生成的 SDK 目录结构通常如下，非常清晰：

daqianai/ ├── daqianai/ # 核心代码包 │ ├── api/ # 按 tag 分类的接口逻辑 │ │ ├── llms/ │ │ ├── agents/ │ │ └── ... │ ├── models/ # 生成的数据模型 (Type Hints) │ │ ├── llm_setting.py │ │ ├── llm_request.py │ │ └── ... │ ├── client.py # 同步客户端 │ ├── async_client.py # 异步客户端 │ └── types.py ├── pyproject.toml # 依赖管理 └── README.md # 自动生成的使用文档

第五步：安装生成的 SDK

在开发阶段，您可以直接以“可编辑模式”安装这个生成的 SDK：

# 进入生成的 SDK 目录cddaqianai# 安装 SDK 及其依赖 (httpx, attrs, etc.)pipinstall.

第六步：如何在项目中使用 (企业级用法示例)

这个 SDK 的强大之处在于它既支持简单的脚本调用，也支持高并发的异步调用。

1. 基础配置与鉴权

生成的Client类支持自定义headers，我们需要在这里按需注入Authorization等。

fromdaqianai.clientimportClient,AuthenticatedClient# 方式 A: 使用普通 Client (需手动加 Header)base_url="https://api.daqianai.cc/v1"token="YOUR_ACCESS_TOKEN"client=Client(base_url=base_url,headers={"Authorization":f"Bearer{token}","X-Dq-Authorization":"sign_value...",# 签名值"X-Dq-Date":"Wed, 23 Jan 2013..."})# 方式 B: 使用 AuthenticatedClient (如果鉴权比较简单)# 生成器通常会生成一个 AuthenticatedClient，专门处理 Tokenauth_client=AuthenticatedClient(base_url=base_url,token=token,prefix="Bearer")# 注意：由于API有自定义 Header (X-Dq-...), 建议用方式 A 或继承 Client 封装

2. 场景一：调用“查询模型列表” (同步调用)

fromdaqianai.api.llmsimportlist_modelsfromdaqianai.modelsimportListResponse,Response# 调用接口# 这里的函数参数会完全对应 OpenAPI 定义的 parametersresponse=list_models.sync_detailed(client=client,limit=20,offset=0,prefix="openai")# 处理响应ifresponse.status_code==200:# response.parsed 是自动反序列化好的 ListResponse 对象data:ListResponse=response.parsedprint(f"总数:{data.total}")foritemindata.items:print(f"模型ID:{item.id}, 标题:{item.title}")else:print(f"请求失败:{response.status_code}")

3. 场景二：创建大模型 (强类型请求体)

fromdaqianai.api.llmsimportcreate_llmfromdaqianai.modelsimportCreateRequest# 构建请求体 (IDE 会自动提示字段！)request_body=CreateRequest(title="OpenAI模型GPT-5.2",type="openai",name="gpt-5.2",creator="daqianai",)# 发起请求response=create_llm.sync(client=client,body=request_body)ifresponse:print(f"创建成功，实例ID:{response.id}")

4. 场景三：异步高并发调用 (Async/Await)

这是企业级应用（如 FastAPI, Django Async）常用的方式。

importasynciofromdaqianai.clientimportClientfromdaqianai.api.llmsimportqa_taskfromdaqianai.modelsimportQaRequestasyncdefbatch_qa(task_ids):asyncwithClient(base_url="...")asclient:# 设置鉴权头...client.headers["Authorization"]="Bearer ..."tasks=[]fortask_idintask_ids:body=QaRequest(model="gpt-5.2",instance_id="inst_1",question="question_1",)# 注意这里调用的是 asyncio 版本tasks.append(qa_task.asyncio(client=client,id=task_id,body=body))# 并发执行results=awaitasyncio.gather(*tasks)print(f"已处理{len(results)}个任务")# 运行# asyncio.run(batch_qa(["task1", "task2", "task3"]))

第七步：进一步封装（打造真正的企业级）

生成的 SDK 是基础，企业级使用通常建议再做一层薄薄的封装（Wrapper）：

1. 统一签名处理：
   继承生成的Client类，重写 request 方法，自动计算X-Dq-Date和X-Dq-Authorization，这样业务代码就不需要关心签名逻辑了。

   # custom_client.pyimportdatetimefromdaqianai.clientimportClientclassDaqianAIClient(Client):def__init__(self,app_id,app_secret,**kwargs):super().__init__(**kwargs)self.app_id=app_id self.app_secret=app_secretdef_calculate_sign(self):# 实现 DQ-1 签名逻辑return"sign_string..."# 拦截所有请求，注入 Headerdefget_headers(self):headers=super().get_headers()headers["X-Dq-Date"]=datetime.datetime.utcnow().strftime("...")headers["X-Dq-Authorization"]=self._calculate_sign()returnheaders

2. 重试机制：
   引入tenacity库，对网络波动（502, 504, ConnectionError）进行自动重试。

3. 统一异常处理：
   将 HTTP 状态码错误转换为业务异常（例如LLMNotFoundError）。

总结

通过openapi-python-client配合整理好的 OpenAPI 文档，就可以直接得到一个90% 完成度的高质量 SDK。只需要补充剩下的 10%（主要是鉴权签名的封装），即可达到企业交付标准。

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