OpenAI Python SDK(PyPI의 openai)는 OpenAI API의 공식 Python 클라이언트입니다. 인증, 요청 형식화, 응답 파싱, 스트리밍, 재시도를 처리합니다. 이 가이드에서는 설치, 핵심 OpenAI 클래스, 채팅 컴플리션, 스트리밍, 함수 호출, 비동기 사용법, 이에 대응하는 JavaScript SDK, Azure OpenAI 통합, Novita AI 호환성을 다룹니다.
OpenAI Python 패키지 설치
Python 3.10 이상이 필요합니다:
pip install openai
레거시 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 |
None | 프록시 또는 인증서 구성을 위한 커스텀 httpx 클라이언트 |
채팅 컴플리션: 기본 요청
채팅 컴플리션은 가장 일반적인 사용 사례입니다. messages 목록은 API와 동일한 형식을 따릅니다. 즉, 대화를 나타내는 role/content 딕셔너리의 목록입니다:
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"를 반환합니다. 함수를 실행하고, 결과를 messages 목록에 추가한 다음, 두 번째 요청을 보냅니다. 이 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는 그대로 사용할 수 있는 비동기 대응 클라이언트이며, 모든 메서드가 awaitable입니다. 동기 클라이언트를 asyncio.to_thread로 감싸는 것보다 이 방법이 권장됩니다.
OpenAI JavaScript SDK
OpenAI JavaScript SDK(npm의 openai)는 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", # Your deployment name in 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 매개변수는 기본 모델 이름이 아니라 배포 이름 을 의미합니다. 배포에서 사용하는 Azure API 버전에 맞게 api_version을 설정하세요(현재 지원 버전은 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",
)
동일한 SDK로 Novita AI 사용
Novita AI는 https://api.novita.ai/openai에서 OpenAI 호환 엔드포인트를 제공합니다. 동일한 openai Python SDK 또는 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-v3.1",
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에서 작동합니다.
Novita AI와 함께 사용하는 JavaScript:
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-480b-a35b-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 Agent Sandbox를 사용해야 하는 경우
모델 호출에는 OpenAI SDK를 사용하고, 워크플로에서 코드 실행, 브라우저 작업, 또는 격리된 파일 작업이 필요할 때는 Novita Agent Sandbox를 사용하세요. 이렇게 하면 SDK 레이어는 추론에 집중하고, Sandbox가 에이전트 루프의 위험한 부분을 처리합니다.
Novita AI의 오픈소스 모델
base_url만 바꾸면 클라이언트 코드를 변경하지 않고 Novita AI의 오픈 웨이트 모델을 사용할 수 있습니다. 코딩, 도구 사용, 긴 컨텍스트 작업에 적합한 모델이 필요하면서도 동일한 SDK 워크플로를 유지하고 싶을 때 유용합니다.
Novita AI의 모델 ID 형식은 provider/model-name이며, 이를 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"])
# Use open-weight for cost-sensitive, high-volume coding tasks
coding_client = get_client(use_novita=True)
# Use OpenAI for tasks where the closed model is genuinely better
openai_client = get_client(use_novita=False)
이렇게 하면 출력 품질을 A/B 테스트하고, 적합한 작업을 Novita AI로 라우팅하며, 여러 제공업체에 걸쳐 동일한 SDK 경로를 유지할 수 있습니다.
자주 묻는 질문
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을 설정해 사용할 수 있습니다. https://api.novita.ai/openai의 Novita AI 엔드포인트가 한 예이며, 스트리밍, 함수 호출, 비동기 등 전체 SDK 기능이 변경 없이 작동합니다.
OpenAI API 키를 어떻게 안전하게 보관하나요?
키를 환경 변수(OPENAI_API_KEY)에 저장하고 os.environ["OPENAI_API_KEY"]로 읽으세요. 소스 코드, 공개 저장소, 빌드 로그, 클라이언트 측 JavaScript에는 절대 넣지 마세요.
추천 글
- Novita AI가 OpenAI Agents SDK를 지원합니다! — Novita AI 모델을 OpenAI Agents SDK에 연결하여 멀티 에이전트 오케스트레이션, 가드레일, 트레이싱을 사용하세요.
- Qwen3 Coder 30B A3B Instruct 빠른 시작 — Novita AI의 비용 효율적인 코딩 모델의 모델 ID, 가격, 컨텍스트 창, API 예제.
- Vercel AI SDK: AI 애플리케이션 구축을 위한 완전한 개발자 가이드 — Novita AI의 OpenAI 호환 엔드포인트와 함께 Vercel AI SDK를 사용하여 TypeScript로 스트리밍, 도구 호출, 에이전트 루프를 구현하세요.
