이미지: openai (GitHub Copilot)
요약
- 오픈AI 파이썬 SDK가 동기·비동기 HTTP 클라이언트를 HTTPX에서 HTTPX2로 바꿨어요.
- TLS 인증서 검증 기준이 certifi CA 번들에서 운영체제 신뢰 저장소로 바뀌었어요.
- 최소 컨테이너나 사내 프록시 환경에서는 인증서 오류가 날 수 있어 사전 점검이 필요해요.
- 변경 대상
- 오픈AI 파이썬 SDK(openai-python)의 동기·비동기 HTTP 클라이언트
- 신규 기본 라이브러리
- HTTPX2 (openai 설치 시 자동 설치, 기존 httpx는 더 이상 자동 설치 안 됨)
- 핵심 변경점
- TLS 인증서 신뢰 저장소가 certifi CA 번들 → 운영체제 신뢰 저장소로 전환
- 영향 가능 환경
- 시스템 CA 인증서 없는 최소 컨테이너, 사내 TLS 검사 프록시, 커스텀 certifi 번들 사용 배포
- 하위 호환
- DefaultHttpxClient·DefaultAsyncHttpxClient 이름은 유지되며 내부적으로 HTTPX2 클라이언트 생성
- 임시 대안
- 레거시 HTTPX 클라이언트를 명시적으로 설치·주입하는 런타임 전용 호환 경로 제공(향후 중단 가능)
오픈AI 파이썬 SDK, HTTP 통신 계층을 갈아 끼웠어요
오픈AI가 파이썬 SDK인 openai-python의 HTTP 통신 방식을 바꿨어요. 지금까지 동기·비동기 API 호출을 처리하던 HTTPX 대신 HTTPX2를 기본 클라이언트로 쓰기 시작했다고 마이그레이션 가이드에서 밝혔어요. openai 패키지를 설치하면 HTTPX2가 자동으로 함께 깔리고, 예전처럼 httpx가 딸려 오지는 않아요.
풀어서 설명하면, HTTPX는 파이썬 프로그램이 인터넷 너머 서버와 통신할 때 쓰는 도구이고, 인증서 검증은 그 통신 상대가 진짜 오픈AI 서버가 맞는지 확인하는 절차예요. 지금까지는 certifi라는 별도 패키지가 들고 있는 인증서 목록으로 이 확인을 했는데, 이제는 각 컴퓨터·서버에 원래 깔려 있는 운영체제 인증서 저장소를 쓰게 바뀐 거예요.
바뀐 건 통신 도구 이름만이 아니에요. 함께 달라진 건 인증서를 검증하는 기준이에요. 지금까지 SDK는 certifi가 제공하는 CA 인증서 목록을 기준으로 서버 인증서를 확인했는데, HTTPX2는 운영체제가 갖고 있는 신뢰 저장소를 대신 사용해요. SDK는 이제 certifi도 따로 설치하지 않고요.
왜 이 변화가 문제가 될 수 있나
문제는 모든 환경에 이 운영체제 인증서 저장소가 제대로 갖춰져 있지는 않다는 점이에요. 가이드는 시스템 CA 인증서가 빠진 최소 컨테이너 이미지, 회사 내부 트래픽을 들여다보는 TLS 검사 프록시를 쓰는 환경, 커스텀하거나 수정된 certifi 번들에 의존해 온 배포에서 인증서 검증이 깨질 수 있다고 설명해요. 지금까지 별다른 설정 없이도 잘 돌아가던 서버가, SDK만 새로 설치했을 뿐인데 접속 오류를 내기 시작할 수 있다는 뜻이에요.
개발자가 지금 확인해야 할 것
가이드가 제시한 대응 방법은 운영체제 신뢰 저장소에 필요한 CA 인증서를 직접 설치하거나, 명시적인 인증서 번들을 지정하는 거예요. 이 값들은 trust_env=True일 때(기본값) 환경변수로도 적용되고, ssl.SSLContext를 verify 인자로 넘겨 커스텀 클라이언트에서 신뢰 범위를 직접 지정할 수도 있어요.
기존 코드와의 호환성도 상당 부분 유지돼요. http_client를 따로 지정하지 않고 OpenAI나 AsyncOpenAI 클라이언트를 만들었다면 API 호출, 응답 모델 파싱, 스트리밍, 인증, 재시도, 숫자로 된 타임아웃 설정은 그대로 동작해요. DefaultHttpxClient·DefaultAsyncHttpxClient라는 이름도 계속 쓸 수 있는데, 다만 내부적으로는 HTTPX2 클라이언트를 만들도록 바뀌었어요. 가이드는 클라이언트 종류를 명시적으로 드러내려면 DefaultHttpx2Client·DefaultAsyncHttpx2Client를 쓰라고 권해요.
반대로 손을 봐야 하는 지점도 있어요. 커스텀 인증 핸들러나 훅은 이제 HTTPX2의 요청·응답 객체를 받기 때문에 관련 클래스를 업데이트해야 하고, 테스트 코드에서 RESPX 같은 목(mock) 라이브러리를 쓴다면 HTTPX2를 가로챌 수 있는 버전으로 바꿔야 해요. 기존 httpx 전용 어댑터로는 SDK의 새 기본 클라이언트를 가로챌 수 없다고 가이드는 밝혀요.
당장 전환이 어려운 프로젝트를 위한 임시 통로도 있어요. httpx를 별도로 설치하고 레거시 클라이언트를 명시적으로 주입하면 기존 HTTPX 기반 코드를 당분간 그대로 쓸 수 있는데, 가이드는 이 경로가 런타임 전용이며 정적 타입 검사를 통과하려면 cast(Any, ...) 같은 우회가 필요하고, 이 지원 자체가 향후 중단될 수 있다고 못박아요.
표로 보는 변경 전후
| 항목 | 기존(HTTPX) | 변경 후(HTTPX2) |
|---|---|---|
| 기본 HTTP 클라이언트 | httpx | httpx2 |
| 자동 설치 여부 | openai 설치 시 자동 설치 | openai 설치 시 자동 설치, httpx는 더 이상 자동 설치 안 됨 |
| 인증서 신뢰 기준 | certifi CA 번들 | 운영체제 신뢰 저장소 |
| DefaultHttpxClient 동작 | HTTPX 클라이언트 생성 | 이름 유지, 내부는 HTTPX2 클라이언트 생성 |
| 레거시 지원 | 해당 없음 | 명시적 설치 시 런타임 호환 경로 제공(중단 가능) |
에디터의 시선
이번 변화는 오픈AI가 새 모델을 내놓거나 요금을 바꾸는 발표와는 결이 달라요. 하지만 실제로 오픈AI API를 붙여 서비스를 운영하는 개발자에게는 모델 업데이트만큼, 어쩌면 그보다 조용히 다가오는 종류의 위험이에요. 모델 이름이 바뀌면 누구나 알아채지만, HTTP 클라이언트 밑단이 바뀌는 건 배포가 갑자기 실패하고 나서야 발견되는 경우가 많거든요.
최근 오픈AI가 GPT-5.6 Luna의 토큰 가격을 입력·출력 모두 80% 낮춘 가격 전쟁과 이번 SDK 변화를 나란히 놓고 보면, 지금 오픈AI가 신경 쓰는 두 개의 전선이 보여요. 하나는 중국발 저가 모델과의 가격 경쟁이고, 다른 하나는 개발자가 API를 얼마나 마찰 없이 쓸 수 있게 만드느냐예요. SDK의 기본 통신 계층과 인증서 검증 기준을 바꾸는 일은 화려하진 않지만, 대규모로 오픈AI API를 호출하는 기업 입장에서는 배포 안정성과 직결되는 문제예요.
실무적으로는 세 가지를 먼저 점검하는 게 좋아요. 하나, 운영 중인 컨테이너 이미지에 시스템 CA 인증서가 실제로 들어 있는지. 둘, 사내 TLS 검사 프록시나 커스텀 인증서 번들에 의존하는 배포가 있는지. 셋, 테스트 코드에 RESPX 같은 HTTP 목 라이브러리를 쓰고 있다면 HTTPX2와 호환되는 버전인지. 이 세 가지를 openai 패키지를 새로 설치하거나 업그레이드하기 전에 확인해 두면, 배포 당일 인증서 오류로 당황할 일은 줄어들어요.
오픈AI가 레거시 HTTPX 지원을 마이그레이션 보조 수단이라고 못 박아 둔 만큼, 언젠가는 이 우회로 자체가 사라질 걸 염두에 두고 지금부터 HTTPX2 기준으로 코드를 정리해 두는 편이 나을 거예요.
댓글