OpenAI SDK

OpenAI 공식 Python 및 TypeScript SDK는 사용자 정의 Base URL을 지원합니다. 클라이언트를 https://api.agtcloud.cn/v1로 지정하면 동일한 SDK 메서드로 AGTCloud의 Chat Completions와 Responses 호환 진입점을 호출할 수 있습니다.

이 페이지는 서버 애플리케이션용입니다. 브라우저 프런트엔드, 데스크톱 애플리케이션 설치 패키지 및 모바일 코드는 장기 API Key를 안전하게 저장할 수 없으므로 실제 자격 증명이 있는 OpenAI 클라이언트를 직접 생성해서는 안 됩니다.

Chat과 Responses 중 선택

두 진입점은 같은 AGTCloud API Key를 사용하지만 모델 지원 범위가 다를 수 있습니다. 모델 목록에서 지원 프로토콜을 확인하고 예시의 MODEL_ID를 전체 모델 ID로 교체합니다.

준비 사항

시작 전에 다음 사항을 확인합니다.

• API Keys 페이지에서 AGTCloud API Key를 생성합니다.
• Chat Completions 또는 Responses를 지원하는 모델 ID를 준비합니다.
• Python 3.10+ 또는 Node.js 22+의 신뢰할 수 있는 서버 실행 환경을 사용합니다.
• 프로젝트에 의존성 잠금 파일을 사용하고 운영 환경에서 SDK를 무제한으로 자동 업그레이드하지 않습니다.

실행 환경 요구 사항은 SDK 버전에 따라 바뀔 수 있습니다. SDK를 업그레이드하기 전에 현재 공식 지원 범위와 프로젝트 배포 환경을 함께 확인합니다.

SDK 설치

python -m pip install openai

설치 후 실제로 결정된 SDK 버전을 프로젝트 잠금 파일에 기록합니다. 버전을 업그레이드할 때는 클라이언트 초기화, 응답 유형 및 Streaming 처리 로직을 다시 검증해야 합니다.

API Key 설정

서버 환경 변수로 API Key를 제공하는 것이 좋습니다. 다음 설정은 안전한 자리표시자 예시이며 실제 배포에서는 클라우드 플랫폼의 비밀 관리 서비스를 사용할 수 있습니다.

export AGTCLOUD_API_KEY="your-api-key"

OpenAI 클라이언트 생성

클라이언트 Base URL에는 반드시 https://api.agtcloud.cn/v1를 입력합니다. API Origin만 입력하거나 /chat/completions 또는 /responses를 더 추가하지 않습니다. SDK가 호출 메서드에 따라 구체적인 경로를 조합합니다.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGTCLOUD_API_KEY"],
    base_url="https://api.agtcloud.cn/v1",
)

Responses 사용

Responses는 input으로 텍스트 또는 Typed Items를 표현하며 성공 응답에는 상태, Output Items 및 Token 사용량이 포함됩니다. SDK의 output_text는 응답의 텍스트 출력을 집계합니다.

response = client.responses.create(
    model="MODEL_ID",
    instructions="간결하고 정확한 한국어로 답변해 주세요.",
    input="API 집계 서비스가 어떤 문제를 해결하는 데 적합한지 세 가지로 설명해 주세요.",
)

print(response.output_text)

output_text는 일반 텍스트 결과를 읽기에 적합합니다. 함수 호출, 검색 결과, 추론 항목 또는 기타 유형을 처리하려면 response.output을 순서대로 순회해야 하며 Message 유형만 남겨서는 안 됩니다. 전체 구조는 OpenAI Responses Reference를 확인합니다.

Chat Completions 사용

Chat Completions는 순서가 있는 messages를 사용합니다. 일반 텍스트는 보통 첫 번째 Choice의 Assistant Message에 있습니다.

completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {
            "role": "developer",
            "content": "간결하고 정확한 한국어로 답변해 주세요.",
        },
        {
            "role": "user",
            "content": "API 집계 서비스가 어떤 문제를 해결하는 데 적합한지 세 가지로 설명해 주세요.",
        },
    ],
)

print(completion.choices[0].message.content)

모델이 도구 호출을 반환하면 message.content가 비어 있을 수 있으므로 message.tool_calls를 확인해야 합니다. 필드 설명은 Chat Completions Reference를 확인합니다.

스트리밍 출력 수신

OpenAI SDK는 SSE 응답을 순회 가능한 이벤트 스트림으로 제공합니다. Responses 이벤트에는 명확한 type이 있습니다. 아래 예시는 텍스트 증분만 출력하며 업무 코드에서는 완료, 실패 및 중단 상태도 처리해야 합니다.

stream = client.responses.create(
    model="MODEL_ID",
    input="한 문장으로 자신을 소개해 주세요.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

상태를 유지하는 이어가기(플랫폼 지원 필요)

모델, 계정 및 업스트림 채널이 응답 저장과 이어가기를 지원하면 첫 응답을 저장하고 그 ID를 previous_response_id로 다음 요청에 전달할 수 있습니다.

first = client.responses.create(
    model="MODEL_ID",
    store=True,
    input="프로젝트 코드명이 Aurora라는 것을 기억해 주세요.",
)

second = client.responses.create(
    model="MODEL_ID",
    previous_response_id=first.id,
    input="프로젝트 코드명은 무엇인가요?",
)

print(second.output_text)

previous_response_id를 사용해도 이전 턴의 instructions가 현재 턴 지시로 자동 적용되지 않습니다. 지속적으로 적용할 동작 제한은 새 요청에 다시 전달해야 합니다.

현재 호출 경로가 응답 저장 또는 이어가기를 지원하지 않으면 애플리케이션이 기록을 유지하고 다음 턴 input에 필요한 Input 및 Output Items를 제출합니다. 전체 기록을 유지할 때는 순수 텍스트뿐 아니라 업무에 필요한 메시지, 추론 및 도구 호출 관계도 보존해야 합니다.

타임아웃, 재시도 및 오류

OpenAI SDK는 HTTP 오류를 해당 예외 유형으로 변환하고 일부 연결 오류, 타임아웃, 요청 제한 및 서버 오류에 제한적인 자동 재시도를 수행합니다. 운영 애플리케이션은 장시간 대기 또는 중복 소비를 방지하도록 요청 유형에 따라 타임아웃과 재시도 상한을 명시적으로 설정해야 합니다.

전체 API Key, 민감한 데이터가 포함된 요청 본문 또는 처리되지 않은 사용자 내용을 로그에 기록하지 않습니다. 응답에 Request ID가 있으면 구체적인 요청을 찾기 쉽도록 오류 로그에 해당 식별자를 저장하는 것이 좋습니다.

완료 확인

• 클라이언트 Base URL은 https://api.agtcloud.cn/v1이며 중복 /v1 또는 구체적인 엔드포인트 경로가 추가되어 있지 않습니다.
• API Key는 신뢰할 수 있는 서버 환경에서 읽으며 프런트엔드 코드 또는 버전 관리에 포함되지 않습니다.
• MODEL_ID는 현재 API Key에 표시되며 대상 진입점을 지원하는 모델로 교체했습니다.
• 일반 요청에서 텍스트, 상태 및 사용량을 올바르게 읽을 수 있습니다.
• Streaming 코드가 텍스트 증분, 완료 이벤트 및 오류 이벤트를 구분합니다.
• 도구 또는 멀티모달 요청은 해당 기능 지원이 명확한 모델에만 보냅니다.

기존 프로젝트의 공급업체 설정을 체계적으로 교체하려면 공식 SDK 마이그레이션을 이어서 읽고 Chat 구조를 Responses로 리팩터링하려면 Chat → Responses를 참고합니다.