OpenAI API | 杨劲松 - Java后端 / AI应用开发工程师

OpenAI API 基础：请求、消息、参数与可靠性

Fri, 21 Aug 2026 00:00:00 +0000

上图：OpenAI — OpenAI API 基础。

调用模型 API 的核心不是记住一个 endpoint，而是把网络请求当作不可靠的外部依赖。请求契约、超时、错误分类和用量记录必须在第一天就设计好。

核心心智模型

请求由 system/developer 规则、user 输入和可选工具组成；模型输出只是候选结果，应用层仍需验证、过滤和持久化。

关键机制

区分 4xx 参数/权限错误、429 限流、5xx 上游故障和本地超时；只对可重试类别做带抖动的指数退避，并设置总预算。

Python 示例

import asyncio, random

async def call_with_retry(client, request, attempts=3):
 for n in range(attempts):
 try:
 return await client.responses.create(**request, timeout=20)
 except (TimeoutError, RateLimitError):
 if n == attempts - 1: raise
 await asyncio.sleep((2 ** n) + random.random())

课程定位

这篇文章把白板上的模块拆成可以落地的工程边界：先定义输入和输出，再决定状态、失败策略与可观测性。示例使用 Python，重点是设计原则而不是绑定某个供应商版本；上线前请以当前依赖的官方文档为准。

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

先实现白板中的最小闭环，再故意注入一个超时、一个空结果和一个格式错误，观察系统能否给出稳定且可诊断的结果。最后补一条指标，证明你的优化确实改善了质量或延迟。

动手练习

为一次调用增加 request id、耗时、输入/输出 token 和错误类别日志；再用模拟 429 与 400 的 fake client 验证只有 429 会重试。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。

OpenAI Multimodal AI：统一处理文本、图片与文档

Fri, 21 Aug 2026 00:00:00 +0000

上图：OpenAI — OpenAI Multimodal AI。

多模态应用的难点在输入治理，而不是把文件上传给模型。每种媒体都需要类型校验、大小限制、内容安全、权限控制和可追溯的预处理。

核心心智模型

Input → Normalize → Multimodal Model → Structured Output → Application。图片可能需要降采样，PDF 可能需要 OCR/版面解析，音频需要转写与时间戳。

关键机制

把文件存储和模型请求解耦：先生成短期对象地址并做病毒扫描，再按最小分辨率/页数发送。响应保存 modality、处理版本和证据区域。

Python 示例

from pydantic import BaseModel, Field

class ImageInsight(BaseModel):
 objects: list[str] = Field(default_factory=list, max_length=20)
 summary: str = Field(max_length=1000)
 confidence: float = Field(ge=0, le=1)

def validate_upload(content_type: str, size: int) -> None:
 if content_type not in {"image/png", "image/jpeg", "application/pdf"}:
 raise ValueError("unsupported_media_type")
 if size > 10 * 1024 * 1024:
 raise ValueError("file_too_large")

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

动手练习

做一个发票图片 → 结构化字段的小实验，分别提交清晰图片、旋转图片、低分辨率图片和超大 PDF，记录字段准确率、处理时延和成本。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。

OpenAI Structured Output：让模型输出可验证的数据

Fri, 21 Aug 2026 00:00:00 +0000

上图：OpenAI — OpenAI Structured Output。

自由文本适合展示，结构化输出适合驱动程序。Structured Output 的目标不是让模型永不出错，而是让成功、拒答和失败都能被程序区分。

核心心智模型

schema 约束字段类型、必填项和枚举，但不能保证事实正确。业务层还要检查金额范围、实体权限、引用存在性等语义规则。

关键机制

将解析分成 transport、schema、domain 三层；遇到 refusal 或不完整结果时不要强行填默认值，否则会把不确定性伪装成事实。

Python 示例

from pydantic import BaseModel, Field

class Incident(BaseModel):
 severity: str = Field(pattern="^(low|medium|high)$")
 summary: str = Field(min_length=1, max_length=500)
 actions: list[str] = Field(min_length=1, max_length=5)

response = client.responses.parse(model="gpt-4o-mini", input="整理故障记录", text_format=Incident)
if response.output_parsed is None: raise ValueError("model_refusal_or_parse_failure")

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

动手练习

给 schema 增加版本号与向后兼容字段，准备正常、拒答、缺字段和越界四种 fixture，验证 API 不会返回看似成功的半结构化 JSON。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。

OpenAI Tool Calling：函数声明、执行循环与安全边界

Fri, 21 Aug 2026 00:00:00 +0000

上图：OpenAI — OpenAI Tool Calling。

Tool Calling 让模型输出函数名和参数，而不是直接执行函数。应用必须验证函数是否允许、参数是否合规、调用者是否有权限，然后把结果以工具消息回传。

核心心智模型

循环是 request → tool_call → validate → execute → tool_result → request。每一轮都有最大次数，最终答复不能绕过业务授权。

关键机制

schema 描述怎样调用，策略层决定是否允许调用。读操作可以自动执行，写操作应二次确认、幂等并审计。

Python 示例

def execute_tool(call, user):
 if call.name not in TOOL_ALLOWLIST:
 return {"ok": False, "error": "tool_not_allowed"}
 args = validate_args(call.name, call.arguments)
 authorize(user, call.name, args)
 if is_side_effecting(call.name) and not user.confirmed:
 return {"ok": False, "error": "confirmation_required"}
 return TOOL_REGISTRY[call.name](**args)

课程定位

工程实践

将业务规则放在应用层，不要藏进难以测试的提示词或路由函数。
为外部调用设置超时、重试上限和幂等键；重试不是错误处理的全部。
记录 request id、耗时、输入版本、模型/索引版本和结果状态，避免记录敏感原文。
用小规模固定数据集做回归测试，再用线上抽样监控质量与成本。

常见错误

只画 happy path，没有画超时、空结果、限流和回滚路径。
让一个函数同时负责解析、调用外部服务、拼接提示词和持久化。
用字符串约定代替类型契约，导致改动只能靠人工联调。

生产检查清单

输入、输出和错误响应均有明确 schema
外部依赖有 timeout、retry、rate limit 和 fallback
日志、指标、trace 能关联到同一次请求
关键路径有单元测试、集成测试和一组离线评测样本
密钥、用户内容和供应商响应按最小权限与隐私策略处理

练习建议

动手练习

实现天气查询和退款申请两个工具；让模型可以自动查天气，但退款必须经过用户确认、幂等键和审计日志。

总结

当白板上的每个箭头都能对应到一个输入、输出和失败策略时，AI 功能才从 demo 变成可维护的系统。