OpenAI API

API Key 적용 방식

1. client 객체를 생성할 때 api_key 인자를 직접 지정
2. api_key 인자를 지정하지 않았다면 환경변수 OPENAI_API_KEY 값을 읽어와서 client 객체를 초기화 (다른 이름이면 안됨)

import os

import openai

# Case 1: client 객체 생성 시 API Key 직접 할당
client = openai.OpenAI(api_key="sk-xxxx")  # 직접 할당

import os

import openai

# Case 2: client 객체 생성 시 API Key 미할당 → OpenAI 클래스가 초기화 시점에 환경변수 OPENAI_API_KEY 값을 자동으로 읽어 사용
os.environ["OPENAI_API_KEY"] = "sk-yyyy"  # 미리 환경변수 설정
client = openai.OpenAI()  # 환경변수 값 자동 적용

주요 함수

def get_completion(client, prompt, model="gpt-3.5-turbo"):
    messages = [{'role': 'user', 'content': prompt}]
    response = client.chat.completions.create(
        model=model,
        messages=messages,
        n=1,
        max_tokens=100,
        temperature=0.9,
    )
    return response.choices[0].message.content

messages 부분 의미

• 정의: messages 는 대화 맥락 (Context) 을 담는 리스트
• 각 원소는 {"role": ..., "content": ...} 형태의 딕셔너리
  • "role": 발화자의 역할을 나타냄
    • "system" → 모델의 기본 지침
    • "user" → 사용자가 입력한 내용
    • "assistant" → 모델이 응답한 내용
  • "content": 실제 텍스트 (메시지)

👉 여기서는 {'role': 'user', 'content': prompt} 만 넣었으므로, 모델은 사용자가 prompt 를 말한 상황을 입력받습니다.

completions.create 함수

• 의미: OpenAI API 의 Chat Completions 엔드포인트를 호출하는 함수
• 역할: 지정한 model 을 사용해서 messages 를 입력받고, 모델이 생성한 n 개의 답변 (Completion) 을 반환
• 내부적으로 OpenAI 서버에 요청을 보내고, 생성된 텍스트 응답을 response 객체로 받아옴

temperature 란?

• 정의: 샘플링 시 랜덤성을 조절하는 하이퍼파라미터
• 값 범위: 0.0 ~ 2.0 (일반적으로 0 ~ 1)
• 동작 방식:
  • 0: 가장 확률이 높은 토큰만 고름 → 결정적 (deterministic) 결과
  • 1: 랜덤성이 커짐 → 다양한 응답 가능
  • >1: 더 창의적/무작위 → 일관성 떨어질 수 있음

👉 0.9 는 비교적 창의적이면서도 맥락을 유지하려는 세팅입니다.

response.choices[0].message.content 의미

• response: 모델이 생성한 응답 전체 (JSON-like 객체)

ChatCompletion(
    id='chatcmpl-abc123',
    choices=[...],
    created=1755572546,
    model='gpt-3.5-turbo-0125',
    object='chat.completion',
    service_tier='default',
    system_fingerprint=None,
    usage=CompletionUsage(
        completion_tokens=77,
        prompt_tokens=15,
        total_tokens=92,
        completion_tokens_details=CompletionTokensDetails(
            accepted_prediction_tokens=0,
            audio_tokens=0,
            reasoning_tokens=0,
            rejected_prediction_tokens=0
        ),
        prompt_tokens_details=PromptTokensDetails(
            audio_tokens=0,
            cached_tokens=0
        )
    )
)

• choices: 모델이 반환한 여러 후보 응답을 담는 리스트
  • 기본적으로 최소 1개의 응답이 오며, choices[0] 은 첫 번째 응답
• message: 각 후보 응답 내부에 있는 메시지 객체
  • 구조: {"role": "assistant", "content": "모델이 생성한 텍스트"}
• message.content: 모델이 실제 생성한 텍스트 (자연어 응답)

👉 따라서 response.choices[0].message.content 는 모델이 첫 번째로 생성한 답변 텍스트 문자열을 의미합니다.

