笔记
0工具
0此页用于记录用户反馈问题后的每一次改进
关于
“写笔记”支持四种格式——Word 文档、Excel 表格、Markdown、纯文本，起稿或二次编辑时都能随时切换，同一篇笔记想用哪种形态来记，都由你说了算。
md、txt、csv、json 这类纯文本则原样载入，不做多余加工。拿一张现成的表倒进来、改几笔、再导出去，等于白用一台免费的格式转换器。
要带走就在右上角点“下载”，可导出 PDF、Word、Markdown、Excel、TXT 等格式；列表卡片“⋯”菜单里，也有同样的下载入口。
在“工具”页点“＋ 上传工具”即可发布：填好名称与链接，再用 Markdown 把使用方法写清楚——能解决什么问题、怎么装、怎么用，比堆介绍实在。
要分发安装包就一并上传压缩包（ZIP、RAR、7Z、TAR.GZ，最大 35MB），别人在详情页一键下载；只放链接不带附件也可以。
工具按大家的收藏热度排序，好用的自然会被顶上来。发布后可在详情页或卡片菜单里编辑、下架。
写笔记时勾上“隐藏”，这篇就只存在于你自己的账号里：不进列表、不进搜索、不上首页精选，也不会出现在任何公开的页面，链接发给别人同样打不开。
适合放密码、草稿、日记这类只给自己看的内容；想公开，去“发布”打开它，把“隐藏”的勾去掉再保存，之后编辑会默认保持原状态，不会悄悄变回公开。
不想公开、只想临时给人看：点“分享”生成一条带密码和有效期的链接，到期自动失效，你也能随时撤销。
你的内容会同时保存在多个副本上，系统定期做备份与完整性校验，再配合异地容灾机制：就算某台机器出问题，数据也不会丢，可以长期放心存放；特别重要的资料，仍建议你另外再留一份备份。
全站跑在容器化、模块化的现代架构上，更新、部署、回滚都很快，扩展性和稳定性都按长期运营的标准来设计（Built for reliability, designed to scale）。
这个网站最早只是一个人的笔记仓库，后来慢慢长成现在的知识中枢。设计上很克制——没有广告、没有追踪、没有推荐算法，只是干干净净地存放一些东西；既然做好了，就公开出来，万一有人用得上呢。
不做大而全，不做平台梦，保持简单、保持克制、保持好奇。所有内容都由用户贡献、由用户维护：不会突然冒出付费墙，不会在角落塞广告位，也不会把你的数据卖给第三方。
产品会持续迭代，站内日志页记录着每一次改动，改了什么都有迹可循；想了解这个站是怎么一步步走到今天的，翻翻日志就能看到来龙去脉。
如果在这里看到涉嫌违规的内容，点对应卡片右侧的“举报”按钮就能提交，我们会尽快核实处理；也谢谢你花一点时间，一起把这里维护干净。
趋势
OpenAI Python SDK 迁移至 HTTPX2：全面技术指南
OpenAI Python SDK 已从 HTTPX 迁移至 HTTPX2，本文详解其对 TLS 证书、自定义客户端、超时配置、流式处理和测试模拟等层面的影响与迁移方案。
背景：为什么迁移到 HTTPX2
OpenAI Python SDK 是 Python 生态中最广泛使用的 AI API 客户端之一（GitHub 31.5k stars）。其底层 HTTP 客户端库长期依赖 httpx——一个功能强大的同步/异步 HTTP 客户端。然而，随着 HTTPX2 的发布，OpenAI 决定将 SDK 的内部 HTTP 层全面切换到 HTTPX2。
这一迁移并非简单的版本号升级。HTTPX2 是 HTTPX 的继任者，在 TLS 信任存储、API 兼容性、异步支持等方面有根本性变化。对于使用 OpenAI SDK 的开发者来说，理解这些变化至关重要，尤其是那些自定义了 HTTP 客户端、依赖特定 TLS 证书链或使用测试模拟库的项目。
核心变化概览
- 依赖关系变化：安装
openai包将自动安装httpx2，但不再安装旧版httpx。 - TLS 信任存储变化：HTTPX2 默认使用操作系统信任存储，而非
certifi提供的 CA 捆绑包。 - API 对象替换：
httpx.Client→httpx2.Client，httpx.Timeout→httpx2.Timeout等。 - 辅助类更名：
DefaultHttpxClient→DefaultHttpx2Client（旧名称仍可用但已弃用）。 - 测试模拟库兼容性：RESPX 等库需要更新到支持 HTTPX2 的版本。
使用默认 HTTP 客户端的场景
如果你使用 SDK 的默认 HTTP 客户端（即不显式传入 http_client 参数），迁移对你的影响最小：
python
from openai import OpenAI
client = OpenAI(timeout=30.0)
response = client.responses.create(
model="gpt-5.5",
input="Hello"
)
上述代码无需任何修改。API 调用、解析后的响应模型、流式 API、认证、重试逻辑和数值型超时都完全兼容。安装方式也不变：
bash
pip install openai
但有一个重要警告：如果你的应用之前仅因为 SDK 的传递依赖而间接获得了 httpx，现在你需要显式添加 httpx 依赖（如果你仍在使用它），或将相关导入迁移到 httpx2。SDK 安装不再自动安装 httpx。
TLS 证书与信任存储：最容易被忽视的破坏点
这是迁移中最容易导致线上事故的变化。
旧行为（HTTPX）
HTTPX 使用 certifi 提供的 CA 证书捆绑包来验证 TLS 证书。certifi 是一个维护良好的 Mozilla CA 证书集合，被广泛使用。SDK 之前会传递安装 certifi。
新行为（HTTPX2）
HTTPX2 默认使用操作系统信任存储。这意味着：
- 在标准 Linux 发行版、macOS 或 Windows 上，系统会使用
/etc/ssl/certs（Linux）或系统钥匙串（macOS/Windows）中的证书。 - 在最小化容器镜像（如
python:3.12-slim、alpine）中，可能没有安装任何 CA 证书，导致所有 HTTPS 请求失败。 - 在使用企业 TLS 拦截代理的环境中，如果代理的根证书未安装到系统信任存储，请求将失败。
- 如果你之前自定义或替换了
certifi捆绑包，现在这些定制不再生效。
SDK 也不再安装 certifi。
解决方案
方案一：安装系统 CA 证书（推荐）
在 Debian/Ubuntu 容器中：
bash
apt-get update && apt-get install -y ca-certificates
在 Alpine 中：
bash
apk add ca-certificates
方案二：通过环境变量指定证书
bash
export SSL_CERT_FILE=/path/to/ca-bundle.pem
或指定证书目录：
bash
export SSL_CERT_DIR=/path/to/ca-directory
这些环境变量在 trust_env=True（默认值）时生效。
方案三：通过 ssl.SSLContext 显式控制
python
import ssl
from openai import OpenAI, DefaultHttpx2Client
ssl_context = ssl.create_default_context(cafile="/path/to/ca-bundle.pem")
client = OpenAI(http_client=DefaultHttpx2Client(verify=ssl_context))
异步版本使用 DefaultAsyncHttpx2Client(verify=ssl_context)。
注意：SDK 的 aiohttp 传输层也使用相同的 HTTPX2 TLS 设置。
自定义 HTTP 客户端的迁移
如果你向 OpenAI 或 AsyncOpenAI 传入了自定义的 http_client，需要遵循以下规则：
使用 SDK 提供的辅助类（推荐）
SDK 提供了 DefaultHttpx2Client 和 DefaultAsyncHttpx2Client，它们保留了 SDK 推荐的超时、连接池和重定向默认值：
python
import httpx2
from openai import OpenAI, AsyncOpenAI, DefaultHttpx2Client, DefaultAsyncHttpx2Client
代理配置
proxy_client = OpenAI(
http_client=DefaultHttpx2Client(proxy="http://proxy.example.com:8080")
)
自定义传输和超时
transport_client = OpenAI(
http_client=DefaultHttpx2Client(
transport=httpx2.HTTPTransport(local_address="0.0.0.0"),
timeout=httpx2.Timeout(30.0, connect=5.0),
)
)
异步客户端
async_client = AsyncOpenAI(
http_client=DefaultAsyncHttpx2Client(timeout=httpx2.Timeout(30.0))
)
直接构造 httpx2.Client 和 httpx2.AsyncClient 实例也是支持的。但要注意，直接构造时，HTTPX2 自身的默认值（而非 SDK 的默认值）会生效，除非你自行配置。
旧名称兼容性
DefaultHttpxClient 和 DefaultAsyncHttpxClient 这两个名称仍然有效，但它们现在构造的是 HTTPX2 客户端。为明确起见，建议使用新名称。
模块级配置
python
import openai
openai.http_client = openai.DefaultHttpx2Client()
对象映射表：从 HTTPX 到 HTTPX2
以下对象需要替换为对应的 HTTPX2 版本：
| HTTPX 旧对象 | HTTPX2 新对象 |
|---|---|
httpx.Client |
httpx2.Client |
httpx.AsyncClient |
httpx2.AsyncClient |
httpx.Timeout |
httpx2.Timeout |
httpx.URL |
httpx2.URL |
httpx.Limits |
httpx2.Limits |
httpx.HTTPTransport |
httpx2.HTTPTransport |
httpx.AsyncHTTPTransport |
httpx2.AsyncHTTPTransport |
httpx.MockTransport |
httpx2.MockTransport |
示例：粒度超时配置
python
import httpx2
from openai import OpenAI
client = OpenAI(
timeout=httpx2.Timeout(60.0, connect=5.0, read=20.0)
)
不变项：
- 数值型超时（如
timeout=30.0）不受影响。 - 字符串 URL 不受影响。
需要关注：自定义传输子类、挂载的传输、代理集成和连接池监控必须针对 HTTPX2 的传输接口进行适配。
认证与事件钩子
认证处理器和事件钩子现在接收 HTTPX2 的请求和响应对象：
python
import httpx2
from openai import OpenAI, DefaultHttpx2Client
def log_request(request: httpx2.Request) -> None:
print(request.method, request.url)
client = OpenAI(
http_client=DefaultHttpx2Client(
event_hooks={"request": [log_request]}
)
)
如果你子类化了 HTTP 认证或传输接口，必须改为子类化对应的 httpx2 类。
第三方集成警告：任何第三方插桩、追踪中间件或认证集成（例如 OpenTelemetry 的 HTTPX 插桩）必须显式支持 HTTPX2，否则将无法工作。
原始响应、流式与异常处理
解析后的响应模型不变
SDK 返回的解析后响应模型（如 client.models.list() 返回的对象）完全不变。
原生 HTTPX2 客户端的类型保证
当你使用原生 HTTPX2 客户端时：
python
import httpx2
from openai import OpenAI
client = OpenAI()
response = client.models.with_raw_response.list()
assert isinstance(response.http_response, httpx2.Response)
assert isinstance(response.http_request, httpx2.Request)
使用 cast_to=httpx2.Response 可以请求未解析的 HTTP 响应。
流式响应包装器也暴露 HTTPX2 响应对象。
异常处理
应用代码通常应捕获 SDK 异常，如 openai.APITimeoutError 和 openai.APIConnectionError。使用原生客户端时，异常底层的传输原因是 HTTPX2 异常（如 httpx2.ConnectError）。
重要限制
这些类型保证仅适用于原生 HTTPX2 客户端。如果你注入了旧版 HTTPX 客户端（例如通过一些兼容层），即使指定了 cast_to=httpx2.Response，实际产生的仍是 httpx.Request、httpx.Response 和 HTTPX 传输异常。
aiohttp 支持
SDK 的 aiohttp extra 现在使用 HTTPX2 原生传输，不再安装旧版 HTTPX 或外部 httpx-aiohttp 适配器：
bash
pip install 'openai[aiohttp]'
python
from openai import AsyncOpenAI, DefaultAioHttpClient
client = AsyncOpenAI(http_client=DefaultAioHttpClient())
DefaultAioHttpClient() 实际上是一个 httpx2.AsyncClient。使用此辅助类时，你无需直接构造或导入传输层。
请求模拟与测试
这是另一个容易踩坑的领域。
MockTransport 示例
模拟必须拦截 HTTPX2 请求并返回 HTTPX2 响应：
python
import httpx2
from openai import OpenAI
def handler(request: httpx2.Request) -> httpx2.Response:
return httpx2.Response(
200,
request=request,
json={"object": "list", "data": []},
)
client = OpenAI(
http_client=httpx2.Client(transport=httpx2.MockTransport(handler))
)
assert client.models.list().data == []
RESPX 兼容性
如果你的测试套件使用 RESPX（一个流行的 HTTPX 模拟库），必须更新到支持 HTTPX2 的版本或自行 fork。仅修补旧版 HTTPX 的 RESPX 版本无法拦截 SDK 默认的 HTTPX2 客户端。
临时逃生通道
如果无法立即迁移某个集成，文档提到了一个“临时旧客户端逃生通道”（原文在此处截断，但通常意味着你可以显式构造一个旧版 httpx.Client 并注入，尽管这会失去 HTTPX2 的所有新特性）。
迁移检查清单
- 检查 TLS 证书：在容器或受限网络环境中，确保系统信任存储包含所需 CA 证书，或设置
SSL_CERT_FILE/SSL_CERT_DIR。 - 替换所有
httpx导入：将代码中的import httpx改为import httpx2，并替换对应的对象。 - 更新自定义认证和钩子：确保类型注解和子类化目标改为
httpx2。 - 检查第三方集成：确认追踪、监控、代理等中间件支持 HTTPX2。
- 更新测试模拟：升级 RESPX 或改用
httpx2.MockTransport。 - 验证异常处理：确保捕获的底层异常类型与 HTTPX2 匹配。
- 审查依赖声明：如果之前依赖 SDK 传递安装的
httpx，现在需要显式声明。
总结
HTTPX2 迁移对大多数使用默认客户端的开发者是透明的，但 TLS 信任存储的变化、自定义客户端的对象替换、以及测试模拟库的兼容性是三个最大的风险点。建议在迁移前仔细审查你的部署环境（尤其是容器镜像）、自定义 HTTP 配置和测试基础设施。
原文链接：https://github.com/openai/openai-python/blob/main/httpx2.md