OpenAI Python SDK (openai on PyPI)는 OpenAI API의 공식 Python 클라이언트입니다. 인증, 요청 포맷팅, 응답 파싱, 스트리밍 및 재시도를 처리하므로 직접 구현할 필요가 없습니다. 이 가이드에서는 설치, 핵심 OpenAI 클래스, 채팅 완성, 스트리밍, 함수 호출, 비동기 사용법, JavaScript SDK, Azure OpenAI 통합, 그리고 동일한 SDK를 Novita AI의 OpenAI 호환 엔드포인트에 연결하여 코드 변경 없이 오픈 웨이트 모델을 사용하는 방법을 다룹니다.
OpenAI Python 패키지 설치
Python 3.8 이상이 필요합니다:
pip install openai
개발 환경에서는 requirements.txt 또는 pyproject.toml에 추가하세요:
pip install openai>=1.0.0
1.x 릴리스(2023년 후반 출시)는 0.x API와 인터페이스가 크게 변경되었습니다. 이전 코드를 마이그레이션하는 경우 openai.ChatCompletion.create()는 더 이상 사용되지 않으며, 대신 client.chat.completions.create()를 사용해야 합니다.
API 키를 환경 변수로 설정하세요. 소스 코드에 넣지 마십시오:
export OPENAI_API_KEY="sk-..."
OpenAI 클라이언트 클래스
OpenAI 클래스는 주요 진입점입니다. 기본적으로 OPENAI_API_KEY 환경 변수에서 API 키를 읽거나, 명시적으로 전달할 수 있습니다:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENAI_API_KEY"],
)
클라이언트는 연결 풀링, 재시도 및 타임아웃을 관리합니다. 요청마다 새로 인스턴스화하지 말고 애플리케이션 전체에서 하나의 인스턴스를 생성하여 재사용해야 합니다.
초기화 시 구성 가능한 옵션:
| 매개변수 | 기본값 | 설명 |
|---|---|---|
api_key |
OPENAI_API_KEY 환경 변수 |
인증 자격 증명 |
base_url |
https://api.openai.com/v1 |
프록시 또는 호환 API를 위한 재정의 |
timeout |
600초 | 요청별 타임아웃 |
max_retries |
2 | 속도 제한 오류 시 자동 재시도 횟수 |
http_client |
없음 | 프록시 또는 인증서 구성을 위한 사용자 지정 httpx 클라이언트 |
채팅 완성: 기본 요청
채팅 완성이 가장 일반적인 사용 사례입니다. messages 목록은 API와 동일한 형식(대화를 나타내는 역할/내용 딕셔너리 목록)을 따릅니다:
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "You are a helpful coding assistant."},
{"role": "user", "content": "What is the difference between a list and a tuple in Python?"},
],
temperature=0.3,
max_tokens=512,
)
print(response.choices[0].message.content)
응답은 ChatCompletion 객체입니다. 주요 필드:
response.choices[0].message.content— 텍스트 응답response.usage.prompt_tokens— 입력에 사용된 토큰 수response.usage.completion_tokens— 출력에 사용된 토큰 수response.model— 요청을 처리한 모델 버전
프로덕션 환경에서는 비용 폭발을 방지하기 위해 max_tokens를 전달하고, 결정적 출력이 필요한 경우 temperature=0 또는 낮은 값을 사용하세요.
스트리밍 응답
사용자가 토큰이 도착하는 것을 실시간으로 볼 수 있는 대화형 인터페이스의 경우 stream=True를 사용하세요:
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
with client.chat.completions.stream(
model="gpt-4o",
messages=[
{"role": "user", "content": "Explain Python generators in plain language."},
],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
컨텍스트 관리자(with 문)를 사용하면 반복 후 연결이 제대로 닫힙니다. .text_stream 속성은 일반 문자열을 생성하고, .stream은 청크별 사용 통계와 같은 메타데이터가 필요한 경우 원시 이벤트 객체를 생성합니다.
컨텍스트 관리자 없이 스트리밍이 필요한 경우:
stream = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "List 5 Python best practices."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta
if delta.content:
print(delta.content, end="", flush=True)
함수 호출
함수 호출을 사용하면 모델이 함수를 호출할 시기를 결정하고 JSON 인수 객체를 반환할 수 있습니다. 애플리케이션에서 함수를 실행한 후 결과를 다시 보내 모델이 응답에 통합하도록 합니다:
import os
import json
from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Returns current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name, e.g. 'San Francisco'",
}
},
"required": ["city"],
},
},
}
]
messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=tools,
tool_choice="auto",
)
choice = response.choices[0]
if choice.finish_reason == "tool_calls":
tool_call = choice.message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
# Execute your actual function here
result = {"city": args["city"], "temperature": "18°C", "condition": "cloudy"}
messages.append(choice.message)
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(result),
})
final = client.chat.completions.create(
model="gpt-4o",
messages=messages,
)
print(final.choices[0].message.content)
모델이 함수를 호출하려고 할 때 finish_reason="tool_calls"를 반환합니다. 함수를 실행하고, 결과를 메시지 목록에 추가한 후 두 번째 요청을 보냅니다. 이 2단계 루프가 표준 패턴입니다.
AsyncOpenAI를 사용한 비동기 사용법
FastAPI, asyncio 기반 서비스 또는 비차단 I/O가 필요한 코드의 경우 AsyncOpenAI를 사용하세요:
import os
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])
async def get_response(prompt: str) -> str:
response = await client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": prompt}],
max_tokens=256,
)
return response.choices[0].message.content
async def main():
result = await get_response("What is asyncio in Python?")
print(result)
asyncio.run(main())
AsyncOpenAI는 동기 클라이언트를 감싸는 asyncio.to_thread를 사용하는 것보다 선호됩니다.
OpenAI JavaScript SDK
OpenAI JavaScript SDK (openai on npm)는 Python 인터페이스와 매우 유사합니다. 설치:
npm install openai
Node.js에서 기본 채팅 완성:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
});
const response = await client.chat.completions.create({
model: "gpt-4o",
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "Explain promises vs async/await in JavaScript." },
],
max_tokens: 512,
});
console.log(response.choices[0].message.content);
JavaScript에서 스트리밍:
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const stream = await client.chat.completions.stream({
model: "gpt-4o",
messages: [{ role: "user", content: "Summarize the fetch API in 3 sentences." }],
});
for await (const chunk of stream) {
const text = chunk.choices[0]?.delta?.content ?? "";
process.stdout.write(text);
}
JavaScript SDK는 Node.js 18+, Deno 및 브라우저 환경을 지원합니다(브라우저에서 API 키를 노출하는 것은 안전하지 않으므로 서버 측 프록시를 사용하세요). 호환 API를 가리키는 base_url 옵션은 Python에서와 동일하게 작동합니다.
Azure OpenAI Python 통합
직접 OpenAI API 대신 Azure OpenAI 서비스를 사용하는 경우 동일한 패키지의 AzureOpenAI 클라이언트를 사용하세요:
import os
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.environ["AZURE_OPENAI_API_KEY"],
azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
api_version="2024-02-01",
)
response = client.chat.completions.create(
model="gpt-4o", # Azure의 배포 이름
messages=[
{"role": "user", "content": "How do I use Azure OpenAI with Python?"},
],
)
print(response.choices[0].message.content)
Azure에 필요한 환경 변수:
AZURE_OPENAI_API_KEY: Azure 리소스 API 키AZURE_OPENAI_ENDPOINT: 엔드포인트 URL (예:https://your-resource.openai.azure.com/)
Azure OpenAI에서 model 매개변수는 기본 모델 이름이 아닌 배포 이름 을 나타냅니다. api_version은 배포에서 사용하는 Azure API 버전과 일치하도록 설정하세요(지원되는 현재 버전은 Azure OpenAI 문서 참조).
API 키 대신 Microsoft Entra ID(이전 Azure AD)를 통한 인증:
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI
token_provider = get_bearer_token_provider(
DefaultAzureCredential(),
"https://cognitiveservices.azure.com/.default",
)
client = AzureOpenAI(
azure_ad_token_provider=token_provider,
azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
api_version="2024-02-01",
)
Novita AI의 OpenAI 호환 API로 전환
Novita AI는 https://api.novita.ai/openai에서 OpenAI 호환 엔드포인트를 제공합니다. 동일한 openai Python 또는 JavaScript SDK를 사용하여 base_url과 api_key만 변경하면 됩니다. 다른 코드 변경은 필요하지 않습니다:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NOVITA_API_KEY"],
base_url="https://api.novita.ai/openai",
)
response = client.chat.completions.create(
model="deepseek/deepseek-v4-pro",
messages=[
{"role": "system", "content": "You are a helpful coding assistant."},
{"role": "user", "content": "Explain how Python's GIL affects multithreading."},
],
temperature=0.3,
max_tokens=512,
)
print(response.choices[0].message.content)
Novita AI API 키는 novita.ai/settings/key-management에서 받을 수 있습니다. 동일한 키가 OpenAI 호환 엔드포인트를 포함한 모든 Novita AI API에서 작동합니다.
JavaScript와 Novita AI:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.NOVITA_API_KEY,
baseURL: "https://api.novita.ai/openai",
});
const response = await client.chat.completions.create({
model: "qwen/qwen3-coder-30b-a3b-instruct",
messages: [{ role: "user", content: "Write a Python type annotation cheatsheet." }],
max_tokens: 600,
});
console.log(response.choices[0].message.content);
스트리밍, 함수 호출, 비동기 사용법, response_format, temperature, max_tokens 등 모든 하위 기능이 동일하게 작동합니다. Novita AI 엔드포인트는 OpenAI Chat Completions API 사양을 따릅니다.
Novita AI를 통한 오픈소스 모델
base_url을 변경하면 특정 작업에서 폐쇄형 최첨단 모델과 경쟁력 있는 다양한 오픈 웨이트 모델 카탈로그에 액세스할 수 있습니다. 코딩 워크플로, 함수 호출 및 긴 컨텍스트 추론의 경우 실용적인 격차가 크게 줄었습니다.
Novita AI의 OpenAI 호환 엔드포인트를 통해 제공되며 평가할 가치가 있는 모델:
DeepSeek V4 Pro (deepseek/deepseek-v4-pro): MIT 유사 라이선스의 대규모 MoE 모델로 SWE-Bench 및 함수 호출 벤치마크에서 최상위권을 기록합니다. 코딩 에이전트, 코드 리뷰 및 GPT-4o나 Claude Opus를 사용했을 다단계 도구 사용 작업에 강력합니다.
Qwen3 Coder 30B A3B Instruct (qwen/qwen3-coder-30b-a3b-instruct): Qwen Coder 제품군의 30B 희소 MoE 모델로, 코드 생성, 버그 분류 및 풀 리퀘스트 리뷰에 최적화되어 있습니다. Novita AI에서 입력 토큰 100만 개당 $0.07, 출력 토큰 100만 개당 $0.27로 일상적인 코딩 지원에 있어 대부분의 폐쇄형 API보다 훨씬 저렴합니다.
Qwen3 235B A22B Instruct (qwen/qwen3-235b-a22b-instruct-2507): Apache 2.0 라이선스의 대규모 MoE 모델로, 강력한 추론 및 다국어 코딩 성능을 제공합니다. 현재 GPT-4o를 창의적이거나 복잡한 응답에 사용하는 작업에 적합하지만, 볼륨이 있는 경우 토큰당 비용을 줄이고자 할 때 좋습니다.
Novita AI의 모델 ID 형식은 provider/model-name입니다. SDK의 model 매개변수에 직접 전달합니다.
오픈 모델과 폐쇄 모델을 혼합하려는 팀을 위한 간단한 라우팅 패턴:
def get_client(use_novita: bool = False) -> OpenAI:
if use_novita:
return OpenAI(
api_key=os.environ["NOVITA_API_KEY"],
base_url="https://api.novita.ai/openai",
)
return OpenAI(api_key=os.environ["OPENAI_API_KEY"])
# 비용에 민감하고 볼륨이 많은 코딩 작업에는 오픈 웨이트 사용
coding_client = get_client(use_novita=True)
# 폐쇄형 모델이 실제로 더 나은 작업에는 OpenAI 사용
openai_client = get_client(use_novita=False)
이를 통해 출력 품질을 A/B 테스트하고, 작업별 성능을 벤치마킹하며, 요청 로직을 변경하지 않고도 볼륨을 더 저렴한 모델로 이동할 수 있습니다.
FAQ
OpenAI Python 패키지 이름은 무엇인가요?
PyPI의 패키지 이름은 openai입니다. pip install openai로 설치하세요.
OpenAI 클라이언트 Python 클래스 이름은 무엇인가요?
동기 사용을 위한 기본 클래스는 OpenAI이고, 비동기 사용을 위한 클래스는 AsyncOpenAI입니다. 둘 다 openai 모듈에 있습니다: from openai import OpenAI, AsyncOpenAI.
OpenAI Python SDK는 스트리밍을 지원하나요?
네. client.chat.completions.stream()을 컨텍스트 관리자로 사용하거나, client.chat.completions.create()에 stream=True를 전달하고 청크를 반복하면 됩니다.
OpenAI JavaScript SDK 패키지 이름은 무엇인가요?
npm 패키지는 openai입니다. npm install openai로 설치하세요. 클래스 및 메서드 시그니처는 Python SDK와 거의 동일합니다.
Python으로 Azure OpenAI를 어떻게 사용하나요?
openai 패키지의 AzureOpenAI 클래스를 사용하세요. azure_endpoint, api_key, api_version을 전달합니다. model 매개변수는 기본 모델이 아닌 Azure 배포 이름을 나타냅니다.
다른 제공업체와 함께 OpenAI Python SDK를 사용할 수 있나요?
네. OpenAI Chat Completions API 형식을 구현하는 모든 제공업체는 클라이언트에 base_url을 설정하여 사용할 수 있습니다. Novita AI의 https://api.novita.ai/openai 엔드포인트가 한 예이며, 스트리밍, 함수 호출, 비동기 등 전체 SDK 기능 세트가 변경 없이 작동합니다.
OpenAI API 키를 어떻게 안전하게 보관하나요?
키를 환경 변수(OPENAI_API_KEY)에 저장하고 os.environ["OPENAI_API_KEY"]로 읽으세요. 소스 코드, 공개 저장소, 빌드 로그 또는 클라이언트 측 JavaScript에 절대 넣지 마십시오.
추천 문서
- Novita AI Now Supports OpenAI Agents SDK! — Novita AI 모델을 OpenAI Agents SDK에 연결하여 다중 에이전트 오케스트레이션, 가드레일 및 추적을 사용하세요.
- Qwen3 Coder 30B A3B Instruct Quick Start — Novita AI에서 이 비용 효율적인 코딩 모델의 모델 ID, 가격, 컨텍스트 창 및 API 예제를 확인하세요.
- Vercel AI SDK: Complete Developer Guide for Building AI Applications — Vercel AI SDK를 Novita AI의 OpenAI 호환 엔드포인트와 함께 사용하여 TypeScript로 스트리밍, 도구 호출 및 에이전트 루프를 구현하세요.