토큰 사용량

• OpenAI 과금은 토큰 단위로 이뤄짐
• 토큰 사용량은 response.usage 에서 확인 가능 (prompt_tokens, completion_tokens, total_tokens)
  • prompt_tokens: 입력 메시지 (messages) 에 쓰인 토큰 수
  • completion_tokens: 모델이 생성한 응답에 쓰인 토큰 수
    • 만약 n > 1로 여러 응답을 받으면, completion_tokens 도 그만큼 늘어남
  • total_tokens: 두 개 합계
• 실제 과금은 total_tokens 기준

토큰 (Token): 텍스트의 최소 단위입니다. 일반적으로 단어와 비슷하지만 완전히 같지는 않습니다. 즉, 토큰은 텍스트의 양을 나타내지만, 단순한 글자 수가 아니라 모델이 쪼개서 인식하는 단위라서 실제 글자 수와는 다릅니다.

모델별 토큰 허용량 (Context Length)

각 모델은 한 번에 처리할 수 있는 최대 토큰 수 (= context length) 가 정해져 있습니다. 이 최대치는 응답 (Choice) 별 total_tokens 기준입니다.

👉 즉, prompt_tokens + completion_tokens <= 모델의 context limit 을 만족해야만 합니다.

• prompt 가 크더라도 context limit 한도 내라면 모델은 completion 을 줄여서라도 답변 생성
• prompt 자체가 context limit 을 넘으면 모델은 답변을 시도하기 전에 에러 발생

토큰 허용량은 각 Choice 가 독립적으로 context limit 규칙을 적용 받습니다. 예를들어 n=3 인 경우, context limit 이 100 tokens 일때 prompt 가 10 tokens 였다면, 세 개의 응답은 각각 completeion_token 을 최대 30 tokens 가 아닌 90 tokens 까지 생성 가능합니다. 즉, 과금은 최대 280 tokens 만큼 발생할 수 있게 됩니다.

completion_tokens 제한 설정

• 모델의 응답 길이를 제한하기 위해 completion_tokens 제한 가능
• 효과: 비용 절감, 응답 길이 제어 가능
• 하지 않을 경우: 비용과 응답 길이 예측 어려움
• max_tokens 값으로 조정 (default = None 이지만 사실상 context limit - prompt_tokens)
  • 값을 지정하지 않은 경우 해당 Choice 의 total_tokens 가 context limit 을 넘어버리기 전에 모델이 알아서 응답 종료
  • 만약 max_tokens 를 context limit - prompt_tokens 보다 크게 설정하면 API 가 요청을 받자마자 에러 반환
• 전체 n 개의 Choice 에 대해 개별적으로 적용

finish_reason

choices=[
        Choice(
            finish_reason='stop',
            index=0,
            logprobs=None,
            message=ChatCompletionMessage(
                content='저는 AI 어시스턴트이니 이름이 따로 없어요. 어떻게 도와드릴까요?',
                refusal=None,
                role='assistant',
                annotations=[],
                audio=None,
                function_call=None,
                tool_calls=None
            )
        ),
]

• 각 Choice 객체에는 응답이 어떻게 종료되었는지를 나타내는 finish_reason 필드가 포함
  • stop: 모델이 스스로 출력을 끝내 정상 종료한 경우
  • length: max_tokens 또는 context limit 에 도달해서 강제로 문장이 잘려서 중단된 경우
  • content filter: 안전성 (content moderation) 필터에 걸려서 일부/전체 응답이 차단된 경우
  • tool_calls: 모델이 tool 호출을 수행했고, 그 때문에 출력을 멈춘 경우
• 각 Choice 객체는 서로 다른 finish_reason 을 가질 수 있음
• 각 Choice 객체는 하나의 finish_reason 값을 가짐
• 에러 발생시 애초에 응답 객체는 생성되지 않고 error 객체가 생성되며 따라서 finish_reason 필드도 존재하지 않음